From a9157ce950dfe2fc30795d43b9d79b9d1bffc48b Mon Sep 17 00:00:00 2001 From: Jacob McDonnell Date: Sat, 25 Apr 2026 19:54:44 -0400 Subject: docs: Added All OpenBSD Manuals --- static/openbsd/man3/ACCESS_DESCRIPTION_new.3 | 152 + static/openbsd/man3/AES_encrypt.3 | 174 + static/openbsd/man3/ASIdentifiers_new.3 | 139 + static/openbsd/man3/ASN1_BIT_STRING_set.3 | 140 + static/openbsd/man3/ASN1_INTEGER_get.3 | 429 +++ static/openbsd/man3/ASN1_NULL_new.3 | 67 + static/openbsd/man3/ASN1_OBJECT_new.3 | 229 ++ static/openbsd/man3/ASN1_PRINTABLE_type.3 | 93 + static/openbsd/man3/ASN1_STRING_TABLE_get.3 | 91 + static/openbsd/man3/ASN1_STRING_length.3 | 460 +++ static/openbsd/man3/ASN1_STRING_new.3 | 302 ++ static/openbsd/man3/ASN1_STRING_print_ex.3 | 241 ++ static/openbsd/man3/ASN1_TIME_set.3 | 753 ++++ static/openbsd/man3/ASN1_TYPE_get.3 | 444 +++ .../openbsd/man3/ASN1_UNIVERSALSTRING_to_string.3 | 65 + static/openbsd/man3/ASN1_generate_nconf.3 | 395 ++ static/openbsd/man3/ASN1_get_object.3 | 201 + static/openbsd/man3/ASN1_item_d2i.3 | 493 +++ static/openbsd/man3/ASN1_item_digest.3 | 72 + static/openbsd/man3/ASN1_item_new.3 | 127 + static/openbsd/man3/ASN1_item_pack.3 | 85 + static/openbsd/man3/ASN1_item_sign.3 | 121 + static/openbsd/man3/ASN1_item_verify.3 | 78 + static/openbsd/man3/ASN1_mbstring_copy.3 | 370 ++ static/openbsd/man3/ASN1_parse_dump.3 | 217 ++ static/openbsd/man3/ASN1_put_object.3 | 227 ++ static/openbsd/man3/ASRange_new.3 | 411 ++ static/openbsd/man3/AUTHORITY_KEYID_new.3 | 74 + static/openbsd/man3/BASIC_CONSTRAINTS_new.3 | 90 + static/openbsd/man3/BF_set_key.3 | 270 ++ static/openbsd/man3/BIO_accept.3 | 388 ++ static/openbsd/man3/BIO_ctrl.3 | 638 ++++ static/openbsd/man3/BIO_dump.3 | 97 + static/openbsd/man3/BIO_dup_chain.3 | 142 + static/openbsd/man3/BIO_f_base64.3 | 149 + static/openbsd/man3/BIO_f_buffer.3 | 263 ++ static/openbsd/man3/BIO_f_cipher.3 | 210 + static/openbsd/man3/BIO_f_md.3 | 367 ++ static/openbsd/man3/BIO_f_null.3 | 100 + static/openbsd/man3/BIO_f_ssl.3 | 610 +++ static/openbsd/man3/BIO_find_type.3 | 272 ++ static/openbsd/man3/BIO_get_data.3 | 407 ++ static/openbsd/man3/BIO_get_ex_new_index.3 | 199 + static/openbsd/man3/BIO_meth_new.3 | 368 ++ static/openbsd/man3/BIO_new.3 | 280 ++ static/openbsd/man3/BIO_new_CMS.3 | 142 + static/openbsd/man3/BIO_printf.3 | 47 + static/openbsd/man3/BIO_push.3 | 336 ++ static/openbsd/man3/BIO_read.3 | 282 ++ static/openbsd/man3/BIO_s_accept.3 | 415 ++ static/openbsd/man3/BIO_s_bio.3 | 417 ++ static/openbsd/man3/BIO_s_connect.3 | 504 +++ static/openbsd/man3/BIO_s_datagram.3 | 574 +++ static/openbsd/man3/BIO_s_fd.3 | 291 ++ static/openbsd/man3/BIO_s_file.3 | 378 ++ static/openbsd/man3/BIO_s_mem.3 | 322 ++ static/openbsd/man3/BIO_s_null.3 | 101 + static/openbsd/man3/BIO_s_socket.3 | 126 + static/openbsd/man3/BIO_set_callback.3 | 397 ++ static/openbsd/man3/BIO_should_retry.3 | 302 ++ static/openbsd/man3/BN_CTX_new.3 | 124 + static/openbsd/man3/BN_CTX_start.3 | 138 + static/openbsd/man3/BN_add.3 | 644 ++++ static/openbsd/man3/BN_add_word.3 | 183 + static/openbsd/man3/BN_bn2bin.3 | 389 ++ static/openbsd/man3/BN_cmp.3 | 170 + static/openbsd/man3/BN_copy.3 | 166 + static/openbsd/man3/BN_generate_prime.3 | 376 ++ static/openbsd/man3/BN_get_rfc3526_prime_8192.3 | 154 + static/openbsd/man3/BN_kronecker.3 | 58 + static/openbsd/man3/BN_mod_inverse.3 | 127 + static/openbsd/man3/BN_mod_mul_montgomery.3 | 272 ++ static/openbsd/man3/BN_mod_sqrt.3 | 112 + static/openbsd/man3/BN_new.3 | 164 + static/openbsd/man3/BN_num_bytes.3 | 176 + static/openbsd/man3/BN_rand.3 | 147 + static/openbsd/man3/BN_set_bit.3 | 217 ++ static/openbsd/man3/BN_set_flags.3 | 161 + static/openbsd/man3/BN_set_negative.3 | 64 + static/openbsd/man3/BN_swap.3 | 149 + static/openbsd/man3/BN_zero.3 | 174 + static/openbsd/man3/BUF_MEM_new.3 | 154 + static/openbsd/man3/CMAC_Init.3 | 274 ++ static/openbsd/man3/CMS_ContentInfo_new.3 | 136 + static/openbsd/man3/CMS_add0_cert.3 | 223 ++ static/openbsd/man3/CMS_add1_recipient_cert.3 | 201 + static/openbsd/man3/CMS_add1_signer.3 | 250 ++ static/openbsd/man3/CMS_compress.3 | 171 + static/openbsd/man3/CMS_decrypt.3 | 227 ++ static/openbsd/man3/CMS_encrypt.3 | 192 + static/openbsd/man3/CMS_final.3 | 102 + static/openbsd/man3/CMS_get0_RecipientInfos.3 | 329 ++ static/openbsd/man3/CMS_get0_SignerInfos.3 | 215 ++ static/openbsd/man3/CMS_get0_type.3 | 227 ++ static/openbsd/man3/CMS_get1_ReceiptRequest.3 | 199 + static/openbsd/man3/CMS_sign.3 | 247 ++ static/openbsd/man3/CMS_sign_receipt.3 | 120 + static/openbsd/man3/CMS_signed_add1_attr.3 | 361 ++ static/openbsd/man3/CMS_uncompress.3 | 116 + static/openbsd/man3/CMS_verify.3 | 231 ++ static/openbsd/man3/CMS_verify_receipt.3 | 111 + static/openbsd/man3/CONF_modules_free.3 | 101 + static/openbsd/man3/CONF_modules_load_file.3 | 277 ++ static/openbsd/man3/CRYPTO_lock.3 | 122 + static/openbsd/man3/CRYPTO_memcmp.3 | 96 + static/openbsd/man3/CRYPTO_set_ex_data.3 | 565 +++ static/openbsd/man3/CRYPTO_set_mem_functions.3 | 97 + static/openbsd/man3/ChaCha.3 | 254 ++ static/openbsd/man3/DES_set_key.3 | 788 ++++ static/openbsd/man3/DH_generate_key.3 | 123 + static/openbsd/man3/DH_generate_parameters.3 | 242 ++ static/openbsd/man3/DH_get0_pqg.3 | 343 ++ static/openbsd/man3/DH_get_ex_new_index.3 | 100 + static/openbsd/man3/DH_new.3 | 134 + static/openbsd/man3/DH_set_method.3 | 196 + static/openbsd/man3/DH_size.3 | 98 + static/openbsd/man3/DIST_POINT_new.3 | 155 + static/openbsd/man3/DSA_SIG_new.3 | 142 + static/openbsd/man3/DSA_do_sign.3 | 120 + static/openbsd/man3/DSA_dup_DH.3 | 89 + static/openbsd/man3/DSA_generate_key.3 | 85 + static/openbsd/man3/DSA_generate_parameters_ex.3 | 173 + static/openbsd/man3/DSA_get0_pqg.3 | 321 ++ static/openbsd/man3/DSA_get_ex_new_index.3 | 99 + static/openbsd/man3/DSA_meth_new.3 | 231 ++ static/openbsd/man3/DSA_new.3 | 142 + static/openbsd/man3/DSA_set_method.3 | 179 + static/openbsd/man3/DSA_sign.3 | 174 + static/openbsd/man3/DSA_size.3 | 123 + static/openbsd/man3/DTLSv1_listen.3 | 188 + static/openbsd/man3/ECDH_compute_key.3 | 89 + static/openbsd/man3/ECDSA_SIG_new.3 | 453 +++ static/openbsd/man3/EC_GROUP_check.3 | 160 + static/openbsd/man3/EC_GROUP_get_curve_name.3 | 266 ++ static/openbsd/man3/EC_GROUP_new_by_curve_name.3 | 311 ++ static/openbsd/man3/EC_GROUP_new_curve_GFp.3 | 463 +++ static/openbsd/man3/EC_KEY_METHOD_new.3 | 330 ++ static/openbsd/man3/EC_KEY_new.3 | 536 +++ static/openbsd/man3/EC_POINT_add.3 | 223 ++ .../openbsd/man3/EC_POINT_get_affine_coordinates.3 | 216 ++ static/openbsd/man3/EC_POINT_new.3 | 208 + static/openbsd/man3/EC_POINT_point2oct.3 | 434 +++ static/openbsd/man3/ENGINE_new.3 | 175 + static/openbsd/man3/ERR_GET_LIB.3 | 127 + static/openbsd/man3/ERR_asprintf_error_data.3 | 56 + static/openbsd/man3/ERR_clear_error.3 | 71 + static/openbsd/man3/ERR_error_string.3 | 177 + static/openbsd/man3/ERR_get_error.3 | 192 + static/openbsd/man3/ERR_load_crypto_strings.3 | 153 + static/openbsd/man3/ERR_load_strings.3 | 117 + static/openbsd/man3/ERR_print_errors.3 | 123 + static/openbsd/man3/ERR_put_error.3 | 126 + static/openbsd/man3/ERR_remove_state.3 | 109 + static/openbsd/man3/ERR_set_mark.3 | 87 + static/openbsd/man3/ESS_SIGNING_CERT_new.3 | 118 + static/openbsd/man3/EVP_AEAD_CTX_init.3 | 412 ++ static/openbsd/man3/EVP_BytesToKey.3 | 146 + static/openbsd/man3/EVP_CIPHER_CTX_ctrl.3 | 262 ++ .../openbsd/man3/EVP_CIPHER_CTX_get_cipher_data.3 | 147 + static/openbsd/man3/EVP_CIPHER_CTX_init.3 | 210 + static/openbsd/man3/EVP_CIPHER_CTX_set_flags.3 | 234 ++ static/openbsd/man3/EVP_CIPHER_do_all.3 | 212 + static/openbsd/man3/EVP_CIPHER_meth_new.3 | 389 ++ static/openbsd/man3/EVP_CIPHER_nid.3 | 307 ++ static/openbsd/man3/EVP_DigestInit.3 | 608 +++ static/openbsd/man3/EVP_DigestSignInit.3 | 244 ++ static/openbsd/man3/EVP_DigestVerifyInit.3 | 224 ++ static/openbsd/man3/EVP_EncodeInit.3 | 335 ++ static/openbsd/man3/EVP_EncryptInit.3 | 814 ++++ static/openbsd/man3/EVP_MD_CTX_ctrl.3 | 282 ++ static/openbsd/man3/EVP_MD_nid.3 | 316 ++ static/openbsd/man3/EVP_OpenInit.3 | 156 + static/openbsd/man3/EVP_PKCS82PKEY.3 | 61 + static/openbsd/man3/EVP_PKEY_CTX_ctrl.3 | 583 +++ static/openbsd/man3/EVP_PKEY_CTX_get_operation.3 | 138 + static/openbsd/man3/EVP_PKEY_CTX_new.3 | 184 + static/openbsd/man3/EVP_PKEY_CTX_set_hkdf_md.3 | 259 ++ static/openbsd/man3/EVP_PKEY_CTX_set_tls1_prf_md.3 | 172 + static/openbsd/man3/EVP_PKEY_asn1_get_count.3 | 243 ++ static/openbsd/man3/EVP_PKEY_cmp.3 | 180 + static/openbsd/man3/EVP_PKEY_decrypt.3 | 176 + static/openbsd/man3/EVP_PKEY_derive.3 | 255 ++ static/openbsd/man3/EVP_PKEY_encrypt.3 | 184 + .../openbsd/man3/EVP_PKEY_get_default_digest_nid.3 | 129 + static/openbsd/man3/EVP_PKEY_keygen.3 | 370 ++ static/openbsd/man3/EVP_PKEY_new.3 | 348 ++ static/openbsd/man3/EVP_PKEY_new_CMAC_key.3 | 160 + static/openbsd/man3/EVP_PKEY_print_private.3 | 130 + static/openbsd/man3/EVP_PKEY_set1_RSA.3 | 499 +++ static/openbsd/man3/EVP_PKEY_sign.3 | 191 + static/openbsd/man3/EVP_PKEY_size.3 | 225 ++ static/openbsd/man3/EVP_PKEY_verify.3 | 168 + static/openbsd/man3/EVP_PKEY_verify_recover.3 | 189 + static/openbsd/man3/EVP_SealInit.3 | 202 + static/openbsd/man3/EVP_SignInit.3 | 212 + static/openbsd/man3/EVP_VerifyInit.3 | 206 + static/openbsd/man3/EVP_aes_128_cbc.3 | 305 ++ static/openbsd/man3/EVP_aes_128_ccm.3 | 574 +++ static/openbsd/man3/EVP_aes_128_gcm.3 | 255 ++ static/openbsd/man3/EVP_camellia_128_cbc.3 | 152 + static/openbsd/man3/EVP_chacha20.3 | 293 ++ static/openbsd/man3/EVP_des_cbc.3 | 231 ++ static/openbsd/man3/EVP_rc2_cbc.3 | 202 + static/openbsd/man3/EVP_rc4.3 | 110 + static/openbsd/man3/EVP_sha1.3 | 121 + static/openbsd/man3/EVP_sha3_224.3 | 92 + static/openbsd/man3/EVP_sm3.3 | 83 + static/openbsd/man3/EVP_sm4_cbc.3 | 83 + static/openbsd/man3/EXTENDED_KEY_USAGE_new.3 | 85 + static/openbsd/man3/GENERAL_NAME_new.3 | 166 + static/openbsd/man3/HMAC.3 | 325 ++ static/openbsd/man3/IPAddressRange_new.3 | 526 +++ static/openbsd/man3/MB_CUR_MAX.3 | 118 + static/openbsd/man3/MD5.3 | 202 + static/openbsd/man3/MD5Init.3 | 213 ++ static/openbsd/man3/NAME_CONSTRAINTS_new.3 | 101 + static/openbsd/man3/OBJ_create.3 | 249 ++ static/openbsd/man3/OBJ_find_sigid_algs.3 | 89 + static/openbsd/man3/OBJ_nid2obj.3 | 522 +++ static/openbsd/man3/OCSP_CRLID_new.3 | 114 + static/openbsd/man3/OCSP_REQUEST_new.3 | 330 ++ static/openbsd/man3/OCSP_SERVICELOC_new.3 | 110 + static/openbsd/man3/OCSP_cert_to_id.3 | 240 ++ static/openbsd/man3/OCSP_request_add1_nonce.3 | 164 + static/openbsd/man3/OCSP_resp_find_status.3 | 495 +++ static/openbsd/man3/OCSP_response_status.3 | 309 ++ static/openbsd/man3/OCSP_sendreq_new.3 | 324 ++ static/openbsd/man3/OPENSSL_VERSION_NUMBER.3 | 282 ++ static/openbsd/man3/OPENSSL_cleanse.3 | 43 + static/openbsd/man3/OPENSSL_config.3 | 150 + static/openbsd/man3/OPENSSL_init_crypto.3 | 112 + static/openbsd/man3/OPENSSL_init_ssl.3 | 77 + static/openbsd/man3/OPENSSL_malloc.3 | 102 + static/openbsd/man3/OPENSSL_sk_new.3 | 554 +++ static/openbsd/man3/OpenSSL_add_all_algorithms.3 | 169 + static/openbsd/man3/PEM_ASN1_read.3 | 173 + static/openbsd/man3/PEM_X509_INFO_read_bio.3 | 173 + static/openbsd/man3/PEM_bytes_read_bio.3 | 185 + static/openbsd/man3/PEM_read.3 | 417 ++ static/openbsd/man3/PEM_read_SSL_SESSION.3 | 148 + static/openbsd/man3/PEM_read_bio_PrivateKey.3 | 1336 +++++++ static/openbsd/man3/PEM_write_bio_CMS_stream.3 | 96 + static/openbsd/man3/PEM_write_bio_PKCS7_stream.3 | 91 + static/openbsd/man3/PKCS12_SAFEBAG_new.3 | 105 + static/openbsd/man3/PKCS12_create.3 | 189 + static/openbsd/man3/PKCS12_new.3 | 100 + static/openbsd/man3/PKCS12_newpass.3 | 156 + static/openbsd/man3/PKCS12_parse.3 | 146 + static/openbsd/man3/PKCS5_PBKDF2_HMAC.3 | 164 + static/openbsd/man3/PKCS7_add_attribute.3 | 370 ++ static/openbsd/man3/PKCS7_dataFinal.3 | 159 + static/openbsd/man3/PKCS7_dataInit.3 | 227 ++ static/openbsd/man3/PKCS7_decrypt.3 | 119 + static/openbsd/man3/PKCS7_encrypt.3 | 170 + static/openbsd/man3/PKCS7_final.3 | 203 + static/openbsd/man3/PKCS7_get_signer_info.3 | 63 + static/openbsd/man3/PKCS7_new.3 | 270 ++ static/openbsd/man3/PKCS7_set_content.3 | 121 + static/openbsd/man3/PKCS7_set_type.3 | 120 + static/openbsd/man3/PKCS7_sign.3 | 252 ++ static/openbsd/man3/PKCS7_sign_add_signer.3 | 188 + static/openbsd/man3/PKCS7_verify.3 | 262 ++ static/openbsd/man3/PKCS8_PRIV_KEY_INFO_new.3 | 66 + static/openbsd/man3/PKCS8_pkey_set0.3 | 160 + static/openbsd/man3/PKEY_USAGE_PERIOD_new.3 | 75 + static/openbsd/man3/POLICYINFO_new.3 | 219 ++ static/openbsd/man3/RAND_add.3 | 74 + static/openbsd/man3/RAND_bytes.3 | 109 + static/openbsd/man3/RAND_load_file.3 | 120 + static/openbsd/man3/RAND_set_rand_method.3 | 56 + static/openbsd/man3/RC2_encrypt.3 | 196 + static/openbsd/man3/RC4.3 | 127 + static/openbsd/man3/RIPEMD160.3 | 155 + static/openbsd/man3/RMD160Init.3 | 236 ++ static/openbsd/man3/RSA_PSS_PARAMS_new.3 | 61 + static/openbsd/man3/RSA_blinding_on.3 | 98 + static/openbsd/man3/RSA_check_key.3 | 131 + static/openbsd/man3/RSA_generate_key.3 | 165 + static/openbsd/man3/RSA_get0_key.3 | 461 +++ static/openbsd/man3/RSA_get_ex_new_index.3 | 383 ++ static/openbsd/man3/RSA_meth_new.3 | 607 +++ static/openbsd/man3/RSA_new.3 | 249 ++ static/openbsd/man3/RSA_padding_add_PKCS1_type_1.3 | 237 ++ static/openbsd/man3/RSA_pkey_ctx_ctrl.3 | 403 ++ static/openbsd/man3/RSA_print.3 | 145 + static/openbsd/man3/RSA_private_encrypt.3 | 151 + static/openbsd/man3/RSA_public_encrypt.3 | 248 ++ static/openbsd/man3/RSA_security_bits.3 | 138 + static/openbsd/man3/RSA_set_method.3 | 253 ++ static/openbsd/man3/RSA_sign.3 | 148 + static/openbsd/man3/RSA_sign_ASN1_OCTET_STRING.3 | 132 + static/openbsd/man3/RSA_size.3 | 98 + static/openbsd/man3/SHA1.3 | 286 ++ static/openbsd/man3/SHA1Init.3 | 239 ++ static/openbsd/man3/SHA256Init.3 | 349 ++ static/openbsd/man3/SMIME_crlf_copy.3 | 99 + static/openbsd/man3/SMIME_read_CMS.3 | 136 + static/openbsd/man3/SMIME_read_PKCS7.3 | 154 + static/openbsd/man3/SMIME_text.3 | 61 + static/openbsd/man3/SMIME_write_CMS.3 | 223 ++ static/openbsd/man3/SMIME_write_PKCS7.3 | 228 ++ static/openbsd/man3/SSL_CIPHER_get_name.3 | 399 ++ .../openbsd/man3/SSL_COMP_add_compression_method.3 | 43 + static/openbsd/man3/SSL_CTX_add1_chain_cert.3 | 223 ++ static/openbsd/man3/SSL_CTX_add_extra_chain_cert.3 | 161 + static/openbsd/man3/SSL_CTX_add_session.3 | 133 + static/openbsd/man3/SSL_CTX_ctrl.3 | 123 + static/openbsd/man3/SSL_CTX_flush_sessions.3 | 101 + static/openbsd/man3/SSL_CTX_free.3 | 102 + static/openbsd/man3/SSL_CTX_get0_certificate.3 | 53 + static/openbsd/man3/SSL_CTX_get_ex_new_index.3 | 125 + static/openbsd/man3/SSL_CTX_get_verify_mode.3 | 132 + .../openbsd/man3/SSL_CTX_load_verify_locations.3 | 239 ++ static/openbsd/man3/SSL_CTX_new.3 | 346 ++ static/openbsd/man3/SSL_CTX_sess_number.3 | 169 + static/openbsd/man3/SSL_CTX_sess_set_cache_size.3 | 110 + static/openbsd/man3/SSL_CTX_sess_set_get_cb.3 | 222 ++ static/openbsd/man3/SSL_CTX_sessions.3 | 87 + static/openbsd/man3/SSL_CTX_set1_groups.3 | 164 + static/openbsd/man3/SSL_CTX_set_alpn_select_cb.3 | 306 ++ static/openbsd/man3/SSL_CTX_set_cert_store.3 | 147 + .../man3/SSL_CTX_set_cert_verify_callback.3 | 164 + static/openbsd/man3/SSL_CTX_set_cipher_list.3 | 376 ++ static/openbsd/man3/SSL_CTX_set_client_CA_list.3 | 184 + static/openbsd/man3/SSL_CTX_set_client_cert_cb.3 | 192 + .../openbsd/man3/SSL_CTX_set_default_passwd_cb.3 | 217 ++ .../openbsd/man3/SSL_CTX_set_generate_session_id.3 | 222 ++ static/openbsd/man3/SSL_CTX_set_info_callback.3 | 234 ++ static/openbsd/man3/SSL_CTX_set_keylog_callback.3 | 57 + static/openbsd/man3/SSL_CTX_set_max_cert_list.3 | 155 + .../openbsd/man3/SSL_CTX_set_min_proto_version.3 | 157 + static/openbsd/man3/SSL_CTX_set_mode.3 | 205 + static/openbsd/man3/SSL_CTX_set_msg_callback.3 | 184 + static/openbsd/man3/SSL_CTX_set_num_tickets.3 | 64 + static/openbsd/man3/SSL_CTX_set_options.3 | 375 ++ static/openbsd/man3/SSL_CTX_set_quiet_shutdown.3 | 162 + static/openbsd/man3/SSL_CTX_set_read_ahead.3 | 145 + static/openbsd/man3/SSL_CTX_set_security_level.3 | 160 + .../openbsd/man3/SSL_CTX_set_session_cache_mode.3 | 199 + .../openbsd/man3/SSL_CTX_set_session_id_context.3 | 161 + static/openbsd/man3/SSL_CTX_set_ssl_version.3 | 147 + static/openbsd/man3/SSL_CTX_set_timeout.3 | 119 + .../man3/SSL_CTX_set_tlsext_servername_callback.3 | 248 ++ static/openbsd/man3/SSL_CTX_set_tlsext_status_cb.3 | 239 ++ .../man3/SSL_CTX_set_tlsext_ticket_key_cb.3 | 301 ++ static/openbsd/man3/SSL_CTX_set_tlsext_use_srtp.3 | 198 + static/openbsd/man3/SSL_CTX_set_tmp_dh_callback.3 | 230 ++ static/openbsd/man3/SSL_CTX_set_tmp_rsa_callback.3 | 115 + static/openbsd/man3/SSL_CTX_set_verify.3 | 480 +++ static/openbsd/man3/SSL_CTX_use_certificate.3 | 452 +++ static/openbsd/man3/SSL_SESSION_free.3 | 149 + static/openbsd/man3/SSL_SESSION_get0_cipher.3 | 95 + static/openbsd/man3/SSL_SESSION_get0_peer.3 | 81 + static/openbsd/man3/SSL_SESSION_get_compress_id.3 | 79 + static/openbsd/man3/SSL_SESSION_get_ex_new_index.3 | 135 + static/openbsd/man3/SSL_SESSION_get_id.3 | 113 + .../man3/SSL_SESSION_get_protocol_version.3 | 85 + static/openbsd/man3/SSL_SESSION_get_time.3 | 166 + static/openbsd/man3/SSL_SESSION_has_ticket.3 | 86 + static/openbsd/man3/SSL_SESSION_is_resumable.3 | 82 + static/openbsd/man3/SSL_SESSION_new.3 | 97 + static/openbsd/man3/SSL_SESSION_print.3 | 75 + static/openbsd/man3/SSL_SESSION_set1_id_context.3 | 114 + static/openbsd/man3/SSL_accept.3 | 156 + static/openbsd/man3/SSL_alert_type_string.3 | 254 ++ static/openbsd/man3/SSL_clear.3 | 145 + static/openbsd/man3/SSL_connect.3 | 155 + static/openbsd/man3/SSL_copy_session_id.3 | 80 + static/openbsd/man3/SSL_do_handshake.3 | 153 + static/openbsd/man3/SSL_dup.3 | 63 + static/openbsd/man3/SSL_dup_CA_list.3 | 56 + static/openbsd/man3/SSL_export_keying_material.3 | 134 + static/openbsd/man3/SSL_free.3 | 116 + static/openbsd/man3/SSL_get_SSL_CTX.3 | 80 + static/openbsd/man3/SSL_get_certificate.3 | 65 + static/openbsd/man3/SSL_get_ciphers.3 | 250 ++ static/openbsd/man3/SSL_get_client_CA_list.3 | 97 + static/openbsd/man3/SSL_get_client_random.3 | 151 + static/openbsd/man3/SSL_get_current_cipher.3 | 123 + static/openbsd/man3/SSL_get_default_timeout.3 | 86 + static/openbsd/man3/SSL_get_error.3 | 218 ++ .../man3/SSL_get_ex_data_X509_STORE_CTX_idx.3 | 117 + static/openbsd/man3/SSL_get_ex_new_index.3 | 137 + static/openbsd/man3/SSL_get_fd.3 | 104 + static/openbsd/man3/SSL_get_finished.3 | 78 + static/openbsd/man3/SSL_get_peer_cert_chain.3 | 108 + static/openbsd/man3/SSL_get_peer_certificate.3 | 106 + static/openbsd/man3/SSL_get_rbio.3 | 99 + static/openbsd/man3/SSL_get_server_tmp_key.3 | 90 + static/openbsd/man3/SSL_get_session.3 | 164 + static/openbsd/man3/SSL_get_shared_ciphers.3 | 104 + static/openbsd/man3/SSL_get_state.3 | 162 + static/openbsd/man3/SSL_get_verify_result.3 | 103 + static/openbsd/man3/SSL_get_version.3 | 118 + static/openbsd/man3/SSL_library_init.3 | 99 + static/openbsd/man3/SSL_load_client_CA_file.3 | 186 + static/openbsd/man3/SSL_new.3 | 111 + static/openbsd/man3/SSL_num_renegotiations.3 | 76 + static/openbsd/man3/SSL_pending.3 | 91 + static/openbsd/man3/SSL_read.3 | 279 ++ static/openbsd/man3/SSL_read_early_data.3 | 175 + static/openbsd/man3/SSL_renegotiate.3 | 167 + static/openbsd/man3/SSL_rstate_string.3 | 109 + static/openbsd/man3/SSL_session_reused.3 | 85 + static/openbsd/man3/SSL_set1_host.3 | 173 + static/openbsd/man3/SSL_set1_param.3 | 138 + static/openbsd/man3/SSL_set_SSL_CTX.3 | 68 + static/openbsd/man3/SSL_set_bio.3 | 100 + static/openbsd/man3/SSL_set_connect_state.3 | 154 + static/openbsd/man3/SSL_set_fd.3 | 130 + static/openbsd/man3/SSL_set_max_send_fragment.3 | 98 + .../man3/SSL_set_psk_use_session_callback.3 | 87 + static/openbsd/man3/SSL_set_session.3 | 120 + static/openbsd/man3/SSL_set_shutdown.3 | 139 + static/openbsd/man3/SSL_set_tmp_ecdh.3 | 120 + static/openbsd/man3/SSL_set_verify_result.3 | 91 + static/openbsd/man3/SSL_shutdown.3 | 254 ++ static/openbsd/man3/SSL_state_string.3 | 111 + static/openbsd/man3/SSL_want.3 | 162 + static/openbsd/man3/SSL_write.3 | 250 ++ static/openbsd/man3/STACK_OF.3 | 208 + static/openbsd/man3/SipHash24_Init.3 | 103 + static/openbsd/man3/TS_REQ_new.3 | 183 + static/openbsd/man3/UI_create_method.3 | 285 ++ static/openbsd/man3/UI_get_string_type.3 | 282 ++ static/openbsd/man3/UI_new.3 | 530 +++ static/openbsd/man3/X25519.3 | 212 + static/openbsd/man3/X509V3_EXT_get_nid.3 | 95 + static/openbsd/man3/X509V3_EXT_print.3 | 196 + static/openbsd/man3/X509V3_extensions_print.3 | 101 + static/openbsd/man3/X509V3_get_d2i.3 | 508 +++ static/openbsd/man3/X509V3_parse_list.3 | 102 + static/openbsd/man3/X509_ALGOR_dup.3 | 298 ++ static/openbsd/man3/X509_ATTRIBUTE_get0_object.3 | 137 + static/openbsd/man3/X509_ATTRIBUTE_new.3 | 181 + static/openbsd/man3/X509_ATTRIBUTE_set1_object.3 | 268 ++ static/openbsd/man3/X509_CINF_new.3 | 118 + static/openbsd/man3/X509_CRL_get0_by_serial.3 | 180 + static/openbsd/man3/X509_CRL_new.3 | 144 + static/openbsd/man3/X509_CRL_print.3 | 114 + static/openbsd/man3/X509_EXTENSION_set_object.3 | 349 ++ static/openbsd/man3/X509_INFO_new.3 | 72 + static/openbsd/man3/X509_LOOKUP_hash_dir.3 | 189 + static/openbsd/man3/X509_LOOKUP_new.3 | 461 +++ static/openbsd/man3/X509_NAME_ENTRY_get_object.3 | 384 ++ static/openbsd/man3/X509_NAME_add_entry_by_txt.3 | 274 ++ static/openbsd/man3/X509_NAME_get_index_by_NID.3 | 266 ++ static/openbsd/man3/X509_NAME_hash.3 | 98 + static/openbsd/man3/X509_NAME_new.3 | 104 + static/openbsd/man3/X509_NAME_print_ex.3 | 261 ++ static/openbsd/man3/X509_OBJECT_get0_X509.3 | 253 ++ static/openbsd/man3/X509_PUBKEY_new.3 | 402 ++ static/openbsd/man3/X509_PURPOSE_set.3 | 296 ++ static/openbsd/man3/X509_REQ_add1_attr.3 | 173 + static/openbsd/man3/X509_REQ_add_extensions.3 | 114 + static/openbsd/man3/X509_REQ_new.3 | 146 + static/openbsd/man3/X509_REQ_print_ex.3 | 175 + static/openbsd/man3/X509_REVOKED_new.3 | 214 ++ static/openbsd/man3/X509_SIG_get0.3 | 91 + static/openbsd/man3/X509_SIG_new.3 | 69 + static/openbsd/man3/X509_STORE_CTX_get_error.3 | 592 +++ .../openbsd/man3/X509_STORE_CTX_get_ex_new_index.3 | 154 + static/openbsd/man3/X509_STORE_CTX_new.3 | 366 ++ static/openbsd/man3/X509_STORE_CTX_set_flags.3 | 325 ++ static/openbsd/man3/X509_STORE_CTX_set_verify.3 | 257 ++ static/openbsd/man3/X509_STORE_CTX_set_verify_cb.3 | 310 ++ static/openbsd/man3/X509_STORE_get_by_subject.3 | 247 ++ static/openbsd/man3/X509_STORE_load_locations.3 | 189 + static/openbsd/man3/X509_STORE_new.3 | 146 + static/openbsd/man3/X509_STORE_set1_param.3 | 269 ++ .../openbsd/man3/X509_STORE_set_verify_cb_func.3 | 122 + static/openbsd/man3/X509_VERIFY_PARAM_new.3 | 307 ++ static/openbsd/man3/X509_VERIFY_PARAM_set_flags.3 | 751 ++++ static/openbsd/man3/X509_add1_trust_object.3 | 100 + static/openbsd/man3/X509_check_ca.3 | 118 + static/openbsd/man3/X509_check_host.3 | 247 ++ static/openbsd/man3/X509_check_issued.3 | 110 + static/openbsd/man3/X509_check_private_key.3 | 74 + static/openbsd/man3/X509_check_purpose.3 | 432 +++ static/openbsd/man3/X509_cmp.3 | 233 ++ static/openbsd/man3/X509_cmp_time.3 | 201 + static/openbsd/man3/X509_digest.3 | 156 + static/openbsd/man3/X509_find_by_subject.3 | 70 + static/openbsd/man3/X509_get0_notBefore.3 | 265 ++ static/openbsd/man3/X509_get0_signature.3 | 288 ++ static/openbsd/man3/X509_get1_email.3 | 124 + static/openbsd/man3/X509_get_extension_flags.3 | 235 ++ static/openbsd/man3/X509_get_pubkey.3 | 297 ++ static/openbsd/man3/X509_get_pubkey_parameters.3 | 100 + static/openbsd/man3/X509_get_serialNumber.3 | 130 + static/openbsd/man3/X509_get_subject_name.3 | 190 + static/openbsd/man3/X509_get_version.3 | 163 + static/openbsd/man3/X509_keyid_set1.3 | 172 + static/openbsd/man3/X509_load_cert_file.3 | 134 + static/openbsd/man3/X509_new.3 | 279 ++ static/openbsd/man3/X509_ocspid_print.3 | 59 + static/openbsd/man3/X509_print_ex.3 | 285 ++ static/openbsd/man3/X509_sign.3 | 210 + static/openbsd/man3/X509_signature_dump.3 | 86 + static/openbsd/man3/X509_verify_cert.3 | 94 + static/openbsd/man3/X509v3_addr_add_inherit.3 | 476 +++ static/openbsd/man3/X509v3_addr_get_range.3 | 133 + static/openbsd/man3/X509v3_addr_inherits.3 | 105 + static/openbsd/man3/X509v3_addr_subset.3 | 177 + static/openbsd/man3/X509v3_addr_validate_path.3 | 204 + static/openbsd/man3/X509v3_asid_add_id_or_range.3 | 328 ++ static/openbsd/man3/X509v3_get_ext_by_NID.3 | 409 ++ static/openbsd/man3/__fpending.3 | 129 + static/openbsd/man3/__tfork_thread.3 | 142 + static/openbsd/man3/a2d_ASN1_OBJECT.3 | 85 + static/openbsd/man3/a2i_ipadd.3 | 137 + static/openbsd/man3/a64l.3 | 133 + static/openbsd/man3/abort.3 | 77 + static/openbsd/man3/abs.3 | 75 + static/openbsd/man3/acos.3 | 82 + static/openbsd/man3/acosh.3 | 83 + static/openbsd/man3/agentx.3 | 661 ++++ static/openbsd/man3/alarm.3 | 108 + static/openbsd/man3/alloca.3 | 74 + static/openbsd/man3/arc4random.3 | 116 + static/openbsd/man3/asin.3 | 84 + static/openbsd/man3/asinh.3 | 77 + static/openbsd/man3/asr_run.3 | 335 ++ static/openbsd/man3/atan.3 | 74 + static/openbsd/man3/atan2.3 | 99 + static/openbsd/man3/atanh.3 | 82 + static/openbsd/man3/atexit.3 | 97 + static/openbsd/man3/atof.3 | 81 + static/openbsd/man3/atoi.3 | 89 + static/openbsd/man3/atol.3 | 68 + static/openbsd/man3/atoll.3 | 68 + static/openbsd/man3/auth_subr.3 | 538 +++ static/openbsd/man3/authenticate.3 | 308 ++ static/openbsd/man3/authnone_create.3 | 130 + static/openbsd/man3/backtrace.3 | 151 + static/openbsd/man3/basename.3 | 93 + static/openbsd/man3/bcmp.3 | 67 + static/openbsd/man3/bcopy.3 | 67 + static/openbsd/man3/bcrypt_pbkdf.3 | 70 + static/openbsd/man3/bindresvport.3 | 142 + static/openbsd/man3/blowfish.3 | 103 + static/openbsd/man3/bsearch.3 | 84 + static/openbsd/man3/btowc.3 | 87 + static/openbsd/man3/btree.3 | 241 ++ static/openbsd/man3/bzero.3 | 92 + static/openbsd/man3/c16rtomb.3 | 207 + static/openbsd/man3/cacheflush.3 | 82 + static/openbsd/man3/cacos.3 | 68 + static/openbsd/man3/cacosh.3 | 69 + static/openbsd/man3/carg.3 | 60 + static/openbsd/man3/casin.3 | 68 + static/openbsd/man3/casinh.3 | 69 + static/openbsd/man3/catan.3 | 70 + static/openbsd/man3/catanh.3 | 69 + static/openbsd/man3/catclose.3 | 28 + static/openbsd/man3/catgets.3 | 42 + static/openbsd/man3/catopen.3 | 62 + static/openbsd/man3/ccos.3 | 67 + static/openbsd/man3/ccosh.3 | 67 + static/openbsd/man3/ceil.3 | 72 + static/openbsd/man3/cexp.3 | 67 + static/openbsd/man3/cgetent.3 | 595 +++ static/openbsd/man3/check_expire.3 | 63 + static/openbsd/man3/cimag.3 | 60 + static/openbsd/man3/clock.3 | 61 + static/openbsd/man3/clock_getcpuclockid.3 | 65 + static/openbsd/man3/clog.3 | 74 + static/openbsd/man3/compress.3 | 4032 ++++++++++++++++++++ static/openbsd/man3/confstr.3 | 205 + static/openbsd/man3/conj.3 | 60 + static/openbsd/man3/copysign.3 | 77 + static/openbsd/man3/cos.3 | 90 + static/openbsd/man3/cosh.3 | 85 + static/openbsd/man3/cpow.3 | 65 + static/openbsd/man3/cproj.3 | 68 + static/openbsd/man3/creal.3 | 59 + static/openbsd/man3/creat.3 | 64 + static/openbsd/man3/crypt.3 | 144 + static/openbsd/man3/crypt_checkpass.3 | 113 + static/openbsd/man3/crypto.3 | 419 ++ static/openbsd/man3/csh.3 | 650 ++++ static/openbsd/man3/csin.3 | 67 + static/openbsd/man3/csinh.3 | 66 + static/openbsd/man3/csqrt.3 | 73 + static/openbsd/man3/ctan.3 | 73 + static/openbsd/man3/ctanh.3 | 67 + static/openbsd/man3/ctermid.3 | 77 + static/openbsd/man3/ctime.3 | 421 ++ static/openbsd/man3/curs_add_wch.3 | 357 ++ static/openbsd/man3/curs_add_wchstr.3 | 124 + static/openbsd/man3/curs_addch.3 | 323 ++ static/openbsd/man3/curs_addchstr.3 | 119 + static/openbsd/man3/curs_addstr.3 | 121 + static/openbsd/man3/curs_addwstr.3 | 117 + static/openbsd/man3/curs_attr.3 | 617 +++ static/openbsd/man3/curs_beep.3 | 63 + static/openbsd/man3/curs_bkgd.3 | 164 + static/openbsd/man3/curs_bkgrnd.3 | 119 + static/openbsd/man3/curs_border.3 | 164 + static/openbsd/man3/curs_border_set.3 | 207 + static/openbsd/man3/curs_clear.3 | 136 + static/openbsd/man3/curs_color.3 | 542 +++ static/openbsd/man3/curs_delch.3 | 77 + static/openbsd/man3/curs_deleteln.3 | 94 + static/openbsd/man3/curs_extend.3 | 96 + static/openbsd/man3/curs_get_wch.3 | 195 + static/openbsd/man3/curs_get_wstr.3 | 226 ++ static/openbsd/man3/curs_getcchar.3 | 196 + static/openbsd/man3/curs_getch.3 | 419 ++ static/openbsd/man3/curs_getstr.3 | 292 ++ static/openbsd/man3/curs_getyx.3 | 102 + static/openbsd/man3/curs_in_wch.3 | 72 + static/openbsd/man3/curs_in_wchstr.3 | 127 + static/openbsd/man3/curs_inch.3 | 120 + static/openbsd/man3/curs_inchstr.3 | 115 + static/openbsd/man3/curs_initscr.3 | 310 ++ static/openbsd/man3/curs_inopts.3 | 415 ++ static/openbsd/man3/curs_ins_wch.3 | 69 + static/openbsd/man3/curs_ins_wstr.3 | 112 + static/openbsd/man3/curs_insch.3 | 80 + static/openbsd/man3/curs_insstr.3 | 106 + static/openbsd/man3/curs_instr.3 | 100 + static/openbsd/man3/curs_inwstr.3 | 105 + static/openbsd/man3/curs_kernel.3 | 225 ++ static/openbsd/man3/curs_legacy.3 | 109 + static/openbsd/man3/curs_memleaks.3 | 127 + static/openbsd/man3/curs_mouse.3 | 418 ++ static/openbsd/man3/curs_move.3 | 67 + static/openbsd/man3/curs_opaque.3 | 156 + static/openbsd/man3/curs_outopts.3 | 215 ++ static/openbsd/man3/curs_overlay.3 | 89 + static/openbsd/man3/curs_pad.3 | 240 ++ static/openbsd/man3/curs_print.3 | 74 + static/openbsd/man3/curs_printw.3 | 156 + static/openbsd/man3/curs_refresh.3 | 164 + static/openbsd/man3/curs_scanw.3 | 171 + static/openbsd/man3/curs_scr_dump.3 | 117 + static/openbsd/man3/curs_scroll.3 | 96 + static/openbsd/man3/curs_slk.3 | 354 ++ static/openbsd/man3/curs_sp_funcs.3 | 286 ++ static/openbsd/man3/curs_termattrs.3 | 137 + static/openbsd/man3/curs_threads.3 | 604 +++ static/openbsd/man3/curs_touch.3 | 129 + static/openbsd/man3/curs_util.3 | 411 ++ static/openbsd/man3/curs_variables.3 | 188 + static/openbsd/man3/curs_window.3 | 275 ++ static/openbsd/man3/curses.3 | 1537 ++++++++ static/openbsd/man3/d2i_ASN1_NULL.3 | 93 + static/openbsd/man3/d2i_ASN1_OBJECT.3 | 165 + static/openbsd/man3/d2i_ASN1_OCTET_STRING.3 | 462 +++ static/openbsd/man3/d2i_ASN1_SEQUENCE_ANY.3 | 99 + static/openbsd/man3/d2i_AUTHORITY_KEYID.3 | 76 + static/openbsd/man3/d2i_BASIC_CONSTRAINTS.3 | 107 + static/openbsd/man3/d2i_CMS_ContentInfo.3 | 129 + static/openbsd/man3/d2i_DHparams.3 | 100 + static/openbsd/man3/d2i_DIST_POINT.3 | 202 + static/openbsd/man3/d2i_DSAPublicKey.3 | 413 ++ static/openbsd/man3/d2i_ECPKParameters.3 | 467 +++ static/openbsd/man3/d2i_ESS_SIGNING_CERT.3 | 119 + static/openbsd/man3/d2i_GENERAL_NAME.3 | 161 + static/openbsd/man3/d2i_OCSP_REQUEST.3 | 182 + static/openbsd/man3/d2i_OCSP_RESPONSE.3 | 249 ++ static/openbsd/man3/d2i_PKCS12.3 | 203 + static/openbsd/man3/d2i_PKCS7.3 | 342 ++ static/openbsd/man3/d2i_PKCS8PrivateKey_bio.3 | 173 + static/openbsd/man3/d2i_PKCS8_PRIV_KEY_INFO.3 | 128 + static/openbsd/man3/d2i_PKEY_USAGE_PERIOD.3 | 75 + static/openbsd/man3/d2i_POLICYINFO.3 | 166 + static/openbsd/man3/d2i_PrivateKey.3 | 313 ++ static/openbsd/man3/d2i_RSAPublicKey.3 | 390 ++ static/openbsd/man3/d2i_SSL_SESSION.3 | 182 + static/openbsd/man3/d2i_TS_REQ.3 | 334 ++ static/openbsd/man3/d2i_X509.3 | 363 ++ static/openbsd/man3/d2i_X509_ALGOR.3 | 90 + static/openbsd/man3/d2i_X509_ATTRIBUTE.3 | 77 + static/openbsd/man3/d2i_X509_CRL.3 | 149 + static/openbsd/man3/d2i_X509_EXTENSION.3 | 105 + static/openbsd/man3/d2i_X509_NAME.3 | 214 ++ static/openbsd/man3/d2i_X509_REQ.3 | 152 + static/openbsd/man3/d2i_X509_SIG.3 | 160 + static/openbsd/man3/daemon.3 | 100 + static/openbsd/man3/dbopen.3 | 538 +++ static/openbsd/man3/default_colors.3 | 147 + static/openbsd/man3/define_key.3 | 68 + static/openbsd/man3/des_read_pw.3 | 198 + static/openbsd/man3/devname.3 | 66 + static/openbsd/man3/dirname.3 | 93 + static/openbsd/man3/div.3 | 63 + static/openbsd/man3/ecvt.3 | 166 + static/openbsd/man3/eddsa_pk_new.3 | 123 + static/openbsd/man3/editline.3 | 986 +++++ static/openbsd/man3/elf.3 | 625 +++ static/openbsd/man3/elf_aux_info.3 | 74 + static/openbsd/man3/elf_begin.3 | 314 ++ static/openbsd/man3/elf_cntl.3 | 110 + static/openbsd/man3/elf_end.3 | 75 + static/openbsd/man3/elf_errmsg.3 | 106 + static/openbsd/man3/elf_fill.3 | 51 + static/openbsd/man3/elf_flagdata.3 | 226 ++ static/openbsd/man3/elf_getarhdr.3 | 96 + static/openbsd/man3/elf_getarsym.3 | 129 + static/openbsd/man3/elf_getbase.3 | 70 + static/openbsd/man3/elf_getdata.3 | 233 ++ static/openbsd/man3/elf_getident.3 | 82 + static/openbsd/man3/elf_getphdrnum.3 | 84 + static/openbsd/man3/elf_getphnum.3 | 91 + static/openbsd/man3/elf_getscn.3 | 154 + static/openbsd/man3/elf_getshdrnum.3 | 76 + static/openbsd/man3/elf_getshdrstrndx.3 | 77 + static/openbsd/man3/elf_getshnum.3 | 82 + static/openbsd/man3/elf_getshstrndx.3 | 93 + static/openbsd/man3/elf_hash.3 | 56 + static/openbsd/man3/elf_kind.3 | 70 + static/openbsd/man3/elf_memory.3 | 121 + static/openbsd/man3/elf_next.3 | 98 + static/openbsd/man3/elf_open.3 | 125 + static/openbsd/man3/elf_rand.3 | 117 + static/openbsd/man3/elf_rawfile.3 | 75 + static/openbsd/man3/elf_strptr.3 | 115 + static/openbsd/man3/elf_update.3 | 381 ++ static/openbsd/man3/elf_version.3 | 94 + static/openbsd/man3/erf.3 | 105 + static/openbsd/man3/err.3 | 153 + static/openbsd/man3/es256_pk_new.3 | 141 + static/openbsd/man3/ether_aton.3 | 114 + static/openbsd/man3/evbuffer_new.3 | 280 ++ static/openbsd/man3/event.3 | 596 +++ static/openbsd/man3/event_base_loop.3 | 192 + static/openbsd/man3/event_base_new.3 | 322 ++ static/openbsd/man3/event_set.3 | 419 ++ static/openbsd/man3/event_set_log_callback.3 | 138 + static/openbsd/man3/evp.3 | 250 ++ static/openbsd/man3/execv.3 | 264 ++ static/openbsd/man3/exit.3 | 101 + static/openbsd/man3/exp.3 | 351 ++ static/openbsd/man3/fabs.3 | 84 + static/openbsd/man3/fclose.3 | 141 + static/openbsd/man3/fdim.3 | 86 + static/openbsd/man3/feclearexcept.3 | 171 + static/openbsd/man3/feenableexcept.3 | 87 + static/openbsd/man3/fegetenv.3 | 128 + static/openbsd/man3/fegetround.3 | 82 + static/openbsd/man3/ferror.3 | 111 + static/openbsd/man3/fflush.3 | 132 + static/openbsd/man3/ffs.3 | 82 + static/openbsd/man3/fgetln.3 | 151 + static/openbsd/man3/fgets.3 | 201 + static/openbsd/man3/fgetwln.3 | 115 + static/openbsd/man3/fgetws.3 | 122 + static/openbsd/man3/fido_assert_allow_cred.3 | 48 + static/openbsd/man3/fido_assert_new.3 | 259 ++ static/openbsd/man3/fido_assert_set_authdata.3 | 239 ++ static/openbsd/man3/fido_assert_verify.3 | 80 + static/openbsd/man3/fido_bio_dev_get_info.3 | 123 + static/openbsd/man3/fido_bio_enroll_new.3 | 96 + static/openbsd/man3/fido_bio_info_new.3 | 82 + static/openbsd/man3/fido_bio_template.3 | 180 + static/openbsd/man3/fido_cbor_info_new.3 | 242 ++ static/openbsd/man3/fido_cred_exclude.3 | 61 + static/openbsd/man3/fido_cred_new.3 | 294 ++ static/openbsd/man3/fido_cred_set_authdata.3 | 355 ++ static/openbsd/man3/fido_cred_verify.3 | 92 + static/openbsd/man3/fido_credman_metadata_new.3 | 327 ++ static/openbsd/man3/fido_dev_enable_entattest.3 | 122 + static/openbsd/man3/fido_dev_get_assert.3 | 77 + static/openbsd/man3/fido_dev_get_touch_begin.3 | 74 + static/openbsd/man3/fido_dev_info_manifest.3 | 189 + static/openbsd/man3/fido_dev_largeblob_get.3 | 195 + static/openbsd/man3/fido_dev_make_cred.3 | 78 + static/openbsd/man3/fido_dev_open.3 | 294 ++ static/openbsd/man3/fido_dev_set_io_functions.3 | 239 ++ static/openbsd/man3/fido_dev_set_pin.3 | 104 + static/openbsd/man3/fido_init.3 | 73 + static/openbsd/man3/fido_strerr.3 | 28 + static/openbsd/man3/flockfile.3 | 74 + static/openbsd/man3/floor.3 | 77 + static/openbsd/man3/fma.3 | 59 + static/openbsd/man3/fmax.3 | 97 + static/openbsd/man3/fmemopen.3 | 198 + static/openbsd/man3/fmod.3 | 95 + static/openbsd/man3/fmt_scaled.3 | 135 + static/openbsd/man3/fn.3 | 13 + static/openbsd/man3/fnmatch.3 | 157 + static/openbsd/man3/fopen.3 | 300 ++ static/openbsd/man3/form.3 | 245 ++ static/openbsd/man3/form_cursor.3 | 73 + static/openbsd/man3/form_data.3 | 63 + static/openbsd/man3/form_driver.3 | 269 ++ static/openbsd/man3/form_field.3 | 95 + static/openbsd/man3/form_field_attributes.3 | 97 + static/openbsd/man3/form_field_buffer.3 | 145 + static/openbsd/man3/form_field_info.3 | 94 + static/openbsd/man3/form_field_just.3 | 80 + static/openbsd/man3/form_field_new.3 | 109 + static/openbsd/man3/form_field_opts.3 | 151 + static/openbsd/man3/form_field_userptr.3 | 68 + static/openbsd/man3/form_field_validation.3 | 234 ++ static/openbsd/man3/form_fieldtype.3 | 168 + static/openbsd/man3/form_hook.3 | 102 + static/openbsd/man3/form_new.3 | 87 + static/openbsd/man3/form_new_page.3 | 76 + static/openbsd/man3/form_opts.3 | 90 + static/openbsd/man3/form_page.3 | 102 + static/openbsd/man3/form_post.3 | 90 + static/openbsd/man3/form_requestname.3 | 71 + static/openbsd/man3/form_userptr.3 | 67 + static/openbsd/man3/form_variables.3 | 81 + static/openbsd/man3/form_win.3 | 97 + static/openbsd/man3/fparseln.3 | 140 + static/openbsd/man3/fpclassify.3 | 157 + static/openbsd/man3/fpgetmask.3 | 122 + static/openbsd/man3/fputs.3 | 107 + static/openbsd/man3/fputws.3 | 89 + static/openbsd/man3/fread.3 | 126 + static/openbsd/man3/frexp.3 | 96 + static/openbsd/man3/fseek.3 | 259 ++ static/openbsd/man3/ftok.3 | 86 + static/openbsd/man3/fts_open.3 | 757 ++++ static/openbsd/man3/ftw.3 | 212 + static/openbsd/man3/funopen.3 | 156 + static/openbsd/man3/fuse_chan_fd.3 | 56 + static/openbsd/man3/fuse_daemonize.3 | 62 + static/openbsd/man3/fuse_destroy.3 | 57 + static/openbsd/man3/fuse_get_context.3 | 59 + static/openbsd/man3/fuse_get_session.3 | 45 + static/openbsd/man3/fuse_loop.3 | 91 + static/openbsd/man3/fuse_lowlevel_new.3 | 610 +++ static/openbsd/man3/fuse_main.3 | 153 + static/openbsd/man3/fuse_mount.3 | 125 + static/openbsd/man3/fuse_new.3 | 249 ++ static/openbsd/man3/fuse_opt.3 | 430 +++ static/openbsd/man3/fuse_parse_cmdline.3 | 101 + static/openbsd/man3/fuse_reply_err.3 | 203 + static/openbsd/man3/fuse_session_loop.3 | 120 + static/openbsd/man3/fuse_set_signal_handlers.3 | 68 + static/openbsd/man3/fuse_setup.3 | 97 + static/openbsd/man3/fuse_teardown.3 | 55 + static/openbsd/man3/fuse_version.3 | 43 + static/openbsd/man3/fwide.3 | 94 + static/openbsd/man3/gai_strerror.3 | 95 + static/openbsd/man3/gelf.3 | 204 + static/openbsd/man3/gelf_checksum.3 | 114 + static/openbsd/man3/gelf_fsize.3 | 95 + static/openbsd/man3/gelf_getcap.3 | 126 + static/openbsd/man3/gelf_getclass.3 | 60 + static/openbsd/man3/gelf_getdyn.3 | 129 + static/openbsd/man3/gelf_getehdr.3 | 122 + static/openbsd/man3/gelf_getmove.3 | 125 + static/openbsd/man3/gelf_getphdr.3 | 140 + static/openbsd/man3/gelf_getrel.3 | 126 + static/openbsd/man3/gelf_getrela.3 | 126 + static/openbsd/man3/gelf_getshdr.3 | 114 + static/openbsd/man3/gelf_getsym.3 | 130 + static/openbsd/man3/gelf_getsyminfo.3 | 120 + static/openbsd/man3/gelf_getsymshndx.3 | 169 + static/openbsd/man3/gelf_newehdr.3 | 196 + static/openbsd/man3/gelf_newphdr.3 | 143 + static/openbsd/man3/gelf_update_ehdr.3 | 122 + static/openbsd/man3/gelf_xlatetof.3 | 279 ++ static/openbsd/man3/get_fpc_csr.3 | 63 + static/openbsd/man3/getaddrinfo.3 | 481 +++ static/openbsd/man3/getbsize.3 | 76 + static/openbsd/man3/getc.3 | 171 + static/openbsd/man3/getcwd.3 | 190 + static/openbsd/man3/getdelim.3 | 171 + static/openbsd/man3/getdiskbyname.3 | 59 + static/openbsd/man3/getdomainname.3 | 104 + static/openbsd/man3/getdtablesize.3 | 62 + static/openbsd/man3/getenv.3 | 191 + static/openbsd/man3/getfsent.3 | 136 + static/openbsd/man3/getgrent.3 | 303 ++ static/openbsd/man3/getgrouplist.3 | 102 + static/openbsd/man3/gethostbyname.3 | 271 ++ static/openbsd/man3/gethostid.3 | 73 + static/openbsd/man3/gethostname.3 | 120 + static/openbsd/man3/getifaddrs.3 | 157 + static/openbsd/man3/getloadavg.3 | 68 + static/openbsd/man3/getmaxpartitions.3 | 53 + static/openbsd/man3/getmntinfo.3 | 102 + static/openbsd/man3/getnameinfo.3 | 264 ++ static/openbsd/man3/getnetent.3 | 147 + static/openbsd/man3/getnetgrent.3 | 127 + static/openbsd/man3/getopt.3 | 365 ++ static/openbsd/man3/getopt_long.3 | 460 +++ static/openbsd/man3/getpagesize.3 | 56 + static/openbsd/man3/getpass.3 | 131 + static/openbsd/man3/getpeereid.3 | 121 + static/openbsd/man3/getprogname.3 | 81 + static/openbsd/man3/getprotoent.3 | 213 ++ static/openbsd/man3/getpwent.3 | 190 + static/openbsd/man3/getpwnam.3 | 291 ++ static/openbsd/man3/getrawpartition.3 | 62 + static/openbsd/man3/getrpcent.3 | 122 + static/openbsd/man3/getrpcport.3 | 61 + static/openbsd/man3/getrrsetbyname.3 | 164 + static/openbsd/man3/getservent.3 | 220 ++ static/openbsd/man3/getsubopt.3 | 162 + static/openbsd/man3/getttyent.3 | 179 + static/openbsd/man3/getusershell.3 | 94 + static/openbsd/man3/getwc.3 | 113 + static/openbsd/man3/glob.3 | 499 +++ static/openbsd/man3/hash.3 | 160 + static/openbsd/man3/hcreate.3 | 234 ++ static/openbsd/man3/history.3 | 640 ++++ static/openbsd/man3/htobe64.3 | 164 + static/openbsd/man3/htonl.3 | 102 + static/openbsd/man3/hypot.3 | 124 + static/openbsd/man3/i2a_ASN1_STRING.3 | 256 ++ static/openbsd/man3/i2d_CMS_bio_stream.3 | 96 + static/openbsd/man3/i2d_PKCS7_bio_stream.3 | 95 + static/openbsd/man3/ibuf_add.3 | 722 ++++ static/openbsd/man3/icdb_new.3 | 68 + static/openbsd/man3/if_indextoname.3 | 143 + static/openbsd/man3/ilogb.3 | 88 + static/openbsd/man3/imaxabs.3 | 70 + static/openbsd/man3/imaxdiv.3 | 65 + static/openbsd/man3/imsg_init.3 | 515 +++ static/openbsd/man3/in.3 | 9 + static/openbsd/man3/inet6_opt_init.3 | 328 ++ static/openbsd/man3/inet6_rth_space.3 | 220 ++ static/openbsd/man3/inet_addr.3 | 195 + static/openbsd/man3/inet_lnaof.3 | 89 + static/openbsd/man3/inet_net_ntop.3 | 195 + static/openbsd/man3/inet_ntop.3 | 213 ++ static/openbsd/man3/initgroups.3 | 82 + static/openbsd/man3/insque.3 | 103 + static/openbsd/man3/isalnum.3 | 125 + static/openbsd/man3/isalpha.3 | 126 + static/openbsd/man3/isascii.3 | 77 + static/openbsd/man3/isblank.3 | 123 + static/openbsd/man3/iscntrl.3 | 116 + static/openbsd/man3/isdigit.3 | 116 + static/openbsd/man3/isduid.3 | 62 + static/openbsd/man3/isfdtype.3 | 73 + static/openbsd/man3/isgraph.3 | 122 + static/openbsd/man3/isgreater.3 | 101 + static/openbsd/man3/islower.3 | 125 + static/openbsd/man3/isprint.3 | 122 + static/openbsd/man3/ispunct.3 | 123 + static/openbsd/man3/isspace.3 | 132 + static/openbsd/man3/isupper.3 | 125 + static/openbsd/man3/iswalnum.3 | 166 + static/openbsd/man3/iswctype.3 | 95 + static/openbsd/man3/isxdigit.3 | 117 + static/openbsd/man3/j0.3 | 161 + static/openbsd/man3/key_defined.3 | 60 + static/openbsd/man3/keybound.3 | 63 + static/openbsd/man3/keynote.3 | 939 +++++ static/openbsd/man3/keyok.3 | 62 + static/openbsd/man3/killpg.3 | 97 + static/openbsd/man3/kvm.3 | 109 + static/openbsd/man3/kvm_dump.3 | 104 + static/openbsd/man3/kvm_geterr.3 | 75 + static/openbsd/man3/kvm_getfiles.3 | 147 + static/openbsd/man3/kvm_getloadavg.3 | 64 + static/openbsd/man3/kvm_getprocs.3 | 188 + static/openbsd/man3/kvm_nlist.3 | 92 + static/openbsd/man3/kvm_open.3 | 203 + static/openbsd/man3/kvm_read.3 | 88 + static/openbsd/man3/labs.3 | 88 + static/openbsd/man3/ldexp.3 | 90 + static/openbsd/man3/ldiv.3 | 71 + static/openbsd/man3/legacy_coding.3 | 75 + static/openbsd/man3/lgamma.3 | 194 + static/openbsd/man3/lh_new.3 | 555 +++ static/openbsd/man3/link_ntoa.3 | 78 + static/openbsd/man3/lldiv.3 | 73 + static/openbsd/man3/localeconv.3 | 198 + static/openbsd/man3/lockf.3 | 259 ++ static/openbsd/man3/logb.3 | 117 + static/openbsd/man3/login.3 | 107 + static/openbsd/man3/login_cap.3 | 342 ++ static/openbsd/man3/login_fbtab.3 | 54 + static/openbsd/man3/lrint.3 | 113 + static/openbsd/man3/lround.3 | 100 + static/openbsd/man3/lsearch.3 | 106 + static/openbsd/man3/malloc.3 | 860 +++++ static/openbsd/man3/mblen.3 | 177 + static/openbsd/man3/mbrlen.3 | 212 + static/openbsd/man3/mbrtoc16.3 | 265 ++ static/openbsd/man3/mbrtowc.3 | 332 ++ static/openbsd/man3/mbsinit.3 | 78 + static/openbsd/man3/mbsrtowcs.3 | 198 + static/openbsd/man3/mbstowcs.3 | 126 + static/openbsd/man3/mbtowc.3 | 249 ++ static/openbsd/man3/memccpy.3 | 81 + static/openbsd/man3/memchr.3 | 102 + static/openbsd/man3/memcmp.3 | 86 + static/openbsd/man3/memcpy.3 | 79 + static/openbsd/man3/memmem.3 | 77 + static/openbsd/man3/memmove.3 | 76 + static/openbsd/man3/memset.3 | 75 + static/openbsd/man3/menu.3 | 214 ++ static/openbsd/man3/menu_attributes.3 | 114 + static/openbsd/man3/menu_cursor.3 | 71 + static/openbsd/man3/menu_driver.3 | 207 + static/openbsd/man3/menu_format.3 | 89 + static/openbsd/man3/menu_hook.3 | 103 + static/openbsd/man3/menu_items.3 | 92 + static/openbsd/man3/menu_mark.3 | 85 + static/openbsd/man3/menu_new.3 | 84 + static/openbsd/man3/menu_opts.3 | 110 + static/openbsd/man3/menu_pattern.3 | 93 + static/openbsd/man3/menu_post.3 | 92 + static/openbsd/man3/menu_requestname.3 | 70 + static/openbsd/man3/menu_spacing.3 | 93 + static/openbsd/man3/menu_userptr.3 | 67 + static/openbsd/man3/menu_win.3 | 97 + static/openbsd/man3/mio_open.3 | 255 ++ static/openbsd/man3/mitem_current.3 | 102 + static/openbsd/man3/mitem_name.3 | 62 + static/openbsd/man3/mitem_new.3 | 92 + static/openbsd/man3/mitem_opts.3 | 85 + static/openbsd/man3/mitem_userptr.3 | 69 + static/openbsd/man3/mitem_value.3 | 74 + static/openbsd/man3/mitem_visible.3 | 56 + static/openbsd/man3/mktemp.3 | 431 +++ static/openbsd/man3/modf.3 | 85 + static/openbsd/man3/moncontrol.3 | 86 + static/openbsd/man3/nan.3 | 97 + static/openbsd/man3/ndbm.3 | 209 + static/openbsd/man3/new_pair.3 | 165 + static/openbsd/man3/newlocale.3 | 175 + static/openbsd/man3/nextafter.3 | 82 + static/openbsd/man3/nice.3 | 92 + static/openbsd/man3/nl_langinfo.3 | 78 + static/openbsd/man3/nlist.3 | 76 + static/openbsd/man3/ober_add_string.3 | 238 ++ static/openbsd/man3/ober_get_string.3 | 191 + static/openbsd/man3/ober_oid_cmp.3 | 99 + static/openbsd/man3/ober_read_elements.3 | 244 ++ static/openbsd/man3/ober_set_header.3 | 160 + static/openbsd/man3/ohash_init.3 | 272 ++ static/openbsd/man3/ohash_interval.3 | 94 + static/openbsd/man3/open_memstream.3 | 107 + static/openbsd/man3/opendev.3 | 114 + static/openbsd/man3/opendir.3 | 316 ++ static/openbsd/man3/opendisk.3 | 160 + static/openbsd/man3/openpty.3 | 219 ++ static/openbsd/man3/ossaudio.3 | 74 + static/openbsd/man3/panel.3 | 278 ++ static/openbsd/man3/pause.3 | 86 + static/openbsd/man3/pcap_open_live.3 | 667 ++++ static/openbsd/man3/perror.3 | 88 + static/openbsd/man3/pidfile.3 | 83 + static/openbsd/man3/pkcs5_pbkdf2.3 | 64 + static/openbsd/man3/popen.3 | 195 + static/openbsd/man3/posix_memalign.3 | 97 + static/openbsd/man3/posix_openpt.3 | 102 + static/openbsd/man3/posix_spawn.3 | 135 + .../man3/posix_spawn_file_actions_addopen.3 | 106 + .../openbsd/man3/posix_spawn_file_actions_init.3 | 57 + static/openbsd/man3/posix_spawnattr_getflags.3 | 98 + static/openbsd/man3/posix_spawnattr_getpgroup.3 | 80 + static/openbsd/man3/posix_spawnattr_init.3 | 75 + static/openbsd/man3/printf.3 | 1033 +++++ static/openbsd/man3/psignal.3 | 99 + static/openbsd/man3/pthread_atfork.3 | 90 + static/openbsd/man3/pthread_attr_init.3 | 81 + static/openbsd/man3/pthread_attr_setdetachstate.3 | 106 + static/openbsd/man3/pthread_attr_setguardsize.3 | 90 + static/openbsd/man3/pthread_attr_setstack.3 | 107 + static/openbsd/man3/pthread_attr_setstackaddr.3 | 83 + static/openbsd/man3/pthread_attr_setstacksize.3 | 80 + static/openbsd/man3/pthread_barrier_init.3 | 103 + static/openbsd/man3/pthread_barrier_wait.3 | 59 + .../openbsd/man3/pthread_barrierattr_getpshared.3 | 86 + static/openbsd/man3/pthread_barrierattr_init.3 | 78 + static/openbsd/man3/pthread_cancel.3 | 72 + static/openbsd/man3/pthread_cleanup_pop.3 | 64 + static/openbsd/man3/pthread_cleanup_push.3 | 67 + static/openbsd/man3/pthread_cond_init.3 | 174 + static/openbsd/man3/pthread_condattr_init.3 | 120 + static/openbsd/man3/pthread_create.3 | 126 + static/openbsd/man3/pthread_detach.3 | 90 + static/openbsd/man3/pthread_equal.3 | 69 + static/openbsd/man3/pthread_exit.3 | 106 + static/openbsd/man3/pthread_getconcurrency.3 | 115 + static/openbsd/man3/pthread_getcpuclockid.3 | 62 + static/openbsd/man3/pthread_getspecific.3 | 84 + static/openbsd/man3/pthread_join.3 | 103 + static/openbsd/man3/pthread_key_create.3 | 105 + static/openbsd/man3/pthread_key_delete.3 | 97 + static/openbsd/man3/pthread_kill.3 | 76 + static/openbsd/man3/pthread_main_np.3 | 40 + static/openbsd/man3/pthread_mutex_init.3 | 235 ++ static/openbsd/man3/pthread_mutexattr.3 | 178 + static/openbsd/man3/pthread_once.3 | 103 + static/openbsd/man3/pthread_rwlock_init.3 | 273 ++ static/openbsd/man3/pthread_rwlockattr_destroy.3 | 72 + .../openbsd/man3/pthread_rwlockattr_getpshared.3 | 85 + static/openbsd/man3/pthread_rwlockattr_init.3 | 71 + .../openbsd/man3/pthread_rwlockattr_setpshared.3 | 89 + static/openbsd/man3/pthread_schedparam.3 | 93 + static/openbsd/man3/pthread_self.3 | 62 + static/openbsd/man3/pthread_set_name_np.3 | 59 + static/openbsd/man3/pthread_setspecific.3 | 95 + static/openbsd/man3/pthread_sigmask.3 | 72 + static/openbsd/man3/pthread_spin_init.3 | 89 + static/openbsd/man3/pthread_spin_lock.3 | 84 + static/openbsd/man3/pthread_spin_unlock.3 | 60 + static/openbsd/man3/pthread_stackseg_np.3 | 50 + static/openbsd/man3/pthread_testcancel.3 | 236 ++ static/openbsd/man3/pthread_yield.3 | 28 + static/openbsd/man3/pthreads.3 | 481 +++ static/openbsd/man3/ptsname.3 | 160 + static/openbsd/man3/putc.3 | 177 + static/openbsd/man3/putwc.3 | 102 + static/openbsd/man3/pw_dup.3 | 80 + static/openbsd/man3/pw_init.3 | 219 ++ static/openbsd/man3/pw_lock.3 | 159 + static/openbsd/man3/qsort.3 | 276 ++ static/openbsd/man3/radius_new_request_packet.3 | 387 ++ static/openbsd/man3/radixsort.3 | 151 + static/openbsd/man3/raise.3 | 68 + static/openbsd/man3/rand.3 | 135 + static/openbsd/man3/rand48.3 | 240 ++ static/openbsd/man3/random.3 | 197 + static/openbsd/man3/rcmd.3 | 232 ++ static/openbsd/man3/rcmdsh.3 | 95 + static/openbsd/man3/readlabelfs.3 | 62 + static/openbsd/man3/readline.3 | 1272 ++++++ static/openbsd/man3/readpassphrase.3 | 167 + static/openbsd/man3/realpath.3 | 165 + static/openbsd/man3/recno.3 | 221 ++ static/openbsd/man3/regex.3 | 746 ++++ static/openbsd/man3/remainder.3 | 148 + static/openbsd/man3/remove.3 | 80 + static/openbsd/man3/res_init.3 | 441 +++ static/openbsd/man3/resizeterm.3 | 178 + static/openbsd/man3/rint.3 | 85 + static/openbsd/man3/round.3 | 68 + static/openbsd/man3/rpc.3 | 1231 ++++++ static/openbsd/man3/rs256_pk_new.3 | 137 + static/openbsd/man3/s2i_ASN1_INTEGER.3 | 216 ++ static/openbsd/man3/scalbn.3 | 102 + static/openbsd/man3/scandir.3 | 172 + static/openbsd/man3/scanf.3 | 479 +++ static/openbsd/man3/sched_get_priority_min.3 | 74 + static/openbsd/man3/sdbm.3 | 295 ++ static/openbsd/man3/sem_destroy.3 | 86 + static/openbsd/man3/sem_getvalue.3 | 77 + static/openbsd/man3/sem_init.3 | 105 + static/openbsd/man3/sem_open.3 | 94 + static/openbsd/man3/sem_post.3 | 74 + static/openbsd/man3/sem_wait.3 | 133 + static/openbsd/man3/setbuf.3 | 140 + static/openbsd/man3/setjmp.3 | 211 + static/openbsd/man3/setlocale.3 | 326 ++ static/openbsd/man3/setmode.3 | 108 + static/openbsd/man3/setproctitle.3 | 94 + static/openbsd/man3/setvbuf.3 | 161 + static/openbsd/man3/shm_open.3 | 105 + static/openbsd/man3/sigaddset.3 | 116 + static/openbsd/man3/sigblock.3 | 122 + static/openbsd/man3/siginterrupt.3 | 91 + static/openbsd/man3/signal.3 | 513 +++ static/openbsd/man3/sigpause.3 | 77 + static/openbsd/man3/sigsetmask.3 | 141 + static/openbsd/man3/sigvec.3 | 331 ++ static/openbsd/man3/sigwait.3 | 76 + static/openbsd/man3/sin.3 | 90 + static/openbsd/man3/sincos.3 | 79 + static/openbsd/man3/sinh.3 | 93 + static/openbsd/man3/sio_open.3 | 872 +++++ static/openbsd/man3/sioctl_open.3 | 324 ++ static/openbsd/man3/skey.3 | 387 ++ static/openbsd/man3/sleep.3 | 103 + static/openbsd/man3/sockatmark.3 | 122 + static/openbsd/man3/sqrt.3 | 105 + static/openbsd/man3/ssl.3 | 353 ++ static/openbsd/man3/statvfs.3 | 148 + static/openbsd/man3/stdio.3 | 308 ++ static/openbsd/man3/stpcpy.3 | 184 + static/openbsd/man3/strcasecmp.3 | 128 + static/openbsd/man3/strcat.3 | 76 + static/openbsd/man3/strchr.3 | 116 + static/openbsd/man3/strcmp.3 | 95 + static/openbsd/man3/strcoll.3 | 103 + static/openbsd/man3/strcpy.3 | 82 + static/openbsd/man3/strcspn.3 | 108 + static/openbsd/man3/strdup.3 | 119 + static/openbsd/man3/strerror.3 | 154 + static/openbsd/man3/strftime.3 | 329 ++ static/openbsd/man3/strlcpy.3 | 195 + static/openbsd/man3/strlen.3 | 103 + static/openbsd/man3/strmode.3 | 153 + static/openbsd/man3/strncat.3 | 132 + static/openbsd/man3/strncpy.3 | 138 + static/openbsd/man3/strpbrk.3 | 80 + static/openbsd/man3/strptime.3 | 333 ++ static/openbsd/man3/strrchr.3 | 118 + static/openbsd/man3/strsep.3 | 110 + static/openbsd/man3/strsignal.3 | 78 + static/openbsd/man3/strspn.3 | 92 + static/openbsd/man3/strstr.3 | 101 + static/openbsd/man3/strtod.3 | 176 + static/openbsd/man3/strtofflags.3 | 98 + static/openbsd/man3/strtok.3 | 169 + static/openbsd/man3/strtol.3 | 273 ++ static/openbsd/man3/strtonum.3 | 152 + static/openbsd/man3/strtoul.3 | 260 ++ static/openbsd/man3/strxfrm.3 | 105 + static/openbsd/man3/swab.3 | 79 + static/openbsd/man3/sysconf.3 | 222 ++ static/openbsd/man3/syslog.3 | 423 ++ static/openbsd/man3/system.3 | 116 + static/openbsd/man3/tan.3 | 85 + static/openbsd/man3/tanh.3 | 87 + static/openbsd/man3/tcgetpgrp.3 | 74 + static/openbsd/man3/tcgetsid.3 | 77 + static/openbsd/man3/tcsendbreak.3 | 153 + static/openbsd/man3/tcsetattr.3 | 361 ++ static/openbsd/man3/tcsetpgrp.3 | 109 + static/openbsd/man3/term_variables.3 | 193 + static/openbsd/man3/termcap.3 | 389 ++ static/openbsd/man3/terminfo.3 | 784 ++++ static/openbsd/man3/time.3 | 84 + static/openbsd/man3/time2posix.3 | 142 + static/openbsd/man3/times.3 | 144 + static/openbsd/man3/timespec_get.3 | 85 + static/openbsd/man3/timingsafe_bcmp.3 | 87 + static/openbsd/man3/tls_accept_socket.3 | 108 + static/openbsd/man3/tls_client.3 | 111 + .../man3/tls_config_ocsp_require_stapling.3 | 41 + static/openbsd/man3/tls_config_set_protocols.3 | 231 ++ static/openbsd/man3/tls_config_set_session_id.3 | 106 + static/openbsd/man3/tls_config_verify.3 | 80 + static/openbsd/man3/tls_conn_version.3 | 226 ++ static/openbsd/man3/tls_connect.3 | 145 + static/openbsd/man3/tls_init.3 | 181 + static/openbsd/man3/tls_load_file.3 | 370 ++ static/openbsd/man3/tls_ocsp_process_response.3 | 168 + static/openbsd/man3/tls_read.3 | 241 ++ static/openbsd/man3/tmpnam.3 | 228 ++ static/openbsd/man3/toascii.3 | 69 + static/openbsd/man3/tolower.3 | 143 + static/openbsd/man3/toupper.3 | 141 + static/openbsd/man3/towctrans.3 | 97 + static/openbsd/man3/towlower.3 | 121 + static/openbsd/man3/trunc.3 | 75 + static/openbsd/man3/tsearch.3 | 126 + static/openbsd/man3/ttyname.3 | 176 + static/openbsd/man3/tzset.3 | 377 ++ static/openbsd/man3/ualarm.3 | 108 + static/openbsd/man3/uname.3 | 99 + static/openbsd/man3/ungetc.3 | 96 + static/openbsd/man3/ungetwc.3 | 96 + static/openbsd/man3/unvis.3 | 195 + static/openbsd/man3/usbhid.3 | 231 ++ static/openbsd/man3/uselocale.3 | 101 + static/openbsd/man3/user_from_uid.3 | 138 + static/openbsd/man3/usleep.3 | 99 + static/openbsd/man3/utime.3 | 145 + static/openbsd/man3/uu_lock.3 | 179 + static/openbsd/man3/uuid_compare.3 | 210 + static/openbsd/man3/v2i_ASN1_BIT_STRING.3 | 126 + static/openbsd/man3/va.3 | 13 + static/openbsd/man3/valloc.3 | 79 + static/openbsd/man3/vis.3 | 394 ++ static/openbsd/man3/wcrtomb.3 | 186 + static/openbsd/man3/wcscasecmp.3 | 134 + static/openbsd/man3/wcscat.3 | 115 + static/openbsd/man3/wcschr.3 | 85 + static/openbsd/man3/wcscmp.3 | 92 + static/openbsd/man3/wcscoll.3 | 102 + static/openbsd/man3/wcscpy.3 | 129 + static/openbsd/man3/wcscspn.3 | 83 + static/openbsd/man3/wcsdup.3 | 97 + static/openbsd/man3/wcsftime.3 | 32 + static/openbsd/man3/wcslcpy.3 | 160 + static/openbsd/man3/wcslen.3 | 102 + static/openbsd/man3/wcspbrk.3 | 81 + static/openbsd/man3/wcsrchr.3 | 85 + static/openbsd/man3/wcsrtombs.3 | 195 + static/openbsd/man3/wcsspn.3 | 79 + static/openbsd/man3/wcsstr.3 | 88 + static/openbsd/man3/wcstod.3 | 83 + static/openbsd/man3/wcstok.3 | 151 + static/openbsd/man3/wcstol.3 | 88 + static/openbsd/man3/wcstombs.3 | 130 + static/openbsd/man3/wcswidth.3 | 69 + static/openbsd/man3/wcsxfrm.3 | 104 + static/openbsd/man3/wctob.3 | 85 + static/openbsd/man3/wctomb.3 | 131 + static/openbsd/man3/wctrans.3 | 96 + static/openbsd/man3/wctype.3 | 96 + static/openbsd/man3/wcwidth.3 | 59 + static/openbsd/man3/wmemchr.3 | 81 + static/openbsd/man3/wmemcmp.3 | 78 + static/openbsd/man3/wmemcpy.3 | 79 + static/openbsd/man3/wmemmove.3 | 78 + static/openbsd/man3/wmemset.3 | 73 + static/openbsd/man3/wprintf.3 | 629 +++ static/openbsd/man3/wresize.3 | 67 + static/openbsd/man3/wscanf.3 | 448 +++ static/openbsd/man3/x509_verify.3 | 221 ++ static/openbsd/man3/xdr.3 | 567 +++ static/openbsd/man3/yp_bind.3 | 355 ++ 1299 files changed, 239063 insertions(+) create mode 100644 static/openbsd/man3/ACCESS_DESCRIPTION_new.3 create mode 100644 static/openbsd/man3/AES_encrypt.3 create mode 100644 static/openbsd/man3/ASIdentifiers_new.3 create mode 100644 static/openbsd/man3/ASN1_BIT_STRING_set.3 create mode 100644 static/openbsd/man3/ASN1_INTEGER_get.3 create mode 100644 static/openbsd/man3/ASN1_NULL_new.3 create mode 100644 static/openbsd/man3/ASN1_OBJECT_new.3 create mode 100644 static/openbsd/man3/ASN1_PRINTABLE_type.3 create mode 100644 static/openbsd/man3/ASN1_STRING_TABLE_get.3 create mode 100644 static/openbsd/man3/ASN1_STRING_length.3 create mode 100644 static/openbsd/man3/ASN1_STRING_new.3 create mode 100644 static/openbsd/man3/ASN1_STRING_print_ex.3 create mode 100644 static/openbsd/man3/ASN1_TIME_set.3 create mode 100644 static/openbsd/man3/ASN1_TYPE_get.3 create mode 100644 static/openbsd/man3/ASN1_UNIVERSALSTRING_to_string.3 create mode 100644 static/openbsd/man3/ASN1_generate_nconf.3 create mode 100644 static/openbsd/man3/ASN1_get_object.3 create mode 100644 static/openbsd/man3/ASN1_item_d2i.3 create mode 100644 static/openbsd/man3/ASN1_item_digest.3 create mode 100644 static/openbsd/man3/ASN1_item_new.3 create mode 100644 static/openbsd/man3/ASN1_item_pack.3 create mode 100644 static/openbsd/man3/ASN1_item_sign.3 create mode 100644 static/openbsd/man3/ASN1_item_verify.3 create mode 100644 static/openbsd/man3/ASN1_mbstring_copy.3 create mode 100644 static/openbsd/man3/ASN1_parse_dump.3 create mode 100644 static/openbsd/man3/ASN1_put_object.3 create mode 100644 static/openbsd/man3/ASRange_new.3 create mode 100644 static/openbsd/man3/AUTHORITY_KEYID_new.3 create mode 100644 static/openbsd/man3/BASIC_CONSTRAINTS_new.3 create mode 100644 static/openbsd/man3/BF_set_key.3 create mode 100644 static/openbsd/man3/BIO_accept.3 create mode 100644 static/openbsd/man3/BIO_ctrl.3 create mode 100644 static/openbsd/man3/BIO_dump.3 create mode 100644 static/openbsd/man3/BIO_dup_chain.3 create mode 100644 static/openbsd/man3/BIO_f_base64.3 create mode 100644 static/openbsd/man3/BIO_f_buffer.3 create mode 100644 static/openbsd/man3/BIO_f_cipher.3 create mode 100644 static/openbsd/man3/BIO_f_md.3 create mode 100644 static/openbsd/man3/BIO_f_null.3 create mode 100644 static/openbsd/man3/BIO_f_ssl.3 create mode 100644 static/openbsd/man3/BIO_find_type.3 create mode 100644 static/openbsd/man3/BIO_get_data.3 create mode 100644 static/openbsd/man3/BIO_get_ex_new_index.3 create mode 100644 static/openbsd/man3/BIO_meth_new.3 create mode 100644 static/openbsd/man3/BIO_new.3 create mode 100644 static/openbsd/man3/BIO_new_CMS.3 create mode 100644 static/openbsd/man3/BIO_printf.3 create mode 100644 static/openbsd/man3/BIO_push.3 create mode 100644 static/openbsd/man3/BIO_read.3 create mode 100644 static/openbsd/man3/BIO_s_accept.3 create mode 100644 static/openbsd/man3/BIO_s_bio.3 create mode 100644 static/openbsd/man3/BIO_s_connect.3 create mode 100644 static/openbsd/man3/BIO_s_datagram.3 create mode 100644 static/openbsd/man3/BIO_s_fd.3 create mode 100644 static/openbsd/man3/BIO_s_file.3 create mode 100644 static/openbsd/man3/BIO_s_mem.3 create mode 100644 static/openbsd/man3/BIO_s_null.3 create mode 100644 static/openbsd/man3/BIO_s_socket.3 create mode 100644 static/openbsd/man3/BIO_set_callback.3 create mode 100644 static/openbsd/man3/BIO_should_retry.3 create mode 100644 static/openbsd/man3/BN_CTX_new.3 create mode 100644 static/openbsd/man3/BN_CTX_start.3 create mode 100644 static/openbsd/man3/BN_add.3 create mode 100644 static/openbsd/man3/BN_add_word.3 create mode 100644 static/openbsd/man3/BN_bn2bin.3 create mode 100644 static/openbsd/man3/BN_cmp.3 create mode 100644 static/openbsd/man3/BN_copy.3 create mode 100644 static/openbsd/man3/BN_generate_prime.3 create mode 100644 static/openbsd/man3/BN_get_rfc3526_prime_8192.3 create mode 100644 static/openbsd/man3/BN_kronecker.3 create mode 100644 static/openbsd/man3/BN_mod_inverse.3 create mode 100644 static/openbsd/man3/BN_mod_mul_montgomery.3 create mode 100644 static/openbsd/man3/BN_mod_sqrt.3 create mode 100644 static/openbsd/man3/BN_new.3 create mode 100644 static/openbsd/man3/BN_num_bytes.3 create mode 100644 static/openbsd/man3/BN_rand.3 create mode 100644 static/openbsd/man3/BN_set_bit.3 create mode 100644 static/openbsd/man3/BN_set_flags.3 create mode 100644 static/openbsd/man3/BN_set_negative.3 create mode 100644 static/openbsd/man3/BN_swap.3 create mode 100644 static/openbsd/man3/BN_zero.3 create mode 100644 static/openbsd/man3/BUF_MEM_new.3 create mode 100644 static/openbsd/man3/CMAC_Init.3 create mode 100644 static/openbsd/man3/CMS_ContentInfo_new.3 create mode 100644 static/openbsd/man3/CMS_add0_cert.3 create mode 100644 static/openbsd/man3/CMS_add1_recipient_cert.3 create mode 100644 static/openbsd/man3/CMS_add1_signer.3 create mode 100644 static/openbsd/man3/CMS_compress.3 create mode 100644 static/openbsd/man3/CMS_decrypt.3 create mode 100644 static/openbsd/man3/CMS_encrypt.3 create mode 100644 static/openbsd/man3/CMS_final.3 create mode 100644 static/openbsd/man3/CMS_get0_RecipientInfos.3 create mode 100644 static/openbsd/man3/CMS_get0_SignerInfos.3 create mode 100644 static/openbsd/man3/CMS_get0_type.3 create mode 100644 static/openbsd/man3/CMS_get1_ReceiptRequest.3 create mode 100644 static/openbsd/man3/CMS_sign.3 create mode 100644 static/openbsd/man3/CMS_sign_receipt.3 create mode 100644 static/openbsd/man3/CMS_signed_add1_attr.3 create mode 100644 static/openbsd/man3/CMS_uncompress.3 create mode 100644 static/openbsd/man3/CMS_verify.3 create mode 100644 static/openbsd/man3/CMS_verify_receipt.3 create mode 100644 static/openbsd/man3/CONF_modules_free.3 create mode 100644 static/openbsd/man3/CONF_modules_load_file.3 create mode 100644 static/openbsd/man3/CRYPTO_lock.3 create mode 100644 static/openbsd/man3/CRYPTO_memcmp.3 create mode 100644 static/openbsd/man3/CRYPTO_set_ex_data.3 create mode 100644 static/openbsd/man3/CRYPTO_set_mem_functions.3 create mode 100644 static/openbsd/man3/ChaCha.3 create mode 100644 static/openbsd/man3/DES_set_key.3 create mode 100644 static/openbsd/man3/DH_generate_key.3 create mode 100644 static/openbsd/man3/DH_generate_parameters.3 create mode 100644 static/openbsd/man3/DH_get0_pqg.3 create mode 100644 static/openbsd/man3/DH_get_ex_new_index.3 create mode 100644 static/openbsd/man3/DH_new.3 create mode 100644 static/openbsd/man3/DH_set_method.3 create mode 100644 static/openbsd/man3/DH_size.3 create mode 100644 static/openbsd/man3/DIST_POINT_new.3 create mode 100644 static/openbsd/man3/DSA_SIG_new.3 create mode 100644 static/openbsd/man3/DSA_do_sign.3 create mode 100644 static/openbsd/man3/DSA_dup_DH.3 create mode 100644 static/openbsd/man3/DSA_generate_key.3 create mode 100644 static/openbsd/man3/DSA_generate_parameters_ex.3 create mode 100644 static/openbsd/man3/DSA_get0_pqg.3 create mode 100644 static/openbsd/man3/DSA_get_ex_new_index.3 create mode 100644 static/openbsd/man3/DSA_meth_new.3 create mode 100644 static/openbsd/man3/DSA_new.3 create mode 100644 static/openbsd/man3/DSA_set_method.3 create mode 100644 static/openbsd/man3/DSA_sign.3 create mode 100644 static/openbsd/man3/DSA_size.3 create mode 100644 static/openbsd/man3/DTLSv1_listen.3 create mode 100644 static/openbsd/man3/ECDH_compute_key.3 create mode 100644 static/openbsd/man3/ECDSA_SIG_new.3 create mode 100644 static/openbsd/man3/EC_GROUP_check.3 create mode 100644 static/openbsd/man3/EC_GROUP_get_curve_name.3 create mode 100644 static/openbsd/man3/EC_GROUP_new_by_curve_name.3 create mode 100644 static/openbsd/man3/EC_GROUP_new_curve_GFp.3 create mode 100644 static/openbsd/man3/EC_KEY_METHOD_new.3 create mode 100644 static/openbsd/man3/EC_KEY_new.3 create mode 100644 static/openbsd/man3/EC_POINT_add.3 create mode 100644 static/openbsd/man3/EC_POINT_get_affine_coordinates.3 create mode 100644 static/openbsd/man3/EC_POINT_new.3 create mode 100644 static/openbsd/man3/EC_POINT_point2oct.3 create mode 100644 static/openbsd/man3/ENGINE_new.3 create mode 100644 static/openbsd/man3/ERR_GET_LIB.3 create mode 100644 static/openbsd/man3/ERR_asprintf_error_data.3 create mode 100644 static/openbsd/man3/ERR_clear_error.3 create mode 100644 static/openbsd/man3/ERR_error_string.3 create mode 100644 static/openbsd/man3/ERR_get_error.3 create mode 100644 static/openbsd/man3/ERR_load_crypto_strings.3 create mode 100644 static/openbsd/man3/ERR_load_strings.3 create mode 100644 static/openbsd/man3/ERR_print_errors.3 create mode 100644 static/openbsd/man3/ERR_put_error.3 create mode 100644 static/openbsd/man3/ERR_remove_state.3 create mode 100644 static/openbsd/man3/ERR_set_mark.3 create mode 100644 static/openbsd/man3/ESS_SIGNING_CERT_new.3 create mode 100644 static/openbsd/man3/EVP_AEAD_CTX_init.3 create mode 100644 static/openbsd/man3/EVP_BytesToKey.3 create mode 100644 static/openbsd/man3/EVP_CIPHER_CTX_ctrl.3 create mode 100644 static/openbsd/man3/EVP_CIPHER_CTX_get_cipher_data.3 create mode 100644 static/openbsd/man3/EVP_CIPHER_CTX_init.3 create mode 100644 static/openbsd/man3/EVP_CIPHER_CTX_set_flags.3 create mode 100644 static/openbsd/man3/EVP_CIPHER_do_all.3 create mode 100644 static/openbsd/man3/EVP_CIPHER_meth_new.3 create mode 100644 static/openbsd/man3/EVP_CIPHER_nid.3 create mode 100644 static/openbsd/man3/EVP_DigestInit.3 create mode 100644 static/openbsd/man3/EVP_DigestSignInit.3 create mode 100644 static/openbsd/man3/EVP_DigestVerifyInit.3 create mode 100644 static/openbsd/man3/EVP_EncodeInit.3 create mode 100644 static/openbsd/man3/EVP_EncryptInit.3 create mode 100644 static/openbsd/man3/EVP_MD_CTX_ctrl.3 create mode 100644 static/openbsd/man3/EVP_MD_nid.3 create mode 100644 static/openbsd/man3/EVP_OpenInit.3 create mode 100644 static/openbsd/man3/EVP_PKCS82PKEY.3 create mode 100644 static/openbsd/man3/EVP_PKEY_CTX_ctrl.3 create mode 100644 static/openbsd/man3/EVP_PKEY_CTX_get_operation.3 create mode 100644 static/openbsd/man3/EVP_PKEY_CTX_new.3 create mode 100644 static/openbsd/man3/EVP_PKEY_CTX_set_hkdf_md.3 create mode 100644 static/openbsd/man3/EVP_PKEY_CTX_set_tls1_prf_md.3 create mode 100644 static/openbsd/man3/EVP_PKEY_asn1_get_count.3 create mode 100644 static/openbsd/man3/EVP_PKEY_cmp.3 create mode 100644 static/openbsd/man3/EVP_PKEY_decrypt.3 create mode 100644 static/openbsd/man3/EVP_PKEY_derive.3 create mode 100644 static/openbsd/man3/EVP_PKEY_encrypt.3 create mode 100644 static/openbsd/man3/EVP_PKEY_get_default_digest_nid.3 create mode 100644 static/openbsd/man3/EVP_PKEY_keygen.3 create mode 100644 static/openbsd/man3/EVP_PKEY_new.3 create mode 100644 static/openbsd/man3/EVP_PKEY_new_CMAC_key.3 create mode 100644 static/openbsd/man3/EVP_PKEY_print_private.3 create mode 100644 static/openbsd/man3/EVP_PKEY_set1_RSA.3 create mode 100644 static/openbsd/man3/EVP_PKEY_sign.3 create mode 100644 static/openbsd/man3/EVP_PKEY_size.3 create mode 100644 static/openbsd/man3/EVP_PKEY_verify.3 create mode 100644 static/openbsd/man3/EVP_PKEY_verify_recover.3 create mode 100644 static/openbsd/man3/EVP_SealInit.3 create mode 100644 static/openbsd/man3/EVP_SignInit.3 create mode 100644 static/openbsd/man3/EVP_VerifyInit.3 create mode 100644 static/openbsd/man3/EVP_aes_128_cbc.3 create mode 100644 static/openbsd/man3/EVP_aes_128_ccm.3 create mode 100644 static/openbsd/man3/EVP_aes_128_gcm.3 create mode 100644 static/openbsd/man3/EVP_camellia_128_cbc.3 create mode 100644 static/openbsd/man3/EVP_chacha20.3 create mode 100644 static/openbsd/man3/EVP_des_cbc.3 create mode 100644 static/openbsd/man3/EVP_rc2_cbc.3 create mode 100644 static/openbsd/man3/EVP_rc4.3 create mode 100644 static/openbsd/man3/EVP_sha1.3 create mode 100644 static/openbsd/man3/EVP_sha3_224.3 create mode 100644 static/openbsd/man3/EVP_sm3.3 create mode 100644 static/openbsd/man3/EVP_sm4_cbc.3 create mode 100644 static/openbsd/man3/EXTENDED_KEY_USAGE_new.3 create mode 100644 static/openbsd/man3/GENERAL_NAME_new.3 create mode 100644 static/openbsd/man3/HMAC.3 create mode 100644 static/openbsd/man3/IPAddressRange_new.3 create mode 100644 static/openbsd/man3/MB_CUR_MAX.3 create mode 100644 static/openbsd/man3/MD5.3 create mode 100644 static/openbsd/man3/MD5Init.3 create mode 100644 static/openbsd/man3/NAME_CONSTRAINTS_new.3 create mode 100644 static/openbsd/man3/OBJ_create.3 create mode 100644 static/openbsd/man3/OBJ_find_sigid_algs.3 create mode 100644 static/openbsd/man3/OBJ_nid2obj.3 create mode 100644 static/openbsd/man3/OCSP_CRLID_new.3 create mode 100644 static/openbsd/man3/OCSP_REQUEST_new.3 create mode 100644 static/openbsd/man3/OCSP_SERVICELOC_new.3 create mode 100644 static/openbsd/man3/OCSP_cert_to_id.3 create mode 100644 static/openbsd/man3/OCSP_request_add1_nonce.3 create mode 100644 static/openbsd/man3/OCSP_resp_find_status.3 create mode 100644 static/openbsd/man3/OCSP_response_status.3 create mode 100644 static/openbsd/man3/OCSP_sendreq_new.3 create mode 100644 static/openbsd/man3/OPENSSL_VERSION_NUMBER.3 create mode 100644 static/openbsd/man3/OPENSSL_cleanse.3 create mode 100644 static/openbsd/man3/OPENSSL_config.3 create mode 100644 static/openbsd/man3/OPENSSL_init_crypto.3 create mode 100644 static/openbsd/man3/OPENSSL_init_ssl.3 create mode 100644 static/openbsd/man3/OPENSSL_malloc.3 create mode 100644 static/openbsd/man3/OPENSSL_sk_new.3 create mode 100644 static/openbsd/man3/OpenSSL_add_all_algorithms.3 create mode 100644 static/openbsd/man3/PEM_ASN1_read.3 create mode 100644 static/openbsd/man3/PEM_X509_INFO_read_bio.3 create mode 100644 static/openbsd/man3/PEM_bytes_read_bio.3 create mode 100644 static/openbsd/man3/PEM_read.3 create mode 100644 static/openbsd/man3/PEM_read_SSL_SESSION.3 create mode 100644 static/openbsd/man3/PEM_read_bio_PrivateKey.3 create mode 100644 static/openbsd/man3/PEM_write_bio_CMS_stream.3 create mode 100644 static/openbsd/man3/PEM_write_bio_PKCS7_stream.3 create mode 100644 static/openbsd/man3/PKCS12_SAFEBAG_new.3 create mode 100644 static/openbsd/man3/PKCS12_create.3 create mode 100644 static/openbsd/man3/PKCS12_new.3 create mode 100644 static/openbsd/man3/PKCS12_newpass.3 create mode 100644 static/openbsd/man3/PKCS12_parse.3 create mode 100644 static/openbsd/man3/PKCS5_PBKDF2_HMAC.3 create mode 100644 static/openbsd/man3/PKCS7_add_attribute.3 create mode 100644 static/openbsd/man3/PKCS7_dataFinal.3 create mode 100644 static/openbsd/man3/PKCS7_dataInit.3 create mode 100644 static/openbsd/man3/PKCS7_decrypt.3 create mode 100644 static/openbsd/man3/PKCS7_encrypt.3 create mode 100644 static/openbsd/man3/PKCS7_final.3 create mode 100644 static/openbsd/man3/PKCS7_get_signer_info.3 create mode 100644 static/openbsd/man3/PKCS7_new.3 create mode 100644 static/openbsd/man3/PKCS7_set_content.3 create mode 100644 static/openbsd/man3/PKCS7_set_type.3 create mode 100644 static/openbsd/man3/PKCS7_sign.3 create mode 100644 static/openbsd/man3/PKCS7_sign_add_signer.3 create mode 100644 static/openbsd/man3/PKCS7_verify.3 create mode 100644 static/openbsd/man3/PKCS8_PRIV_KEY_INFO_new.3 create mode 100644 static/openbsd/man3/PKCS8_pkey_set0.3 create mode 100644 static/openbsd/man3/PKEY_USAGE_PERIOD_new.3 create mode 100644 static/openbsd/man3/POLICYINFO_new.3 create mode 100644 static/openbsd/man3/RAND_add.3 create mode 100644 static/openbsd/man3/RAND_bytes.3 create mode 100644 static/openbsd/man3/RAND_load_file.3 create mode 100644 static/openbsd/man3/RAND_set_rand_method.3 create mode 100644 static/openbsd/man3/RC2_encrypt.3 create mode 100644 static/openbsd/man3/RC4.3 create mode 100644 static/openbsd/man3/RIPEMD160.3 create mode 100644 static/openbsd/man3/RMD160Init.3 create mode 100644 static/openbsd/man3/RSA_PSS_PARAMS_new.3 create mode 100644 static/openbsd/man3/RSA_blinding_on.3 create mode 100644 static/openbsd/man3/RSA_check_key.3 create mode 100644 static/openbsd/man3/RSA_generate_key.3 create mode 100644 static/openbsd/man3/RSA_get0_key.3 create mode 100644 static/openbsd/man3/RSA_get_ex_new_index.3 create mode 100644 static/openbsd/man3/RSA_meth_new.3 create mode 100644 static/openbsd/man3/RSA_new.3 create mode 100644 static/openbsd/man3/RSA_padding_add_PKCS1_type_1.3 create mode 100644 static/openbsd/man3/RSA_pkey_ctx_ctrl.3 create mode 100644 static/openbsd/man3/RSA_print.3 create mode 100644 static/openbsd/man3/RSA_private_encrypt.3 create mode 100644 static/openbsd/man3/RSA_public_encrypt.3 create mode 100644 static/openbsd/man3/RSA_security_bits.3 create mode 100644 static/openbsd/man3/RSA_set_method.3 create mode 100644 static/openbsd/man3/RSA_sign.3 create mode 100644 static/openbsd/man3/RSA_sign_ASN1_OCTET_STRING.3 create mode 100644 static/openbsd/man3/RSA_size.3 create mode 100644 static/openbsd/man3/SHA1.3 create mode 100644 static/openbsd/man3/SHA1Init.3 create mode 100644 static/openbsd/man3/SHA256Init.3 create mode 100644 static/openbsd/man3/SMIME_crlf_copy.3 create mode 100644 static/openbsd/man3/SMIME_read_CMS.3 create mode 100644 static/openbsd/man3/SMIME_read_PKCS7.3 create mode 100644 static/openbsd/man3/SMIME_text.3 create mode 100644 static/openbsd/man3/SMIME_write_CMS.3 create mode 100644 static/openbsd/man3/SMIME_write_PKCS7.3 create mode 100644 static/openbsd/man3/SSL_CIPHER_get_name.3 create mode 100644 static/openbsd/man3/SSL_COMP_add_compression_method.3 create mode 100644 static/openbsd/man3/SSL_CTX_add1_chain_cert.3 create mode 100644 static/openbsd/man3/SSL_CTX_add_extra_chain_cert.3 create mode 100644 static/openbsd/man3/SSL_CTX_add_session.3 create mode 100644 static/openbsd/man3/SSL_CTX_ctrl.3 create mode 100644 static/openbsd/man3/SSL_CTX_flush_sessions.3 create mode 100644 static/openbsd/man3/SSL_CTX_free.3 create mode 100644 static/openbsd/man3/SSL_CTX_get0_certificate.3 create mode 100644 static/openbsd/man3/SSL_CTX_get_ex_new_index.3 create mode 100644 static/openbsd/man3/SSL_CTX_get_verify_mode.3 create mode 100644 static/openbsd/man3/SSL_CTX_load_verify_locations.3 create mode 100644 static/openbsd/man3/SSL_CTX_new.3 create mode 100644 static/openbsd/man3/SSL_CTX_sess_number.3 create mode 100644 static/openbsd/man3/SSL_CTX_sess_set_cache_size.3 create mode 100644 static/openbsd/man3/SSL_CTX_sess_set_get_cb.3 create mode 100644 static/openbsd/man3/SSL_CTX_sessions.3 create mode 100644 static/openbsd/man3/SSL_CTX_set1_groups.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_alpn_select_cb.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_cert_store.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_cert_verify_callback.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_cipher_list.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_client_CA_list.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_client_cert_cb.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_default_passwd_cb.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_generate_session_id.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_info_callback.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_keylog_callback.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_max_cert_list.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_min_proto_version.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_mode.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_msg_callback.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_num_tickets.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_options.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_quiet_shutdown.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_read_ahead.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_security_level.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_session_cache_mode.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_session_id_context.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_ssl_version.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_timeout.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_tlsext_servername_callback.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_tlsext_status_cb.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_tlsext_ticket_key_cb.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_tlsext_use_srtp.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_tmp_dh_callback.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_tmp_rsa_callback.3 create mode 100644 static/openbsd/man3/SSL_CTX_set_verify.3 create mode 100644 static/openbsd/man3/SSL_CTX_use_certificate.3 create mode 100644 static/openbsd/man3/SSL_SESSION_free.3 create mode 100644 static/openbsd/man3/SSL_SESSION_get0_cipher.3 create mode 100644 static/openbsd/man3/SSL_SESSION_get0_peer.3 create mode 100644 static/openbsd/man3/SSL_SESSION_get_compress_id.3 create mode 100644 static/openbsd/man3/SSL_SESSION_get_ex_new_index.3 create mode 100644 static/openbsd/man3/SSL_SESSION_get_id.3 create mode 100644 static/openbsd/man3/SSL_SESSION_get_protocol_version.3 create mode 100644 static/openbsd/man3/SSL_SESSION_get_time.3 create mode 100644 static/openbsd/man3/SSL_SESSION_has_ticket.3 create mode 100644 static/openbsd/man3/SSL_SESSION_is_resumable.3 create mode 100644 static/openbsd/man3/SSL_SESSION_new.3 create mode 100644 static/openbsd/man3/SSL_SESSION_print.3 create mode 100644 static/openbsd/man3/SSL_SESSION_set1_id_context.3 create mode 100644 static/openbsd/man3/SSL_accept.3 create mode 100644 static/openbsd/man3/SSL_alert_type_string.3 create mode 100644 static/openbsd/man3/SSL_clear.3 create mode 100644 static/openbsd/man3/SSL_connect.3 create mode 100644 static/openbsd/man3/SSL_copy_session_id.3 create mode 100644 static/openbsd/man3/SSL_do_handshake.3 create mode 100644 static/openbsd/man3/SSL_dup.3 create mode 100644 static/openbsd/man3/SSL_dup_CA_list.3 create mode 100644 static/openbsd/man3/SSL_export_keying_material.3 create mode 100644 static/openbsd/man3/SSL_free.3 create mode 100644 static/openbsd/man3/SSL_get_SSL_CTX.3 create mode 100644 static/openbsd/man3/SSL_get_certificate.3 create mode 100644 static/openbsd/man3/SSL_get_ciphers.3 create mode 100644 static/openbsd/man3/SSL_get_client_CA_list.3 create mode 100644 static/openbsd/man3/SSL_get_client_random.3 create mode 100644 static/openbsd/man3/SSL_get_current_cipher.3 create mode 100644 static/openbsd/man3/SSL_get_default_timeout.3 create mode 100644 static/openbsd/man3/SSL_get_error.3 create mode 100644 static/openbsd/man3/SSL_get_ex_data_X509_STORE_CTX_idx.3 create mode 100644 static/openbsd/man3/SSL_get_ex_new_index.3 create mode 100644 static/openbsd/man3/SSL_get_fd.3 create mode 100644 static/openbsd/man3/SSL_get_finished.3 create mode 100644 static/openbsd/man3/SSL_get_peer_cert_chain.3 create mode 100644 static/openbsd/man3/SSL_get_peer_certificate.3 create mode 100644 static/openbsd/man3/SSL_get_rbio.3 create mode 100644 static/openbsd/man3/SSL_get_server_tmp_key.3 create mode 100644 static/openbsd/man3/SSL_get_session.3 create mode 100644 static/openbsd/man3/SSL_get_shared_ciphers.3 create mode 100644 static/openbsd/man3/SSL_get_state.3 create mode 100644 static/openbsd/man3/SSL_get_verify_result.3 create mode 100644 static/openbsd/man3/SSL_get_version.3 create mode 100644 static/openbsd/man3/SSL_library_init.3 create mode 100644 static/openbsd/man3/SSL_load_client_CA_file.3 create mode 100644 static/openbsd/man3/SSL_new.3 create mode 100644 static/openbsd/man3/SSL_num_renegotiations.3 create mode 100644 static/openbsd/man3/SSL_pending.3 create mode 100644 static/openbsd/man3/SSL_read.3 create mode 100644 static/openbsd/man3/SSL_read_early_data.3 create mode 100644 static/openbsd/man3/SSL_renegotiate.3 create mode 100644 static/openbsd/man3/SSL_rstate_string.3 create mode 100644 static/openbsd/man3/SSL_session_reused.3 create mode 100644 static/openbsd/man3/SSL_set1_host.3 create mode 100644 static/openbsd/man3/SSL_set1_param.3 create mode 100644 static/openbsd/man3/SSL_set_SSL_CTX.3 create mode 100644 static/openbsd/man3/SSL_set_bio.3 create mode 100644 static/openbsd/man3/SSL_set_connect_state.3 create mode 100644 static/openbsd/man3/SSL_set_fd.3 create mode 100644 static/openbsd/man3/SSL_set_max_send_fragment.3 create mode 100644 static/openbsd/man3/SSL_set_psk_use_session_callback.3 create mode 100644 static/openbsd/man3/SSL_set_session.3 create mode 100644 static/openbsd/man3/SSL_set_shutdown.3 create mode 100644 static/openbsd/man3/SSL_set_tmp_ecdh.3 create mode 100644 static/openbsd/man3/SSL_set_verify_result.3 create mode 100644 static/openbsd/man3/SSL_shutdown.3 create mode 100644 static/openbsd/man3/SSL_state_string.3 create mode 100644 static/openbsd/man3/SSL_want.3 create mode 100644 static/openbsd/man3/SSL_write.3 create mode 100644 static/openbsd/man3/STACK_OF.3 create mode 100644 static/openbsd/man3/SipHash24_Init.3 create mode 100644 static/openbsd/man3/TS_REQ_new.3 create mode 100644 static/openbsd/man3/UI_create_method.3 create mode 100644 static/openbsd/man3/UI_get_string_type.3 create mode 100644 static/openbsd/man3/UI_new.3 create mode 100644 static/openbsd/man3/X25519.3 create mode 100644 static/openbsd/man3/X509V3_EXT_get_nid.3 create mode 100644 static/openbsd/man3/X509V3_EXT_print.3 create mode 100644 static/openbsd/man3/X509V3_extensions_print.3 create mode 100644 static/openbsd/man3/X509V3_get_d2i.3 create mode 100644 static/openbsd/man3/X509V3_parse_list.3 create mode 100644 static/openbsd/man3/X509_ALGOR_dup.3 create mode 100644 static/openbsd/man3/X509_ATTRIBUTE_get0_object.3 create mode 100644 static/openbsd/man3/X509_ATTRIBUTE_new.3 create mode 100644 static/openbsd/man3/X509_ATTRIBUTE_set1_object.3 create mode 100644 static/openbsd/man3/X509_CINF_new.3 create mode 100644 static/openbsd/man3/X509_CRL_get0_by_serial.3 create mode 100644 static/openbsd/man3/X509_CRL_new.3 create mode 100644 static/openbsd/man3/X509_CRL_print.3 create mode 100644 static/openbsd/man3/X509_EXTENSION_set_object.3 create mode 100644 static/openbsd/man3/X509_INFO_new.3 create mode 100644 static/openbsd/man3/X509_LOOKUP_hash_dir.3 create mode 100644 static/openbsd/man3/X509_LOOKUP_new.3 create mode 100644 static/openbsd/man3/X509_NAME_ENTRY_get_object.3 create mode 100644 static/openbsd/man3/X509_NAME_add_entry_by_txt.3 create mode 100644 static/openbsd/man3/X509_NAME_get_index_by_NID.3 create mode 100644 static/openbsd/man3/X509_NAME_hash.3 create mode 100644 static/openbsd/man3/X509_NAME_new.3 create mode 100644 static/openbsd/man3/X509_NAME_print_ex.3 create mode 100644 static/openbsd/man3/X509_OBJECT_get0_X509.3 create mode 100644 static/openbsd/man3/X509_PUBKEY_new.3 create mode 100644 static/openbsd/man3/X509_PURPOSE_set.3 create mode 100644 static/openbsd/man3/X509_REQ_add1_attr.3 create mode 100644 static/openbsd/man3/X509_REQ_add_extensions.3 create mode 100644 static/openbsd/man3/X509_REQ_new.3 create mode 100644 static/openbsd/man3/X509_REQ_print_ex.3 create mode 100644 static/openbsd/man3/X509_REVOKED_new.3 create mode 100644 static/openbsd/man3/X509_SIG_get0.3 create mode 100644 static/openbsd/man3/X509_SIG_new.3 create mode 100644 static/openbsd/man3/X509_STORE_CTX_get_error.3 create mode 100644 static/openbsd/man3/X509_STORE_CTX_get_ex_new_index.3 create mode 100644 static/openbsd/man3/X509_STORE_CTX_new.3 create mode 100644 static/openbsd/man3/X509_STORE_CTX_set_flags.3 create mode 100644 static/openbsd/man3/X509_STORE_CTX_set_verify.3 create mode 100644 static/openbsd/man3/X509_STORE_CTX_set_verify_cb.3 create mode 100644 static/openbsd/man3/X509_STORE_get_by_subject.3 create mode 100644 static/openbsd/man3/X509_STORE_load_locations.3 create mode 100644 static/openbsd/man3/X509_STORE_new.3 create mode 100644 static/openbsd/man3/X509_STORE_set1_param.3 create mode 100644 static/openbsd/man3/X509_STORE_set_verify_cb_func.3 create mode 100644 static/openbsd/man3/X509_VERIFY_PARAM_new.3 create mode 100644 static/openbsd/man3/X509_VERIFY_PARAM_set_flags.3 create mode 100644 static/openbsd/man3/X509_add1_trust_object.3 create mode 100644 static/openbsd/man3/X509_check_ca.3 create mode 100644 static/openbsd/man3/X509_check_host.3 create mode 100644 static/openbsd/man3/X509_check_issued.3 create mode 100644 static/openbsd/man3/X509_check_private_key.3 create mode 100644 static/openbsd/man3/X509_check_purpose.3 create mode 100644 static/openbsd/man3/X509_cmp.3 create mode 100644 static/openbsd/man3/X509_cmp_time.3 create mode 100644 static/openbsd/man3/X509_digest.3 create mode 100644 static/openbsd/man3/X509_find_by_subject.3 create mode 100644 static/openbsd/man3/X509_get0_notBefore.3 create mode 100644 static/openbsd/man3/X509_get0_signature.3 create mode 100644 static/openbsd/man3/X509_get1_email.3 create mode 100644 static/openbsd/man3/X509_get_extension_flags.3 create mode 100644 static/openbsd/man3/X509_get_pubkey.3 create mode 100644 static/openbsd/man3/X509_get_pubkey_parameters.3 create mode 100644 static/openbsd/man3/X509_get_serialNumber.3 create mode 100644 static/openbsd/man3/X509_get_subject_name.3 create mode 100644 static/openbsd/man3/X509_get_version.3 create mode 100644 static/openbsd/man3/X509_keyid_set1.3 create mode 100644 static/openbsd/man3/X509_load_cert_file.3 create mode 100644 static/openbsd/man3/X509_new.3 create mode 100644 static/openbsd/man3/X509_ocspid_print.3 create mode 100644 static/openbsd/man3/X509_print_ex.3 create mode 100644 static/openbsd/man3/X509_sign.3 create mode 100644 static/openbsd/man3/X509_signature_dump.3 create mode 100644 static/openbsd/man3/X509_verify_cert.3 create mode 100644 static/openbsd/man3/X509v3_addr_add_inherit.3 create mode 100644 static/openbsd/man3/X509v3_addr_get_range.3 create mode 100644 static/openbsd/man3/X509v3_addr_inherits.3 create mode 100644 static/openbsd/man3/X509v3_addr_subset.3 create mode 100644 static/openbsd/man3/X509v3_addr_validate_path.3 create mode 100644 static/openbsd/man3/X509v3_asid_add_id_or_range.3 create mode 100644 static/openbsd/man3/X509v3_get_ext_by_NID.3 create mode 100644 static/openbsd/man3/__fpending.3 create mode 100644 static/openbsd/man3/__tfork_thread.3 create mode 100644 static/openbsd/man3/a2d_ASN1_OBJECT.3 create mode 100644 static/openbsd/man3/a2i_ipadd.3 create mode 100644 static/openbsd/man3/a64l.3 create mode 100644 static/openbsd/man3/abort.3 create mode 100644 static/openbsd/man3/abs.3 create mode 100644 static/openbsd/man3/acos.3 create mode 100644 static/openbsd/man3/acosh.3 create mode 100644 static/openbsd/man3/agentx.3 create mode 100644 static/openbsd/man3/alarm.3 create mode 100644 static/openbsd/man3/alloca.3 create mode 100644 static/openbsd/man3/arc4random.3 create mode 100644 static/openbsd/man3/asin.3 create mode 100644 static/openbsd/man3/asinh.3 create mode 100644 static/openbsd/man3/asr_run.3 create mode 100644 static/openbsd/man3/atan.3 create mode 100644 static/openbsd/man3/atan2.3 create mode 100644 static/openbsd/man3/atanh.3 create mode 100644 static/openbsd/man3/atexit.3 create mode 100644 static/openbsd/man3/atof.3 create mode 100644 static/openbsd/man3/atoi.3 create mode 100644 static/openbsd/man3/atol.3 create mode 100644 static/openbsd/man3/atoll.3 create mode 100644 static/openbsd/man3/auth_subr.3 create mode 100644 static/openbsd/man3/authenticate.3 create mode 100644 static/openbsd/man3/authnone_create.3 create mode 100644 static/openbsd/man3/backtrace.3 create mode 100644 static/openbsd/man3/basename.3 create mode 100644 static/openbsd/man3/bcmp.3 create mode 100644 static/openbsd/man3/bcopy.3 create mode 100644 static/openbsd/man3/bcrypt_pbkdf.3 create mode 100644 static/openbsd/man3/bindresvport.3 create mode 100644 static/openbsd/man3/blowfish.3 create mode 100644 static/openbsd/man3/bsearch.3 create mode 100644 static/openbsd/man3/btowc.3 create mode 100644 static/openbsd/man3/btree.3 create mode 100644 static/openbsd/man3/bzero.3 create mode 100644 static/openbsd/man3/c16rtomb.3 create mode 100644 static/openbsd/man3/cacheflush.3 create mode 100644 static/openbsd/man3/cacos.3 create mode 100644 static/openbsd/man3/cacosh.3 create mode 100644 static/openbsd/man3/carg.3 create mode 100644 static/openbsd/man3/casin.3 create mode 100644 static/openbsd/man3/casinh.3 create mode 100644 static/openbsd/man3/catan.3 create mode 100644 static/openbsd/man3/catanh.3 create mode 100644 static/openbsd/man3/catclose.3 create mode 100644 static/openbsd/man3/catgets.3 create mode 100644 static/openbsd/man3/catopen.3 create mode 100644 static/openbsd/man3/ccos.3 create mode 100644 static/openbsd/man3/ccosh.3 create mode 100644 static/openbsd/man3/ceil.3 create mode 100644 static/openbsd/man3/cexp.3 create mode 100644 static/openbsd/man3/cgetent.3 create mode 100644 static/openbsd/man3/check_expire.3 create mode 100644 static/openbsd/man3/cimag.3 create mode 100644 static/openbsd/man3/clock.3 create mode 100644 static/openbsd/man3/clock_getcpuclockid.3 create mode 100644 static/openbsd/man3/clog.3 create mode 100644 static/openbsd/man3/compress.3 create mode 100644 static/openbsd/man3/confstr.3 create mode 100644 static/openbsd/man3/conj.3 create mode 100644 static/openbsd/man3/copysign.3 create mode 100644 static/openbsd/man3/cos.3 create mode 100644 static/openbsd/man3/cosh.3 create mode 100644 static/openbsd/man3/cpow.3 create mode 100644 static/openbsd/man3/cproj.3 create mode 100644 static/openbsd/man3/creal.3 create mode 100644 static/openbsd/man3/creat.3 create mode 100644 static/openbsd/man3/crypt.3 create mode 100644 static/openbsd/man3/crypt_checkpass.3 create mode 100644 static/openbsd/man3/crypto.3 create mode 100644 static/openbsd/man3/csh.3 create mode 100644 static/openbsd/man3/csin.3 create mode 100644 static/openbsd/man3/csinh.3 create mode 100644 static/openbsd/man3/csqrt.3 create mode 100644 static/openbsd/man3/ctan.3 create mode 100644 static/openbsd/man3/ctanh.3 create mode 100644 static/openbsd/man3/ctermid.3 create mode 100644 static/openbsd/man3/ctime.3 create mode 100644 static/openbsd/man3/curs_add_wch.3 create mode 100644 static/openbsd/man3/curs_add_wchstr.3 create mode 100644 static/openbsd/man3/curs_addch.3 create mode 100644 static/openbsd/man3/curs_addchstr.3 create mode 100644 static/openbsd/man3/curs_addstr.3 create mode 100644 static/openbsd/man3/curs_addwstr.3 create mode 100644 static/openbsd/man3/curs_attr.3 create mode 100644 static/openbsd/man3/curs_beep.3 create mode 100644 static/openbsd/man3/curs_bkgd.3 create mode 100644 static/openbsd/man3/curs_bkgrnd.3 create mode 100644 static/openbsd/man3/curs_border.3 create mode 100644 static/openbsd/man3/curs_border_set.3 create mode 100644 static/openbsd/man3/curs_clear.3 create mode 100644 static/openbsd/man3/curs_color.3 create mode 100644 static/openbsd/man3/curs_delch.3 create mode 100644 static/openbsd/man3/curs_deleteln.3 create mode 100644 static/openbsd/man3/curs_extend.3 create mode 100644 static/openbsd/man3/curs_get_wch.3 create mode 100644 static/openbsd/man3/curs_get_wstr.3 create mode 100644 static/openbsd/man3/curs_getcchar.3 create mode 100644 static/openbsd/man3/curs_getch.3 create mode 100644 static/openbsd/man3/curs_getstr.3 create mode 100644 static/openbsd/man3/curs_getyx.3 create mode 100644 static/openbsd/man3/curs_in_wch.3 create mode 100644 static/openbsd/man3/curs_in_wchstr.3 create mode 100644 static/openbsd/man3/curs_inch.3 create mode 100644 static/openbsd/man3/curs_inchstr.3 create mode 100644 static/openbsd/man3/curs_initscr.3 create mode 100644 static/openbsd/man3/curs_inopts.3 create mode 100644 static/openbsd/man3/curs_ins_wch.3 create mode 100644 static/openbsd/man3/curs_ins_wstr.3 create mode 100644 static/openbsd/man3/curs_insch.3 create mode 100644 static/openbsd/man3/curs_insstr.3 create mode 100644 static/openbsd/man3/curs_instr.3 create mode 100644 static/openbsd/man3/curs_inwstr.3 create mode 100644 static/openbsd/man3/curs_kernel.3 create mode 100644 static/openbsd/man3/curs_legacy.3 create mode 100644 static/openbsd/man3/curs_memleaks.3 create mode 100644 static/openbsd/man3/curs_mouse.3 create mode 100644 static/openbsd/man3/curs_move.3 create mode 100644 static/openbsd/man3/curs_opaque.3 create mode 100644 static/openbsd/man3/curs_outopts.3 create mode 100644 static/openbsd/man3/curs_overlay.3 create mode 100644 static/openbsd/man3/curs_pad.3 create mode 100644 static/openbsd/man3/curs_print.3 create mode 100644 static/openbsd/man3/curs_printw.3 create mode 100644 static/openbsd/man3/curs_refresh.3 create mode 100644 static/openbsd/man3/curs_scanw.3 create mode 100644 static/openbsd/man3/curs_scr_dump.3 create mode 100644 static/openbsd/man3/curs_scroll.3 create mode 100644 static/openbsd/man3/curs_slk.3 create mode 100644 static/openbsd/man3/curs_sp_funcs.3 create mode 100644 static/openbsd/man3/curs_termattrs.3 create mode 100644 static/openbsd/man3/curs_threads.3 create mode 100644 static/openbsd/man3/curs_touch.3 create mode 100644 static/openbsd/man3/curs_util.3 create mode 100644 static/openbsd/man3/curs_variables.3 create mode 100644 static/openbsd/man3/curs_window.3 create mode 100644 static/openbsd/man3/curses.3 create mode 100644 static/openbsd/man3/d2i_ASN1_NULL.3 create mode 100644 static/openbsd/man3/d2i_ASN1_OBJECT.3 create mode 100644 static/openbsd/man3/d2i_ASN1_OCTET_STRING.3 create mode 100644 static/openbsd/man3/d2i_ASN1_SEQUENCE_ANY.3 create mode 100644 static/openbsd/man3/d2i_AUTHORITY_KEYID.3 create mode 100644 static/openbsd/man3/d2i_BASIC_CONSTRAINTS.3 create mode 100644 static/openbsd/man3/d2i_CMS_ContentInfo.3 create mode 100644 static/openbsd/man3/d2i_DHparams.3 create mode 100644 static/openbsd/man3/d2i_DIST_POINT.3 create mode 100644 static/openbsd/man3/d2i_DSAPublicKey.3 create mode 100644 static/openbsd/man3/d2i_ECPKParameters.3 create mode 100644 static/openbsd/man3/d2i_ESS_SIGNING_CERT.3 create mode 100644 static/openbsd/man3/d2i_GENERAL_NAME.3 create mode 100644 static/openbsd/man3/d2i_OCSP_REQUEST.3 create mode 100644 static/openbsd/man3/d2i_OCSP_RESPONSE.3 create mode 100644 static/openbsd/man3/d2i_PKCS12.3 create mode 100644 static/openbsd/man3/d2i_PKCS7.3 create mode 100644 static/openbsd/man3/d2i_PKCS8PrivateKey_bio.3 create mode 100644 static/openbsd/man3/d2i_PKCS8_PRIV_KEY_INFO.3 create mode 100644 static/openbsd/man3/d2i_PKEY_USAGE_PERIOD.3 create mode 100644 static/openbsd/man3/d2i_POLICYINFO.3 create mode 100644 static/openbsd/man3/d2i_PrivateKey.3 create mode 100644 static/openbsd/man3/d2i_RSAPublicKey.3 create mode 100644 static/openbsd/man3/d2i_SSL_SESSION.3 create mode 100644 static/openbsd/man3/d2i_TS_REQ.3 create mode 100644 static/openbsd/man3/d2i_X509.3 create mode 100644 static/openbsd/man3/d2i_X509_ALGOR.3 create mode 100644 static/openbsd/man3/d2i_X509_ATTRIBUTE.3 create mode 100644 static/openbsd/man3/d2i_X509_CRL.3 create mode 100644 static/openbsd/man3/d2i_X509_EXTENSION.3 create mode 100644 static/openbsd/man3/d2i_X509_NAME.3 create mode 100644 static/openbsd/man3/d2i_X509_REQ.3 create mode 100644 static/openbsd/man3/d2i_X509_SIG.3 create mode 100644 static/openbsd/man3/daemon.3 create mode 100644 static/openbsd/man3/dbopen.3 create mode 100644 static/openbsd/man3/default_colors.3 create mode 100644 static/openbsd/man3/define_key.3 create mode 100644 static/openbsd/man3/des_read_pw.3 create mode 100644 static/openbsd/man3/devname.3 create mode 100644 static/openbsd/man3/dirname.3 create mode 100644 static/openbsd/man3/div.3 create mode 100644 static/openbsd/man3/ecvt.3 create mode 100644 static/openbsd/man3/eddsa_pk_new.3 create mode 100644 static/openbsd/man3/editline.3 create mode 100644 static/openbsd/man3/elf.3 create mode 100644 static/openbsd/man3/elf_aux_info.3 create mode 100644 static/openbsd/man3/elf_begin.3 create mode 100644 static/openbsd/man3/elf_cntl.3 create mode 100644 static/openbsd/man3/elf_end.3 create mode 100644 static/openbsd/man3/elf_errmsg.3 create mode 100644 static/openbsd/man3/elf_fill.3 create mode 100644 static/openbsd/man3/elf_flagdata.3 create mode 100644 static/openbsd/man3/elf_getarhdr.3 create mode 100644 static/openbsd/man3/elf_getarsym.3 create mode 100644 static/openbsd/man3/elf_getbase.3 create mode 100644 static/openbsd/man3/elf_getdata.3 create mode 100644 static/openbsd/man3/elf_getident.3 create mode 100644 static/openbsd/man3/elf_getphdrnum.3 create mode 100644 static/openbsd/man3/elf_getphnum.3 create mode 100644 static/openbsd/man3/elf_getscn.3 create mode 100644 static/openbsd/man3/elf_getshdrnum.3 create mode 100644 static/openbsd/man3/elf_getshdrstrndx.3 create mode 100644 static/openbsd/man3/elf_getshnum.3 create mode 100644 static/openbsd/man3/elf_getshstrndx.3 create mode 100644 static/openbsd/man3/elf_hash.3 create mode 100644 static/openbsd/man3/elf_kind.3 create mode 100644 static/openbsd/man3/elf_memory.3 create mode 100644 static/openbsd/man3/elf_next.3 create mode 100644 static/openbsd/man3/elf_open.3 create mode 100644 static/openbsd/man3/elf_rand.3 create mode 100644 static/openbsd/man3/elf_rawfile.3 create mode 100644 static/openbsd/man3/elf_strptr.3 create mode 100644 static/openbsd/man3/elf_update.3 create mode 100644 static/openbsd/man3/elf_version.3 create mode 100644 static/openbsd/man3/erf.3 create mode 100644 static/openbsd/man3/err.3 create mode 100644 static/openbsd/man3/es256_pk_new.3 create mode 100644 static/openbsd/man3/ether_aton.3 create mode 100644 static/openbsd/man3/evbuffer_new.3 create mode 100644 static/openbsd/man3/event.3 create mode 100644 static/openbsd/man3/event_base_loop.3 create mode 100644 static/openbsd/man3/event_base_new.3 create mode 100644 static/openbsd/man3/event_set.3 create mode 100644 static/openbsd/man3/event_set_log_callback.3 create mode 100644 static/openbsd/man3/evp.3 create mode 100644 static/openbsd/man3/execv.3 create mode 100644 static/openbsd/man3/exit.3 create mode 100644 static/openbsd/man3/exp.3 create mode 100644 static/openbsd/man3/fabs.3 create mode 100644 static/openbsd/man3/fclose.3 create mode 100644 static/openbsd/man3/fdim.3 create mode 100644 static/openbsd/man3/feclearexcept.3 create mode 100644 static/openbsd/man3/feenableexcept.3 create mode 100644 static/openbsd/man3/fegetenv.3 create mode 100644 static/openbsd/man3/fegetround.3 create mode 100644 static/openbsd/man3/ferror.3 create mode 100644 static/openbsd/man3/fflush.3 create mode 100644 static/openbsd/man3/ffs.3 create mode 100644 static/openbsd/man3/fgetln.3 create mode 100644 static/openbsd/man3/fgets.3 create mode 100644 static/openbsd/man3/fgetwln.3 create mode 100644 static/openbsd/man3/fgetws.3 create mode 100644 static/openbsd/man3/fido_assert_allow_cred.3 create mode 100644 static/openbsd/man3/fido_assert_new.3 create mode 100644 static/openbsd/man3/fido_assert_set_authdata.3 create mode 100644 static/openbsd/man3/fido_assert_verify.3 create mode 100644 static/openbsd/man3/fido_bio_dev_get_info.3 create mode 100644 static/openbsd/man3/fido_bio_enroll_new.3 create mode 100644 static/openbsd/man3/fido_bio_info_new.3 create mode 100644 static/openbsd/man3/fido_bio_template.3 create mode 100644 static/openbsd/man3/fido_cbor_info_new.3 create mode 100644 static/openbsd/man3/fido_cred_exclude.3 create mode 100644 static/openbsd/man3/fido_cred_new.3 create mode 100644 static/openbsd/man3/fido_cred_set_authdata.3 create mode 100644 static/openbsd/man3/fido_cred_verify.3 create mode 100644 static/openbsd/man3/fido_credman_metadata_new.3 create mode 100644 static/openbsd/man3/fido_dev_enable_entattest.3 create mode 100644 static/openbsd/man3/fido_dev_get_assert.3 create mode 100644 static/openbsd/man3/fido_dev_get_touch_begin.3 create mode 100644 static/openbsd/man3/fido_dev_info_manifest.3 create mode 100644 static/openbsd/man3/fido_dev_largeblob_get.3 create mode 100644 static/openbsd/man3/fido_dev_make_cred.3 create mode 100644 static/openbsd/man3/fido_dev_open.3 create mode 100644 static/openbsd/man3/fido_dev_set_io_functions.3 create mode 100644 static/openbsd/man3/fido_dev_set_pin.3 create mode 100644 static/openbsd/man3/fido_init.3 create mode 100644 static/openbsd/man3/fido_strerr.3 create mode 100644 static/openbsd/man3/flockfile.3 create mode 100644 static/openbsd/man3/floor.3 create mode 100644 static/openbsd/man3/fma.3 create mode 100644 static/openbsd/man3/fmax.3 create mode 100644 static/openbsd/man3/fmemopen.3 create mode 100644 static/openbsd/man3/fmod.3 create mode 100644 static/openbsd/man3/fmt_scaled.3 create mode 100644 static/openbsd/man3/fn.3 create mode 100644 static/openbsd/man3/fnmatch.3 create mode 100644 static/openbsd/man3/fopen.3 create mode 100644 static/openbsd/man3/form.3 create mode 100644 static/openbsd/man3/form_cursor.3 create mode 100644 static/openbsd/man3/form_data.3 create mode 100644 static/openbsd/man3/form_driver.3 create mode 100644 static/openbsd/man3/form_field.3 create mode 100644 static/openbsd/man3/form_field_attributes.3 create mode 100644 static/openbsd/man3/form_field_buffer.3 create mode 100644 static/openbsd/man3/form_field_info.3 create mode 100644 static/openbsd/man3/form_field_just.3 create mode 100644 static/openbsd/man3/form_field_new.3 create mode 100644 static/openbsd/man3/form_field_opts.3 create mode 100644 static/openbsd/man3/form_field_userptr.3 create mode 100644 static/openbsd/man3/form_field_validation.3 create mode 100644 static/openbsd/man3/form_fieldtype.3 create mode 100644 static/openbsd/man3/form_hook.3 create mode 100644 static/openbsd/man3/form_new.3 create mode 100644 static/openbsd/man3/form_new_page.3 create mode 100644 static/openbsd/man3/form_opts.3 create mode 100644 static/openbsd/man3/form_page.3 create mode 100644 static/openbsd/man3/form_post.3 create mode 100644 static/openbsd/man3/form_requestname.3 create mode 100644 static/openbsd/man3/form_userptr.3 create mode 100644 static/openbsd/man3/form_variables.3 create mode 100644 static/openbsd/man3/form_win.3 create mode 100644 static/openbsd/man3/fparseln.3 create mode 100644 static/openbsd/man3/fpclassify.3 create mode 100644 static/openbsd/man3/fpgetmask.3 create mode 100644 static/openbsd/man3/fputs.3 create mode 100644 static/openbsd/man3/fputws.3 create mode 100644 static/openbsd/man3/fread.3 create mode 100644 static/openbsd/man3/frexp.3 create mode 100644 static/openbsd/man3/fseek.3 create mode 100644 static/openbsd/man3/ftok.3 create mode 100644 static/openbsd/man3/fts_open.3 create mode 100644 static/openbsd/man3/ftw.3 create mode 100644 static/openbsd/man3/funopen.3 create mode 100644 static/openbsd/man3/fuse_chan_fd.3 create mode 100644 static/openbsd/man3/fuse_daemonize.3 create mode 100644 static/openbsd/man3/fuse_destroy.3 create mode 100644 static/openbsd/man3/fuse_get_context.3 create mode 100644 static/openbsd/man3/fuse_get_session.3 create mode 100644 static/openbsd/man3/fuse_loop.3 create mode 100644 static/openbsd/man3/fuse_lowlevel_new.3 create mode 100644 static/openbsd/man3/fuse_main.3 create mode 100644 static/openbsd/man3/fuse_mount.3 create mode 100644 static/openbsd/man3/fuse_new.3 create mode 100644 static/openbsd/man3/fuse_opt.3 create mode 100644 static/openbsd/man3/fuse_parse_cmdline.3 create mode 100644 static/openbsd/man3/fuse_reply_err.3 create mode 100644 static/openbsd/man3/fuse_session_loop.3 create mode 100644 static/openbsd/man3/fuse_set_signal_handlers.3 create mode 100644 static/openbsd/man3/fuse_setup.3 create mode 100644 static/openbsd/man3/fuse_teardown.3 create mode 100644 static/openbsd/man3/fuse_version.3 create mode 100644 static/openbsd/man3/fwide.3 create mode 100644 static/openbsd/man3/gai_strerror.3 create mode 100644 static/openbsd/man3/gelf.3 create mode 100644 static/openbsd/man3/gelf_checksum.3 create mode 100644 static/openbsd/man3/gelf_fsize.3 create mode 100644 static/openbsd/man3/gelf_getcap.3 create mode 100644 static/openbsd/man3/gelf_getclass.3 create mode 100644 static/openbsd/man3/gelf_getdyn.3 create mode 100644 static/openbsd/man3/gelf_getehdr.3 create mode 100644 static/openbsd/man3/gelf_getmove.3 create mode 100644 static/openbsd/man3/gelf_getphdr.3 create mode 100644 static/openbsd/man3/gelf_getrel.3 create mode 100644 static/openbsd/man3/gelf_getrela.3 create mode 100644 static/openbsd/man3/gelf_getshdr.3 create mode 100644 static/openbsd/man3/gelf_getsym.3 create mode 100644 static/openbsd/man3/gelf_getsyminfo.3 create mode 100644 static/openbsd/man3/gelf_getsymshndx.3 create mode 100644 static/openbsd/man3/gelf_newehdr.3 create mode 100644 static/openbsd/man3/gelf_newphdr.3 create mode 100644 static/openbsd/man3/gelf_update_ehdr.3 create mode 100644 static/openbsd/man3/gelf_xlatetof.3 create mode 100644 static/openbsd/man3/get_fpc_csr.3 create mode 100644 static/openbsd/man3/getaddrinfo.3 create mode 100644 static/openbsd/man3/getbsize.3 create mode 100644 static/openbsd/man3/getc.3 create mode 100644 static/openbsd/man3/getcwd.3 create mode 100644 static/openbsd/man3/getdelim.3 create mode 100644 static/openbsd/man3/getdiskbyname.3 create mode 100644 static/openbsd/man3/getdomainname.3 create mode 100644 static/openbsd/man3/getdtablesize.3 create mode 100644 static/openbsd/man3/getenv.3 create mode 100644 static/openbsd/man3/getfsent.3 create mode 100644 static/openbsd/man3/getgrent.3 create mode 100644 static/openbsd/man3/getgrouplist.3 create mode 100644 static/openbsd/man3/gethostbyname.3 create mode 100644 static/openbsd/man3/gethostid.3 create mode 100644 static/openbsd/man3/gethostname.3 create mode 100644 static/openbsd/man3/getifaddrs.3 create mode 100644 static/openbsd/man3/getloadavg.3 create mode 100644 static/openbsd/man3/getmaxpartitions.3 create mode 100644 static/openbsd/man3/getmntinfo.3 create mode 100644 static/openbsd/man3/getnameinfo.3 create mode 100644 static/openbsd/man3/getnetent.3 create mode 100644 static/openbsd/man3/getnetgrent.3 create mode 100644 static/openbsd/man3/getopt.3 create mode 100644 static/openbsd/man3/getopt_long.3 create mode 100644 static/openbsd/man3/getpagesize.3 create mode 100644 static/openbsd/man3/getpass.3 create mode 100644 static/openbsd/man3/getpeereid.3 create mode 100644 static/openbsd/man3/getprogname.3 create mode 100644 static/openbsd/man3/getprotoent.3 create mode 100644 static/openbsd/man3/getpwent.3 create mode 100644 static/openbsd/man3/getpwnam.3 create mode 100644 static/openbsd/man3/getrawpartition.3 create mode 100644 static/openbsd/man3/getrpcent.3 create mode 100644 static/openbsd/man3/getrpcport.3 create mode 100644 static/openbsd/man3/getrrsetbyname.3 create mode 100644 static/openbsd/man3/getservent.3 create mode 100644 static/openbsd/man3/getsubopt.3 create mode 100644 static/openbsd/man3/getttyent.3 create mode 100644 static/openbsd/man3/getusershell.3 create mode 100644 static/openbsd/man3/getwc.3 create mode 100644 static/openbsd/man3/glob.3 create mode 100644 static/openbsd/man3/hash.3 create mode 100644 static/openbsd/man3/hcreate.3 create mode 100644 static/openbsd/man3/history.3 create mode 100644 static/openbsd/man3/htobe64.3 create mode 100644 static/openbsd/man3/htonl.3 create mode 100644 static/openbsd/man3/hypot.3 create mode 100644 static/openbsd/man3/i2a_ASN1_STRING.3 create mode 100644 static/openbsd/man3/i2d_CMS_bio_stream.3 create mode 100644 static/openbsd/man3/i2d_PKCS7_bio_stream.3 create mode 100644 static/openbsd/man3/ibuf_add.3 create mode 100644 static/openbsd/man3/icdb_new.3 create mode 100644 static/openbsd/man3/if_indextoname.3 create mode 100644 static/openbsd/man3/ilogb.3 create mode 100644 static/openbsd/man3/imaxabs.3 create mode 100644 static/openbsd/man3/imaxdiv.3 create mode 100644 static/openbsd/man3/imsg_init.3 create mode 100644 static/openbsd/man3/in.3 create mode 100644 static/openbsd/man3/inet6_opt_init.3 create mode 100644 static/openbsd/man3/inet6_rth_space.3 create mode 100644 static/openbsd/man3/inet_addr.3 create mode 100644 static/openbsd/man3/inet_lnaof.3 create mode 100644 static/openbsd/man3/inet_net_ntop.3 create mode 100644 static/openbsd/man3/inet_ntop.3 create mode 100644 static/openbsd/man3/initgroups.3 create mode 100644 static/openbsd/man3/insque.3 create mode 100644 static/openbsd/man3/isalnum.3 create mode 100644 static/openbsd/man3/isalpha.3 create mode 100644 static/openbsd/man3/isascii.3 create mode 100644 static/openbsd/man3/isblank.3 create mode 100644 static/openbsd/man3/iscntrl.3 create mode 100644 static/openbsd/man3/isdigit.3 create mode 100644 static/openbsd/man3/isduid.3 create mode 100644 static/openbsd/man3/isfdtype.3 create mode 100644 static/openbsd/man3/isgraph.3 create mode 100644 static/openbsd/man3/isgreater.3 create mode 100644 static/openbsd/man3/islower.3 create mode 100644 static/openbsd/man3/isprint.3 create mode 100644 static/openbsd/man3/ispunct.3 create mode 100644 static/openbsd/man3/isspace.3 create mode 100644 static/openbsd/man3/isupper.3 create mode 100644 static/openbsd/man3/iswalnum.3 create mode 100644 static/openbsd/man3/iswctype.3 create mode 100644 static/openbsd/man3/isxdigit.3 create mode 100644 static/openbsd/man3/j0.3 create mode 100644 static/openbsd/man3/key_defined.3 create mode 100644 static/openbsd/man3/keybound.3 create mode 100644 static/openbsd/man3/keynote.3 create mode 100644 static/openbsd/man3/keyok.3 create mode 100644 static/openbsd/man3/killpg.3 create mode 100644 static/openbsd/man3/kvm.3 create mode 100644 static/openbsd/man3/kvm_dump.3 create mode 100644 static/openbsd/man3/kvm_geterr.3 create mode 100644 static/openbsd/man3/kvm_getfiles.3 create mode 100644 static/openbsd/man3/kvm_getloadavg.3 create mode 100644 static/openbsd/man3/kvm_getprocs.3 create mode 100644 static/openbsd/man3/kvm_nlist.3 create mode 100644 static/openbsd/man3/kvm_open.3 create mode 100644 static/openbsd/man3/kvm_read.3 create mode 100644 static/openbsd/man3/labs.3 create mode 100644 static/openbsd/man3/ldexp.3 create mode 100644 static/openbsd/man3/ldiv.3 create mode 100644 static/openbsd/man3/legacy_coding.3 create mode 100644 static/openbsd/man3/lgamma.3 create mode 100644 static/openbsd/man3/lh_new.3 create mode 100644 static/openbsd/man3/link_ntoa.3 create mode 100644 static/openbsd/man3/lldiv.3 create mode 100644 static/openbsd/man3/localeconv.3 create mode 100644 static/openbsd/man3/lockf.3 create mode 100644 static/openbsd/man3/logb.3 create mode 100644 static/openbsd/man3/login.3 create mode 100644 static/openbsd/man3/login_cap.3 create mode 100644 static/openbsd/man3/login_fbtab.3 create mode 100644 static/openbsd/man3/lrint.3 create mode 100644 static/openbsd/man3/lround.3 create mode 100644 static/openbsd/man3/lsearch.3 create mode 100644 static/openbsd/man3/malloc.3 create mode 100644 static/openbsd/man3/mblen.3 create mode 100644 static/openbsd/man3/mbrlen.3 create mode 100644 static/openbsd/man3/mbrtoc16.3 create mode 100644 static/openbsd/man3/mbrtowc.3 create mode 100644 static/openbsd/man3/mbsinit.3 create mode 100644 static/openbsd/man3/mbsrtowcs.3 create mode 100644 static/openbsd/man3/mbstowcs.3 create mode 100644 static/openbsd/man3/mbtowc.3 create mode 100644 static/openbsd/man3/memccpy.3 create mode 100644 static/openbsd/man3/memchr.3 create mode 100644 static/openbsd/man3/memcmp.3 create mode 100644 static/openbsd/man3/memcpy.3 create mode 100644 static/openbsd/man3/memmem.3 create mode 100644 static/openbsd/man3/memmove.3 create mode 100644 static/openbsd/man3/memset.3 create mode 100644 static/openbsd/man3/menu.3 create mode 100644 static/openbsd/man3/menu_attributes.3 create mode 100644 static/openbsd/man3/menu_cursor.3 create mode 100644 static/openbsd/man3/menu_driver.3 create mode 100644 static/openbsd/man3/menu_format.3 create mode 100644 static/openbsd/man3/menu_hook.3 create mode 100644 static/openbsd/man3/menu_items.3 create mode 100644 static/openbsd/man3/menu_mark.3 create mode 100644 static/openbsd/man3/menu_new.3 create mode 100644 static/openbsd/man3/menu_opts.3 create mode 100644 static/openbsd/man3/menu_pattern.3 create mode 100644 static/openbsd/man3/menu_post.3 create mode 100644 static/openbsd/man3/menu_requestname.3 create mode 100644 static/openbsd/man3/menu_spacing.3 create mode 100644 static/openbsd/man3/menu_userptr.3 create mode 100644 static/openbsd/man3/menu_win.3 create mode 100644 static/openbsd/man3/mio_open.3 create mode 100644 static/openbsd/man3/mitem_current.3 create mode 100644 static/openbsd/man3/mitem_name.3 create mode 100644 static/openbsd/man3/mitem_new.3 create mode 100644 static/openbsd/man3/mitem_opts.3 create mode 100644 static/openbsd/man3/mitem_userptr.3 create mode 100644 static/openbsd/man3/mitem_value.3 create mode 100644 static/openbsd/man3/mitem_visible.3 create mode 100644 static/openbsd/man3/mktemp.3 create mode 100644 static/openbsd/man3/modf.3 create mode 100644 static/openbsd/man3/moncontrol.3 create mode 100644 static/openbsd/man3/nan.3 create mode 100644 static/openbsd/man3/ndbm.3 create mode 100644 static/openbsd/man3/new_pair.3 create mode 100644 static/openbsd/man3/newlocale.3 create mode 100644 static/openbsd/man3/nextafter.3 create mode 100644 static/openbsd/man3/nice.3 create mode 100644 static/openbsd/man3/nl_langinfo.3 create mode 100644 static/openbsd/man3/nlist.3 create mode 100644 static/openbsd/man3/ober_add_string.3 create mode 100644 static/openbsd/man3/ober_get_string.3 create mode 100644 static/openbsd/man3/ober_oid_cmp.3 create mode 100644 static/openbsd/man3/ober_read_elements.3 create mode 100644 static/openbsd/man3/ober_set_header.3 create mode 100644 static/openbsd/man3/ohash_init.3 create mode 100644 static/openbsd/man3/ohash_interval.3 create mode 100644 static/openbsd/man3/open_memstream.3 create mode 100644 static/openbsd/man3/opendev.3 create mode 100644 static/openbsd/man3/opendir.3 create mode 100644 static/openbsd/man3/opendisk.3 create mode 100644 static/openbsd/man3/openpty.3 create mode 100644 static/openbsd/man3/ossaudio.3 create mode 100644 static/openbsd/man3/panel.3 create mode 100644 static/openbsd/man3/pause.3 create mode 100644 static/openbsd/man3/pcap_open_live.3 create mode 100644 static/openbsd/man3/perror.3 create mode 100644 static/openbsd/man3/pidfile.3 create mode 100644 static/openbsd/man3/pkcs5_pbkdf2.3 create mode 100644 static/openbsd/man3/popen.3 create mode 100644 static/openbsd/man3/posix_memalign.3 create mode 100644 static/openbsd/man3/posix_openpt.3 create mode 100644 static/openbsd/man3/posix_spawn.3 create mode 100644 static/openbsd/man3/posix_spawn_file_actions_addopen.3 create mode 100644 static/openbsd/man3/posix_spawn_file_actions_init.3 create mode 100644 static/openbsd/man3/posix_spawnattr_getflags.3 create mode 100644 static/openbsd/man3/posix_spawnattr_getpgroup.3 create mode 100644 static/openbsd/man3/posix_spawnattr_init.3 create mode 100644 static/openbsd/man3/printf.3 create mode 100644 static/openbsd/man3/psignal.3 create mode 100644 static/openbsd/man3/pthread_atfork.3 create mode 100644 static/openbsd/man3/pthread_attr_init.3 create mode 100644 static/openbsd/man3/pthread_attr_setdetachstate.3 create mode 100644 static/openbsd/man3/pthread_attr_setguardsize.3 create mode 100644 static/openbsd/man3/pthread_attr_setstack.3 create mode 100644 static/openbsd/man3/pthread_attr_setstackaddr.3 create mode 100644 static/openbsd/man3/pthread_attr_setstacksize.3 create mode 100644 static/openbsd/man3/pthread_barrier_init.3 create mode 100644 static/openbsd/man3/pthread_barrier_wait.3 create mode 100644 static/openbsd/man3/pthread_barrierattr_getpshared.3 create mode 100644 static/openbsd/man3/pthread_barrierattr_init.3 create mode 100644 static/openbsd/man3/pthread_cancel.3 create mode 100644 static/openbsd/man3/pthread_cleanup_pop.3 create mode 100644 static/openbsd/man3/pthread_cleanup_push.3 create mode 100644 static/openbsd/man3/pthread_cond_init.3 create mode 100644 static/openbsd/man3/pthread_condattr_init.3 create mode 100644 static/openbsd/man3/pthread_create.3 create mode 100644 static/openbsd/man3/pthread_detach.3 create mode 100644 static/openbsd/man3/pthread_equal.3 create mode 100644 static/openbsd/man3/pthread_exit.3 create mode 100644 static/openbsd/man3/pthread_getconcurrency.3 create mode 100644 static/openbsd/man3/pthread_getcpuclockid.3 create mode 100644 static/openbsd/man3/pthread_getspecific.3 create mode 100644 static/openbsd/man3/pthread_join.3 create mode 100644 static/openbsd/man3/pthread_key_create.3 create mode 100644 static/openbsd/man3/pthread_key_delete.3 create mode 100644 static/openbsd/man3/pthread_kill.3 create mode 100644 static/openbsd/man3/pthread_main_np.3 create mode 100644 static/openbsd/man3/pthread_mutex_init.3 create mode 100644 static/openbsd/man3/pthread_mutexattr.3 create mode 100644 static/openbsd/man3/pthread_once.3 create mode 100644 static/openbsd/man3/pthread_rwlock_init.3 create mode 100644 static/openbsd/man3/pthread_rwlockattr_destroy.3 create mode 100644 static/openbsd/man3/pthread_rwlockattr_getpshared.3 create mode 100644 static/openbsd/man3/pthread_rwlockattr_init.3 create mode 100644 static/openbsd/man3/pthread_rwlockattr_setpshared.3 create mode 100644 static/openbsd/man3/pthread_schedparam.3 create mode 100644 static/openbsd/man3/pthread_self.3 create mode 100644 static/openbsd/man3/pthread_set_name_np.3 create mode 100644 static/openbsd/man3/pthread_setspecific.3 create mode 100644 static/openbsd/man3/pthread_sigmask.3 create mode 100644 static/openbsd/man3/pthread_spin_init.3 create mode 100644 static/openbsd/man3/pthread_spin_lock.3 create mode 100644 static/openbsd/man3/pthread_spin_unlock.3 create mode 100644 static/openbsd/man3/pthread_stackseg_np.3 create mode 100644 static/openbsd/man3/pthread_testcancel.3 create mode 100644 static/openbsd/man3/pthread_yield.3 create mode 100644 static/openbsd/man3/pthreads.3 create mode 100644 static/openbsd/man3/ptsname.3 create mode 100644 static/openbsd/man3/putc.3 create mode 100644 static/openbsd/man3/putwc.3 create mode 100644 static/openbsd/man3/pw_dup.3 create mode 100644 static/openbsd/man3/pw_init.3 create mode 100644 static/openbsd/man3/pw_lock.3 create mode 100644 static/openbsd/man3/qsort.3 create mode 100644 static/openbsd/man3/radius_new_request_packet.3 create mode 100644 static/openbsd/man3/radixsort.3 create mode 100644 static/openbsd/man3/raise.3 create mode 100644 static/openbsd/man3/rand.3 create mode 100644 static/openbsd/man3/rand48.3 create mode 100644 static/openbsd/man3/random.3 create mode 100644 static/openbsd/man3/rcmd.3 create mode 100644 static/openbsd/man3/rcmdsh.3 create mode 100644 static/openbsd/man3/readlabelfs.3 create mode 100644 static/openbsd/man3/readline.3 create mode 100644 static/openbsd/man3/readpassphrase.3 create mode 100644 static/openbsd/man3/realpath.3 create mode 100644 static/openbsd/man3/recno.3 create mode 100644 static/openbsd/man3/regex.3 create mode 100644 static/openbsd/man3/remainder.3 create mode 100644 static/openbsd/man3/remove.3 create mode 100644 static/openbsd/man3/res_init.3 create mode 100644 static/openbsd/man3/resizeterm.3 create mode 100644 static/openbsd/man3/rint.3 create mode 100644 static/openbsd/man3/round.3 create mode 100644 static/openbsd/man3/rpc.3 create mode 100644 static/openbsd/man3/rs256_pk_new.3 create mode 100644 static/openbsd/man3/s2i_ASN1_INTEGER.3 create mode 100644 static/openbsd/man3/scalbn.3 create mode 100644 static/openbsd/man3/scandir.3 create mode 100644 static/openbsd/man3/scanf.3 create mode 100644 static/openbsd/man3/sched_get_priority_min.3 create mode 100644 static/openbsd/man3/sdbm.3 create mode 100644 static/openbsd/man3/sem_destroy.3 create mode 100644 static/openbsd/man3/sem_getvalue.3 create mode 100644 static/openbsd/man3/sem_init.3 create mode 100644 static/openbsd/man3/sem_open.3 create mode 100644 static/openbsd/man3/sem_post.3 create mode 100644 static/openbsd/man3/sem_wait.3 create mode 100644 static/openbsd/man3/setbuf.3 create mode 100644 static/openbsd/man3/setjmp.3 create mode 100644 static/openbsd/man3/setlocale.3 create mode 100644 static/openbsd/man3/setmode.3 create mode 100644 static/openbsd/man3/setproctitle.3 create mode 100644 static/openbsd/man3/setvbuf.3 create mode 100644 static/openbsd/man3/shm_open.3 create mode 100644 static/openbsd/man3/sigaddset.3 create mode 100644 static/openbsd/man3/sigblock.3 create mode 100644 static/openbsd/man3/siginterrupt.3 create mode 100644 static/openbsd/man3/signal.3 create mode 100644 static/openbsd/man3/sigpause.3 create mode 100644 static/openbsd/man3/sigsetmask.3 create mode 100644 static/openbsd/man3/sigvec.3 create mode 100644 static/openbsd/man3/sigwait.3 create mode 100644 static/openbsd/man3/sin.3 create mode 100644 static/openbsd/man3/sincos.3 create mode 100644 static/openbsd/man3/sinh.3 create mode 100644 static/openbsd/man3/sio_open.3 create mode 100644 static/openbsd/man3/sioctl_open.3 create mode 100644 static/openbsd/man3/skey.3 create mode 100644 static/openbsd/man3/sleep.3 create mode 100644 static/openbsd/man3/sockatmark.3 create mode 100644 static/openbsd/man3/sqrt.3 create mode 100644 static/openbsd/man3/ssl.3 create mode 100644 static/openbsd/man3/statvfs.3 create mode 100644 static/openbsd/man3/stdio.3 create mode 100644 static/openbsd/man3/stpcpy.3 create mode 100644 static/openbsd/man3/strcasecmp.3 create mode 100644 static/openbsd/man3/strcat.3 create mode 100644 static/openbsd/man3/strchr.3 create mode 100644 static/openbsd/man3/strcmp.3 create mode 100644 static/openbsd/man3/strcoll.3 create mode 100644 static/openbsd/man3/strcpy.3 create mode 100644 static/openbsd/man3/strcspn.3 create mode 100644 static/openbsd/man3/strdup.3 create mode 100644 static/openbsd/man3/strerror.3 create mode 100644 static/openbsd/man3/strftime.3 create mode 100644 static/openbsd/man3/strlcpy.3 create mode 100644 static/openbsd/man3/strlen.3 create mode 100644 static/openbsd/man3/strmode.3 create mode 100644 static/openbsd/man3/strncat.3 create mode 100644 static/openbsd/man3/strncpy.3 create mode 100644 static/openbsd/man3/strpbrk.3 create mode 100644 static/openbsd/man3/strptime.3 create mode 100644 static/openbsd/man3/strrchr.3 create mode 100644 static/openbsd/man3/strsep.3 create mode 100644 static/openbsd/man3/strsignal.3 create mode 100644 static/openbsd/man3/strspn.3 create mode 100644 static/openbsd/man3/strstr.3 create mode 100644 static/openbsd/man3/strtod.3 create mode 100644 static/openbsd/man3/strtofflags.3 create mode 100644 static/openbsd/man3/strtok.3 create mode 100644 static/openbsd/man3/strtol.3 create mode 100644 static/openbsd/man3/strtonum.3 create mode 100644 static/openbsd/man3/strtoul.3 create mode 100644 static/openbsd/man3/strxfrm.3 create mode 100644 static/openbsd/man3/swab.3 create mode 100644 static/openbsd/man3/sysconf.3 create mode 100644 static/openbsd/man3/syslog.3 create mode 100644 static/openbsd/man3/system.3 create mode 100644 static/openbsd/man3/tan.3 create mode 100644 static/openbsd/man3/tanh.3 create mode 100644 static/openbsd/man3/tcgetpgrp.3 create mode 100644 static/openbsd/man3/tcgetsid.3 create mode 100644 static/openbsd/man3/tcsendbreak.3 create mode 100644 static/openbsd/man3/tcsetattr.3 create mode 100644 static/openbsd/man3/tcsetpgrp.3 create mode 100644 static/openbsd/man3/term_variables.3 create mode 100644 static/openbsd/man3/termcap.3 create mode 100644 static/openbsd/man3/terminfo.3 create mode 100644 static/openbsd/man3/time.3 create mode 100644 static/openbsd/man3/time2posix.3 create mode 100644 static/openbsd/man3/times.3 create mode 100644 static/openbsd/man3/timespec_get.3 create mode 100644 static/openbsd/man3/timingsafe_bcmp.3 create mode 100644 static/openbsd/man3/tls_accept_socket.3 create mode 100644 static/openbsd/man3/tls_client.3 create mode 100644 static/openbsd/man3/tls_config_ocsp_require_stapling.3 create mode 100644 static/openbsd/man3/tls_config_set_protocols.3 create mode 100644 static/openbsd/man3/tls_config_set_session_id.3 create mode 100644 static/openbsd/man3/tls_config_verify.3 create mode 100644 static/openbsd/man3/tls_conn_version.3 create mode 100644 static/openbsd/man3/tls_connect.3 create mode 100644 static/openbsd/man3/tls_init.3 create mode 100644 static/openbsd/man3/tls_load_file.3 create mode 100644 static/openbsd/man3/tls_ocsp_process_response.3 create mode 100644 static/openbsd/man3/tls_read.3 create mode 100644 static/openbsd/man3/tmpnam.3 create mode 100644 static/openbsd/man3/toascii.3 create mode 100644 static/openbsd/man3/tolower.3 create mode 100644 static/openbsd/man3/toupper.3 create mode 100644 static/openbsd/man3/towctrans.3 create mode 100644 static/openbsd/man3/towlower.3 create mode 100644 static/openbsd/man3/trunc.3 create mode 100644 static/openbsd/man3/tsearch.3 create mode 100644 static/openbsd/man3/ttyname.3 create mode 100644 static/openbsd/man3/tzset.3 create mode 100644 static/openbsd/man3/ualarm.3 create mode 100644 static/openbsd/man3/uname.3 create mode 100644 static/openbsd/man3/ungetc.3 create mode 100644 static/openbsd/man3/ungetwc.3 create mode 100644 static/openbsd/man3/unvis.3 create mode 100644 static/openbsd/man3/usbhid.3 create mode 100644 static/openbsd/man3/uselocale.3 create mode 100644 static/openbsd/man3/user_from_uid.3 create mode 100644 static/openbsd/man3/usleep.3 create mode 100644 static/openbsd/man3/utime.3 create mode 100644 static/openbsd/man3/uu_lock.3 create mode 100644 static/openbsd/man3/uuid_compare.3 create mode 100644 static/openbsd/man3/v2i_ASN1_BIT_STRING.3 create mode 100644 static/openbsd/man3/va.3 create mode 100644 static/openbsd/man3/valloc.3 create mode 100644 static/openbsd/man3/vis.3 create mode 100644 static/openbsd/man3/wcrtomb.3 create mode 100644 static/openbsd/man3/wcscasecmp.3 create mode 100644 static/openbsd/man3/wcscat.3 create mode 100644 static/openbsd/man3/wcschr.3 create mode 100644 static/openbsd/man3/wcscmp.3 create mode 100644 static/openbsd/man3/wcscoll.3 create mode 100644 static/openbsd/man3/wcscpy.3 create mode 100644 static/openbsd/man3/wcscspn.3 create mode 100644 static/openbsd/man3/wcsdup.3 create mode 100644 static/openbsd/man3/wcsftime.3 create mode 100644 static/openbsd/man3/wcslcpy.3 create mode 100644 static/openbsd/man3/wcslen.3 create mode 100644 static/openbsd/man3/wcspbrk.3 create mode 100644 static/openbsd/man3/wcsrchr.3 create mode 100644 static/openbsd/man3/wcsrtombs.3 create mode 100644 static/openbsd/man3/wcsspn.3 create mode 100644 static/openbsd/man3/wcsstr.3 create mode 100644 static/openbsd/man3/wcstod.3 create mode 100644 static/openbsd/man3/wcstok.3 create mode 100644 static/openbsd/man3/wcstol.3 create mode 100644 static/openbsd/man3/wcstombs.3 create mode 100644 static/openbsd/man3/wcswidth.3 create mode 100644 static/openbsd/man3/wcsxfrm.3 create mode 100644 static/openbsd/man3/wctob.3 create mode 100644 static/openbsd/man3/wctomb.3 create mode 100644 static/openbsd/man3/wctrans.3 create mode 100644 static/openbsd/man3/wctype.3 create mode 100644 static/openbsd/man3/wcwidth.3 create mode 100644 static/openbsd/man3/wmemchr.3 create mode 100644 static/openbsd/man3/wmemcmp.3 create mode 100644 static/openbsd/man3/wmemcpy.3 create mode 100644 static/openbsd/man3/wmemmove.3 create mode 100644 static/openbsd/man3/wmemset.3 create mode 100644 static/openbsd/man3/wprintf.3 create mode 100644 static/openbsd/man3/wresize.3 create mode 100644 static/openbsd/man3/wscanf.3 create mode 100644 static/openbsd/man3/x509_verify.3 create mode 100644 static/openbsd/man3/xdr.3 create mode 100644 static/openbsd/man3/yp_bind.3 (limited to 'static/openbsd/man3') diff --git a/static/openbsd/man3/ACCESS_DESCRIPTION_new.3 b/static/openbsd/man3/ACCESS_DESCRIPTION_new.3 new file mode 100644 index 00000000..bfa915c8 --- /dev/null +++ b/static/openbsd/man3/ACCESS_DESCRIPTION_new.3 @@ -0,0 +1,152 @@ +.\" $OpenBSD: ACCESS_DESCRIPTION_new.3,v 1.7 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt ACCESS_DESCRIPTION_NEW 3 +.Os +.Sh NAME +.Nm ACCESS_DESCRIPTION_new , +.Nm ACCESS_DESCRIPTION_free , +.Nm AUTHORITY_INFO_ACCESS_new , +.Nm AUTHORITY_INFO_ACCESS_free +.Nd X.509 information access extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft ACCESS_DESCRIPTION * +.Fn ACCESS_DESCRIPTION_new void +.Ft void +.Fn ACCESS_DESCRIPTION_free "ACCESS_DESCRIPTION *ad" +.Ft AUTHORITY_INFO_ACCESS +.Fn AUTHORITY_INFO_ACCESS_new void +.Ft void +.Fn AUTHORITY_INFO_ACCESS_free "AUTHORITY_INFO_ACCESS *aia" +.Sh DESCRIPTION +Using the information access extensions, certificates and certificate +revocation lists can point to auxiliary information and services +available online, for example online validation services or CA +policy data. +.Pp +.Fn ACCESS_DESCRIPTION_new +allocates and initializes an empty +.Vt ACCESS_DESCRIPTION +object, representing an ASN.1 +.Vt AccessDescription +structure defined in RFC 5280 section 4.2.2.1. +It can hold a pointer to a +.Vt GENERAL_NAME +object documented in +.Xr GENERAL_NAME_new 3 +and an access method identifier. +.Fn ACCESS_DESCRIPTION_free +frees +.Fa ad . +.Pp +The access method identifier is somewhat misnamed; it identifies +the type and format of the information provided. +How to access that information is often obvious from the +.Vt GENERAL_NAME +which may for example include a uniform resource identifier. +.Pp +Four standard access method identifiers are defined in RFC 5280: +.Bl -bullet +.It +.Qq id-ad-caIssuers +can occur in the authority information access extension of certificates +and certificate revocation lists and provides access to certificates +issued to the CA that issued the certificate, or provides access +to certificates used for signing the CRL, in order to help constructing +a certification path. +.It +.Qq id-ad-ocsp +can occur in the authority information access extension of certificates +and provides access to revocation information via the Online +Certificate Status Protocol (OCSP) defined in RFC 6960. +.It +.Qq id-ad-caRepository +can occur in the subject information access extension of CA +certificates and provides access to an online repository of +certificates issued by the CA. +.It +.Qq id-ad-timeStamping +can occur in the subject information access extension of end entity +certificates and indicates that the subject offers timestamping +services using the Time Stamp Protocol defined in RFC 3161. +.El +.Pp +.Fn AUTHORITY_INFO_ACCESS_new +allocates and initializes an empty +.Vt AUTHORITY_INFO_ACCESS +object, which is a +.Vt STACK_OF(ACCESS_DESCRIPTION) +and represents an ASN.1 +.Vt AuthorityInfoAccessSyntax +structure defined in RFC 5280 section 4.2.2.1. +It can be used for the authority information access extension of +certificates and certificate revocation lists and for the subject +information access extension of certificates. +.Fn AUTHORITY_INFO_ACCESS_free +frees +.Fa aia . +.Sh RETURN VALUES +.Fn ACCESS_DESCRIPTION_new +and +.Fn AUTHORITY_INFO_ACCESS_new +return the new +.Vt ACCESS_DESCRIPTION +or +.Vt AUTHORITY_INFO_ACCESS +object, respectively, or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_ACCESS_DESCRIPTION 3 , +.Xr DIST_POINT_new 3 , +.Xr GENERAL_NAME_new 3 , +.Xr OCSP_REQUEST_new 3 , +.Xr TS_REQ_new 3 , +.Xr X509_CRL_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_new 3 +.Sh STANDARDS +These extensions are only defined in the following RFC and not +specified in the underlying X.509 standard. +.Pp +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile: +.Bl -dash -compact +.It +section 4.2.2.1: Certificate Extensions: Authority Information Access +.It +section 4.2.2.2: Certificate Extensions: Subject Information Access +.It +section 5.2.7: CRL Extensions: Authority Information Access +.El +.Pp +Regarding OCSP and TSP, see: +.Pp +RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate +Status Protocol +.Pp +RFC 3161: Internet X.509 Public Key Infrastructure Time-Stamp Protocol +.Sh HISTORY +.Fn ACCESS_DESCRIPTION_new , +.Fn ACCESS_DESCRIPTION_free , +.Fn AUTHORITY_INFO_ACCESS_new , +and +.Fn AUTHORITY_INFO_ACCESS_free +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/AES_encrypt.3 b/static/openbsd/man3/AES_encrypt.3 new file mode 100644 index 00000000..0a3c63dc --- /dev/null +++ b/static/openbsd/man3/AES_encrypt.3 @@ -0,0 +1,174 @@ +.\" $OpenBSD: AES_encrypt.3,v 1.3 2025/12/20 08:51:56 tb Exp $ +.\" +.\" Copyright (c) 2019 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 $Mdocdate: December 20 2025 $ +.Dt AES_ENCRYPT 3 +.Os +.Sh NAME +.Nm AES_set_encrypt_key , +.Nm AES_set_decrypt_key , +.Nm AES_encrypt , +.Nm AES_decrypt , +.Nm AES_cbc_encrypt +.Nd low-level interface to the AES symmetric cipher +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/aes.h +.Ft int +.Fo AES_set_encrypt_key +.Fa "const unsigned char *userKey" +.Fa "const int bits" +.Fa "AES_KEY *key" +.Fc +.Ft int +.Fo AES_set_decrypt_key +.Fa "const unsigned char *userKey" +.Fa "const int bits" +.Fa "AES_KEY *key" +.Fc +.Ft void +.Fo AES_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "const AES_KEY *key" +.Fc +.Ft void +.Fo AES_decrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "const AES_KEY *key" +.Fc +.Ft void +.Fo AES_cbc_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "size_t length" +.Fa "const AES_KEY *key" +.Fa "unsigned char *ivec" +.Fa "const int enc" +.Fc +.Sh DESCRIPTION +These functions provide a low-level interface to the AES symmetric +cipher algorithm, also called Rijndael. +For reasons of flexibility, it is recommended that application +programs use the high-level interface described in +.Xr EVP_EncryptInit 3 +and +.Xr EVP_aes_128_cbc 3 +instead whenever possible. +.Pp +.Vt AES_KEY +is a structure that can hold up to 60 +.Vt int +values and a number of rounds. +.Pp +.Fn AES_set_encrypt_key +expands the +.Fa userKey , +which is +.Fa bits +long, into the +.Fa key +structure to prepare for encryption. +The number of bits and bytes read from +.Fa userKey , +the number of +.Vt int +values stored into +.Fa key , +and the number of rounds are as follows: +.Pp +.Bl -column bits bytes ints rounds -offset indent -compact +.It bits Ta bytes Ta ints Ta rounds +.It 128 Ta 16 Ta 44 Ta 10 +.It 192 Ta 24 Ta 52 Ta 12 +.It 256 Ta 32 Ta 60 Ta 14 +.El +.Pp +.Fn AES_set_decrypt_key +does the same, but in preparation for decryption. +.Pp +.Fn AES_encrypt +reads a single 16 byte block from +.Pf * Fa in , +encrypts it with the +.Fa key , +and writes the 16 resulting bytes to +.Pf * Fa out . +The 16 byte buffers starting at +.Fa in +and +.Fa out +can overlap, and +.Fa in +and +.Fa out +can even point to the same memory location. +.Pp +.Fn AES_decrypt +decrypts a single block and is otherwise identical to +.Fn AES_encrypt . +.Pp +If +.Fa enc +is non-zero, +.Fn AES_cbc_encrypt +encrypts +.Fa len +bytes at +.Fa in +to +.Fa out +using the 128 bit +.Fa key +and the 128 bit +initialization vector +.Fa ivec +in CBC mode. +If +.Fa enc +is 0, +.Fn AES_cbc_encrypt +performs the corresponding decryption. +.Sh RETURN VALUES +.Fn AES_set_encrypt_key +and +.Fn AES_set_decrypt_key +return 0 for success, -1 if +.Fa userKey +or +.Fa key +is +.Dv NULL , +or -2 if the number of +.Fa bits +is unsupported. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr EVP_aes_128_cbc 3 , +.Xr EVP_EncryptInit 3 +.Sh STANDARDS +ISO/IEC 18033-3:2010 +Information technology \(em Security techniques \(em +Encryption algorithms \(em Part 3: Block ciphers +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.2 . +.Sh AUTHORS +.An Vincent Rijmen +.An Antoon Bosselaers +.An Paulo Barreto diff --git a/static/openbsd/man3/ASIdentifiers_new.3 b/static/openbsd/man3/ASIdentifiers_new.3 new file mode 100644 index 00000000..f5f4a121 --- /dev/null +++ b/static/openbsd/man3/ASIdentifiers_new.3 @@ -0,0 +1,139 @@ +.\" $OpenBSD: ASIdentifiers_new.3,v 1.12 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: June 8 2025 $ +.Dt ASIDENTIFIERS_NEW 3 +.Os +.Sh NAME +.Nm ASIdentifiers_new , +.Nm ASIdentifiers_free , +.Nm d2i_ASIdentifiers , +.Nm i2d_ASIdentifiers +.Nd RFC 3779 autonomous system identifier delegation extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft ASIdentifiers * +.Fo ASIdentifiers_new +.Fa "void" +.Fc +.Ft void +.Fo ASIdentifiers_free +.Fa "ASIdentifiers *asid" +.Fc +.Ft ASIdentifiers * +.Fo d2i_ASIdentifiers +.Fa "ASIdentifiers **asid" +.Fa "const unsigned char **in" +.Fa "long len" +.Fc +.Ft int +.Fo i2d_ASIdentifiers +.Fa "ASIdentifiers *asid" +.Fa "unsigned char **out" +.Fc +.Sh DESCRIPTION +RFC 3779 defines two X.509v3 certificate extensions that allow the +delegation of +IP addresses and autonomous system (AS) identifiers +from the issuer to the subject of the certificate. +An +.Vt ASIdentifiers +object contains collections of individual AS numbers and +ranges of AS numbers to be delegated. +.Pp +.Fn ASIdentifiers_new +allocates and initializes a new, empty +.Vt ASIdentifiers +object that can be populated with +.Xr X509v3_asid_add_id_or_range 3 . +See +.Xr ASRange_new 3 +for implementation details. +.Pp +.Fn ASIdentifiers_free +frees +.Fa asid +including any data contained in it. +If +.Fa asid +is +.Dv NULL , +no action occurs. +.Pp +.Fn d2i_ASIdentifiers +and +.Fn i2d_ASIdentifiers +decode and encode ASN.1 +.Vt ASIdentifiers +objects as defined in RFC 3779, section 3.2.3.1. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +In order for the encoding produced by +.Fn i2d_ASIdentifiers +to conform to RFC 3779, +.Fa asid +must be in +.Dq canonical form , +see +.Xr X509v3_asid_canonize 3 . +.Sh RETURN VALUES +.Fn ASIdentifiers_new +returns a new +.Vt ASIdentifiers +object or +.Dv NULL +if an error occurs. +.Pp +.Fn d2i_ASIdentifiers +returns an +.Vt ASIdentifiers +object or +.Dv NULL +if a decoding or memory allocation error occurs. +.Pp +.Fn i2d_ASIdentifiers +returns the number of bytes successfully encoded +or a value <= 0 if an error occurs. +.Sh SEE ALSO +.Xr ASRange_new 3 , +.Xr crypto 3 , +.Xr IPAddressRange_new 3 , +.Xr X509_new 3 , +.Xr X509v3_addr_add_inherit 3 , +.Xr X509v3_addr_get_range 3 , +.Xr X509v3_addr_inherits 3 , +.Xr X509v3_addr_subset 3 , +.Xr X509v3_addr_validate_path 3 , +.Xr X509v3_asid_add_id_or_range 3 +.Sh STANDARDS +RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: +.Bl -dash -compact +.It +section 3: Autonomous System Identifier Delegation Extension +.El +.Pp +RFC 7020: The Internet Numbers Registry System +.Pp +RFC 7249: Internet Numbers Registries +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . +.Sh BUGS +There are no corresponding functions for the RFC 3779 +IP address delegation extension represented by +.Vt IPAddrBlocks . diff --git a/static/openbsd/man3/ASN1_BIT_STRING_set.3 b/static/openbsd/man3/ASN1_BIT_STRING_set.3 new file mode 100644 index 00000000..d3ab3b1e --- /dev/null +++ b/static/openbsd/man3/ASN1_BIT_STRING_set.3 @@ -0,0 +1,140 @@ +.\" $OpenBSD: ASN1_BIT_STRING_set.3,v 1.6 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_BIT_STRING_SET 3 +.Os +.Sh NAME +.Nm ASN1_BIT_STRING_set , +.Nm ASN1_BIT_STRING_set_bit , +.Nm ASN1_BIT_STRING_get_bit +.Nd ASN.1 BIT STRING accessors +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo ASN1_BIT_STRING_set +.Fa "ASN1_BIT_STRING *bitstr" +.Fa "unsigned char *data" +.Fa "int len" +.Fc +.Ft int +.Fo ASN1_BIT_STRING_set_bit +.Fa "ASN1_BIT_STRING *bitstr" +.Fa "int bitnumber" +.Fa "int set" +.Fc +.Ft int +.Fo ASN1_BIT_STRING_get_bit +.Fa "ASN1_BIT_STRING *bitstr" +.Fa "int bitnumber" +.Fc +.Sh DESCRIPTION +.Fn ASN1_BIT_STRING_set +sets the length attribute of +.Fa bitstr +to +.Fa len +and copies that number of bytes from +.Fa data +into +.Fa bitstr , +overwriting any previous data, by merely calling +.Xr ASN1_STRING_set 3 . +This function does no validation whatsoever. +In particular, it neither checks that +.Fa bitstr +is actually of the type +.Dv V_ASN1_BIT_STRING +nor, even if it is, that the +.Fa data +and +.Fa len +arguments make sense for this particular bit string. +.Pp +If the +.Fa set +argument is non-zero, +.Fn ASN1_BIT_STRING_set_bit +sets the bit with the given +.Fa bitnumber +in the +.Fa bitstr ; +otherwise, it clears that bit. +A +.Fa bitnumber +of 0 addresses the most significant bit in the first data byte of +.Fa bitstr , +7 the least significant bit in the same byte, +8 the most significant bit in the second data byte, and so on. +.Pp +If setting a bit is requested beyond the last existing data byte, +additional bytes are added to the +.Fa bitstr +as needed. +After clearing a bit, any trailing NUL bytes are removed from the +.Fa bitstr . +.Pp +.Fn ASN1_BIT_STRING_get_bit +checks that the bit with the given +.Fa bitnumber +is set in +.Fa bitstr . +.Sh RETURN VALUES +.Fn ASN1_BIT_STRING_set +returns 1 on success or 0 if memory allocation fails or if +.Fa data +is +.Dv NULL +and +.Fa len +is \-1 in the same call. +.Pp +.Fn ASN1_BIT_STRING_set_bit +returns 1 on success or 0 if +.Fa bitstr +is +.Dv NULL +or if memory allocation fails. +.Pp +.Fn ASN1_BIT_STRING_get_bit +returns 1 if the bit with the given +.Fa bitnumber +is set in the +.Fa bitstr +or 0 if +.Fa bitstr +is +.Dv NULL , +if +.Fa bitnumber +points beyond the last data byte in +.Fa bitstr , +or if the requested bit is not set. +.Sh SEE ALSO +.Xr ASN1_BIT_STRING_new 3 , +.Xr ASN1_STRING_set 3 , +.Xr d2i_ASN1_BIT_STRING 3 , +.Xr v2i_ASN1_BIT_STRING 3 +.Sh HISTORY +.Fn ASN1_BIT_STRING_set +first appeared in SSLeay 0.6.5. +.Fn ASN1_BIT_STRING_set_bit +and +.Fn ASN1_BIT_STRING_get_bit +first appeared in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/ASN1_INTEGER_get.3 b/static/openbsd/man3/ASN1_INTEGER_get.3 new file mode 100644 index 00000000..985e2e50 --- /dev/null +++ b/static/openbsd/man3/ASN1_INTEGER_get.3 @@ -0,0 +1,429 @@ +.\" $OpenBSD: ASN1_INTEGER_get.3,v 1.8 2025/06/08 22:40:29 schwarze Exp $ +.\" selective merge up to: +.\" OpenSSL man3/ASN1_INTEGER_get_int64 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2021, 2022 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ASN1_INTEGER_GET 3 +.Os +.Sh NAME +.Nm ASN1_INTEGER_get_uint64 , +.Nm ASN1_INTEGER_get_int64 , +.Nm ASN1_INTEGER_get , +.Nm ASN1_INTEGER_set_uint64 , +.Nm ASN1_INTEGER_set_int64 , +.Nm ASN1_INTEGER_set , +.Nm ASN1_INTEGER_cmp , +.Nm ASN1_INTEGER_dup , +.Nm BN_to_ASN1_INTEGER , +.Nm ASN1_INTEGER_to_BN , +.Nm ASN1_ENUMERATED_get_int64 , +.Nm ASN1_ENUMERATED_get , +.Nm ASN1_ENUMERATED_set_int64 , +.Nm ASN1_ENUMERATED_set , +.Nm BN_to_ASN1_ENUMERATED , +.Nm ASN1_ENUMERATED_to_BN +.Nd ASN.1 INTEGER and ENUMERATED utilities +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo ASN1_INTEGER_get_uint64 +.Fa "uint64_t *out_val" +.Fa "const ASN1_INTEGER *a" +.Fc +.Ft int +.Fo ASN1_INTEGER_get_int64 +.Fa "int64_t *out_val" +.Fa "const ASN1_INTEGER *a" +.Fc +.Ft long +.Fo ASN1_INTEGER_get +.Fa "const ASN1_INTEGER *a" +.Fc +.Ft int +.Fo ASN1_INTEGER_set_uint64 +.Fa "ASN1_INTEGER *a" +.Fa "uint64_t v" +.Fc +.Ft int +.Fo ASN1_INTEGER_set_int64 +.Fa "ASN1_INTEGER *a" +.Fa "int64_t v" +.Fc +.Ft int +.Fo ASN1_INTEGER_set +.Fa "ASN1_INTEGER *a" +.Fa "long v" +.Fc +.Ft int +.Fo ASN1_INTEGER_cmp +.Fa "const ASN1_INTEGER *a1" +.Fa "const ASN1_INTEGER *a2" +.Fc +.Ft ASN1_INTEGER * +.Fo ASN1_INTEGER_dup +.Fa "const ASN1_INTEGER *a" +.Fc +.Ft ASN1_INTEGER * +.Fo BN_to_ASN1_INTEGER +.Fa "const BIGNUM *bn" +.Fa "ASN1_INTEGER *ai" +.Fc +.Ft BIGNUM * +.Fo ASN1_INTEGER_to_BN +.Fa "const ASN1_INTEGER *ai" +.Fa "BIGNUM *bn" +.Fc +.Ft int +.Fo ASN1_ENUMERATED_get_int64 +.Fa "int64_t *out_val" +.Fa "const ASN1_ENUMERATED *a" +.Fc +.Ft long +.Fo ASN1_ENUMERATED_get +.Fa "const ASN1_ENUMERATED *a" +.Fc +.Ft int +.Fo ASN1_ENUMERATED_set_int64 +.Fa "ASN1_ENUMERATED *a" +.Fa "int64_t v" +.Fc +.Ft int +.Fo ASN1_ENUMERATED_set +.Fa "ASN1_ENUMERATED *a" +.Fa "long v" +.Fc +.Ft ASN1_ENUMERATED * +.Fo BN_to_ASN1_ENUMERATED +.Fa "const BIGNUM *bn" +.Fa "ASN1_ENUMERATED *ai" +.Fc +.Ft BIGNUM * +.Fo ASN1_ENUMERATED_to_BN +.Fa "const ASN1_ENUMERATED *ai" +.Fa "BIGNUM *bn" +.Fc +.Sh DESCRIPTION +These functions convert to and from +.Vt ASN1_INTEGER +and +.Vt ASN1_ENUMERATED +objects. +.Pp +.Fn ASN1_INTEGER_get_uint64 +and +.Fn ASN1_INTEGER_get_int64 +store the value of +.Fa a +in +.Pf * Fa out_val +if successful. +.Pp +The deprecated function +.Fn ASN1_INTEGER_get +converts +.Fa a +to the +.Vt long +type. +.Pp +.Fn ASN1_INTEGER_set_uint64 , +.Fn ASN1_INTEGER_set_int64 , +and +.Fn ASN1_INTEGER_set +set the type of +.Fa a +to +.Dv V_ASN1_INTEGER +or +.Dv V_ASN1_NEG_INTEGER +depending on the sign of +.Fa v +and set the value of +.Fa a +to +.Fa v . +.Pp +.Fn ASN1_INTEGER_cmp +compares the signed integer numbers represented by +.Fa a1 +and +.Fa a2 . +.Pp +.Fn ASN1_INTEGER_dup +does exactly the same as +.Xr ASN1_STRING_dup 3 +without providing any type safety, +except that it fails if the +.Xr ASN1_STRING_length 3 +of +.Fa a +is 0. +.Pp +.Fn BN_to_ASN1_INTEGER +converts +.Fa bn +to an +.Vt ASN1_INTEGER . +If +.Fa ai +is +.Dv NULL , +a new +.Vt ASN1_INTEGER +object is returned. +Otherwise, the existing object +.Fa ai +is used instead. +.Pp +.Fn ASN1_INTEGER_to_BN +converts +.Fa ai +into a +.Vt BIGNUM . +If +.Fa bn +is +.Dv NULL , +a new +.Vt BIGNUM +object is returned. +Otherwise, the existing object +.Fa bn +is used instead. +.Pp +.Fn ASN1_ENUMERATED_get_int64 , +.Fn ASN1_ENUMERATED_get , +.Fn ASN1_ENUMERATED_set_int64 , +.Fn ASN1_ENUMERATED_set , +.Fn BN_to_ASN1_ENUMERATED , +and +.Fn ASN1_ENUMERATED_to_BN +behave like their +.Vt ASN1_INTEGER +counterparts except that they operate on an +.Vt ASN1_ENUMERATED +object. +.Sh RETURN VALUES +.Fn ASN1_INTEGER_get_uint64 +returns 1 in case of success or 0 if +.Fa a +is not of the type +.Dv V_ASN1_INTEGER +or greater than +.Dv UINT64_MAX . +.Pp +.Fn ASN1_INTEGER_get_int64 +returns 1 in case of success or 0 if +.Fa a +is not of the type +.Dv V_ASN1_INTEGER +or +.Dv V_ASN1_NEG_INTEGER , +less than +.Dv INT64_MIN , +or greater than +.Dv INT64_MAX . +.Pp +.Fn ASN1_INTEGER_get +and +.Fn ASN1_ENUMERATED_get +return the converted value, 0 if +.Fa a +is +.Dv NULL , +or \-1 on error, which is ambiguous because \-1 is a legitimate +value for an +.Vt ASN1_INTEGER . +.Pp +.Fn ASN1_INTEGER_set_uint64 , +.Fn ASN1_INTEGER_set_int64 , +.Fn ASN1_INTEGER_set , +.Fn ASN1_ENUMERATED_set_int64 , +and +.Fn ASN1_ENUMERATED_set +return 1 for success or 0 for failure. +They only fail if a memory allocation error occurs. +.Pp +.Fn ASN1_INTEGER_cmp +returns a value greater than, equal to, or less than 0 +if the signed integer number represented by +.Fa a1 +is greater than, equal to, or less than +the signed integer number represented by +.Fa a2 , +respectively. +.Pp +.Fn ASN1_INTEGER_dup +returns a pointer to a newly allocated +.Vt ASN1_STRING +structure or +.Dv NULL +if +.Fa a +is a +.Dv NULL +pointer, if the length of +.Fa a +is 0, or if memory allocation fails. +.Pp +.Fn BN_to_ASN1_INTEGER +and +.Fn BN_to_ASN1_ENUMERATED +return an +.Vt ASN1_INTEGER +or +.Vt ASN1_ENUMERATED +object, respectively, or +.Dv NULL +if an error occurs. +They only fail due to memory allocation errors. +.Pp +.Fn ASN1_INTEGER_to_BN +and +.Fn ASN1_ENUMERATED_to_BN +return a +.Vt BIGNUM +object of +.Dv NULL +if an error occurs. +They can fail if the passed type is incorrect (due to a programming error) +or due to memory allocation failures. +.Sh SEE ALSO +.Xr ASN1_INTEGER_new 3 , +.Xr ASN1_STRING_length 3 +.Sh HISTORY +.Fn ASN1_INTEGER_set +first appeared in SSLeay 0.5.1. +.Fn ASN1_INTEGER_get , +.Fn BN_to_ASN1_INTEGER , +and +.Fn ASN1_INTEGER_to_BN +first appeared in SSLeay 0.6.0. +.Fn ASN1_INTEGER_cmp +and +.Fn ASN1_INTEGER_dup +first appeared in SSLeay 0.6.5. +These functions have been available since +.Ox 2.3 . +.Pp +.Fn ASN1_ENUMERATED_get , +.Fn ASN1_ENUMERATED_set , +.Fn BN_to_ASN1_ENUMERATED , +and +.Fn ASN1_ENUMERATED_to_BN +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . +.Pp +.Fn ASN1_INTEGER_get_uint64 , +.Fn ASN1_INTEGER_get_int64 , +.Fn ASN1_INTEGER_set_uint64 , +.Fn ASN1_INTEGER_set_int64 , +.Fn ASN1_ENUMERATED_get_int64 , +and +.Fn ASN1_ENUMERATED_set_int64 +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.2 . +.Sh CAVEATS +In general an +.Vt ASN1_INTEGER +or +.Vt ASN1_ENUMERATED +type can contain an integer of almost arbitrary size +and so cannot always be represented by a C +.Vt long +type. +The ambiguous return values of +.Fn ASN1_INTEGER_get +and +.Fn ASN1_ENUMERATED_get +imply that these functions should be avoided if possible. +.Sh BUGS +.Fn ASN1_INTEGER_cmp , +.Fn ASN1_INTEGER_dup , +and +.Fn ASN1_INTEGER_to_BN +do not check whether their arguments are really of the type +.Dv V_ASN1_INTEGER +or +.Dv V_ASN1_NEG_INTEGER . +They may report success even if their arguments are of a wrong type. +Consequently, even in case of success, the return value of +.Fn ASN1_INTEGER_dup +is not guaranteed to be of the type +.Dv V_ASN1_INTEGER +or +.Dv V_ASN1_NEG_INTEGER +either. +.Pp +Similarly, +.Fn ASN1_ENUMERATED_to_BN +does not check whether its argument is really of the type +.Dv V_ASN1_ENUMERATED +or +.Dv V_ASN1_NEG_ENUMERATED +and may report success even if the argument is of a wrong type. diff --git a/static/openbsd/man3/ASN1_NULL_new.3 b/static/openbsd/man3/ASN1_NULL_new.3 new file mode 100644 index 00000000..1244f2e2 --- /dev/null +++ b/static/openbsd/man3/ASN1_NULL_new.3 @@ -0,0 +1,67 @@ +.\" $OpenBSD: ASN1_NULL_new.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_NULL_NEW 3 +.Os +.Sh NAME +.Nm ASN1_NULL_new , +.Nm ASN1_NULL_free +.Nd ASN.1 NULL value +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_NULL * +.Fn ASN1_NULL_new void +.Ft void +.Fn ASN1_NULL_free "ASN1_NULL *val_in" +.Sh DESCRIPTION +.Fn ASN1_NULL_new +returns a specific invalid pointer that represents the ASN.1 NULL value, +which is the only possible value of the ASN.1 NULL type. +That pointer is different from a +.Dv NULL +pointer. +Dereferencing it almost certainly results in a segmentation fault. +This function does not allocate memory and cannot fail. +.Pp +.Fn ASN1_NULL_free +has no effect whatsoever. +In particular, it ignores the +.Fa val_in +argument and does not free any memory. +In normal use, application programs only pass the invalid pointer +obtained from +.Fn ASN1_NULL_new +to this function. +But even if a valid pointer is passed, that pointer does not become invalid. +.Pp +The ASN.1 NULL type is also represented by the +.Dv V_ASN1_NULL +type identifier constant. +.Sh SEE ALSO +.Xr ASN1_item_new 3 , +.Xr d2i_ASN1_NULL 3 +.Sh STANDARDS +ITU-T Recommendation X.208, also known as ISO/IEC 8824-1: +Specification of Abstract Syntax Notation One (ASN.1), +section 19: Notation for the null type +.Sh HISTORY +.Fn ASN1_NULL_new +and +.Fn ASN1_NULL_free +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/ASN1_OBJECT_new.3 b/static/openbsd/man3/ASN1_OBJECT_new.3 new file mode 100644 index 00000000..3df3dd8e --- /dev/null +++ b/static/openbsd/man3/ASN1_OBJECT_new.3 @@ -0,0 +1,229 @@ +.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.17 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2017, 2021, 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson. +.\" Copyright (c) 2002, 2006 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ASN1_OBJECT_NEW 3 +.Os +.Sh NAME +.Nm ASN1_OBJECT_new , +.Nm ASN1_OBJECT_create , +.Nm ASN1_OBJECT_free +.Nd ASN.1 object identifiers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_OBJECT * +.Fo ASN1_OBJECT_new +.Fa void +.Fc +.Ft ASN1_OBJECT * +.Fo ASN1_OBJECT_create +.Fa "int nid" +.Fa "unsigned char *content" +.Fa "int len" +.Fa "const char *short_name" +.Fa "const char *long_name" +.Fc +.Ft void +.Fo ASN1_OBJECT_free +.Fa "ASN1_OBJECT *a" +.Fc +.Sh DESCRIPTION +.Fn ASN1_OBJECT_new +allocates and initializes an empty +.Vt ASN1_OBJECT +object, representing an ASN.1 OBJECT IDENTIFIER. +It can hold a short name, a long name, a numeric identifier (NID), +and a sequence of integers identifying a node in the International +Object Identifier tree as specified in ITU-T recommendation X.660. +The new object is marked as dynamically allocated. +.Pp +The ASN.1 object identifier type is also represented by the +.Dv V_ASN1_OBJECT +type identifier constant. +.Pp +.Fn ASN1_OBJECT_create +allocates a new +.Vt ASN1_OBJECT +with the given +.Fa nid , +copies the +.Fa len +DER +.Fa content +octets, the +.Fa short_name , +and the +.Fa long_name +into it, and marks the new object and all data contained in it +as dynamically allocated. +.Pp +Application programs normally use utility functions like +.Xr OBJ_nid2obj 3 +rather than using +.Fn ASN1_OBJECT_new +or +.Fn ASN1_OBJECT_create +directly. +.Pp +.Fn ASN1_OBJECT_free +has the following effects: +.Pp +All data contained in +.Fa a +that is marked as dynamically allocated is freed, +and the respective fields of +.Fa a +become empty. +Contained data not marked as dynamically allocated remains intact. +.Pp +If the object +.Fa a +itself is marked as dynamically allocated, it is freed. +Otherwise, the pointer +.Fa a +remains valid. +.Pp +If +.Fa a +is a +.Dv NULL +pointer or if neither the object itself nor any of its content +is marked as dynamically allocated, no action occurs. +.Sh RETURN VALUES +.Fn ASN1_OBJECT_new +and +.Fn ASN1_OBJECT_create +return a pointer to the new object or +.Dv NULL +if memory allocation fails, +.Sh ERRORS +After failure of +.Fn ASN1_OBJECT_new +or +.Fn ASN1_OBJECT_create , +the following diagnostic can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" +Memory allocation failed. +.El +.Pp +After some cases of failure of +.Fn ASN1_OBJECT_create , +the following diagnostic can be retrieved in addition to the above: +.Bl -tag -width Ds +.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib" +Memory allocation failed. +.El +.Sh SEE ALSO +.Xr a2d_ASN1_OBJECT 3 , +.Xr ASN1_TYPE_get 3 , +.Xr d2i_ASN1_OBJECT 3 , +.Xr OBJ_create 3 , +.Xr OBJ_nid2obj 3 +.Sh STANDARDS +ITU-T Recommendation X.208, also known as ISO/IEC 8824-1: +Specification of Abstract Syntax Notation One (ASN.1), +section 28: Notation for the object identifier type +.Pp +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules: +Specification of Basic Encoding Rules (BER), Canonical Encoding +Rules (CER) and Distinguished Encoding Rules (DER), +section 8.19: Encoding of an object identifier value +.Sh HISTORY +.Fn ASN1_OBJECT_new +and +.Fn ASN1_OBJECT_free +first appeared in SSLeay 0.5.1 and +.Fn ASN1_OBJECT_create +in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Sh BUGS +The function +.Fn ASN1_OBJECT_new +is not useful for any practical purpose because the library does not +provide any function capable of adding data to an existing object. +Consequently, if the application program creates an object with +.Fn ASN1_OBJECT_new , +that object will always remain empty. +.Pp +Similarly, if an +.Fa nid +of +.Dv NID_undef +is passed to +.Fn ASN1_OBJECT_create , +or if +.Dv NULL +is passed for any of its pointer arguments, the returned object +will permanently remain incomplete. diff --git a/static/openbsd/man3/ASN1_PRINTABLE_type.3 b/static/openbsd/man3/ASN1_PRINTABLE_type.3 new file mode 100644 index 00000000..47288ee9 --- /dev/null +++ b/static/openbsd/man3/ASN1_PRINTABLE_type.3 @@ -0,0 +1,93 @@ +.\" $OpenBSD: ASN1_PRINTABLE_type.3,v 1.2 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_PRINTABLE_TYPE 3 +.Os +.Sh NAME +.Nm ASN1_PRINTABLE_type +.Nd classify a single-byte character string +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo ASN1_PRINTABLE_type +.Fa "const unsigned char *string" +.Fa "int len" +.Fc +.Sh DESCRIPTION +.Fn ASN1_PRINTABLE_type +assumes that the given +.Fa string +consists of single-byte characters and classifies it +according to which kinds characters occur. +If +.Fa len +is greater than 0, at most +.Fa len +characters are inspected. +Otherwise, the +.Fa string +needs to be NUL-terminated. +.Sh RETURN VALUES +If the given +.Fa string +contains a character outside the +.Xr ascii 7 +range, +.Fn ASN1_PRINTABLE_type +returns +.Dv V_ASN1_T61STRING . +.Pp +Otherwise, if it contains a character that is neither a letter +nor a digit nor the space character +.Po +.Ql "\ " , +ASCII 0x20 +.Pc +nor the apostrophe quote +.Po +.Ql \(aq , +ASCII 0x27 +.Pc +nor contained in the set +.Qq ()+,\-./:=?\& , +it returns +.Dv V_ASN1_IA5STRING . +.Pp +Otherwise, including if +.Fa string +is a +.Dv NULL +pointer or points to an empty string, it returns +.Dv V_ASN1_PRINTABLESTRING . +.Sh SEE ALSO +.Xr ASN1_mbstring_copy 3 , +.Xr ASN1_STRING_new 3 , +.Xr ASN1_STRING_to_UTF8 3 , +.Xr isascii 3 , +.Xr ascii 7 +.Sh HISTORY +.Fn ASN1_PRINTABLE_type +first appeared in SSLeay 0.4.5d, has been part of the public API +since SSLeay 0.5.1, and has been available since +.Ox 2.4 . +.Sh CAVEATS +The ASN.1 notion of what constitutes a +.Vt PrintableString +is more restrictive than what the C library function +.Xr isprint 3 +considers printable. diff --git a/static/openbsd/man3/ASN1_STRING_TABLE_get.3 b/static/openbsd/man3/ASN1_STRING_TABLE_get.3 new file mode 100644 index 00000000..f9e69a89 --- /dev/null +++ b/static/openbsd/man3/ASN1_STRING_TABLE_get.3 @@ -0,0 +1,91 @@ +.\" $OpenBSD: ASN1_STRING_TABLE_get.3,v 1.6 2025/12/31 13:48:01 tb Exp $ +.\" checked up to: +.\" OpenSSL ASN1_STRING_TABLE_add.pod 7b608d08 Jul 27 01:18:50 2017 +0800 +.\" +.\" Copyright (c) 2017, 2021 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 $Mdocdate: December 31 2025 $ +.Dt ASN1_STRING_TABLE_GET 3 +.Os +.Sh NAME +.Nm ASN1_STRING_TABLE_get +.Nd retrieve an entry from the global ASN.1 string table +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_STRING_TABLE * +.Fo ASN1_STRING_TABLE_get +.Fa "int nid" +.Fc +.Sh DESCRIPTION +The ASN.1 string table is a unique global object. +Each entry is of the type +.Vt ASN1_STRING_TABLE +and contains information about one NID object. +The entries are predefined according to RFC 5280 appendix A.1. +.Pp +The upper bounds for the number of characters in various kinds of +.Vt ASN1_STRING +objects are: +.Pp +.Bl -column -compact NID_organizationalUnitNa maxsi ub_organization_unit_na +.It object type Ta maxsize Ta symbolic constant +.It Dv NID_commonName Ta 64 Ta Dv ub_common_name +.It Dv NID_countryName Ta 2 Ta \(em +.It Dv NID_givenName Ta 32768 Ta Dv ub_name +.It Dv NID_initials Ta 32768 Ta Dv ub_name +.It Dv NID_localityName Ta 128 Ta Dv ub_locality_name +.It Dv NID_name Ta 32768 Ta Dv ub_name +.It Dv NID_organizationName Ta 64 Ta Dv ub_organization_name +.It Dv NID_organizationalUnitName Ta 64 Ta Dv ub_organization_unit_name +.It Dv NID_pkcs9_emailAddress Ta 128 Ta Dv ub_email_address +.It Dv NID_serialNumber Ta 64 Ta Dv ub_serial_number +.It Dv NID_stateOrProvinceName Ta 128 Ta Dv ub_state_name +.It Dv NID_surname Ta 32768 Ta Dv ub_name +.El +.Pp +The function +.Fn ASN1_STRING_TABLE_get +retrieves the entry for +.Fa nid . +If the +.Dv STABLE_NO_MASK +flag is set, +.Xr ASN1_STRING_set_by_NID 3 +skips applying the global mask that can be set with +.Xr ASN1_STRING_set_default_mask 3 . +.Sh RETURN VALUES +.Fn ASN1_STRING_TABLE_get +returns a valid +.Vt ASN1_STRING_TABLE +structure or +.Dv NULL +if nothing is found. +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr ASN1_STRING_set_by_NID 3 , +.Xr OBJ_create 3 , +.Xr OBJ_nid2obj 3 +.Sh HISTORY +.Fn ASN1_STRING_TABLE_get +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Sh BUGS +Most aspects of the semantics considerably differ from OpenSSL. +.Pp +.Dv ub_email_address , +which should really be called +.Dv ub_emailaddress_length , +was changed in RFC 5280 from 128 to 255 to match PKCS#9 (RFC 2985). diff --git a/static/openbsd/man3/ASN1_STRING_length.3 b/static/openbsd/man3/ASN1_STRING_length.3 new file mode 100644 index 00000000..922ae89a --- /dev/null +++ b/static/openbsd/man3/ASN1_STRING_length.3 @@ -0,0 +1,460 @@ +.\" $OpenBSD: ASN1_STRING_length.3,v 1.31 2025/06/08 22:37:23 schwarze Exp $ +.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2019, 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson. +.\" Copyright (c) 2002, 2006, 2013, 2015, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ASN1_STRING_LENGTH 3 +.Os +.Sh NAME +.Nm ASN1_STRING_cmp , +.Nm ASN1_OCTET_STRING_cmp , +.Nm ASN1_STRING_data , +.Nm ASN1_STRING_dup , +.Nm ASN1_OCTET_STRING_dup , +.Nm ASN1_STRING_get0_data , +.Nm ASN1_STRING_length , +.Nm ASN1_STRING_length_set , +.Nm ASN1_STRING_set0 , +.Nm ASN1_STRING_set , +.Nm ASN1_OCTET_STRING_set , +.Nm ASN1_STRING_copy , +.Nm ASN1_STRING_to_UTF8 , +.Nm ASN1_STRING_type +.Nd ASN1_STRING utility functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo ASN1_STRING_cmp +.Fa "const ASN1_STRING *a" +.Fa "const ASN1_STRING *b" +.Fc +.Ft int +.Fo ASN1_OCTET_STRING_cmp +.Fa "const ASN1_OCTET_STRING *a" +.Fa "const ASN1_OCTET_STRING *b" +.Fc +.Ft unsigned char * +.Fo ASN1_STRING_data +.Fa "ASN1_STRING *x" +.Fc +.Ft ASN1_STRING * +.Fo ASN1_STRING_dup +.Fa "const ASN1_STRING *a" +.Fc +.Ft ASN1_OCTET_STRING * +.Fo ASN1_OCTET_STRING_dup +.Fa "const ASN1_OCTET_STRING *a" +.Fc +.Ft const unsigned char * +.Fo ASN1_STRING_get0_data +.Fa "const ASN1_STRING *x" +.Fc +.Ft int +.Fo ASN1_STRING_length +.Fa "const ASN1_STRING *x" +.Fc +.Ft void +.Fo ASN1_STRING_length_set +.Fa "ASN1_STRING *x" +.Fa "int len" +.Fc +.Ft void +.Fo ASN1_STRING_set0 +.Fa "ASN1_STRING *str" +.Fa "void *data" +.Fa "int len" +.Fc +.Ft int +.Fo ASN1_STRING_set +.Fa "ASN1_STRING *str" +.Fa "const void *data" +.Fa "int len" +.Fc +.Ft int +.Fo ASN1_OCTET_STRING_set +.Fa "ASN1_OCTET_STRING *str" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft int +.Fo ASN1_STRING_copy +.Fa "ASN1_STRING *dst" +.Fa "const ASN1_STRING *src" +.Fc +.Ft int +.Fo ASN1_STRING_to_UTF8 +.Fa "unsigned char **out" +.Fa "const ASN1_STRING *in" +.Fc +.Ft int +.Fo ASN1_STRING_type +.Fa "const ASN1_STRING *x" +.Fc +.Sh DESCRIPTION +These functions manipulate +.Vt ASN1_STRING +structures. +.Pp +.Fn ASN1_STRING_cmp +compares the type, the length, and the content of +.Fa a +and +.Fa b . +.Pp +.Fn ASN1_OCTET_STRING_cmp +does exactly the same as +.Fn ASN1_STRING_cmp +without providing any type safety. +.Pp +.Fn ASN1_STRING_data +is similar to +.Fn ASN1_STRING_get0_data +except that the returned value is not constant. +This function is deprecated. +Applications should use +.Fn ASN1_STRING_get0_data +instead. +.Pp +.Fn ASN1_STRING_dup +allocates a new +.Vt ASN1_STRING +object and copies the type, length, data, and flags from +.Fa a +into it. +.Pp +.Fn ASN1_OCTET_STRING_dup +does exactly the same as +.Fn ASN1_STRING_dup +without providing any type safety. +.Pp +.Fn ASN1_STRING_get0_data +returns an internal pointer to the data of +.Fa x . +It should not be freed or modified in any way. +.Pp +.Fn ASN1_STRING_length +returns the length attribute of +.Fa x , +measured in bytes. +.Pp +.Fn ASN1_STRING_length_set +sets the length attribute of +.Fa x +to +.Fa len . +It may put +.Fa x +into an inconsistent internal state. +.Pp +.Fn ASN1_STRING_set0 +frees any data stored in +.Fa str , +sets the length attribute to +.Fa len +bytes, and sets the data attribute to +.Fa data , +transferring ownership, without doing any validation. +.Pp +.Fn ASN1_STRING_set +sets the length attribute of +.Fa str +to +.Fa len +and copies that number of bytes from +.Fa data +into +.Fa str , +overwriting any previous data. +If +.Fa len +is \-1, then +.Fn strlen data +is used instead of +.Fa len . +If +.Fa data +is +.Dv NULL , +the content of +.Fa str +remains uninitialized; that is not considered an error unless +.Fa len +is negative. +.Pp +.Fn ASN1_OCTET_STRING_set +does exactly the same as +.Fn ASN1_STRING_set +without providing any type safety. +.Pp +.Fn ASN1_STRING_copy +copies the length and data of +.Fa src +into +.Fa dst +using +.Fn ASN1_STRING_set +and changes the type and flags of +.Fa dst +to match the type and flags of +.Fa src . +.Pp +.Fn ASN1_STRING_to_UTF8 +converts the string +.Fa in +to UTF-8 format. +The converted data is copied into a newly allocated buffer +.Pf * Fa out . +The buffer +.Pf * Fa out +should be freed using +.Xr free 3 . +.Pp +.Fn ASN1_STRING_type +returns the type of +.Fa x . +If the bit +.Dv V_ASN1_NEG +is set in the return value, +.Fa x +is an ASN.1 INTEGER or ENUMERATED object with a negative value. +.Pp +Almost all ASN.1 types are represented as +.Vt ASN1_STRING +structures. +Other types such as +.Vt ASN1_OCTET_STRING +are simply typedefed to +.Vt ASN1_STRING +and the functions call the +.Vt ASN1_STRING +equivalents. +.Vt ASN1_STRING +is also used for some CHOICE types which consist entirely of primitive +string types such as +.Vt DirectoryString +and +.Vt Time . +.Pp +These functions should +.Em not +be used to examine or modify +.Vt ASN1_INTEGER +or +.Vt ASN1_ENUMERATED +types: the relevant INTEGER or ENUMERATED utility functions should +be used instead. +.Pp +In general it cannot be assumed that the data returned by +.Fn ASN1_STRING_get0_data +and +.Fn ASN1_STRING_data +is NUL terminated, and it may contain embedded NUL characters. +The format of the data depends on the string type: +for example for an +.Vt IA5String +the data contains ASCII characters, for a +.Vt BMPString +two bytes per character in big endian format, and for a +.Vt UTF8String +UTF-8 characters. +.Pp +Similar care should be taken to ensure the data is in the correct format +when calling +.Fn ASN1_STRING_set +or +.Fn ASN1_STRING_set0 . +.Sh RETURN VALUES +.Fn ASN1_STRING_cmp +and +.Fn ASN1_OCTET_STRING_cmp +return 0 if the type, the length, and the content of +.Fa a +and +.Fa b +agree, or a non-zero value otherwise. +In contrast to +.Xr strcmp 3 , +the sign of the return value does not indicate lexicographical ordering. +.Pp +.Fn ASN1_STRING_data +and +.Fn ASN1_STRING_get0_data +return an internal pointer to the data of +.Fa x . +.Pp +.Fn ASN1_STRING_dup +and +.Fn ASN1_OCTET_STRING_dup +return a pointer to a newly allocated +.Vt ASN1_STRING +structure or +.Dv NULL +if an error occurred. +.Pp +.Fn ASN1_STRING_length +returns a number of bytes. +.Pp +.Fn ASN1_STRING_set , +.Fn ASN1_OCTET_STRING_set , +and +.Fn ASN1_STRING_copy +return 1 on success or 0 on failure. +They fail if memory allocation fails. +.Fn ASN1_STRING_set +and +.Fn ASN1_OCTET_STRING_set +also fail if +.Fa data +is +.Dv NULL +and +.Fa len +is \-1 in the same call. +.Fn ASN1_STRING_copy +also fails if +.Fa src +is +.Dv NULL . +.Pp +.Fn ASN1_STRING_to_UTF8 +returns the number of bytes in the output buffer +.Pf * Fa out , +or a negative number if an error occurred. +.Pp +.Fn ASN1_STRING_type +returns an integer constant, for example +.Dv V_ASN1_OCTET_STRING +or +.Dv V_ASN1_NEG_INTEGER . +.Pp +In some cases of failure of +.Fn ASN1_STRING_dup , +.Fn ASN1_STRING_set , +and +.Fn ASN1_STRING_to_UTF8 , +the reason can be determined with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr a2i_ASN1_STRING 3 , +.Xr a2i_ipadd 3 , +.Xr ASN1_BIT_STRING_set 3 , +.Xr ASN1_mbstring_copy 3 , +.Xr ASN1_PRINTABLE_type 3 , +.Xr ASN1_STRING_new 3 , +.Xr ASN1_UNIVERSALSTRING_to_string 3 , +.Xr s2i_ASN1_INTEGER 3 +.Sh HISTORY +.Fn ASN1_STRING_cmp , +.Fn ASN1_STRING_dup , +.Fn ASN1_STRING_set , +and +.Fn ASN1_OCTET_STRING_set +first appeared in SSLeay 0.6.5. +.Fn ASN1_OCTET_STRING_cmp , +.Fn ASN1_STRING_data , +.Fn ASN1_OCTET_STRING_dup , +and +.Fn ASN1_STRING_type +first appeared in SSLeay 0.8.0. +.Fn ASN1_STRING_length +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn ASN1_STRING_length_set +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn ASN1_STRING_to_UTF8 +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Pp +.Fn ASN1_STRING_set0 +first appeared in OpenSSL 0.9.8h and has been available since +.Ox 4.5 . +.Pp +.Fn ASN1_STRING_copy +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Pp +.Fn ASN1_STRING_get0_data +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . +.Sh BUGS +.Fn ASN1_OCTET_STRING_cmp , +.Fn ASN1_OCTET_STRING_dup , +and +.Fn ASN1_OCTET_STRING_set +do not check whether their arguments are really of the type +.Dv V_ASN1_OCTET_STRING . +They may report success even if their arguments are of a wrong type. +Consequently, even in case of success, the return value of +.Fn ASN1_OCTET_STRING_dup +is not guaranteed to be of the type +.Dv V_ASN1_OCTET_STRING +either. diff --git a/static/openbsd/man3/ASN1_STRING_new.3 b/static/openbsd/man3/ASN1_STRING_new.3 new file mode 100644 index 00000000..d653b70d --- /dev/null +++ b/static/openbsd/man3/ASN1_STRING_new.3 @@ -0,0 +1,302 @@ +.\" $OpenBSD: ASN1_STRING_new.3,v 1.28 2025/06/08 22:37:23 schwarze Exp $ +.\" OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400 +.\" +.\" Copyright (c) 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_STRING_NEW 3 +.Os +.Sh NAME +.Nm ASN1_STRING_new , +.Nm ASN1_STRING_type_new , +.Nm ASN1_STRING_free , +.Nm ASN1_OCTET_STRING_new , +.Nm ASN1_OCTET_STRING_free , +.Nm ASN1_BIT_STRING_new , +.Nm ASN1_BIT_STRING_free , +.Nm ASN1_INTEGER_new , +.Nm ASN1_INTEGER_free , +.Nm ASN1_ENUMERATED_new , +.Nm ASN1_ENUMERATED_free , +.Nm ASN1_UTF8STRING_new , +.Nm ASN1_UTF8STRING_free , +.Nm ASN1_IA5STRING_new , +.Nm ASN1_IA5STRING_free , +.Nm ASN1_UNIVERSALSTRING_new , +.Nm ASN1_UNIVERSALSTRING_free , +.Nm ASN1_BMPSTRING_new , +.Nm ASN1_BMPSTRING_free , +.Nm ASN1_GENERALSTRING_new , +.Nm ASN1_GENERALSTRING_free , +.Nm ASN1_T61STRING_new , +.Nm ASN1_T61STRING_free , +.Nm ASN1_VISIBLESTRING_new , +.Nm ASN1_VISIBLESTRING_free , +.Nm ASN1_PRINTABLESTRING_new , +.Nm ASN1_PRINTABLESTRING_free , +.Nm ASN1_PRINTABLE_new , +.Nm ASN1_PRINTABLE_free , +.Nm DIRECTORYSTRING_new , +.Nm DIRECTORYSTRING_free , +.Nm DISPLAYTEXT_new , +.Nm DISPLAYTEXT_free , +.Nm ASN1_GENERALIZEDTIME_new , +.Nm ASN1_GENERALIZEDTIME_free , +.Nm ASN1_UTCTIME_new , +.Nm ASN1_UTCTIME_free , +.Nm ASN1_TIME_new , +.Nm ASN1_TIME_free +.Nd allocate and free ASN1_STRING objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_STRING * +.Fn ASN1_STRING_new void +.Ft ASN1_STRING * +.Fn ASN1_STRING_type_new "int type" +.Ft void +.Fn ASN1_STRING_free "ASN1_STRING *a" +.Ft ASN1_OCTET_STRING * +.Fn ASN1_OCTET_STRING_new void +.Ft void +.Fn ASN1_OCTET_STRING_free "ASN1_OCTET_STRING *a" +.Ft ASN1_BIT_STRING * +.Fn ASN1_BIT_STRING_new void +.Ft void +.Fn ASN1_BIT_STRING_free "ASN1_BIT_STRING *a" +.Ft ASN1_INTEGER * +.Fn ASN1_INTEGER_new void +.Ft void +.Fn ASN1_INTEGER_free "ASN1_INTEGER *a" +.Ft ASN1_ENUMERATED * +.Fn ASN1_ENUMERATED_new void +.Ft void +.Fn ASN1_ENUMERATED_free "ASN1_ENUMERATED *a" +.Ft ASN1_UTF8STRING * +.Fn ASN1_UTF8STRING_new void +.Ft void +.Fn ASN1_UTF8STRING_free "ASN1_UTF8STRING *a" +.Ft ASN1_IA5STRING * +.Fn ASN1_IA5STRING_new void +.Ft void +.Fn ASN1_IA5STRING_free "ASN1_IA5STRING *a" +.Ft ASN1_UNIVERSALSTRING * +.Fn ASN1_UNIVERSALSTRING_new void +.Ft void +.Fn ASN1_UNIVERSALSTRING_free "ASN1_UNIVERSALSTRING *a" +.Ft ASN1_BMPSTRING * +.Fn ASN1_BMPSTRING_new void +.Ft void +.Fn ASN1_BMPSTRING_free "ASN1_BMPSTRING *a" +.Ft ASN1_GENERALSTRING * +.Fn ASN1_GENERALSTRING_new void +.Ft void +.Fn ASN1_GENERALSTRING_free "ASN1_GENERALSTRING *a" +.Ft ASN1_T61STRING * +.Fn ASN1_T61STRING_new void +.Ft void +.Fn ASN1_T61STRING_free "ASN1_T61STRING *a" +.Ft ASN1_VISIBLESTRING * +.Fn ASN1_VISIBLESTRING_new void +.Ft void +.Fn ASN1_VISIBLESTRING_free "ASN1_VISIBLESTRING *a" +.Ft ASN1_PRINTABLESTRING * +.Fn ASN1_PRINTABLESTRING_new void +.Ft void +.Fn ASN1_PRINTABLESTRING_free "ASN1_PRINTABLESTRING *a" +.Ft ASN1_STRING * +.Fn ASN1_PRINTABLE_new void +.Ft void +.Fn ASN1_PRINTABLE_free "ASN1_STRING *a" +.Ft ASN1_STRING * +.Fn DIRECTORYSTRING_new void +.Ft void +.Fn DIRECTORYSTRING_free "ASN1_STRING *a" +.Ft ASN1_STRING * +.Fn DISPLAYTEXT_new void +.Ft void +.Fn DISPLAYTEXT_free "ASN1_STRING *a" +.Ft ASN1_GENERALIZEDTIME * +.Fn ASN1_GENERALIZEDTIME_new void +.Ft void +.Fn ASN1_GENERALIZEDTIME_free "ASN1_GENERALIZEDTIME *a" +.Ft ASN1_UTCTIME * +.Fn ASN1_UTCTIME_new void +.Ft void +.Fn ASN1_UTCTIME_free "ASN1_UTCTIME *a" +.Ft ASN1_TIME * +.Fn ASN1_TIME_new void +.Ft void +.Fn ASN1_TIME_free "ASN1_TIME *a" +.Sh DESCRIPTION +The +.Vt ASN1_STRING +object can represent a variety of ASN.1 built-in types. +It can store a type and a value. +.Pp +All the +.Fn *_new +functions +allocate and initialize an empty +.Vt ASN1_STRING +object. +The following table shows the type assigned to the new object, +and which ASN.1 type it represents. +.Bl -column "ASN1_GENERALIZEDTIME_new()" "V_ASN1_GENERALIZEDTIME" +.It Em constructor function Ta Em OpenSSL type Ta Em ASN.1 type +.It Ta +.It Fn ASN1_STRING_new Ta Dv V_ASN1_OCTET_STRING +.It Fn ASN1_STRING_type_new Ta Fa type No argument +.It Ta +.It Fn ASN1_OCTET_STRING_new Ta Dv V_ASN1_OCTET_STRING Ta OCTET STRING +.It Fn ASN1_BIT_STRING_new Ta Dv V_ASN1_BIT_STRING Ta BIT STRING +.It Fn ASN1_INTEGER_new Ta Dv V_ASN1_INTEGER Ta INTEGER +.It Fn ASN1_ENUMERATED_new Ta Dv V_ASN1_ENUMERATED Ta ENUMERATED +.It Ta +.It Fn ASN1_UTF8STRING_new Ta Dv V_ASN1_UTF8STRING Ta UTF8String +.It Fn ASN1_IA5STRING_new Ta Dv V_ASN1_IA5STRING Ta IA5String +.It Ta +.It Fn ASN1_UNIVERSALSTRING_new Ta Dv V_ASN1_UNIVERSALSTRING Ta UniversalString +.It Fn ASN1_BMPSTRING_new Ta Dv V_ASN1_BMPSTRING Ta BMPString +.It Fn ASN1_GENERALSTRING_new Ta Dv V_ASN1_GENERALSTRING Ta GeneralString +.It Fn ASN1_T61STRING_new Ta Dv V_ASN1_T61STRING Ta T61String +.It Fn ASN1_VISIBLESTRING_new Ta Dv V_ASN1_VISIBLESTRING Ta VisibleString +.It Fn ASN1_PRINTABLESTRING_new Ta Dv V_ASN1_PRINTABLESTRING Ta PrintableString +.It Ta +.It Fn ASN1_PRINTABLE_new Ta Dv V_ASN1_UNDEF +.It Fn DIRECTORYSTRING_new Ta Dv V_ASN1_UNDEF +.It Fn DISPLAYTEXT_new Ta Dv V_ASN1_UNDEF +.It Ta +.It Fn ASN1_GENERALIZEDTIME_new Ta Dv V_ASN1_GENERALIZEDTIME Ta GeneralizedTime +.It Fn ASN1_UTCTIME_new Ta Dv V_ASN1_UTCTIME Ta UTCTime +.It Fn ASN1_TIME_new Ta Dv V_ASN1_UNDEF Ta TIME +.El +.Pp +All the +.Fn *_free +functions free +.Fa a +including any data contained in it. +If +.Fa a +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +All the +.Fn *_new +functions return the new +.Vt ASN1_STRING +object if successful; otherwise +.Dv NULL +is returned and an error code can be retrieved with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr a2i_ipadd 3 , +.Xr ASN1_BIT_STRING_set 3 , +.Xr ASN1_INTEGER_get 3 , +.Xr ASN1_item_pack 3 , +.Xr ASN1_mbstring_copy 3 , +.Xr ASN1_PRINTABLE_type 3 , +.Xr ASN1_STRING_length 3 , +.Xr ASN1_STRING_print_ex 3 , +.Xr ASN1_TIME_set 3 , +.Xr ASN1_TYPE_get 3 , +.Xr ASN1_UNIVERSALSTRING_to_string 3 , +.Xr d2i_ASN1_OBJECT 3 , +.Xr d2i_ASN1_OCTET_STRING 3 , +.Xr i2a_ASN1_STRING 3 , +.Xr s2i_ASN1_INTEGER 3 , +.Xr X509_cmp_time 3 , +.Xr X509_EXTENSION_get_object 3 , +.Xr X509_get_ext_by_OBJ 3 , +.Xr X509_NAME_ENTRY_get_object 3 +.Sh HISTORY +.Fn ASN1_OCTET_STRING_new , +.Fn ASN1_OCTET_STRING_free , +.Fn ASN1_BIT_STRING_new , +.Fn ASN1_BIT_STRING_free , +.Fn ASN1_INTEGER_new , +.Fn ASN1_INTEGER_free , +.Fn ASN1_IA5STRING_new , +.Fn ASN1_IA5STRING_free , +.Fn ASN1_T61STRING_new , +.Fn ASN1_T61STRING_free , +.Fn ASN1_PRINTABLESTRING_new , +.Fn ASN1_PRINTABLESTRING_free , +.Fn ASN1_PRINTABLE_new , +.Fn ASN1_PRINTABLE_free , +.Fn ASN1_UTCTIME_new , +and +.Fn ASN1_UTCTIME_free +first appeared in SSLeay 0.5.1. +.Fn ASN1_STRING_new , +.Fn ASN1_STRING_type_new , +and +.Fn ASN1_STRING_free +first appeared in SSLeay 0.6.5. +.Fn ASN1_UNIVERSALSTRING_new , +.Fn ASN1_UNIVERSALSTRING_free , +.Fn ASN1_GENERALSTRING_new , +and +.Fn ASN1_GENERALSTRING_free +first appeared in SSLeay 0.8.0. +.Fn ASN1_BMPSTRING_new , +.Fn ASN1_BMPSTRING_free , +.Fn ASN1_GENERALIZEDTIME_new , +and +.Fn ASN1_GENERALIZEDTIME_free +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn ASN1_ENUMERATED_new , +.Fn ASN1_ENUMERATED_free , +.Fn ASN1_TIME_new , +and +.Fn ASN1_TIME_free +first appeared in OpenSSL 0.9.2b. +.Fn ASN1_UTF8STRING_new , +.Fn ASN1_UTF8STRING_free , +.Fn ASN1_VISIBLESTRING_new , +.Fn ASN1_VISIBLESTRING_free , +.Fn DIRECTORYSTRING_new , +.Fn DIRECTORYSTRING_free , +.Fn DISPLAYTEXT_new , +and +.Fn DISPLAYTEXT_free +first appeared in OpenSSL 0.9.3. +These functions have been available since +.Ox 2.6 . +.Sh BUGS +.Vt ASN1_OCTET_STRING , +.Vt ASN1_BIT_STRING , +.Vt ASN1_INTEGER , +.Vt ASN1_ENUMERATED , +.Vt ASN1_UTF8STRING , +.Vt ASN1_IA5STRING , +.Vt ASN1_UNIVERSALSTRING , +.Vt ASN1_BMPSTRING , +.Vt ASN1_GENERALSTRING , +.Vt ASN1_T61STRING , +.Vt ASN1_VISIBLESTRING , +.Vt ASN1_PRINTABLESTRING , +.Vt ASN1_GENERALIZEDTIME , +.Vt ASN1_UTCTIME , +and +.Vt ASN1_TIME +are merely typedef aliases of +.Vt ASN1_STRING +and provide no type safety whatsoever. diff --git a/static/openbsd/man3/ASN1_STRING_print_ex.3 b/static/openbsd/man3/ASN1_STRING_print_ex.3 new file mode 100644 index 00000000..8295b3e9 --- /dev/null +++ b/static/openbsd/man3/ASN1_STRING_print_ex.3 @@ -0,0 +1,241 @@ +.\" $OpenBSD: ASN1_STRING_print_ex.3,v 1.19 2025/06/08 22:37:23 schwarze Exp $ +.\" full merge up to: OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 +.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Dr. Stephen Henson. +.\" Copyright (c) 2002, 2004, 2007, 2013, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ASN1_STRING_PRINT_EX 3 +.Os +.Sh NAME +.Nm ASN1_STRING_print_ex , +.Nm ASN1_STRING_print_ex_fp , +.Nm ASN1_STRING_print , +.Nm ASN1_tag2str +.Nd ASN1_STRING output routines +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo ASN1_STRING_print_ex +.Fa "BIO *out" +.Fa "const ASN1_STRING *str" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo ASN1_STRING_print_ex_fp +.Fa "FILE *fp" +.Fa "const ASN1_STRING *str" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo ASN1_STRING_print +.Fa "BIO *out" +.Fa "const ASN1_STRING *str" +.Fc +.Ft const char * +.Fo ASN1_tag2str +.Fa "int tag" +.Fc +.Sh DESCRIPTION +These functions output an +.Vt ASN1_STRING +structure. +.Vt ASN1_STRING +is used to +represent all the ASN.1 string types. +.Pp +.Fn ASN1_STRING_print_ex +outputs +.Fa str +to +.Fa out , +the format being determined by the options +.Fa flags . +.Fn ASN1_STRING_print_ex_fp +is identical except it outputs to +.Fa fp +instead. +.Pp +.Fn ASN1_STRING_print +prints +.Fa str +to +.Fa out +but using a different format to +.Fn ASN1_STRING_print_ex . +It replaces unprintable characters (other than CR, LF) with +.Sq \&. . +.Pp +.Fn ASN1_tag2str +returns a human-readable name of the specified ASN.1 +.Fa tag . +.Pp +.Fn ASN1_STRING_print +is a deprecated function which should be avoided; use +.Fn ASN1_STRING_print_ex +instead. +.Pp +Although there are a large number of options, +.Dv ASN1_STRFLGS_RFC2253 +is often suitable, or on UTF-8 terminals +.Dv ASN1_STRFLGS_RFC2253 +and +.Pf ~ Dv ASN1_STRFLGS_ESC_MSB . +.Pp +The complete set of supported options for +.Fa flags +is listed below. +.Pp +Various characters can be escaped. +If +.Dv ASN1_STRFLGS_ESC_2253 +is set, the characters determined by RFC 2253 are escaped. +If +.Dv ASN1_STRFLGS_ESC_CTRL +is set, control characters are escaped. +If +.Dv ASN1_STRFLGS_ESC_MSB +is set, characters with the MSB set are escaped: this option should +.Em not +be used if the terminal correctly interprets UTF-8 sequences. +.Pp +Escaping takes several forms. +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 UTF-8 conversion is not set (see below). +.Pp +Printable characters are normally escaped using the backslash +.Pq Sq \e +character. +If +.Dv ASN1_STRFLGS_ESC_QUOTE +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 +.Dv ASN1_STRFLGS_UTF8_CONVERT +is set, then characters are converted to UTF-8 format first. +If the terminal supports the display of UTF-8 sequences then this +option will correctly display multi-byte characters. +.Pp +If +.Dv ASN1_STRFLGS_IGNORE_TYPE +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 +.Dv ASN1_STRFLGS_SHOW_TYPE +is set, then the string type itself is printed before its value +(for example "BMPSTRING"), using +.Fn ASN1_tag2str . +.Pp +Instead of being interpreted the contents of a string can be "dumped": +this just outputs the value of the string using the form #XXXX +using hex format for each octet. +.Pp +If +.Dv ASN1_STRFLGS_DUMP_ALL +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 +.Dv ASN1_STRFLGS_DUMP_UNKNOWN +is set, then they will be dumped instead. +.Pp +When a type is dumped normally just the content octets are printed; if +.Dv ASN1_STRFLGS_DUMP_DER +is set, then the complete encoding is dumped +instead (including tag and length octets). +.Pp +.Dv ASN1_STRFLGS_RFC2253 +includes all the flags required by RFC 2253. +It is equivalent to +.Dv ASN1_STRFLGS_ESC_2253 | +.Dv ASN1_STRFLGS_ESC_CTRL | +.Dv ASN1_STRFLGS_ESC_MSB | +.Dv ASN1_STRFLGS_UTF8_CONVERT | +.Dv ASN1_STRFLGS_DUMP_UNKNOWN | +.Dv ASN1_STRFLGS_DUMP_DER . +.Sh RETURN VALUES +.Fn ASN1_STRING_print_ex +and +.Fn ASN1_STRING_print_ex_fp +return the number of characters written or \-1 if an error occurred. +.Pp +.Fn ASN1_STRING_print +returns 1 on success or 0 on error. +.Pp +.Fn ASN1_tag2str +returns a static string. +.Sh SEE ALSO +.Xr ASN1_parse_dump 3 , +.Xr ASN1_STRING_new 3 , +.Xr X509_NAME_print_ex 3 , +.Xr X509_signature_dump 3 +.Sh HISTORY +.Fn ASN1_STRING_print +first appeared in SSLeay 0.6.5 and has been available since +.Ox 2.4 . +.Pp +.Fn ASN1_tag2str +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn ASN1_STRING_print_ex +and +.Fn ASN1_STRING_print_ex_fp +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . diff --git a/static/openbsd/man3/ASN1_TIME_set.3 b/static/openbsd/man3/ASN1_TIME_set.3 new file mode 100644 index 00000000..8cfcf433 --- /dev/null +++ b/static/openbsd/man3/ASN1_TIME_set.3 @@ -0,0 +1,753 @@ +.\" $OpenBSD: ASN1_TIME_set.3,v 1.24 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 3d0f1cb9 Jul 11 03:01:24 2017 +0800 +.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022 Ingo Schwarze +.\" Copyright (c) 2022 Bob Beck +.\" +.\" 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 AUTHORS DISCLAIM ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Todd Short . +.\" Copyright (c) 2015, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ASN1_TIME_SET 3 +.Os +.Sh NAME +.Nm ASN1_TIME_set , +.Nm ASN1_UTCTIME_set , +.Nm ASN1_GENERALIZEDTIME_set , +.Nm ASN1_TIME_adj , +.Nm ASN1_UTCTIME_adj , +.Nm ASN1_GENERALIZEDTIME_adj , +.Nm ASN1_TIME_set_string , +.Nm ASN1_TIME_set_string_X509 , +.Nm ASN1_UTCTIME_set_string , +.Nm ASN1_GENERALIZEDTIME_set_string , +.Nm ASN1_TIME_normalize , +.Nm ASN1_TIME_check , +.Nm ASN1_UTCTIME_check , +.Nm ASN1_GENERALIZEDTIME_check , +.Nm ASN1_TIME_print , +.Nm ASN1_UTCTIME_print , +.Nm ASN1_GENERALIZEDTIME_print , +.Nm ASN1_TIME_to_tm , +.Nm ASN1_TIME_diff , +.Nm ASN1_TIME_cmp_time_t , +.Nm ASN1_UTCTIME_cmp_time_t , +.Nm ASN1_TIME_compare , +.Nm ASN1_TIME_to_generalizedtime , +.Nm OPENSSL_gmtime , +.Nm OPENSSL_timegm , +.Nm OPENSSL_posix_to_tm , +.Nm OPENSSL_tm_to_posix +.Nd ASN.1 Time functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_TIME * +.Fo ASN1_TIME_set +.Fa "ASN1_TIME *s" +.Fa "time_t t" +.Fc +.Ft ASN1_UTCTIME * +.Fo ASN1_UTCTIME_set +.Fa "ASN1_UTCTIME *s" +.Fa "time_t t" +.Fc +.Ft ASN1_GENERALIZEDTIME * +.Fo ASN1_GENERALIZEDTIME_set +.Fa "ASN1_GENERALIZEDTIME *s" +.Fa "time_t t" +.Fc +.Ft ASN1_TIME * +.Fo ASN1_TIME_adj +.Fa "ASN1_TIME *s" +.Fa "time_t t" +.Fa "int offset_day" +.Fa "long offset_sec" +.Fc +.Ft ASN1_UTCTIME * +.Fo ASN1_UTCTIME_adj +.Fa "ASN1_UTCTIME *s" +.Fa "time_t t" +.Fa "int offset_day" +.Fa "long offset_sec" +.Fc +.Ft ASN1_GENERALIZEDTIME * +.Fo ASN1_GENERALIZEDTIME_adj +.Fa "ASN1_GENERALIZEDTIME *s" +.Fa "time_t t" +.Fa "int offset_day" +.Fa "long offset_sec" +.Fc +.Ft int +.Fo ASN1_TIME_set_string +.Fa "ASN1_TIME *s" +.Fa "const char *str" +.Fc +.Ft int +.Fo ASN1_TIME_set_string_X509 +.Fa "ASN1_TIME *s" +.Fa "const char *str" +.Fc +.Ft int +.Fo ASN1_UTCTIME_set_string +.Fa "ASN1_UTCTIME *s" +.Fa "const char *str" +.Fc +.Ft int +.Fo ASN1_GENERALIZEDTIME_set_string +.Fa "ASN1_GENERALIZEDTIME *s" +.Fa "const char *str" +.Fc +.Ft int +.Fo ASN1_TIME_normalize +.Fa "ASN1_TIME *s" +.Fc +.Ft int +.Fo ASN1_TIME_check +.Fa "const ASN1_TIME *t" +.Fc +.Ft int +.Fo ASN1_UTCTIME_check +.Fa "const ASN1_UTCTIME *t" +.Fc +.Ft int +.Fo ASN1_GENERALIZEDTIME_check +.Fa "const ASN1_GENERALIZEDTIME *t" +.Fc +.Ft int +.Fo ASN1_TIME_print +.Fa "BIO *b" +.Fa "const ASN1_TIME *s" +.Fc +.Ft int +.Fo ASN1_UTCTIME_print +.Fa "BIO *b" +.Fa "const ASN1_UTCTIME *s" +.Fc +.Ft int +.Fo ASN1_GENERALIZEDTIME_print +.Fa "BIO *b" +.Fa "const ASN1_GENERALIZEDTIME *s" +.Fc +.Ft int +.Fo ASN1_TIME_to_tm +.Fa "const ASN1_TIME *s" +.Fa "struct tm *tm" +.Fc +.Ft int +.Fo ASN1_TIME_diff +.Fa "int *pday" +.Fa "int *psec" +.Fa "const ASN1_TIME *from" +.Fa "const ASN1_TIME *to" +.Fc +.Ft int +.Fo ASN1_TIME_cmp_time_t +.Fa "const ASN1_TIME *s" +.Fa "time_t t" +.Fc +.Ft int +.Fo ASN1_UTCTIME_cmp_time_t +.Fa "const ASN1_UTCTIME *s" +.Fa "time_t t" +.Fc +.Ft int +.Fo ASN1_TIME_compare +.Fa "const ASN1_TIME *s" +.Fa "const ASN1_TIME *t" +.Fc +.Ft ASN1_GENERALIZEDTIME * +.Fo ASN1_TIME_to_generalizedtime +.Fa "const ASN1_TIME *t" +.Fa "ASN1_GENERALIZEDTIME **out" +.Fc +.In openssl/crypto.h +.Ft struct tm * +.Fo OPENSSL_gmtime +.Fa "const time_t *time" +.Fa "struct tm *out_tm" +.Fc +.In openssl/posix_time.h +.Ft int +.Fo OPENSSL_timegm +.Fa "const struct tm *tm" +.Fa "time_t *out_time" +.Fc +.Ft int +.Fo OPENSSL_posix_to_tm +.Fa "int64_t time" +.Fa "struct tm *out_tm" +.Fc +.Ft int +.Fo OPENSSL_tm_to_posix +.Fa "struct tm *t_tm" +.Fa "int64_t *out" +.Fc +.Sh DESCRIPTION +An +.Vt ASN1_TIME +object is a shallow wrapper around a string containing an ASN.1 +.Vt Time +value in the restricted format valid in X.509 certificates. +An +.Vt ASN1_TIME +object is either an +.Vt ASN1_UTCTIME +object containing a string of the format +.Ar YYMMDDHHMMSS Ns Cm Z +which is valid for the years 1950 to 2049, or an +.Vt ASN1_GENERALIZEDTIME +object containing a string of the format +.Ar YYYYMMDDHHMMSS Ns Cm Z +which is valid for the years 0000 to 1949 and 2050 to 9999. +In both cases, the mandatory suffix +.Sq Cm Z +represents the GMT time zone. +LibreSSL by design does not support the full syntax of ASN.1 times. +In particular, it neither supports fractional seconds +nor any other time zone. +.Pp +The functions +.Fn ASN1_TIME_set , +.Fn ASN1_UTCTIME_set , +and +.Fn ASN1_GENERALIZEDTIME_set +set the time object +.Fa s +to the time represented by the +.Vt time_t +value +.Fa t . +If +.Fa s +is +.Dv NULL , +a new time object is allocated and returned. +.Pp +The functions +.Fn ASN1_TIME_adj , +.Fn ASN1_UTCTIME_adj , +and +.Fn ASN1_GENERALIZEDTIME_adj +set the time object +.Fa s +to the time represented by the time +.Fa offset_day +and +.Fa offset_sec +after the +.Vt time_t +value +.Fa t . +The values of +.Fa offset_day +or +.Fa offset_sec +can be negative to set a time before +.Fa t . +The +.Fa offset_sec +value can also exceed the number of seconds in a day. +If +.Fa s +is +.Dv NULL , +a new time object is allocated and returned. +.Pp +.Fn ASN1_TIME_adj +may change the type from +.Vt ASN1_GENERALIZEDTIME +to +.Vt ASN1_UTCTIME +or vice versa depending on the resulting year. +The functions +.Fn ASN1_UTCTIME_adj +and +.Fn ASN1_GENERALIZEDTIME_adj +do not modify the type of the return object. +.Pp +The functions +.Fn ASN1_TIME_set_string , +.Fn ASN1_TIME_set_string_X509 , +.Fn ASN1_UTCTIME_set_string , +and +.Fn ASN1_GENERALIZEDTIME_set_string +set the time object +.Fa s +to the time string +.Fa str , +which must be in appropriate ASN.1 time format: +YYMMDDHHMMSSZ for +.Vt ASN1_UTCTIME , +YYYYMMDDHHMMSSZ for +.Vt ASN1_GENERALIZEDTIME , +or either of the two for +.Vt ASN1_TIME . +The string +.Fa str +is copied into +.Fa s . +If +.Fa s +is +.Dv NULL , +these functions only perform a format check on +.Fa str . +.Pp +In LibreSSL, +.Fn ASN1_TIME_set_string +and +.Fn ASN1_TIME_set_string_X509 +behave identically and always set the time object +to a valid value to use in an X.509 certificate. +.Fn ASN1_GENERALIZEDTIME_set_string +may encode a time string that is not valid in an X.509 certificate. +.Pp +The function +.Fn ASN1_TIME_normalize +converts an +.Vt ASN1_GENERALIZEDTIME +into a time value that can be used in a certificate +by changing it to an +.Vt ASN1_UTCTIME +if possible. +It has no effect on an +.Vt ASN1_UTCTIME . +.Pp +The functions +.Fn ASN1_TIME_check , +.Fn ASN1_UTCTIME_check , +and +.Fn ASN1_GENERALIZEDTIME_check +check the syntax of the time string contained in the object +.Fa s . +.Pp +The functions +.Fn ASN1_TIME_print , +.Fn ASN1_UTCTIME_print , +and +.Fn ASN1_GENERALIZEDTIME_print +print out the time +.Fa s +to +.Vt BIO +.Fa b +in human readable format. +It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example "Feb 3 +00:55:52 2015 GMT". +It does not include a newline. +If the time string has an invalid format, +it prints out "Bad time value" and returns an error. +.Pp +The function +.Fn ASN1_TIME_to_tm +converts the time +.Fa s +to the standard +.Vt tm +structure. +If +.Fa s +is +.Dv NULL , +then the current time is converted. +The output time is always in the GMT time zone. +The +.Fa tm_sec , tm_min , tm_hour , tm_mday , tm_mon , +and +.Fa tm_year +fields of the +.Vt tm +structure are set to the proper values, +whereas all other fields are set to 0. +If +.Fa tm +is +.Dv NULL , +this function performs a format check on +.Fa s +only. +.Pp +The function +.Fn ASN1_TIME_diff +sets +.Pf * Fa pday +and +.Pf * Fa psec +to the time difference between +.Fa from +and +.Fa to . +If +.Fa to +represents a time later than +.Fa from , +then one or both (depending on the time difference) of +.Pf * Fa pday +and +.Pf * Fa psec +will be positive. +If +.Fa to +represents a time earlier than +.Fa from , +then one or both of +.Pf * Fa pday +and +.Pf * Fa psec +will be negative. +If +.Fa to +and +.Fa from +represent the same time, then +.Pf * Fa pday +and +.Pf * Fa psec +will both be zero. +If both +.Pf * Fa pday +and +.Pf * Fa psec +are nonzero, they will always have the same sign. +The value of +.Pf * Fa psec +will always be less than the number of seconds in a day. +If +.Fa from +or +.Fa to +is +.Dv NULL , +the current time is used. +.Pp +The functions +.Fn ASN1_TIME_cmp_time_t , +.Fn ASN1_UTCTIME_cmp_time_t , +and +.Fn ASN1_TIME_compare +compare the two times represented by +.Fa s +and +.Fa t . +.Pp +The function +.Fn ASN1_TIME_to_generalizedtime +converts the +.Vt ASN1_TIME +.Fa t +to an +.Vt ASN1_GENERALIZEDTIME , +regardless of year. +If either +.Fa out +or +.Pf * Fa out +is +.Dv NULL , +then a new object is allocated and must be freed after use. +.Pp +The +.Vt ASN1_TIME , +.Vt ASN1_UTCTIME , +and +.Vt ASN1_GENERALIZEDTIME +objects are represented as +.Vt ASN1_STRING +objects internally and can be freed using +.Xr ASN1_STRING_free 3 . +.Pp +It is recommended that +.Vt ASN1_TIME +functions be used instead of +.Vt ASN1_UTCTIME +or +.Vt ASN1_GENERALIZEDTIME +functions because the +.Vt ASN1_UTCTIME +and +.Vt ASN1_GENERALIZEDTIME +functions act only on that specific time format, while the +.Vt ASN1_TIME +functions operate on either format. +.Pp +.Fn OPENSSL_gmtime +converts a time_t value in +.Fa time +to a struct tm in +.Fa out_tm +and also returns the struct passed in on success. +.Pp +.Fn OPENSSL_timegm +converts a time structure in UTC time in +.Fa tm +to a time_t value in +.Fa out_time . +.Pp +.Fn OPENSSL_posix_to_tm +converts an +.Vt int64_t +POSIX time value in +.Fa time , +which must be in the range of year 0 to 9999, +to a broken out time value in +.Fa tm . +.Pp +.Fn OPENSSL_tm_to_posix +converts a time value between the years 0 and 9999 in +.Fa tm +to a POSIX time value in +.Fa out . +.Sh RETURN VALUES +.Fn ASN1_TIME_set , +.Fn ASN1_UTCTIME_set , +.Fn ASN1_GENERALIZEDTIME_set , +.Fn ASN1_TIME_adj , +.Fn ASN1_UTCTIME_adj , +.Fn ASN1_GENERALIZEDTIME_adj , +and +.Fn ASN1_TIME_to_generalizedtime +return a pointer to a time object or +.Dv NULL +if an error occurred. +.Pp +.Fn ASN1_TIME_set_string , +.Fn ASN1_TIME_set_string_X509 , +.Fn ASN1_UTCTIME_set_string , +and +.Fn ASN1_GENERALIZEDTIME_set_string +return 1 if the time value is successfully set or 0 otherwise. +.Pp +.Fn ASN1_TIME_normalize +returns 1 on success or 0 on error. +.Pp +.Fn ASN1_TIME_check , +.Fn ASN1_UTCTIME_check , +and +.Fn ASN1_GENERALIZEDTIME_check +return 1 if the time string contained in the object is syntactically +correct or 0 otherwise. +.Pp +.Fn ASN1_TIME_print , +.Fn ASN1_UTCTIME_print , +and +.Fn ASN1_GENERALIZEDTIME_print +return 1 if the time is successfully printed or 0 if an error +occurred (I/O error or invalid time format). +.Pp +.Fn ASN1_TIME_to_tm +returns 1 if the time is successfully parsed +or 0 if an error occurred, usually due to an invalid time format. +.Pp +.Fn ASN1_TIME_diff +returns 1 for success or 0 for failure. +It can for example fail if a time string passed in has invalid syntax. +.Pp +.Fn ASN1_TIME_cmp_time_t , +.Fn ASN1_UTCTIME_cmp_time_t , +and +.Fn ASN1_TIME_compare +return \-1 if +.Fa s +is earlier than +.Fa t , +0 if both are equal, 1 if +.Fa s +is later than +.Fa t , +or \-2 on error. +.Pp +.Fn OPENSSL_timegm +returns 1 for success or 0 for failure. +It can fail if the time is not representable in a time_t, +or falls outside the range allowed in RFC 5280 times. +.Pp +.Fn OPENSSL_gmtime +returns +.Fa out_tm +on success or NULL for failure. +It can fail if the time is not representable in a struct tm, +or falls outside the range allowed in RFC 5280 times. +.Pp +.Fn OPENSSL_posix_to_tm +and +.Fn OPENSSL_tm_to_posix +return 1 for success or 0 on failure. +It is a failure if the year is less than 0 or more than 9999. +.Sh EXAMPLES +Set a time object to one hour after the current time and print it +out: +.Bd -literal -offset indent +#include +#include + +ASN1_TIME *asn1_time; +time_t t; +BIO *b; + +t = time(NULL); +asn1_time = ASN1_TIME_adj(NULL, t, 0, 60 * 60); +b = BIO_new_fp(stdout, BIO_NOCLOSE); +if (asn1_time != NULL) { + ASN1_TIME_print(b, asn1_time); + BIO_printf(b, "\en"); +} else { + BIO_printf(b, "Time out of range or un-representable\en"); +} +ASN1_STRING_free(asn1_time); +BIO_free(b); +.Ed +.Sh SEE ALSO +.Xr ASN1_TIME_new 3 , +.Xr X509_cmp_time 3 +.Sh STANDARDS +The usage of the ASN.1 +.Vt Time , +.Vt UTCTime , +and +.Vt GeneralizedTime +data types in X.509 certificates is specified in +RFC 5280, Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 4.1.2.5 (TBS Certificate Validity). +.Sh HISTORY +.Fn ASN1_UTCTIME_check +and +.Fn ASN1_UTCTIME_print +first appeared in SSLeay 0.5.1. +.Fn ASN1_UTCTIME_set +first appeared in SSLeay 0.6.0. +.Fn ASN1_UTCTIME_set_string +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn ASN1_TIME_set , +.Fn ASN1_GENERALIZEDTIME_set , +.Fn ASN1_GENERALIZEDTIME_set_string , +.Fn ASN1_GENERALIZEDTIME_check , +.Fn ASN1_TIME_print , +and +.Fn ASN1_GENERALIZEDTIME_print +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . +.Pp +.Fn ASN1_UTCTIME_cmp_time_t +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Pp +.Fn ASN1_TIME_check +and +.Fn ASN1_TIME_to_generalizedtime +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn ASN1_TIME_adj , +.Fn ASN1_UTCTIME_adj , +.Fn ASN1_GENERALIZEDTIME_adj , +and +.Fn ASN1_TIME_set_string +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +.Fn ASN1_TIME_diff +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 7.1 . +.Pp +.Fn ASN1_TIME_set_string_X509 , +.Fn ASN1_TIME_normalize , +.Fn ASN1_TIME_to_tm , +.Fn ASN1_TIME_cmp_time_t , +and +.Fn ASN1_TIME_compare +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.2 . +.Pp +.Fn OPENSSL_gmtime +first appeared in OpenSSL 0.9.7. +.Fn OPENSSL_timegm , +.Fn OPENSSL_posix_to_tm , +and +.Fn OPENSSL_tm_to_posix +first appeared in BoringSSL; +all these functions have been available since +.Ox 7.5 . +.Sh CAVEATS +Some applications add offset times directly to a +.Vt time_t +value and pass the results to +.Fn ASN1_TIME_set +(or equivalent). +This can cause problems as the +.Vt time_t +value can overflow on some systems resulting in unexpected results. +New applications should use +.Fn ASN1_TIME_adj +instead and pass the offset value in the +.Fa offset_sec +and +.Fa offset_day +parameters instead of directly manipulating a +.Vt time_t +value. diff --git a/static/openbsd/man3/ASN1_TYPE_get.3 b/static/openbsd/man3/ASN1_TYPE_get.3 new file mode 100644 index 00000000..3b3359b6 --- /dev/null +++ b/static/openbsd/man3/ASN1_TYPE_get.3 @@ -0,0 +1,444 @@ +.\" $OpenBSD: ASN1_TYPE_get.3,v 1.20 2025/06/08 22:40:29 schwarze Exp $ +.\" selective merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2017, 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ASN1_TYPE_GET 3 +.Os +.Sh NAME +.Nm ASN1_TYPE_new , +.Nm ASN1_TYPE_free , +.Nm ASN1_TYPE_get , +.Nm ASN1_TYPE_set , +.Nm ASN1_TYPE_set1 , +.Nm ASN1_TYPE_set_octetstring , +.Nm ASN1_TYPE_get_octetstring , +.Nm ASN1_TYPE_set_int_octetstring , +.Nm ASN1_TYPE_get_int_octetstring , +.Nm ASN1_TYPE_cmp +.Nd ASN.1 objects of arbitrary type +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_TYPE * +.Fn ASN1_TYPE_new void +.Ft void +.Fn ASN1_TYPE_free "ASN1_TYPE *a" +.Ft int +.Fo ASN1_TYPE_get +.Fa "const ASN1_TYPE *a" +.Fc +.Ft void +.Fo ASN1_TYPE_set +.Fa "ASN1_TYPE *a" +.Fa "int type" +.Fa "void *value" +.Fc +.Ft int +.Fo ASN1_TYPE_set1 +.Fa "ASN1_TYPE *a" +.Fa "int type" +.Fa "const void *value" +.Fc +.Ft int +.Fo ASN1_TYPE_set_octetstring +.Fa "ASN1_TYPE *a" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft int +.Fo ASN1_TYPE_get_octetstring +.Fa "const ASN1_TYPE *a" +.Fa "unsigned char *buffer" +.Fa "int buflen" +.Fc +.Ft int +.Fo ASN1_TYPE_set_int_octetstring +.Fa "ASN1_TYPE *a" +.Fa "long num" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft int +.Fo ASN1_TYPE_get_int_octetstring +.Fa "const ASN1_TYPE *a", +.Fa "long *num" +.Fa "unsigned char *buffer", +.Fa "int buflen" +.Fc +.Ft int +.Fo ASN1_TYPE_cmp +.Fa "const ASN1_TYPE *a" +.Fa "const ASN1_TYPE *b" +.Fc +.Sh DESCRIPTION +The +.Vt ASN1_TYPE +data type and the +.Dv V_ASN1_ANY +type identifier constant represent the ASN.1 ANY type. +An +.Vt ASN1_TYPE +object can store an ASN.1 value of arbitrary type, +including constructed types such as a SEQUENCE. +It also remembers internally which type it currently holds. +.Pp +.Fn ASN1_TYPE_new +allocates and initializes an empty +.Vt ASN1_TYPE +object of type +.Dv V_ASN1_UNDEF . +.Pp +.Fn ASN1_TYPE_free +frees +.Fa a +including the value stored in it, if any. +If +.Fa a +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn ASN1_TYPE_get +returns the type currently held by +.Fa a , +represented by one of the +.Dv V_ASN1_* +constants defined in +.In openssl/asn1.h . +.Pp +.Fn ASN1_TYPE_set +frees the value contained in +.Fa a , +if any, and sets the +.Fa value +and +.Fa type +now held in +.Fa a . +This function uses the pointer +.Fa value +internally so it must +.Sy not +be freed up after the call. +.Pp +.Fn ASN1_TYPE_set1 +sets the type held by +.Fa a +to +.Fa type +and its value to a copy of +.Fa value . +If copying succeeds, the previous value that was contained in +.Fa a +is freed. +If copying fails, +.Fa a +remains unchanged. +.Pp +The type and meaning of the +.Fa value +argument of +.Fn ASN1_TYPE_set +and +.Fn ASN1_TYPE_set1 +is determined by the +.Fa type +argument. +If +.Fa type +is +.Dv V_ASN1_NULL , +.Fa value +is ignored. +If +.Fa type +is +.Dv V_ASN1_BOOLEAN , +then the boolean is set to TRUE if +.Fa value +is not +.Dv NULL . +If +.Fa type +is +.Dv V_ASN1_OBJECT , +then +.Fa value +is an +.Vt ASN1_OBJECT +structure. +Otherwise +.Fa type +is an +.Vt ASN1_STRING +structure. +If +.Fa type +corresponds to a primitive type or a string type, then the contents +of the +.Vt ASN1_STRING +contains the content octets of the type. +If +.Fa type +corresponds to a constructed type or a tagged type +.Pq Dv V_ASN1_SEQUENCE , V_ASN1_SET , No or Dv V_ASN1_OTHER , +then the +.Vt ASN1_STRING +contains the entire ASN.1 encoding verbatim, including tag and +length octets. +.Pp +.Fn ASN1_TYPE_set_octetstring +allocates a new +.Vt ASN1_OCTET_STRING +object, copies +.Fa len +bytes of +.Fa data +into it using +.Xr ASN1_STRING_set 3 , +and replaces the value of +.Fa a +with it by calling +.Fn ASN1_TYPE_set +with a type of +.Dv V_ASN1_OCTET_STRING . +.Pp +.Fn ASN1_TYPE_get_octetstring +copies the contents of the +.Vt ASN1_OCTET_STRING +object contained in +.Fa a , +but not more than +.Fa buflen +bytes, into the +.Fa buffer +provided by the caller. +.Pp +.Fn ASN1_TYPE_set_int_octetstring +frees the value contained in +.Fa a , +if any, sets its type to +.Dv V_ASN1_SEQUENCE , +and sets its value to a two-element ASN.1 sequence consisting of +an ASN.1 INTEGER object with the value +.Fa num +and an ASN.1 OCTET STRING object +containing a copy of the +.Fa len +bytes pointed to by +.Fa data . +.Pp +.Fn ASN1_TYPE_get_int_octetstring +copies the integer value from the first element of the ASN.1 sequence +.Fa a +to +.Pf * Fa num +unless +.Fa num +is a +.Dv NULL +pointer and copies the octet string value from the second element, +but not more than +.Fa buflen +bytes, into the +.Fa buffer +provided by the caller unless +.Fa buffer +is a +.Dv NULL +pointer. +.Pp +.Fn ASN1_TYPE_cmp +checks that +.Fa a +and +.Fa b +hold the same type, the same value, and are encoded in the same way. +.Pp +If the types agree and the values have the same meaning but are +encoded differently, they are considered different. +For example, a boolean value is represented +using a single content octet. +Under BER, any non-zero octet represents the TRUE value, but +.Fn ASN1_TYPE_cmp +will only report a match if the content octet is the same. +.Pp +If either or both of the arguments passed to +.Fn ASN1_TYPE_cmp +is +.Dv NULL , +the result is a mismatch. +Technically, if both arguments are +.Dv NULL , +the two types could be absent OPTIONAL fields and so should match, +however passing +.Dv NULL +values could also indicate a programming error (for example an +unparsable type which returns +.Dv NULL ) +for types which do +.Sy not +match. +So applications should handle the case of two absent values separately. +.Sh RETURN VALUES +.Fn ASN1_TYPE_new +returns the new +.Vt ASN1_TYPE +object or +.Dv NULL +if an error occurs. +.Pp +.Fn ASN1_TYPE_get +returns the type currently held by +.Fa a +or 0 if an error occurs. +The latter can happen if +.Fa a +does not contain a value even though its type is not +.Dv V_ASN1_NULL . +For example, it will always happen for empty objects +newly constructed with +.Fn ASN1_TYPE_new . +.Pp +.Fn ASN1_TYPE_set1 , +.Fn ASN1_TYPE_set_octetstring , +and +.Fn ASN1_TYPE_set_int_octetstring +return 1 on success or 0 on failure. +.Pp +.Fn ASN1_TYPE_get_octetstring +returns the number of data bytes contained in the +.Vt ASN1_OCTET_STRING +object contained in +.Fa a +or \-1 if +.Fa a +is not of the type +.Dv V_ASN1_OCTET_STRING +or does not contain any object. +If the return value is greater than the +.Fa buflen +argument, the content was truncated when copied to the +.Fa buffer . +.Pp +.Fn ASN1_TYPE_get_int_octetstring +returns the number of data bytes contained in the +.Vt ASN1_OCTET_STRING +object that is the second element of the ASN.1 sequence +.Fa a +or \-1 if +.Fa a +is not of the type +.Dv V_ASN1_SEQUENCE +or if decoding fails. +If the return value is greater than the +.Fa buflen +argument, the content was truncated when copied to the +.Fa buffer . +.Pp +.Fn ASN1_TYPE_cmp +returns 0 for a match or non-zero for a mismatch. +.Sh SEE ALSO +.Xr ASN1_generate_nconf 3 , +.Xr ASN1_get_object 3 , +.Xr ASN1_item_free 3 , +.Xr ASN1_OBJECT_new 3 , +.Xr ASN1_parse_dump 3 , +.Xr ASN1_put_object 3 , +.Xr ASN1_STRING_dup 3 , +.Xr ASN1_STRING_new 3 , +.Xr crypto 3 , +.Xr d2i_ASN1_NULL 3 , +.Xr d2i_ASN1_SEQUENCE_ANY 3 , +.Xr d2i_ASN1_TYPE 3 , +.Xr OBJ_dup 3 +.Sh HISTORY +.Fn ASN1_TYPE_new +and +.Fn ASN1_TYPE_free +first appeared in SSLeay 0.5.1, +.Fn ASN1_TYPE_get +and +.Fn ASN1_TYPE_set +in SSLeay 0.8.0, and +.Fn ASN1_TYPE_set_octetstring , +.Fn ASN1_TYPE_get_octetstring , +.Fn ASN1_TYPE_set_int_octetstring , +and +.Fn ASN1_TYPE_get_int_octetstring +in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn ASN1_TYPE_set1 +first appeared in OpenSSL 0.9.8h and has been available since +.Ox 4.5 . +.Pp +.Fn ASN1_TYPE_cmp +first appeared in OpenSSL 0.9.8zd, 1.0.0p, and 1.0.1k +and has been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/ASN1_UNIVERSALSTRING_to_string.3 b/static/openbsd/man3/ASN1_UNIVERSALSTRING_to_string.3 new file mode 100644 index 00000000..c7695610 --- /dev/null +++ b/static/openbsd/man3/ASN1_UNIVERSALSTRING_to_string.3 @@ -0,0 +1,65 @@ +.\" $OpenBSD: ASN1_UNIVERSALSTRING_to_string.3,v 1.2 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_UNIVERSALSTRING_TO_STRING 3 +.Os +.Sh NAME +.Nm ASN1_UNIVERSALSTRING_to_string +.Nd recode UTF-32 to ISO Latin-1 +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo ASN1_UNIVERSALSTRING_to_string +.Fa "ASN1_UNIVERSALSTRING *string" +.Fc +.Sh DESCRIPTION +.Fn ASN1_UNIVERSALSTRING_to_string +assumes that the given +.Fa string +is encoded in UTF-32, recodes it in place to ISO Latin-1, +and changes the type according to +.Xr ASN1_PRINTABLE_type 3 . +.Pp +.Fn ASN1_UNIVERSALSTRING_to_string +fails and leaves the +.Fa string +unchanged if its +.Xr ASN1_STRING_type 3 +is not +.Dv V_ASN1_UNIVERSALSTRING , +if its +.Xr ASN1_STRING_length 3 +is not a multiple of four bytes, +or if any of its characters cannot be represented in ISO Latin-1. +.Pp +In case of success, the +.Xr ASN1_STRING_length 3 +of the +.Fa string +is reduced by a factor of four. +.Sh RETURN VALUES +.Fn ASN1_UNIVERSALSTRING_to_string +returns 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr ASN1_mbstring_copy 3 , +.Xr ASN1_STRING_new 3 , +.Xr ASN1_STRING_to_UTF8 3 +.Sh HISTORY +.Fn ASN1_UNIVERSALSTRING_to_string +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/ASN1_generate_nconf.3 b/static/openbsd/man3/ASN1_generate_nconf.3 new file mode 100644 index 00000000..ed92bb13 --- /dev/null +++ b/static/openbsd/man3/ASN1_generate_nconf.3 @@ -0,0 +1,395 @@ +.\" $OpenBSD: ASN1_generate_nconf.3,v 1.14 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL 05ea606a Fri May 20 20:52:46 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson. +.\" Copyright (c) 2002, 2003, 2006-2009, 2013-2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ASN1_GENERATE_NCONF 3 +.Os +.Sh NAME +.Nm ASN1_generate_nconf , +.Nm ASN1_generate_v3 +.Nd ASN.1 generation functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_TYPE * +.Fo ASN1_generate_nconf +.Fa "const char *str" +.Fa "CONF *nconf" +.Fc +.Ft ASN1_TYPE * +.Fo ASN1_generate_v3 +.Fa "const char *str" +.Fa "X509V3_CTX *cnf" +.Fc +.Sh DESCRIPTION +These functions generate the ASN.1 encoding of a string in an +.Vt ASN1_TYPE +structure. +.Pp +.Fa str +contains the string to encode +.Fa nconf +or +.Fa cnf +contains the optional configuration information +where additional strings will be read from. +.Fa nconf +will typically come from a config file whereas +.Fa cnf +is obtained from an +.Vt X509V3_CTX +structure which will typically be used +by X509 v3 certificate extension functions. +.Fa cnf +or +.Fa nconf +can be set to +.Dv NULL +if no additional configuration will be used. +.Sh GENERATION STRING FORMAT +The actual data encoded is determined by the string +.Fa str +and the configuration information. +The general format of the string is: +.Pp +.D1 Oo Ar modifier , Oc Ns Ar type Ns Op : Ns Ar 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 +.Ar type , +.Ar value +and +.Ar modifier +are explained below. +.Ss Supported types +The supported types are listed below. +Unless otherwise specified, only the +.Cm ASCII +format is permissible. +.Bl -tag -width Ds +.It Cm BOOLEAN , BOOL +This encodes a boolean type. +The +.Ar value +string is mandatory and should be +.Cm TRUE +or +.Cm FALSE . +Additionally +.Cm true , +.Cm Y , +.Cm y , +.Cm YES , +.Cm yes , +.Cm false , +.Cm N , +.Cm n , +.Cm NO +and +.Cm no +are acceptable. +.It Cm NULL +Encode the NULL type. +The +.Ar value +string must not be present. +.It Cm INTEGER , INT +Encodes an ASN.1 INTEGER type. +The +.Ar value +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 +.Cm 0x +is included. +.It Cm ENUMERATED , ENUM +Encodes the ASN.1 ENUMERATED type. +It is otherwise identical to +.Cm INTEGER . +.It Cm OBJECT , OID +Encodes an ASN.1 OBJECT IDENTIFIER. +The +.Ar value +string can be a short name, a long name, or numerical format. +.It Cm UTCTIME , UTC +Encodes an ASN.1 UTCTime structure. +The value should be in the format +.Ar YYMMDDHHMMSSZ . +.It Cm GENERALIZEDTIME , GENTIME +Encodes an ASN.1 GeneralizedTime structure. +The value should be in the format +.Ar YYYYMMDDHHMMSSZ . +.It Cm OCTETSTRING , OCT +Encodes an ASN.1 OCTET STRING. +.Ar value +represents the contents of this structure. +The format strings +.Cm ASCII +and +.Cm HEX +can be used to specify the format of +.Ar value . +.It Cm BITSTRING , BITSTR +Encodes an ASN.1 BIT STRING. +.Ar value +represents the contents of this structure. +The format strings +.Cm ASCII , +.Cm HEX , +and +.Cm BITLIST +can be used to specify the format of +.Ar value . +.Pp +If the format is anything other than +.Cm BITLIST , +the number of unused bits is set to zero. +.It Xo +.Cm BMPSTRING , BMP , +.Cm GeneralString , +.Cm IA5STRING , IA5 , +.Cm NUMERICSTRING , NUMERIC , +.Cm PRINTABLESTRING , PRINTABLE , +.Cm T61STRING , T61 , +.Cm TELETEXSTRING , +.Cm UNIVERSALSTRING , UNIV , +.Cm UTF8String , UTF8 , +.Cm VISIBLESTRING , VISIBLE +.Xc +These encode the corresponding string types. +.Ar value +represents the contents of this structure. +The format can be +.Cm ASCII +or +.Cm UTF8 . +.It Cm SEQUENCE , SEQ , SET +Formats the result as an ASN.1 SEQUENCE or SET type. +.Ar value +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 +.Ar value +is absent, then an empty SEQUENCE will be encoded. +.El +.Ss 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: +.Bl -tag -width Ds +.It Cm 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. +.Pp +By following the number with +.Cm U , +.Cm A , +.Cm P +or +.Cm C , +UNIVERSAL, APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used. +The default is CONTEXT SPECIFIC. +.It Cm IMPLICIT , IMP +This is the same as +.Cm EXPLICIT +except IMPLICIT tagging is used instead. +.It Cm 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. +.It Cm FORMAT +This specifies the format of the ultimate value. +It should be followed by a colon and one of the strings +.Cm ASCII , +.Cm UTF8 , +.Cm HEX , +or +.Cm BITLIST . +.Pp +If no format specifier is included, then +.Cm ASCII +is used. +If +.Cm UTF8 +is specified, then the +.Ar value +string must be a valid UTF-8 string. +For +.Cm HEX , +the output must be a set of hex digits. +.Cm BITLIST +(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. +.El +.Sh RETURN VALUES +.Fn ASN1_generate_nconf +and +.Fn ASN1_generate_v3 +return the encoded data as an +.Vt ASN1_TYPE +structure or +.Dv NULL +if an error occurred. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh EXAMPLES +A simple +.Vt IA5String : +.Pp +.Dl IA5STRING:Hello World +.Pp +An +.Vt IA5String +explicitly tagged: +.Pp +.Dl EXPLICIT:0,IA5STRING:Hello World +.Pp +An +.Vt IA5String +explicitly tagged using APPLICATION tagging: +.Pp +.Dl EXPLICIT:0A,IA5STRING:Hello World +.Pp +A BITSTRING with bits 1 and 5 set and all others zero: +.Pp +.Dl FORMAT:BITLIST,BITSTRING:1,5 +.Pp +A more complex example using a config file to produce a +SEQUENCE consisting of a BOOL an OID and a +.Vt UTF8String : +.Bd -literal -offset indent +asn1 = SEQUENCE:seq_section + +[seq_section] + +field1 = BOOLEAN:TRUE +field2 = OID:commonName +field3 = UTF8:Third field +.Ed +.Pp +This example produces an +.Vt RSAPrivateKey +structure. +This is the key contained in the file +.Pa client.pem +in all OpenSSL distributions. +Note that the field names such as +.Qq coeff +are ignored and are present just for clarity. +.Bd -literal -offset 2n +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 +.Ed +.Pp +This example is the corresponding public key in an ASN.1 +.Vt SubjectPublicKeyInfo +structure: +.Bd -literal -offset 2n +# 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 +.Ed +.Sh SEE ALSO +.Xr ASN1_TYPE_get 3 , +.Xr d2i_ASN1_TYPE 3 , +.Xr x509v3.cnf 5 +.Sh HISTORY +.Fn ASN1_generate_nconf +and +.Fn ASN1_generate_v3 +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/ASN1_get_object.3 b/static/openbsd/man3/ASN1_get_object.3 new file mode 100644 index 00000000..7f92ff6d --- /dev/null +++ b/static/openbsd/man3/ASN1_get_object.3 @@ -0,0 +1,201 @@ +.\" $OpenBSD: ASN1_get_object.3,v 1.3 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_GET_OBJECT 3 +.Os +.Sh NAME +.Nm ASN1_get_object +.Nd parse identifier and length octets +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo ASN1_get_object +.Fa "const unsigned char **ber_in" +.Fa "long *plength" +.Fa "int *ptag" +.Fa "int *pclass" +.Fa "long omax" +.Fc +.Sh DESCRIPTION +.Fn ASN1_get_object +parses the identifier and length octets of a BER-encoded value. +On function entry, +.Pf * Fa ber_in +is expected to point to the first identifier octet. +If the identifier and length octets turn out to be valid, +the function advances +.Pf * Fa ber_in +to the first content octet before returning. +.Pp +If the identifier octets are valid, +.Fn ASN1_get_object +stores the tag number in +.Pf * Fa ptag +and the class of the tag in +.Pf * Fa pclass . +The class is either +.Dv V_ASN1_UNIVERSAL +or +.Dv V_ASN1_APPLICATION +or +.Dv V_ASN1_CONTEXT_SPECIFIC +or +.Dv V_ASN1_PRIVATE . +.Pp +If the length octets are valid, too, +.Fn ASN1_get_object +stores the number encoded in the length octets in +.Pf * Fa plength . +If the length octet indicates the indefinite form, +.Pf * Fa plength +is set to 0. +.Pp +.Fn ASN1_get_object +inspects at most +.Fa omax +bytes. +If parsing of the length octets remains incomplete after inspecting +that number of bytes, parsing fails with +.Dv ASN1_R_HEADER_TOO_LONG . +.Sh RETURN VALUES +Bits set in the return value of +.Fn ASN1_get_object +have the following meanings: +.Bl -tag -width Ds +.It 0x80 +An error occurred. +One of the +.Sx ERRORS +described below has been set. +.It 0x20 = Dv V_ASN1_CONSTRUCTED +The encoding is constructed rather than primitive, +and the identifier and length octets are valid. +.It 0x01 +The length octet indicates the indefinite form. +This bit can only occur if +.Dv V_ASN1_CONSTRUCTED +is also set. +.El +.Pp +Consequently, the following combinations can occur: +.Bl -tag -width Ds +.It 0x00 +A valid primitive encoding. +.It 0x20 +A valid constructed encoding, definite form. +.It 0x21 +A valid constructed encoding, indefinite form. +.It 0x80 +Either a primitive encoding with a valid tag and definite length, +but the content octets won't fit into +.Fa omax , +or parsing failed. +Use +.Xr ERR_GET_REASON 3 +to distinguish the two cases. +.It 0xa0 +A constructed encoding with a valid tag and definite length, +but the content octets won't fit into +.Fa omax . +.El +.Pp +The bit combinations 0x01, 0x81, and 0xa1 cannot occur as return values. +.Sh ERRORS +If the bit 0x80 is set in the return value, +diagnostics can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv ASN1_R_HEADER_TOO_LONG Qq "header too long" +Inspecting +.Fa omax +bytes was insufficient to finish parsing, +the tag number encoded in the identifier octets exceeds +.Dv INT_MAX , +the number encoded in the length octets exceeds +.Dv LONG_MAX , +or using the indefinite form for the length octets is attempted +even though the encoding is primitive. +.Pp +In this case, the return value is exactly 0x80; no other bits are set. +.Pp +If the problem occurred while parsing the identifier octets, +.Pf * Fa ptag +and +.Pf * Fa pclass +remain unchanged. +If the problem occurred while parsing the length octets, +.Pf * Fa ptag +and +.Pf * Fa pclass +are set according to the identifier octets. +In both cases, +.Pf * Fa ber_in +and +.Pf * Fa plength +remain unchanged. +.Pp +The wording of the error message is confusing. +On the one hand, the header might be just fine, +and the root cause of the problem could be that the chosen +.Fa omax +argument was too small. +On the other hand, outright BER syntax errors are also reported as +.Dv ASN1_R_HEADER_TOO_LONG . +.It Dv ASN1_R_TOO_LONG Qq "too long" +The identifier and length octets are valid, +but the content octets won't fit into +.Fa omax . +The following have been set as appropriate and can safely be inspected: +.Pf * pclass , +.Pf * ptag , +.Pf * plength , +and the bits +.Dv V_ASN1_CONSTRUCTED +and 0x01 in the return value. +The parse pointer +.Pf * ber_in +has been advanced to the first content octet. +.Pp +Again, the error message may occasionally sound confusing. +The length of the content may be reasonable, and the root cause of +the problem could be that the chosen +.Fa omax +argument was too small. +.El +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr ASN1_item_new 3 , +.Xr ASN1_parse_dump 3 +.Sh STANDARDS +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules: +Specification of Basic Encoding Rules (BER), Canonical Encoding +Rules (CER) and Distinguished Encoding Rules (DER): +.Bl -dash -offset 2n -width 1n -compact +.It +Section 8.1.2: Identifier octets +.It +Section 8.1.3: Length octets +.El +.Sh HISTORY +.Fn ASN1_get_object +first appeared in SSLeay 0.5.1 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/ASN1_item_d2i.3 b/static/openbsd/man3/ASN1_item_d2i.3 new file mode 100644 index 00000000..cb5fd19f --- /dev/null +++ b/static/openbsd/man3/ASN1_item_d2i.3 @@ -0,0 +1,493 @@ +.\" $OpenBSD: ASN1_item_d2i.3,v 1.19 2025/06/08 22:40:29 schwarze Exp $ +.\" selective merge up to: +.\" OpenSSL doc/man3/d2i_X509.pod 256989ce Jun 19 15:00:32 2020 +0200 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016, 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2003, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ASN1_ITEM_D2I 3 +.Os +.Sh NAME +.Nm ASN1_item_d2i , +.Nm ASN1_item_d2i_bio , +.Nm ASN1_item_d2i_fp , +.Nm d2i_ASN1_TYPE , +.Nm ASN1_item_i2d , +.Nm ASN1_item_i2d_bio , +.Nm ASN1_item_i2d_fp , +.Nm i2d_ASN1_TYPE , +.Nm ASN1_item_dup , +.Nm ASN1_item_print +.Nd decode and encode ASN.1 objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_VALUE * +.Fo ASN1_item_d2i +.Fa "ASN1_VALUE **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fa "const ASN1_ITEM *it" +.Fc +.Ft void * +.Fo ASN1_item_d2i_bio +.Fa "const ASN1_ITEM *it" +.Fa "BIO *in_bio" +.Fa "void *val_out" +.Fc +.Ft void * +.Fo ASN1_item_d2i_fp +.Fa "const ASN1_ITEM *it" +.Fa "FILE *in_fp" +.Fa "void *val_out" +.Fc +.Ft ASN1_TYPE * +.Fo d2i_ASN1_TYPE +.Fa "ASN1_TYPE **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo ASN1_item_i2d +.Fa "ASN1_VALUE *val_in" +.Fa "unsigned char **der_out" +.Fa "const ASN1_ITEM *it" +.Fc +.Ft int +.Fo ASN1_item_i2d_bio +.Fa "const ASN1_ITEM *it" +.Fa "BIO *out_bio" +.Fa "void *val_in" +.Fc +.Ft int +.Fo ASN1_item_i2d_fp +.Fa "const ASN1_ITEM *it" +.Fa "FILE *out_fp" +.Fa "void *val_in" +.Fc +.Ft int +.Fo i2d_ASN1_TYPE +.Fa "ASN1_TYPE *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft void * +.Fo ASN1_item_dup +.Fa "const ASN1_ITEM *it" +.Fa "void *val_in" +.Fc +.Ft int +.Fo ASN1_item_print +.Fa "BIO *out_bio" +.Fa "ASN1_VALUE *val_in" +.Fa "int indent" +.Fa "const ASN1_ITEM *it" +.Fa "const ASN1_PCTX *pctx" +.Fc +.Sh DESCRIPTION +These functions convert ASN.1 values from their BER encoding to +internal C structures +.Pq Dq d2i +and vice versa +.Pq Dq i2d . +Unlike the C structures which contain pointers to sub-objects, BER +is a serialized encoding, suitable for transfer over the network +and for storage in a file. +.Pp +.Fn ASN1_item_d2i +interprets +.Pf * Fa der_in +as a DER- or BER-encoded byte array and decodes one value of type +.Fa it +represented by up to +.Fa length +bytes. +If successful, +.Pf * Fa der_in +is advanced to the byte following the parsed data. +.Pp +If decoding succeeds and +.Fa val_out +or +.Pf * Fa val_out +is +.Dv NULL , +a new object is allocated. +.Pp +If decoding succeeds and +.Pf * Fa val_out +is not +.Dv NULL , +it is assumed to point to a valid populated object and an attempt +is made to reuse it. +It must not be an empty structure such as one returned by +.Xr ASN1_item_new 3 +or by one of the various type-specific +.Fn *_new +functions. +This +.Dq reuse +capability is present for backward compatibility, but its use is +strongly discouraged; see the +.Sx BUGS +section below. +.Pp +.Fn ASN1_item_d2i_bio +and +.Fn ASN1_item_d2i_fp +are similar to +.Fn ASN1_item_d2i +except that they read from a +.Vt BIO +or +.Vt FILE , +respectively. +.Pp +.Fn d2i_ASN1_TYPE +is similar to +.Fn ASN1_item_d2i +except that it does not require a desired type to be specified by +the user, but instead returns an +.Vt ASN1_TYPE +wrapper object containing both the type and the value found in the input. +.Pp +.Fn ASN1_item_i2d +encodes the object pointed to by +.Fa val_in +into DER format. +.Pp +If +.Pf * Fa der_out +is not +.Dv NULL , +it writes the DER-encoded data to the buffer at +.Pf * Fa der_out +and increments it to point after the data just written. +In this case, it is the responsibility of the user to make sure +that the buffer pointed to by +.Pf * Fa der_out +is long enough, such that no buffer overflow can occur. +.Pp +If +.Pf * Fa der_out +is +.Dv NULL , +memory is allocated for a buffer, and +.Pf * Fa der_out +is not incremented, but points to the start of the data just written. +.Pp +If +.Fa der_out +is +.Dv NULL , +the encoded bytes are not written anywhere but discarded. +For +.Fa val_in +objects of variable encoding size, this is sometimes used to first +find the number of bytes that will be written. +Then, a sufficient amount of memory is allocated before calling +.Fn ASN1_item_i2d +again. +This explicit double-call technique is often not needed because the +auto-allocation technique described in the previous paragraph can +be used. +.Pp +.Fn ASN1_item_i2d_bio +and +.Fn ASN1_item_i2d_fp +are similar to +.Fn ASN1_item_i2d +except that they write to a +.Vt BIO +or +.Vt FILE , +respectively. +.Pp +.Fn i2d_ASN1_TYPE +is similar to +.Fn ASN1_item_i2d +except that the type and the value are not provided separately, +but in the form of a single +.Vt ASN1_TYPE +object. +.Pp +.Fn ASN1_item_dup +creates a deep copy of +.Fa val_in +by calling +.Fn ASN1_item_i2d +and +.Fn ASN1_item_d2i . +.Sh RETURN VALUES +If successful, +.Fn ASN1_item_d2i , +.Fn ASN1_item_d2i_bio , +.Fn ASN1_item_d2i_fp , +and +.Fn d2i_ASN1_TYPE +return a pointer to the decoded ASN.1 value. +In addition, if +.Fa val_out +is not +.Dv NULL , +the pointer is also written to +.Pf * Fa val_out . +If an error occurs, +.Dv NULL +is returned. +.Pp +.Fn ASN1_item_i2d +and +.Fn i2d_ASN1_TYPE +return the number of bytes written +or a negative value if an error occurs. +.Pp +.Fn ASN1_item_i2d_bio +and +.Fn ASN1_item_i2d_fp +return 1 for success or 0 for failure. +.Pp +.Fn ASN1_item_dup +returns the new +.Vt ASN1_VALUE +object or +.Dv NULL +if an error occurs. +.Sh EXAMPLES +Many type-specific wrapper functions exist. +Using those wrappers is recommended in application code +because it restores part of the type safety that the low-level +interfaces using +.Vt ASN1_VALUE +lack. +.Pp +For example, to allocate a buffer and write the DER encoding of an +.Vt X509 +object into it: +.Bd -literal -offset indent +X509 *x; +unsigned char *buf; +int len; + +buf = NULL; +len = i2d_X509(x, &buf); +if (len < 0) + /* error */ +.Ed +.Pp +Attempt to decode a buffer: +.Bd -literal -offset indent +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 */ +.Ed +.Pp +Equivalent technique: +.Bd -literal -offset indent +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 */ +.Ed +.Sh SEE ALSO +.Xr ASN1_get_object 3 , +.Xr ASN1_item_digest 3 , +.Xr ASN1_item_new 3 , +.Xr ASN1_item_pack 3 , +.Xr ASN1_item_sign 3 , +.Xr ASN1_item_verify 3 , +.Xr ASN1_TYPE_new 3 +.Sh HISTORY +.Fn d2i_ASN1_TYPE +and +.Fn i2d_ASN1_TYPE +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn ASN1_item_d2i , +.Fn ASN1_item_d2i_bio , +.Fn ASN1_item_d2i_fp , +.Fn ASN1_item_i2d , +.Fn ASN1_item_i2d_bio , +.Fn ASN1_item_i2d_fp , +and +.Fn ASN1_item_dup +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn ASN1_item_print +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Sh CAVEATS +If the type described by +.Fa it +fails to match the true type of +.Fa val_in +or +.Pf * Fa val_out , +buffer overflows and segmentation faults are likely to occur. +For more details about why the type +.Vt ASN1_VALUE +constitutes dangerous user interface design, see +.Xr ASN1_item_new 3 . +.Pp +The encoded data is in binary form and may contain embedded NUL bytes. +Functions such as +.Xr strlen 3 +will not return the correct length of the encoded data. +.Pp +While the way that +.Pf * Fa der_in +and +.Pf * Fa der_out +are incremented after the operation supports the typical usage +patterns of reading or writing one object after another, this +behaviour can trap the unwary. +.Pp +Using a temporary pointer into the buffer is mandatory. +A common mistake is to attempt to use a buffer directly as follows: +.Bd -literal -offset indent +X509 *x; +unsigned char *buf; +int len; + +len = i2d_X509(x, NULL); +buf = malloc(len); +i2d_X509(x, &buf); +/* do something with buf[] */ +free(buf); +.Ed +.Pp +This code will result in +.Va buf +apparently containing garbage because it was incremented during +.Fn i2d_X509 +to point after the data just written. +Also +.Va buf +will no longer contain the pointer allocated by +.Xr malloc 3 +and the subsequent call to +.Xr free 3 +is likely to crash. +.Pp +Another trap to avoid is misuse of the +.Fa val_out +argument: +.Bd -literal -offset indent +X509 *x; + +if (d2i_X509(&x, &p, len) == NULL) + /* error */ +.Ed +.Pp +This will probably crash somewhere in +.Fn d2i_X509 +because +.Va x +is uninitialized and an attempt will be made to interpret its invalid +content as an +.Vt X509 +object, typically causing a segmentation violation. +If +.Va x +is set to +.Dv NULL +first, then this will not happen. +.Sh BUGS +If the +.Dq reuse +capability is used, a valid object is passed in via +.Pf * Fa val_out , +and an error occurs, then the object is not freed and may be left +in an invalid or inconsistent state. +.Pp +In some versions of OpenSSL, the +.Dq reuse +behaviour is broken such that some parts of the reused object may +persist if they are not present in the new one. +.Pp +In many versions of OpenSSL, +.Fn ASN1_item_i2d +will not return an error if mandatory fields are not initialized +due to a programming error. +In that case, the encoded structure may contain invalid data and +some fields may be missing entirely, such that trying to parse it +with +.Fn ASN1_item_d2i +may fail. diff --git a/static/openbsd/man3/ASN1_item_digest.3 b/static/openbsd/man3/ASN1_item_digest.3 new file mode 100644 index 00000000..829b82a5 --- /dev/null +++ b/static/openbsd/man3/ASN1_item_digest.3 @@ -0,0 +1,72 @@ +.\" $OpenBSD: ASN1_item_digest.3,v 1.3 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_ITEM_DIGEST 3 +.Os +.Sh NAME +.Nm ASN1_item_digest +.Nd DER-encode and hash an ASN.1 value +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo ASN1_item_digest +.Fa "const ASN1_ITEM *it" +.Fa "const EVP_MD *type" +.Fa "void *val_in" +.Fa "unsigned char *md" +.Fa "unsigned int *s" +.Fc +.Sh DESCRIPTION +.Fn ASN1_item_digest +assumes that +.Fa val_in +is an +.Vt ASN1_VALUE +of the type specified by +.Fa it , +encodes it into DER format by calling +.Xr ASN1_item_i2d 3 , +hashes the resulting byte array using the digest +.Fa type +by calling +.Xr EVP_Digest 3 , +places the digest value into +.Pf * Fa md , +and, unless +.Fa s +is +.Dv NULL , +places the length in bytes of the digest into +.Pf * Fa s . +Providing a buffer +.Pf * Fa md +large enough to contain the digest is the responsibility of the caller; +providing a buffer of +.Dv EVP_MAX_MD_SIZE +bytes is recommended. +.Sh RETURN VALUES +.Fn ASN1_item_digest +returns 1 for success or 0 if encoding or hashing fails. +.Sh SEE ALSO +.Xr ASN1_item_i2d 3 , +.Xr ASN1_item_sign 3 , +.Xr EVP_Digest 3 +.Sh HISTORY +.Fn ASN1_item_digest +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.1 . diff --git a/static/openbsd/man3/ASN1_item_new.3 b/static/openbsd/man3/ASN1_item_new.3 new file mode 100644 index 00000000..42e9dd8f --- /dev/null +++ b/static/openbsd/man3/ASN1_item_new.3 @@ -0,0 +1,127 @@ +.\" $OpenBSD: ASN1_item_new.3,v 1.12 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2016, 2018 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_ITEM_NEW 3 +.Os +.Sh NAME +.Nm ASN1_item_new , +.Nm ASN1_item_free +.Nd generic ASN.1 value constructor and destructor +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_VALUE * +.Fo ASN1_item_new +.Fa "const ASN1_ITEM *it" +.Fc +.Ft void +.Fo ASN1_item_free +.Fa "ASN1_VALUE *val_in" +.Fa "const ASN1_ITEM *it" +.Fc +.Sh DESCRIPTION +.Fn ASN1_item_new +allocates and initializes an empty ASN.1 value +of the type described by the global static object +.Fa it . +.Pp +If the item type described by +.Fa it +is reference counted, +.Fn ASN1_item_free +decrements the reference count of +.Fa val_in . +Otherwise, or if the reference count reaches 0, +.Fn ASN1_item_free +frees +.Fa val_in , +assuming that it is of the type described by +.Fa it . +If the true type of +.Fa val_in +fails to match the specified +.Fa it , +buffer overflows and segmentation faults are likely to occur. +It is not possible to recover the type of an +.Vt ASN1_VALUE +object by inspecting it; the type always needs to be remembered +separately. +.Pp +.Vt ASN1_VALUE +is an incomplete type, and pointers to it always require casting +to the correct complete type before they can be dereferenced. +For all practical purposes, a pointer to +.Vt ASN1_VALUE +is equivalent to a +.Vt void +pointer. +.Pp +Depending on +.Fa it , +there are more than 150 different types that +.Fn ASN1_item_new +may return. +Most of them are pointers to structures or pointers to arrays of +structures, but there are a few exceptions, for example: +If +.Fa it +is +.Dv ASN1_NULL_it , +.Fn ASN1_item_new +returns a specific invalid pointer representing the unique +.Vt ASN1_NULL +object. +If +.Fa it +is +.Dv LONG_it , +.Fn ASN1_item_new +does not return a pointer at all, but a +.Vt long +value cast to +.Vt ASN1_VALUE * . +.Sh RETURN VALUES +The +.Fn ASN1_item_new +function returns the new +.Vt ASN1_VALUE +object if successful; otherwise +.Dv NULL +is returned and an error code can be retrieved with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ASN1_get_object 3 , +.Xr ASN1_item_d2i 3 , +.Xr ASN1_item_digest 3 , +.Xr ASN1_item_pack 3 , +.Xr ASN1_item_sign 3 , +.Xr ASN1_item_verify 3 , +.Xr ASN1_NULL_new 3 , +.Xr ASN1_TYPE_new 3 , +.Xr d2i_ASN1_NULL 3 , +.Xr OBJ_nid2obj 3 +.Sh HISTORY +.Fn ASN1_item_new +and +.Fn ASN1_item_free +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Sh BUGS +The +.Vt ASN1_VALUE +type compromises type safety and invites programming mistakes that +will typically have severe consequences. diff --git a/static/openbsd/man3/ASN1_item_pack.3 b/static/openbsd/man3/ASN1_item_pack.3 new file mode 100644 index 00000000..d0023f59 --- /dev/null +++ b/static/openbsd/man3/ASN1_item_pack.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: ASN1_item_pack.3,v 1.2 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_ITEM_PACK 3 +.Os +.Sh NAME +.Nm ASN1_item_pack , +.Nm ASN1_item_unpack +.Nd pack an ASN.1 object into an ASN1_STRING +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_STRING * +.Fo ASN1_item_pack +.Fa "void *val_in" +.Fa "const ASN1_ITEM *it" +.Fa "ASN1_STRING **string_out" +.Fc +.Ft void * +.Fo ASN1_item_unpack +.Fa "const ASN1_STRING *string_in" +.Fa "const ASN1_ITEM *it" +.Fc +.Sh DESCRIPTION +.Fn ASN1_item_pack +encodes the object pointed to by +.Fa val_in +into DER format using +.Xr ASN1_item_i2d 3 +and stores the encoded form in +.Pf ** Fa string_out . +If +.Fa string_out +or +.Pf * Fa string_out +is a +.Dv NULL +pointer, a new +.Vt ASN1_STRING +object is allocated and returned. +.Pp +.Fn ASN1_item_unpack +interprets the data in +.Fa string_in +as a DER- or BER-encoded byte array and decodes one value of the type +.Fa it +into a newly allocated object using +.Xr ASN1_item_d2i 3 . +.Sh RETURN VALUES +.Fn ASN1_item_pack +returns the modified or new object or +.Dv NULL +if memory allocation or encoding fails. +.Pp +.Fn ASN1_item_unpack +returns the new object or +.Dv NULL +if memory allocation or decoding fails. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr ASN1_item_new 3 , +.Xr ASN1_STRING_new 3 +.Sh HISTORY +.Fn ASN1_item_pack +and +.Fn ASN1_item_unpack +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Sh BUGS +See the BUGS section in +.Xr ASN1_item_i2d 3 . diff --git a/static/openbsd/man3/ASN1_item_sign.3 b/static/openbsd/man3/ASN1_item_sign.3 new file mode 100644 index 00000000..72e317c3 --- /dev/null +++ b/static/openbsd/man3/ASN1_item_sign.3 @@ -0,0 +1,121 @@ +.\" $OpenBSD: ASN1_item_sign.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_ITEM_SIGN 3 +.Os +.Sh NAME +.Nm ASN1_item_sign , +.Nm ASN1_item_sign_ctx +.Nd DER-encode and sign an ASN.1 value +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo ASN1_item_sign +.Fa "const ASN1_ITEM *it" +.Fa "X509_ALGOR *algor1" +.Fa "X509_ALGOR *algor2" +.Fa "ASN1_BIT_STRING *sig_out" +.Fa "void *val_in" +.Fa "EVP_PKEY *pkey" +.Fa "const EVP_MD *type" +.Fc +.Ft int +.Fo ASN1_item_sign_ctx +.Fa "const ASN1_ITEM *it" +.Fa "X509_ALGOR *algor1" +.Fa "X509_ALGOR *algor2" +.Fa "ASN1_BIT_STRING *sig_out" +.Fa "void *val_in" +.Fa "EVP_MD_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn ASN1_item_sign +assumes that +.Fa val_in +is an +.Vt ASN1_VALUE +of the type specified by +.Fa it , +encodes it into DER format by calling +.Xr ASN1_item_i2d 3 , +and signs the resulting byte array in a way similar to +.Xr EVP_DigestSign 3 , +using a signing context created with +.Xr EVP_DigestSignInit 3 +for the given digest +.Fa type +and private key +.Fa pkey . +The created signature is placed into the +.Fa sig_out +object provided by the caller, +freeing and replacing any data already contained in that object. +.Pp +.Fn ASN1_item_sign_ctx +is similar except that the provided +.Ft ctx +is used rather than creating a new one. +No matter whether +.Fn ASN1_item_sign_ctx +succeeds or fails, +.Xr EVP_MD_CTX_cleanup 3 +is called on +.Fa ctx +before returning. +.Pp +For both functions, unless +.Fa algor1 +is +.Dv NULL , +its algorithm OID and parameter type are set according to the digest +.Fa type +used, and its parameter value is cleared. +In RSA-PSS mode, the parameter value is also copied into +.Fa algor1 . +Unless +.Fa algor2 +is +.Dv NULL , +the same data is copied into it. +.Sh RETURN VALUES +These functions return the length of the signature in bytes +or 0 if memory allocation, encoding, or signing fails. +.Pp +.Fn ASN1_item_sign_ctx +also fails and returns 0 if +.Fa ctx +is not fully initialized. +.Sh SEE ALSO +.Xr ASN1_BIT_STRING_new 3 , +.Xr ASN1_item_digest 3 , +.Xr ASN1_item_i2d 3 , +.Xr ASN1_item_verify 3 , +.Xr EVP_Digest 3 , +.Xr EVP_DigestSign 3 , +.Xr EVP_MD_CTX_new 3 , +.Xr EVP_PKEY_new 3 , +.Xr OBJ_find_sigid_by_algs 3 , +.Xr X509_ALGOR_new 3 +.Sh HISTORY +.Fn ASN1_item_sign +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.1 . +.Pp +.Fn ASN1_item_sign_ctx +first appeared in OpenSSL 1.0.1 and has been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/ASN1_item_verify.3 b/static/openbsd/man3/ASN1_item_verify.3 new file mode 100644 index 00000000..282db875 --- /dev/null +++ b/static/openbsd/man3/ASN1_item_verify.3 @@ -0,0 +1,78 @@ +.\" $OpenBSD: ASN1_item_verify.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_ITEM_VERIFY 3 +.Os +.Sh NAME +.Nm ASN1_item_verify +.Nd signature verification for ASN.1 values +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo ASN1_item_verify +.Fa "const ASN1_ITEM *it" +.Fa "X509_ALGOR *algor1" +.Fa "ASN1_BIT_STRING *sig_in" +.Fa "void *val_in" +.Fa "EVP_PKEY *pkey" +.Fc +.Sh DESCRIPTION +.Fn ASN1_item_verify +assumes that +.Fa val_in +is an +.Ft ASN1_VALUE +of the type specified by +.Fa it , +encodes it into DER format by calling +.Xr ASN1_item_i2d 3 , +and verifies in a way similar to +.Xr EVP_DigestVerify 3 +that +.Fa sig_in +contains a valid signature of the resulting byte array, +a signature that was created with the signature algorithm +.Fa algor1 +and the private key corresponding to the public key +.Fa pkey . +.Sh RETURN VALUES +.Fn ASN1_item_verify +returns 1 if signature verification succeeds, 0 if signature verification +fails, or \-1 if +.Fa pkey +is +.Dv NULL , +if +.Fa sig_in +contains invalid flags, or if +.Fa algor1 +requests an invalid or unsupported digest algorithm +or does not work with the given +.Fa pkey . +.Sh SEE ALSO +.Xr ASN1_BIT_STRING_new 3 , +.Xr ASN1_item_i2d 3 , +.Xr ASN1_item_sign 3 , +.Xr EVP_DigestVerify 3 , +.Xr EVP_PKEY_new 3 , +.Xr OBJ_find_sigid_algs 3 , +.Xr X509_ALGOR_new 3 +.Sh HISTORY +.Fn ASN1_item_verify +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.1 . diff --git a/static/openbsd/man3/ASN1_mbstring_copy.3 b/static/openbsd/man3/ASN1_mbstring_copy.3 new file mode 100644 index 00000000..6a64bc74 --- /dev/null +++ b/static/openbsd/man3/ASN1_mbstring_copy.3 @@ -0,0 +1,370 @@ +.\" $OpenBSD: ASN1_mbstring_copy.3,v 1.7 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_MBSTRING_COPY 3 +.Os +.Sh NAME +.Nm ASN1_mbstring_copy , +.Nm ASN1_mbstring_ncopy , +.Nm ASN1_STRING_set_by_NID , +.Nm ASN1_STRING_set_default_mask , +.Nm ASN1_STRING_set_default_mask_asc , +.Nm ASN1_STRING_get_default_mask , +.Nm ASN1_tag2bit +.Nd copy a multibyte string into an ASN.1 string object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo ASN1_mbstring_copy +.Fa "ASN1_STRING **out" +.Fa "const unsigned char *in" +.Fa "int inbytes" +.Fa "int inform" +.Fa "unsigned long mask" +.Fc +.Ft int +.Fo ASN1_mbstring_ncopy +.Fa "ASN1_STRING **out" +.Fa "const unsigned char *in" +.Fa "int inbytes" +.Fa "int inform" +.Fa "unsigned long mask" +.Fa "long minchars" +.Fa "long maxchars" +.Fc +.Ft ASN1_STRING * +.Fo ASN1_STRING_set_by_NID +.Fa "ASN1_STRING **out" +.Fa "const unsigned char *in" +.Fa "int inbytes" +.Fa "int inform" +.Fa "int nid" +.Fc +.Ft void +.Fo ASN1_STRING_set_default_mask +.Fa "unsigned long mask" +.Fc +.Ft int +.Fo ASN1_STRING_set_default_mask_asc +.Fa "const char *maskname" +.Fc +.Ft unsigned long +.Fn ASN1_STRING_get_default_mask void +.Ft unsigned long +.Fn ASN1_tag2bit "int tag" +.Sh DESCRIPTION +.Fn ASN1_mbstring_copy +interprets +.Fa inbytes +bytes starting at +.Fa in +as a multibyte string and copies it to +.Pf * Fa out , +optionally changing the encoding. +If the +.Fa inbytes +argument is negative, the +.Xr strlen 3 +of +.Fa in +is used instead. +.Pp +The +.Fa inform +argument specifies the character encoding of +.Fa in : +.Bl -column MBSTRING_UNIV encoding +.It Ar inform Ta encoding +.It Dv MBSTRING_ASC Ta ISO-Latin-1 +.It Dv MBSTRING_BMP Ta UTF-16 +.It Dv MBSTRING_UNIV Ta UTF-32 +.It Dv MBSTRING_UTF8 Ta UTF-8 +.El +.Pp +The bit +.Fa mask +specifies a set of ASN.1 string types +that the user is willing to accept: +.Bl -column B_ASN1_UNIVERSALSTRING ASN1_UNIVERSALSTRING default +.It bit in Fa mask Ta acceptable output type Ta default +.It Dv B_ASN1_PRINTABLESTRING Ta Vt ASN1_PRINTABLESTRING Ta yes +.It Dv B_ASN1_IA5STRING Ta Vt ASN1_IA5STRING Ta no +.It Dv B_ASN1_T61STRING Ta Vt ASN1_T61STRING Ta yes +.It Dv B_ASN1_BMPSTRING Ta Vt ASN1_BMPSTRING Ta yes +.It Dv B_ASN1_UNIVERSALSTRING Ta Vt ASN1_UNIVERSALSTRING Ta no +.It any other bit Ta Vt ASN1_UTF8STRING Ta yes +.El +.Pp +The first type from the above table that is included in the +.Fa mask +argument and that can represent +.Fa in +is used as the output type. +The +.Dq default +column indicates whether the type is considered acceptable if the +.Fa mask +argument has the special value 0. +.Pp +The following bit mask constants +each include several of the bits listed above: +.Bl -column B_ASN1_DIRECTORYSTRING_ MMM MMM MMM MMM MMM MMMM +.It mask constant Ta PRI Ta IA5 Ta T61 Ta BMP Ta UNI Ta UTF8 +.It Dv B_ASN1_DIRECTORYSTRING Ta yes Ta no Ta yes Ta yes Ta yes Ta yes +.It Dv DIRSTRING_TYPE Ta yes Ta no Ta yes Ta yes Ta no Ta yes +.It Dv PKCS9STRING_TYPE Ta yes Ta yes Ta yes Ta yes Ta no Ta yes +.El +.Pp +If +.Fa out +is +.Dv NULL , +.Fa inform , +.Fa inbytes , +and +.Fa in +are validated and the output type is determined and returned, +but nothing is copied. +.Pp +Otherwise, if +.Pf * Fa out +is +.Dv NULL , +a new output object of the output type is allocated +and a pointer to it is stored in +.Pf * Fa out . +.Pp +Otherwise, +.Pf ** Fa out +is used as the output object. +Any data already stored in it is freed +and its type is changed to the output type. +.Pp +Finally, +.Fa in +is copied to the output object, changing the character encoding if +.Fa inform +does not match the encoding used by the output type. +.Pp +.Fn ASN1_mbstring_ncopy +is similar except that the number of characters in +.Fa in +is restricted to the range from +.Fa minchars +to +.Fa maxchars , +inclusive. +If +.Fa maxchars +is 0, no upper limit is enforced on the number of characters. +.Pp +.Fn ASN1_STRING_set_by_NID +is similar with the following differences: +.Bl -bullet -width 1n +.It +If +.Fa out +is +.Dv NULL , +a new output object is allocated and returned +instead of skipping the copying. +.It +If +.Fa nid +has a global string table entry that can be retrieved with +.Xr ASN1_STRING_TABLE_get 3 , +.Fa mask , +.Fa minchars , +and +.Fa maxchars +are taken from that string table entry. +For some values of +.Fa nid , +an additional global mask is AND'ed into the mask before using it. +The default value of the global mask is +.Dv B_ASN1_UTF8STRING . +.It +If +.Fa nid +has no global string table entry, +.Dv B_ASN1_PRINTABLESTRING | B_ASN1_T61STRING | +.Dv B_ASN1_BMPSTRING | B_ASN1_UTF8STRING +is used instead of the mask taken from the table, +and the global mask is also AND'ed into it. +.It +Even though success and failure happen in the same situations, +the return value is different. +.Xr ASN1_STRING_type 3 +can be used to determine the type of the return value. +.El +.Pp +.Fn ASN1_STRING_set_default_mask +sets the global mask used by +.Fn ASN1_STRING_set_by_NID +to the +.Fa mask +argument. +.Pp +.Fn ASN1_STRING_set_default_mask_asc +sets the global mask as follows: +.Bl -column utf8only +.It Ar maskname Ta Ar mask +.It Qo default Qc Ta anything +.It Qo nombstr Qc Ta anything except Dv B_ASN1_BMPSTRING | B_ASN1_UTF8STRING +.It Qo pkix Qc Ta anything except Dv B_ASN1_T61STRING +.It Qo utf8only Qc Ta Dv B_ASN1_UTF8STRING +.El +.Pp +If the +.Fa maskname +argument starts with the substring +.Qq MASK:\& , +the rest of it is interpreted as an +.Vt unsigned long +value using +.Xr strtoul 3 . +.Pp +.Fn ASN1_tag2bit +translates ASN.1 data types to type bits as follows: +.Bl -column V_ASN1_OBJECT_DESCRIPTOR B_ASN1_UNIVERSALSTRING +.It Fa tag Ta return value +.It Dv V_ASN1_BIT_STRING Ta Dv B_ASN1_BIT_STRING +.It Dv V_ASN1_BMPSTRING Ta Dv B_ASN1_BMPSTRING +.It Dv V_ASN1_BOOLEAN Ta 0 +.It Dv V_ASN1_ENUMERATED Ta Dv B_ASN1_UNKNOWN +.It Dv V_ASN1_EOC Ta 0 +.It Dv V_ASN1_EXTERNAL Ta Dv B_ASN1_UNKNOWN +.It Dv V_ASN1_GENERALIZEDTIME Ta Dv B_ASN1_GENERALIZEDTIME +.It Dv V_ASN1_GENERALSTRING Ta Dv B_ASN1_GENERALSTRING +.It Dv V_ASN1_GRAPHICSTRING Ta Dv B_ASN1_GRAPHICSTRING +.It Dv V_ASN1_IA5STRING Ta Dv B_ASN1_IA5STRING +.It Dv V_ASN1_INTEGER Ta 0 +.It Dv V_ASN1_ISO64STRING Ta Dv B_ASN1_ISO64STRING +.It Dv V_ASN1_NULL Ta 0 +.It Dv V_ASN1_NUMERICSTRING Ta Dv B_ASN1_NUMERICSTRING +.It Dv V_ASN1_OBJECT Ta 0 +.It Dv V_ASN1_OBJECT_DESCRIPTOR Ta Dv B_ASN1_UNKNOWN +.It Dv V_ASN1_OCTET_STRING Ta Dv B_ASN1_OCTET_STRING +.It Dv V_ASN1_PRINTABLESTRING Ta Dv B_ASN1_PRINTABLESTRING +.It Dv V_ASN1_REAL Ta Dv B_ASN1_UNKNOWN +.It Dv V_ASN1_SEQUENCE Ta Dv B_ASN1_SEQUENCE +.It Dv V_ASN1_SET Ta 0 +.It Dv V_ASN1_T61STRING Ta Dv B_ASN1_T61STRING +.It Dv V_ASN1_TELETEXSTRING Ta Dv B_ASN1_TELETEXSTRING +.It Dv V_ASN1_UNDEF Ta 0 +.It Dv V_ASN1_UNIVERSALSTRING Ta Dv B_ASN1_UNIVERSALSTRING +.It Dv V_ASN1_UTCTIME Ta Dv B_ASN1_UTCTIME +.It Dv V_ASN1_UTF8STRING Ta Dv B_ASN1_UTF8STRING +.It Dv V_ASN1_VIDEOTEXSTRING Ta Dv B_ASN1_VIDEOTEXSTRING +.It Dv V_ASN1_VISIBLESTRING Ta Dv B_ASN1_VISIBLESTRING +.It 11, 13, 14, 15, 29 Ta Dv B_ASN1_UNKNOWN +.It Dv other Po < 0, > 30 Pc Ta Dv 0 +.El +.Pp +In typical usage, the calling code calculates the bitwise AND +of the return value and a mask describing data types +that the calling code is willing to use. +If the result of the AND operation is non-zero, the data type is +adequate; otherwise, the calling code may need to raise an error. +.Sh RETURN VALUES +.Fn ASN1_mbstring_copy +and +.Fn ASN1_mbstring_ncopy +return the +.Dv V_ASN1_* +constant representing the output type or \-1 if +.Fa inform +is invalid, if +.Fa inbytes +or +.Fa in +is invalid for the +.Fa inform +encoding, if +.Fa in +contains an UTF-16 surrogate, +which is unsupported even for input using the UTF-16 encoding, +or if memory allocation fails. +.Pp +.Fn ASN1_mbstring_ncopy +also returns \-1 if +.Fa in +contains fewer than +.Fa minchars +or more than +.Fa maxchars +characters. +.Pp +.Fn ASN1_STRING_set_by_NID +returns the new or changed ASN.1 string object or +.Dv NULL +on failure. +.Pp +.Fn ASN1_STRING_set_default_mask_asc +returns 1 if successful or 0 if +.Qq MASK:\& +is not followed by a number, if the number is followed by a non-numeric +character, or if the +.Fa maskname +is invalid. +.Pp +.Fn ASN1_STRING_get_default_mask +returns the global mask. +.Pp +.Fn ASN1_tag2bit +returns a +.Dv B_ASN1_* +constant or 0. +.Sh SEE ALSO +.Xr ASN1_PRINTABLE_type 3 , +.Xr ASN1_STRING_new 3 , +.Xr ASN1_STRING_set 3 , +.Xr ASN1_STRING_TABLE_get 3 , +.Xr ASN1_UNIVERSALSTRING_to_string 3 +.Sh HISTORY +.Fn ASN1_mbstring_copy , +.Fn ASN1_mbstring_ncopy , +.Fn ASN1_STRING_set_by_NID , +.Fn ASN1_STRING_set_default_mask , +.Fn ASN1_STRING_set_default_mask_asc , +and +.Fn ASN1_STRING_get_default_mask +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn ASN1_tag2bit +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Sh BUGS +If integer overflow occurs in +.Fn ASN1_STRING_set_default_mask_asc +while parsing a number following +.Qq MASK:\& , +the function succeeds, essentially behaving in the same way as for +.Qq default . +.Pp +Passing +.Qq default +to +.Fn ASN1_STRING_set_default_mask_asc +does +.Em not +restore the default mask. +Instead, passing +.Qq utf8only +does that. diff --git a/static/openbsd/man3/ASN1_parse_dump.3 b/static/openbsd/man3/ASN1_parse_dump.3 new file mode 100644 index 00000000..45aa673d --- /dev/null +++ b/static/openbsd/man3/ASN1_parse_dump.3 @@ -0,0 +1,217 @@ +.\" $OpenBSD: ASN1_parse_dump.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt ASN1_PARSE_DUMP 3 +.Os +.Sh NAME +.Nm ASN1_parse_dump , +.Nm ASN1_parse +.Nd parse BER and print information about it +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo ASN1_parse_dump +.Fa "BIO *bio" +.Fa "const unsigned char *ber_in" +.Fa "long length" +.Fa "int indent" +.Fa "int dump" +.Fc +.Ft int +.Fo ASN1_parse +.Fa "BIO *bio" +.Fa "const unsigned char *ber_in" +.Fa "long length" +.Fa "int indent" +.Fc +.Sh DESCRIPTION +.Fn ASN1_parse_dump +parses BER-encoded values and prints information about them to +.Fa bio . +On function entry, +.Pf * Fa ber_in +is expected to point to the first identifier octet of an encoded value. +At most +.Fa length +bytes are inspected. +.Pp +For each value successfully parsed, the following information is printed: +.Bl -enum +.It +The index of its first identifier octet relative to +.Fa ber_in +as a decimal number followed by a colon. +For the first value parsed and printed, this is +.Qq 0:\& . +.It +The nesting depth as a decimal integer. +For the first value parsed and printed, this is +.Qq d=0 . +.It +The header length in bytes, including the identifier octets and the +length octets, as a decimal integer. +For example, for a boolean value, this is +.Qq hl=2 +because the encoding of a boolean value contains +one identifier octet (0x01) and one length octet (also 0x01, +because one content octet follows after the header). +.It +If the value is encoded using the definite form for the length octets, +the number encoded in the length octets as a decimal integer. +This is the number of content octets that follow. +For example, for a boolean value, this is +.Qq l=1 . +If the value is encoded using a length octet indicating the indefinite form, +.Qq l=inf +is printed instead. +.It +If the value is primitive, +.Qq prim:\& +is printed; +if it is constructed, +.Qq cons:\& . +.It +The next field depends on the class of the tag: +.Bl -tag -width Ds +.It Dv V_ASN1_PRIVATE +.Qq priv +followed by the decimal tag number in square brackets +.It Dv V_ASN1_CONTEXT_SPECIFIC +.Qq cont +followed by the decimal tag number in square brackets +.It Dv V_ASN1_APPLICATION +.Qq appl +followed by the decimal tag number in square brackets +.It V_ASN1_UNIVERSAL +If the tag number is 30 or less, the return value from +.Xr ASN1_tag2str 3 +is printed; otherwise, +.Qq +.\" +.\" 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: June 8 2025 $ +.Dt ASN1_PUT_OBJECT 3 +.Os +.Sh NAME +.Nm ASN1_put_object , +.Nm ASN1_put_eoc , +.Nm ASN1_object_size +.Nd start and end the BER encoding of an arbitrary ASN.1 data element +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft void +.Fo ASN1_put_object +.Fa "unsigned char **ber_out" +.Fa "int constructed" +.Fa "int content_length" +.Fa "int tag" +.Fa "int class" +.Fc +.Ft int +.Fo ASN1_put_eoc +.Fa "unsigned char **ber_out" +.Fc +.Ft int +.Fo ASN1_object_size +.Fa "int constructed" +.Fa "int content_length" +.Fa "int tag" +.Fc +.Sh DESCRIPTION +.Fn ASN1_put_object +begins writing the BER encoding of an arbitrary ASN.1 data element +to the buffer +.Pf * ber_out +by writing the identifier and the length bytes. +Making sure that there is sufficient space in the buffer +is the responsibility of the caller. +This function does not write any content bytes +nor any end-of-content bytes. +.Pp +The tag +.Fa class +can be +.Dv V_ASN1_UNIVERSAL , +.Dv V_ASN1_APPLICATION , +.Dv V_ASN1_CONTEXT_SPECIFIC , +or +.Dv V_ASN1_PRIVATE +and is written to the two most significant bits of the first byte written. +.Pp +The +.Fa constructed +argument can have the following values: +.Bl -tag -width 1n -offset 2n -compact +.It 0 +Start a primitive value by setting the third most significant bit +of the first byte written to 0. +Always use the definite form. +.It 1 +Start a constructed value by setting the third most significant bit +of the first byte written to 1, and use the definite form. +.It 2 +Start a constructed value and use the indefinite form, +.El +.Pp +If the +.Fa tag +is less than +.Dv V_ASN1_PRIMITIVE_TAG Pq = 0x1f , +it is written to the five least significant bits +of the only identifier byte written. +Otherwise, these five bits are all set to 1, and the +.Fa tag +is encoded in one or more following identifier bytes as needed. +.Pp +After completing the identifier byte(s), +when using the definite form, the given +.Fa content_length +is encoded in one or more bytes as needed, +using the long form if and only if the +.Fa content_length +is greater than 127. +When using the indefinite form, +the special byte 0x80 is written instead and the +.Fa content_length +argument is ignored. +.Pp +At the end, +.Pf * Fa ber_out +is set to the byte following the last byte written. +The calling code can then start writing content bytes. +.Pp +If the indefinite form was selected, +the calling code is also responsible for calling +.Fn ASN1_put_eoc +which writes an end-of-content marker to +.Pf * Fa ber_out , +consisting of two NUL bytes, and advances +.Pf * Fa ber_out +by two bytes. +.Pp +.Fn ASN1_object_size +calculates the total length in bytes of the BER encoding +of an ASN.1 data element with the given +.Fa tag +and the number of content bytes given by +.Fa content_length . +The +.Fa constructed +argument has the same meaning as for +.Fn ASN1_put_object . +The return value includes the identifier, length, and content bytes. +If +.Fa constructed +is 2, it also includes the end-of-content bytes. +For the definite form, only the short form is supported if the +.Fa content_length +is less than 128. +.Sh RETURN VALUES +.Fn ASN1_put_eoc +returns the number of bytes written, which is always 2. +.Pp +.Fn ASN1_object_size +returns the total number of bytes in the encoding of the data element. +.Sh SEE ALSO +.Xr ASN1_item_i2d 3 , +.Xr ASN1_TYPE_get 3 , +.Xr i2d_ASN1_NULL 3 , +.Xr i2d_ASN1_OBJECT 3 , +.Xr i2d_ASN1_OCTET_STRING 3 , +.Xr i2d_ASN1_SEQUENCE_ANY 3 +.Sh STANDARDS +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules: +Specification of Basic Encoding Rules (BER), Canonical Encoding +Rules (CER) and Distinguished Encoding Rules (DER), +section 8.1: General rules for encoding +.Sh HISTORY +.Fn ASN1_put_object +and +.Fn ASN1_object_size +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn ASN1_put_eoc +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Sh CAVEATS +None of these functions do any sanity checking. +When called in inconsistent ways, invalid content may result in +.Pf * Fa ber_out , +for example +.Bl -dash -compact +.It +a +.Fa tag +number less than +.Dv V_ASN1_PRIMITIVE_TAG +with a +.Fa class +other than +.Dv V_ASN1_UNIVERSAL +.It +a +.Fa tag +number equal to +.Dv V_ASN1_EOC Pq 0x00 +or +.Dv V_ASN1_PRIMITIVE_TAG Pq 0x1f +.It +a +.Vt BOOLEAN , +.Vt INTEGER , +.Vt NULL +etc. with the +.Fa constructed +bit set +.It +a +.Vt SEQUENCE +or +.Vt SET +etc. without the +.Fa constructed +bit set +.It +a +.Fa content_length +that makes no sense for the given +.Fa tag +.It +a +.Fa content_length +that disagrees with the following data +.It +a +.Vt BOOLEAN , +.Vt INTEGER , +.Vt NULL +etc. in indefinite form +.It +an end-of-content marker even though no indefinite form was started +.It +\&... +.El +.Pp +If the calling code wants to find out how many bytes were written, +it needs to save a copy of the pointer +.Pf * Fa ber_out +before calling +.Fn ASN1_put_object . diff --git a/static/openbsd/man3/ASRange_new.3 b/static/openbsd/man3/ASRange_new.3 new file mode 100644 index 00000000..b507213b --- /dev/null +++ b/static/openbsd/man3/ASRange_new.3 @@ -0,0 +1,411 @@ +.\" $OpenBSD: ASRange_new.3,v 1.10 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: June 13 2025 $ +.Dt ASRANGE_NEW 3 +.Os +.Sh NAME +.Nm ASRange_new , +.Nm ASRange_free , +.Nm d2i_ASRange , +.Nm i2d_ASRange , +.Nm ASIdOrRange_new , +.Nm ASIdOrRange_free , +.Nm d2i_ASIdOrRange , +.Nm i2d_ASIdOrRange , +.Nm ASIdentifierChoice_new , +.Nm ASIdentifierChoice_free , +.Nm d2i_ASIdentifierChoice , +.Nm i2d_ASIdentifierChoice +.Nd RFC 3779 autonomous system identifiers and ranges +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft ASRange * +.Fn ASRange_new void +.Ft void +.Fn ASRange_free "ASRange *asrange" +.Ft ASRange * +.Fo d2i_ASRange +.Fa "ASRange **asrange" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASRange +.Fa "ASRange *asrange" +.Fa "unsigned char **der_out" +.Fc +.Ft ASIdOrRange * +.Fn ASIdOrRange_new void +.Ft void +.Fn ASIdOrRange_free "ASIdOrRange *aor" +.Ft ASIdOrRange * +.Fo d2i_ASIdOrRange +.Fa "ASIdOrRange **aor" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASIdOrRange +.Fa "ASIdOrRange *aor" +.Fa "unsigned char **der_out" +.Fc +.Ft ASIdentifierChoice * +.Fn ASIdentifierChoice_new void +.Ft void +.Fn ASIdentifierChoice_free "ASIdentifierChoice *aic" +.Ft ASIdentifierChoice * +.Fo d2i_ASIdentifierChoice +.Fa "ASIdentifierChoice **aic" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASIdentifierChoice +.Fa "ASIdentifierChoice *aic" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +.Vt ASRange , +.Vt ASIdOrRange , +and +.Vt ASIdentifierChoice +are building blocks of the +.Vt ASIdentifiers +type representing the RFC 3779 +autonomous system identifier delegation extension. +.Pp +All +.Vt ASN1_INTEGER Ns s +in this manual must be representable as unsigned 32-bit integers. +The API performs no corresponding checks. +An +.Vt ASN1_INTEGER +can be set using +.Xr ASN1_INTEGER_set_uint64 3 . +.Pp +The +.Vt ASRange +type defined in RFC 3779 section 3.2.3.8 is implemented as +.Bd -literal -offset indent +typedef struct ASRange_st { + ASN1_INTEGER *min; + ASN1_INTEGER *max; +} ASRange; +.Ed +.Pp +It represents the closed range [min,max] of AS identifiers between +.Fa min +and +.Fa max , +where +.Fa min +should be strictly smaller than +.Fa max . +.Pp +.Fn ASRange_new +allocates a new +.Vt ASRange +object with allocated, empty +.Fa min +and +.Fa max , +thus representing the invalid range [0,0]. +.Pp +.Fn ASRange_free +frees +.Fa asrange +including any data contained in it. +If +.Fa asrange +is +.Dv NULL , +no action occurs. +.Pp +The +.Vt ASIdOrRange +type defined in RFC 3779 section 3.2.3.5 is implemented as +.Bd -literal -offset indent +typedef struct ASIdOrRange_st { + int type; + union { + ASN1_INTEGER *id; + ASRange *range; + } u; +} ASIdOrRange; +.Ed +.Pp +representing an individual AS identifier or a range. +When populating an +.Vt ASIdOrRange +object by hand, its +.Fa type +should be set to +.Dv ASIdOrRange_id +or +.Dv ASIdOrRange_range +to indicate which member of the union +.Fa u +is valid. +.Pp +.Fn ASIdOrRange_new +returns a new +.Vt ASIdOrRange +object with invalid type and +.Dv NULL +members of the union +.Fa u . +.Pp +.Fn ASIdOrRange_free +frees +.Fa aor +including any data contained in it, +provided +.Fa type +is set correctly. +If +.Fa asrange +is +.Dv NULL , +no action occurs. +.Pp +In order to express a list of AS identifiers and ranges, +RFC 3779 section 3.2.3.4 +uses an ASN.1 SEQUENCE, +which is implemented via a +.Xr STACK_OF 3 +construction over +.Vt ASIdOrRange : +.Bd -literal -offset indent +typedef STACK_OF(ASIdOrRange) ASIdOrRanges; +.Ed +.Pp +Since an +.Vt ASIdOrRanges +object should be sorted in a specific way (see +.Xr X509v3_asid_canonize 3 Ns ), +a comparison function is needed for a correct instantiation +with +.Xr sk_new 3 . +The +.Fn ASIdOrRange_cmp +function is not directly exposed and not easily accessible +from outside the library, +and it is non-trivial to implement. +It is therefore discouraged to use +.Vt ASIdOrRanges +objects that are not part of an +.Vt ASIdentifiers +object. +.Pp +The +.Dq inherit +marker from RFC 3779 section 3.2.3.3 is implemented as +.Vt ASN1_NULL . +It has no dedicated type or API and can be instantiated with +.Xr ASN1_NULL_new 3 . +.Pp +The +.Vt ASIdentifierChoice +type defined in RFC 3779 section 3.2.3.2 is implemented as +.Bd -literal -offset indent +typedef struct ASIdentifierChoice_st { + int type; + union { + ASN1_NULL *inherit; + ASIdOrRanges *asIdsOrRanges; + } u; +} ASIdentifierChoice; +.Ed +.Pp +where the +.Fa type +member should be set to +.Dv ASIdentifierChoice_inherit +or +.Dv ASIdentifierChoice_asIdsOrRanges +to indicate whether a given +.Vt ASIdentifierChoice +object represents an inherited list or an explicit list. +.Pp +.Fn ASIdentifierChoice_new +returns a new +.Vt ASIdentifierChoice +object with invalid type and +.Dv NULL +members of the union +.Fa u . +.Pp +.Fn ASIdentifierChoice_free +frees +.Fa aic +including any data contained in it, +provided +.Fa type +is set correctly. +.Pp +The +.Vt ASIdentifiers +type defined in RFC 3779 section 3.2.3.1 is implemented as +.Bd -literal -offset indent +typedef struct ASIdentifiers_st { + ASIdentifierChoice *asnum; + ASIdentifierChoice *rdi; +} ASIdentifiers; +.Ed +.Pp +It should be instantiated with +.Xr ASIdentifiers_new 3 +and populated with +.Xr X509v3_asid_add_id_or_range 3 . +.Pp +.Fn d2i_ASRange , +.Fn i2d_ASRange , +.Fn d2i_ASIdOrRange , +.Fn i2d_ASIdOrRange , +.Fn d2i_ASIdentifierChoice , +and +.Fn i2d_ASIdentifierChoice +decode and encode ASN.1 +.Vt ASRange , +.Vt ASIdOrRange , +and +.Vt ASIdentifierChoice +objects. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +In order for the encoding produced by +.Fn i2d_ASRange +to be correct, +.Fa min +must be strictly less than +.Fa max . +Similarly for +.Fn i2d_ASIdOrRange +and an +.Fa ASIdOrRange +object of +.Fa type +.Dv ASIdOrRange_range . +.Sh RETURN VALUES +.Fn ASRange_new +returns a new +.Vt ASRange +object with allocated, empty members, or +.Dv NULL +if an error occurs. +.Pp +.Fn ASIdOrRange_new +returns a new, empty +.Vt ASIdOrRange +object or +.Dv NULL +if an error occurs. +.Pp +.Fn ASIdentifierChoice_new +returns a new, empty +.Vt ASIdentifierChoice +object or +.Dv NULL +if an error occurs. +.Pp +The decoding functions +.Fn d2i_ASRange , +.Fn d2i_ASIdOrRange , +and +.Fn d2i_ASIdentifierChoice +return an +.Vt ASRange , +an +.Vt ASIdOrRange , +or an +.Vt ASIdentifierChoice , +object, respectively, +or +.Dv NULL +if an error occurs. +.Pp +The encoding functions +.Fn i2d_ASRange , +.Fn i2d_ASIdOrRange , +and +.Fn i2d_ASIdentifierChoice +return the number of bytes successfully encoded +or a value <= 0 if an error occurs. +.Sh SEE ALSO +.Xr ASIdentifiers_new 3 , +.Xr ASN1_INTEGER_set_uint64 3 , +.Xr crypto 3 , +.Xr IPAddressRange_new 3 , +.Xr s2i_ASN1_INTEGER 3 , +.Xr STACK_OF 3 , +.Xr X509_new 3 , +.Xr X509v3_asid_add_id_or_range 3 +.Sh STANDARDS +RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: +.Bl -dash -compact +.It +section 3.2.3: Syntax +.It +section 3.2.3.1: Type ASIdentifiers +.It +section 3.2.3.2: Elements asnum, rdi, and Type ASIdentifierChoice +.It +section 3.2.3.3: Element inherit +.It +section 3.2.3.4: Element asIdsOrRanges +.It +section 3.2.3.5: Type ASIdOrRange +.It +section 3.2.3.6: Element id +.It +section 3.2.3.7: Element range +.It +section 3.2.3.8: Type ASRange +.It +section 3.2.3.9: Elements min and max +.El +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . +.Sh BUGS +An +.Fn ASIdOrRanges_new +function that installs the correct comparison function +on the stack of +.Vt ASIdOrRange +should have been part of the API to make it usable. +.Pp +.Fn ASIdentifierChoice_new +is of very limited use because +.Fn ASIdOrRanges_new +is missing. +.Pp +There is no way of ensuring that an +.Vt ASIdOrRanges +object is in canonical form unless it is part of an +.Vt ASIdentifiers +object. +It is therefore difficult to guarantee that the output of +.Fn i2d_ASIdentifierChoice +is conformant. +.Pp +RFC 3779 3.2.3.4 has +.Dq Fa asIdsOrRanges +while its type in this implementation is +.Vt ASIdOrRanges . diff --git a/static/openbsd/man3/AUTHORITY_KEYID_new.3 b/static/openbsd/man3/AUTHORITY_KEYID_new.3 new file mode 100644 index 00000000..982685d1 --- /dev/null +++ b/static/openbsd/man3/AUTHORITY_KEYID_new.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: AUTHORITY_KEYID_new.3,v 1.5 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt AUTHORITY_KEYID_NEW 3 +.Os +.Sh NAME +.Nm AUTHORITY_KEYID_new , +.Nm AUTHORITY_KEYID_free +.Nd X.509 authority key identifier extension +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft AUTHORITY_KEYID * +.Fn AUTHORITY_KEYID_new void +.Ft void +.Fn AUTHORITY_KEYID_free "AUTHORITY_KEYID *id" +.Sh DESCRIPTION +Using the authority key identifier extension, an X.509 certificate +or certificate revocation list can specify which key pair was used +for signing it. +.Pp +.Fn AUTHORITY_KEYID_new +allocates and initializes an empty +.Vt AUTHORITY_KEYID +object, representing an ASN.1 +.Vt AuthorityKeyIdentifier +structure defined in RFC 5280 section 4.2.1.1. +It can hold an issuer name, a serial number, and a key identifier. +.Pp +.Fn AUTHORITY_KEYID_free +frees +.Fa id . +.Sh RETURN VALUES +.Fn AUTHORITY_KEYID_new +returns the new +.Vt AUTHORITY_KEYID +object or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_AUTHORITY_KEYID 3 , +.Xr GENERAL_NAMES_new 3 , +.Xr X509_CRL_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile: +.Bl -dash -compact +.It +section 4.2.1.1: Certificate Extensions: Authority Key Identifier +.It +section 5.2.1: CRL Extensions: Authority Key Identifier +.El +.Sh HISTORY +.Fn AUTHORITY_KEYID_new +and +.Fn AUTHORITY_KEYID_free +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/BASIC_CONSTRAINTS_new.3 b/static/openbsd/man3/BASIC_CONSTRAINTS_new.3 new file mode 100644 index 00000000..f1b1486a --- /dev/null +++ b/static/openbsd/man3/BASIC_CONSTRAINTS_new.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: BASIC_CONSTRAINTS_new.3,v 1.7 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt BASIC_CONSTRAINTS_NEW 3 +.Os +.Sh NAME +.Nm BASIC_CONSTRAINTS_new , +.Nm BASIC_CONSTRAINTS_free +.Nd X.509 extension to mark CA certificates +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft BASIC_CONSTRAINTS * +.Fn BASIC_CONSTRAINTS_new void +.Ft void +.Fn BASIC_CONSTRAINTS_free "BASIC_CONSTRAINTS *bc" +.Sh DESCRIPTION +.Fn BASIC_CONSTRAINTS_new +allocates and initializes an empty +.Vt BASIC_CONSTRAINTS +object, representing an ASN.1 +.Vt BasicConstraints +structure defined in RFC 5280 section 4.2.1.9. +.Pp +This object contains two fields. +The field +.Fa "int ca" +is non-zero if the certificate is a CA certificate. +The field +.Fa "ASN1_INTEGER *pathlen" +specifies the maximum number of non-self-issued intermediate +certificates that may follow this certificate in a valid +certification path. +.Pp +If an X.509 version 3 certificate does not contain this extension +or if the +.Fa ca +field of the +.Vt BASIC_CONSTRAINTS +object is 0, or if the certificate contains a key usage extension +having the +.Dv KU_KEY_CERT_SIGN +bit unset, then it is not a CA certificate but an end entity +certificate. +.Pp +.Fn BASIC_CONSTRAINTS_free +frees +.Fa bc . +.Sh RETURN VALUES +.Fn BASIC_CONSTRAINTS_new +returns the new +.Vt BASIC_CONSTRAINTS +object or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_BASIC_CONSTRAINTS 3 , +.Xr X509_check_purpose 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_get_extension_flags 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile: +.Bl -dash -compact +.It +section 4.2.1.9: Basic Constraints +.It +section 6.1: Basic Path Validation +.El +.Sh HISTORY +.Fn BASIC_CONSTRAINTS_new +and +.Fn BASIC_CONSTRAINTS_free +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/BF_set_key.3 b/static/openbsd/man3/BF_set_key.3 new file mode 100644 index 00000000..1299a0f2 --- /dev/null +++ b/static/openbsd/man3/BF_set_key.3 @@ -0,0 +1,270 @@ +.\" $OpenBSD: BF_set_key.3,v 1.13 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL 99d63d46 Jul 19 09:27:53 2016 -0400 +.\" +.\" This file was written by Richard Levitte . +.\" Copyright (c) 2000, 2002, 2005, 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BF_SET_KEY 3 +.Os +.Sh NAME +.Nm BF_set_key , +.Nm BF_encrypt , +.Nm BF_decrypt , +.Nm BF_ecb_encrypt , +.Nm BF_cbc_encrypt , +.Nm BF_cfb64_encrypt , +.Nm BF_ofb64_encrypt +.Nd Blowfish encryption +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/blowfish.h +.Ft void +.Fo BF_set_key +.Fa "BF_KEY *key" +.Fa "int len" +.Fa "const unsigned char *data" +.Fc +.Ft void +.Fo BF_encrypt +.Fa "BF_LONG *data" +.Fa "const BF_KEY *key" +.Fc +.Ft void +.Fo BF_decrypt +.Fa "BF_LONG *data" +.Fa "const BF_KEY *key" +.Fc +.Ft void +.Fo BF_ecb_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "BF_KEY *key" +.Fa "int enc" +.Fc +.Ft void +.Fo BF_cbc_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "BF_KEY *schedule" +.Fa "unsigned char *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo BF_cfb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "BF_KEY *schedule" +.Fa "unsigned char *ivec" +.Fa "int *num" +.Fa "int enc" +.Fc +.Ft void +.Fo BF_ofb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "BF_KEY *schedule" +.Fa "unsigned char *ivec" +.Fa "int *num" +.Fc +.Sh DESCRIPTION +This library implements the Blowfish cipher, +which was invented and defined by +.An Counterpane . +Note that applications should use higher level functions such as +.Xr EVP_EncryptInit 3 +instead of calling the Blowfish functions directly. +.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 +and 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 +.Fn BF_set_key +sets up the +.Vt BF_KEY +.Fa key +using the +.Fa len +bytes long key at +.Fa data . +.Pp +.Fn BF_ecb_encrypt +is the basic Blowfish encryption and decryption function. +It encrypts or decrypts the first 64 bits of +.Fa in +using the key +.Fa key , +putting the result in +.Fa out . +.Fa enc +decides if encryption +.Pq Dv BF_ENCRYPT +or decryption +.Pq Dv BF_DECRYPT +shall be performed. +The vector pointed at by +.Fa in +and +.Fa out +must be 64 bits in length, no less. +If they are larger, everything after the first 64 bits is ignored. +.Pp +The mode functions +.Fn BF_cbc_encrypt , +.Fn BF_cfb64_encrypt , +and +.Fn BF_ofb64_encrypt +all operate on variable length data. +They all take an initialization vector +.Fa ivec +which needs to be passed along into the next call of the same function +for the same message. +.Fa ivec +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 SSH, where +.Fa ivec +is simply initialized to zero. +.Fn BF_cbc_encrypt +operates on data that is a multiple of 8 bytes long, while +.Fn BF_cfb64_encrypt +and +.Fn BF_ofb64_encrypt +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 +.Fa num , +which is a pointer to an integer where the current offset in +.Fa ivec +is stored between calls. +This integer must be initialized to zero when +.Fa ivec +is initialized. +.Pp +.Fn BF_cbc_encrypt +is the Cipher Block Chaining function for Blowfish. +It encrypts or decrypts the 64-bit chunks of +.Fa in +using the key +.Fa schedule , +putting the result in +.Fa out . +.Fa enc +decides if encryption +.Pq Dv BF_ENCRYPT +or decryption +.Pq Dv BF_DECRYPT +shall be performed. +.Fa ivec +must point at an 8-byte long initialization vector. +.Pp +.Fn BF_cfb64_encrypt +is the CFB mode for Blowfish with 64-bit feedback. +It encrypts or decrypts the bytes in +.Fa in +using the key +.Fa schedule , +putting the result in +.Fa out . +.Fa enc +decides if encryption +.Pq Dv BF_ENCRYPT +or decryption +.Pq Dv BF_DECRYPT +shall be performed. +.Fa ivec +must point at an +8-byte long initialization vector. +.Fa num +must point at an integer which must be initially zero. +.Pp +.Fn BF_ofb64_encrypt +is the OFB mode for Blowfish with 64-bit feedback. +It uses the same parameters as +.Fn BF_cfb64_encrypt , +which must be initialized the same way. +.Pp +.Fn BF_encrypt +and +.Fn BF_decrypt +are the lowest level functions for Blowfish encryption. +They encrypt/decrypt the first 64 bits of the vector pointed by +.Fa data , +using the key +.Fa key . +These functions should not be used unless implementing `modes' of Blowfish. +The alternative is to use +.Fn BF_ecb_encrypt . +Be aware that these functions 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 SEE ALSO +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn BF_set_key , +.Fn BF_encrypt , +.Fn BF_ecb_encrypt , +.Fn BF_cbc_encrypt , +.Fn BF_cfb64_encrypt , +and +.Fn BF_ofb64_encrypt +first appeared in SSLeay 0.6.6. +.Fn BF_decrypt +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BIO_accept.3 b/static/openbsd/man3/BIO_accept.3 new file mode 100644 index 00000000..73b41501 --- /dev/null +++ b/static/openbsd/man3/BIO_accept.3 @@ -0,0 +1,388 @@ +.\" $OpenBSD: BIO_accept.3,v 1.3 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2022 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 $Mdocdate: June 8 2025 $ +.Dt BIO_ACCEPT 3 +.Os +.Sh NAME +.\" mentioned in OpenSSL documentation and still used internally in LibreSSL +.Nm BIO_get_host_ip , +.Nm BIO_get_port , +.Nm BIO_get_accept_socket , +.Nm BIO_accept , +.Nm BIO_sock_error , +.Nm BIO_sock_non_fatal_error , +.Nm BIO_sock_should_retry , +.\" used internally in LibreSSL and OpenSSL and not deprecated in OpenSSL +.Nm BIO_socket_nbio , +.\" mentioned in OpenSSL documentation and not deprecated in OpenSSL +.Nm BIO_set_tcp_ndelay +.\" deprecated in OpenSSL and unused anywhere, hence intentionally undocumented +.\" .Nm BIO_gethostbyname +.\" .Nm BIO_GHBN_CTRL_CACHE_SIZE +.\" .Nm BIO_GHBN_CTRL_FLUSH +.\" .Nm BIO_GHBN_CTRL_GET_ENTRY +.\" .Nm BIO_GHBN_CTRL_HITS +.\" .Nm BIO_GHBN_CTRL_MISSES +.\" .Nm BIO_socket_ioctl +.\" does almost nothing and used very rarely, hence intentionally undocumented +.\" .Nm BIO_sock_init +.\" .Nm BIO_sock_cleanup +.Nd wrappers for socket operations +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft int +.Fo BIO_get_host_ip +.Fa "const char *hostname" +.Fa "unsigned char *in_addr_buffer" +.Fc +.Ft int +.Fo BIO_get_port +.Fa "const char *servname" +.Fa "unsigned short *port" +.Fc +.Ft int +.Fo BIO_get_accept_socket +.Fa "char *host_port" +.Fa "int bind_mode" +.Fc +.Ft int +.Fo BIO_accept +.Fa "int socket" +.Fa "char **addr" +.Fc +.Ft int +.Fn BIO_sock_error "int socket" +.Ft int +.Fn BIO_sock_non_fatal_error "int errnum" +.Ft int +.Fn BIO_sock_should_retry "int retval" +.Ft int +.Fn BIO_socket_nbio "int socket" "int mode" +.Ft int +.Fn BIO_set_tcp_ndelay "int socket" "int on" +.Sh DESCRIPTION +.Fn BIO_get_host_ip +looks up one IPv4 address for the given +.Fa hostname +using +.Xr getaddrinfo 3 +and writes the first returned IPv4 address into +.Pf * Fa in_addr_buffer . +The caller is responsible for providing a buffer that is at least +.Fn sizeof in_addr_t +bytes long. +After a successful call, the caller needs to cast +.Fa in_addr_buffer +to +.Pq Vt in_addr_t * . +.Pp +.Fn BIO_get_port +looks up +.Fa servname +in the +.Xr services 5 +database using +.Xr getaddrinfo 3 +and stores the associated port number at the location specified by the +.Fa port +argument. +.Pp +.Fn BIO_get_accept_socket +creates an IPv4 TCP socket and +.Xr listen 2 Ns s +for incoming connections. +The string +.Fa host_port +is parsed. +If it contains a colon, the substring before the colon is interpreted +as a local hostname of the interface to +.Xr bind 2 +to. +If the hostname is empty, consists of a single asterisk +.Pq Qq *:... , +or if there is no colon, +.Dv INADDR_ANY +is used instead of a local hostname. +The rest of the string +.Fa host_port , +or the whole string if it contains no colon, +is treated as a service name. +The hostname and the service name are converted to a local IP address +and port number using +.Xr getaddrinfo 3 . +If +.Fa bind_mode +is the constant +.Dv BIO_BIND_REUSEADDR , +allowing local address reuse is attempted using +.Xr setsockopt 2 +with an argument of +.Dv SO_REUSEADDR +before calling +.Xr bind 2 . +.Pp +.Fn BIO_accept +calls +.Xr accept 2 +to receive one connection on the +.Fa socket . +When it receives a connection, it +.Xr free 3 Ns s +.Pf * Fa addr , +and if it is an IPv4 connection, it allocates a new string, +writes the peer IP address in dotted decimal form, a colon, +and the decimal port number into the string, and stores a pointer +to the string in +.Pf * Fa addr . +For other address families or if +.Xr getnameinfo 3 +or memory allocation fails, +.Pf * Fa addr +is set to +.Dv NULL +but +.Fn BIO_accept +succeeds anyway. +.Pp +.Fn BIO_sock_error +retrieves, clears, and returns the error status code of the +.Fa socket +by calling +.Xr getsockopt 2 +with arguments +.Dv SOL_SOCKET +and +.Dv SO_ERROR . +.Pp +.Fn BIO_sock_non_fatal_error +determines whether the error status code +.Fa errnum +represents a recoverable error. +.Pp +.Fn BIO_sock_should_retry +determines whether a recoverable error occurred by inspecting both +.Xr errno 2 +and +.Fa retval , +which is supposed to usually be +the return value of a previously called function like +.Fn BIO_accept , +.Xr BIO_read 3 , +or +.Xr BIO_write 3 . +.Pp +If +.Fa mode +is non-zero, +.Fn BIO_socket_nbio +switches the +.Fa socket +to non-blocking mode using +.Xr fcntl 2 . +If +.Fa mode +is 0, it switches to blocking mode. +.Pp +.Fn BIO_set_tcp_ndelay +sets the +.Dv TCP_NODELAY +option on the +.Fa socket +if +.Fa on +is 1 or clears it if +.Fa on +is 0; see +.Xr tcp 4 +for details. +.Sh RETURN VALUES +.Fn BIO_get_host_ip , +.Fn BIO_get_port , +and +.Fn BIO_socket_nbio +return 1 on success or 0 on failure. +.Pp +.Fn BIO_get_accept_socket +returns the file descriptor of the newly created listening socket or \-1 if +.Fa host_port +is +.Dv NULL , +no service is specified, or +.Xr getaddrinfo 3 , +.Xr socket 2 , +.Xr bind 2 , +.Xr listen 2 , +or memory allocation fails. +.Pp +.Fn BIO_accept +returns the file descriptor of the received connection, +\-1 on fatal errors, that is, when +.Fa addr +is +.Dv NULL +or +.Xr accept 2 +fails fatally, or \-2 when +.Xr accept 2 +fails in a non-fatal way and might succeed when retried later. +.Pp +.Fn BIO_sock_error +returns an error status code like +.Dv EAGAIN , +.Dv ECONNABORTED , +.Dv ECONNREFUSED , +.Dv ECONNRESET , +.Dv ELOOP , +.Dv EMSGSIZE , +.Dv ENOBUFS , +.Dv ENOTCONN , +.Dv EPIPE , +.Dv ETIMEDOUT , +or others, 0 if the +.Fa socket +is not in an error state, or 1 if +.Xr getsockopt 2 +fails. +.Pp +.Fn BIO_sock_non_fatal_error +returns 1 if +.Fa errnum +is +.Dv EAGAIN , +.Dv EALREADY , +.Dv EINPROGRESS , +.Dv EINTR , +or +.Dv ENOTCONN +and 0 otherwise, even if +.Fa errnum +is 0. +.Pp +.Fn BIO_sock_should_retry +returns 1 if +.Fn BIO_sock_non_fatal_error errno +is 1 and +.Fa retval +is either 0 or \-1, or 0 otherwise. +.Pp +.Fn BIO_set_tcp_ndelay +returns 0 on success or \-1 on failure. +.Sh ERRORS +If +.Fn BIO_get_host_ip , +.Fn BIO_get_port , +or +.Fn BIO_get_accept_socket +fail or +.Fn BIO_accept +fails fatally, the following diagnostics can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv BIO_R_ACCEPT_ERROR Qq "accept error" +.Xr accept 2 +failed fatally in +.Fn BIO_accept . +.It Dv BIO_R_BAD_HOSTNAME_LOOKUP Qq "bad hostname lookup" +.Xr getaddrinfo 3 +failed or +.Fa hostname +was +.Dv NULL +in +.Fn BIO_get_host_ip , +or +.Xr getaddrinfo 3 +failed in +.Fn BIO_get_accept_socket . +.It Dv BIO_R_INVALID_ARGUMENT Qq "invalid argument" +.Xr getaddrinfo 3 +failed in +.Fn BIO_get_port . +.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" +Memory allocation failed in +.Fn BIO_get_accept_socket , +or +.Fn BIO_accept +.Em succeeded +but was unable to allocate memory for +.Pf * Fa addr . +For +.Fn BIO_accept , +the returned file descriptor is valid, +and communication with the peer can be attempted using it. +.It Dv BIO_R_NO_PORT_SPECIFIED Qq "no port specified" +The +.Fa servname +argument was +.Dv NULL +in +.Fn BIO_get_port , +or +.Fa host_port +was +.Dv NULL +or ended after the first colon in +.Fn BIO_get_accept_socket . +.It Dv BIO_R_NULL_PARAMETER Qq "null parameter" +The +.Fa addr +argument was +.Dv NULL +in +.Fn BIO_accept . +.It Dv BIO_R_UNABLE_TO_BIND_SOCKET Qq "unable to bind socket" +.Xr bind 2 +failed in +.Fn BIO_get_accept_socket . +.It Dv BIO_R_UNABLE_TO_CREATE_SOCKET Qq "unable to create socket" +.Xr socket 2 +failed in +.Fn BIO_get_accept_socket . +.It Dv BIO_R_UNABLE_TO_LISTEN_SOCKET Qq "unable to listen socket" +.Xr listen 2 +failed in +.Fn BIO_get_accept_socket . +.El +.Sh SEE ALSO +.Xr bind 2 , +.Xr connect 2 , +.Xr errno 2 , +.Xr fcntl 2 , +.Xr getsockopt 2 , +.Xr listen 2 , +.Xr sigaction 2 , +.Xr socket 2 , +.Xr BIO_new 3 , +.Xr BIO_read 3 , +.Xr getaddrinfo 3 , +.Xr ip 4 , +.Xr tcp 4 +.Sh HISTORY +.Fn BIO_sock_should_retry +first appeared in SSLeay 0.6.5 and the other functions except +.Fn BIO_socket_nbio +in SSLeay 0.8.0. +They have all been available since +.Ox 2.4 . +.Pp +.Fn BIO_socket_nbio +first appeared in SSLeay 0.9.1 and has been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/BIO_ctrl.3 b/static/openbsd/man3/BIO_ctrl.3 new file mode 100644 index 00000000..ca13f206 --- /dev/null +++ b/static/openbsd/man3/BIO_ctrl.3 @@ -0,0 +1,638 @@ +.\" $OpenBSD: BIO_ctrl.3,v 1.26 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 24a535eaf Tue Sep 22 13:14:20 2020 +0100 +.\" selective merge up to: OpenSSL 0c5bc96f Tue Mar 15 13:57:22 2022 +0000 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_CTRL 3 +.Os +.Sh NAME +.Nm BIO_ctrl , +.Nm BIO_callback_ctrl , +.Nm BIO_ptr_ctrl , +.Nm BIO_int_ctrl , +.Nm BIO_reset , +.Nm BIO_seek , +.Nm BIO_tell , +.Nm BIO_flush , +.Nm BIO_eof , +.Nm BIO_set_close , +.Nm BIO_get_close , +.Nm BIO_pending , +.Nm BIO_wpending , +.Nm BIO_ctrl_pending , +.Nm BIO_ctrl_wpending , +.Nm BIO_get_info_callback , +.Nm BIO_set_info_callback , +.Nm BIO_info_cb , +.Nm bio_info_cb +.Nd BIO control operations +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft long +.Fo BIO_ctrl +.Fa "BIO *b" +.Fa "int cmd" +.Fa "long larg" +.Fa "void *parg" +.Fc +.Ft long +.Fo BIO_callback_ctrl +.Fa "BIO *b" +.Fa "int cmd" +.Fa "BIO_info_cb *cb" +.Fc +.Ft char * +.Fo BIO_ptr_ctrl +.Fa "BIO *b" +.Fa "int cmd" +.Fa "long larg" +.Fc +.Ft long +.Fo BIO_int_ctrl +.Fa "BIO *b" +.Fa "int cmd" +.Fa "long larg" +.Fa "int iarg" +.Fc +.Ft int +.Fo BIO_reset +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_seek +.Fa "BIO *b" +.Fa "int ofs" +.Fc +.Ft int +.Fo BIO_tell +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_flush +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_eof +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_set_close +.Fa "BIO *b" +.Fa "long flag" +.Fc +.Ft int +.Fo BIO_get_close +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_pending +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_wpending +.Fa "BIO *b" +.Fc +.Ft size_t +.Fo BIO_ctrl_pending +.Fa "BIO *b" +.Fc +.Ft size_t +.Fo BIO_ctrl_wpending +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_get_info_callback +.Fa "BIO *b" +.Fa "BIO_info_cb **cbp" +.Fc +.Ft int +.Fo BIO_set_info_callback +.Fa "BIO *b" +.Fa "BIO_info_cb *cb" +.Fc +.Ft typedef int +.Fo BIO_info_cb +.Fa "BIO *b" +.Fa "int state" +.Fa "int res" +.Fc +.Ft typedef int +.Fo bio_info_cb +.Fa "BIO *b" +.Fa "int state" +.Fa "int res" +.Fc +.Sh DESCRIPTION +.Fn BIO_ctrl , +.Fn BIO_callback_ctrl , +.Fn BIO_ptr_ctrl , +and +.Fn BIO_int_ctrl +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 BIO's manual page +as well as any special features of the standard calls. +.Pp +Depending on the +.Fa cmd +and on the type of +.Fa b , +.Fn BIO_ctrl +may have a read-only effect on +.Fa b +or change data in +.Fa b +or in its sub-structures. +It may also have a side effect of changing the memory pointed to by +.Fa parg . +.Pp +.Fn BIO_callback_ctrl +does not call +.Fn BIO_ctrl +but instead requires that the BIO type of +.Fa b +provides a dedicated +.Fa callback_ctrl +function pointer, which is built into the library for some standard BIO +types and can be provided with +.Xr BIO_meth_set_callback_ctrl 3 +for application-defined BIO types. +The only +.Fa cmd +supported by +.Fn BIO_callback_ctrl +is +.Dv BIO_CTRL_SET_CALLBACK . +.Pp +.Fn BIO_ptr_ctrl +calls +.Fn BIO_ctrl +with +.Fa parg +pointing to the location of a temporary pointer variable initialized to +.Dv NULL . +.Pp +.Fn BIO_int_ctrl +calls +.Fn BIO_ctrl +with +.Fa parg +pointing to the location of a temporary +.Vt int +variable initialized to +.Fa iarg . +If +.Fn BIO_ctrl +changes the value stored at +.Pf * Fa parg , +the new value is ignored. +.Pp +.Fn BIO_reset +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 +.Fn BIO_seek +resets a file related BIO's (that is file descriptor and +FILE BIOs) file position pointer to +.Fa ofs +bytes from start of file. +.Pp +.Fn BIO_tell +returns the current file position of a file related BIO. +.Pp +.Fn BIO_flush +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 +.Fn BIO_eof +returns 1 if the BIO has read EOF. +The precise meaning of "EOF" varies according to the BIO type. +.Pp +.Fn BIO_set_close +sets the BIO +.Fa b +close flag to +.Fa flag . +.Fa flag +can take the value +.Dv BIO_CLOSE +or +.Dv BIO_NOCLOSE . +Typically +.Dv 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 +.Fn BIO_get_close +returns the BIO's close flag. +.Pp +.Fn BIO_pending , +.Fn BIO_ctrl_pending , +.Fn BIO_wpending , +and +.Fn BIO_ctrl_wpending +return the number of pending characters in the BIO's read and write buffers. +Not all BIOs support these calls. +.Fn BIO_ctrl_pending +and +.Fn BIO_ctrl_wpending +return a +.Vt size_t +type and are functions. +.Pp +.Fn BIO_set_info_callback +installs the function pointer +.Fa cb +as an info callback in +.Fa b +by calling +.Fn BIO_callback_ctrl +with a command of +.Dv BIO_CTRL_SET_CALLBACK . +Among the BIO types built into the library, only +.Xr BIO_s_connect 3 +and +.Xr BIO_f_ssl 3 +support this functionality. +Some filter BIO types forward this control call +to the next BIO in the chain instead of processing it themselves. +.Pp +.Fn BIO_get_info_callback +places the function pointer to the info callback into +.Pf * Fa cbp +if any was installed using +.Fn BIO_set_info_callback +or +.Fn BIO_callback_ctrl . +If the type of +.Fa b +supports setting an info callback but none was installed, it stores a +.Dv NULL +pointer in +.Pf * Fa cbp . +.Pp +The function type name +.Vt bio_info_cb +is a deprecated synonym for +.Vt BIO_info_cb +provided for backward compatibility with some existing application software. +.Pp +The following +.Fa cmd +constants correspond to macros: +.Bl -column BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT BIO_set_ssl_renegotiate_timeout(3) +.It Fa cmd No constant Ta corresponding macro +.It Dv BIO_C_DESTROY_BIO_PAIR Ta Xr BIO_destroy_bio_pair 3 +.It Dv BIO_C_DO_STATE_MACHINE Ta Xr BIO_do_handshake 3 +.It Dv BIO_C_FILE_SEEK Ta Fn BIO_seek +.It Dv BIO_C_FILE_TELL Ta Fn BIO_tell +.It Dv BIO_C_GET_ACCEPT Ta Xr BIO_get_accept_port 3 +.It Dv BIO_C_GET_BIND_MODE Ta Xr BIO_get_bind_mode 3 +.It Dv BIO_C_GET_BUF_MEM_PTR Ta Xr BIO_get_mem_ptr 3 +.It Dv BIO_C_GET_BUFF_NUM_LINES Ta Xr BIO_get_buffer_num_lines 3 +.It Dv BIO_C_GET_CIPHER_CTX Ta Xr BIO_get_cipher_ctx 3 +.It Dv BIO_C_GET_CIPHER_STATUS Ta Xr BIO_get_cipher_status 3 +.It Dv BIO_C_GET_FD Ta Xr BIO_get_fd 3 +.It Dv BIO_C_GET_FILE_PTR Ta Xr BIO_get_fp 3 +.It Dv BIO_C_GET_MD Ta Xr BIO_get_md 3 +.It Dv BIO_C_GET_MD_CTX Ta Xr BIO_get_md_ctx 3 +.It Dv BIO_C_GET_READ_REQUEST Ta Xr BIO_get_read_request 3 +.It Dv BIO_C_GET_SSL Ta Xr BIO_get_ssl 3 +.It Dv BIO_C_GET_SSL_NUM_RENEGOTIATES Ta Xr BIO_get_num_renegotiates 3 +.It Dv BIO_C_GET_WRITE_BUF_SIZE Ta Xr BIO_get_write_buf_size 3 +.It Dv BIO_C_GET_WRITE_GUARANTEE Ta Xr BIO_get_write_guarantee 3 +.It Dv BIO_C_MAKE_BIO_PAIR Ta Xr BIO_make_bio_pair 3 +.It Dv BIO_C_RESET_READ_REQUEST Ta Xr BIO_ctrl_reset_read_request 3 +.It Dv BIO_C_SET_BIND_MODE Ta Xr BIO_set_bind_mode 3 +.It Dv BIO_C_SET_BUF_MEM Ta Xr BIO_set_mem_buf 3 +.It Dv BIO_C_SET_BUF_MEM_EOF_RETURN Ta Xr BIO_set_mem_eof_return 3 +.It Dv BIO_C_SET_BUFF_READ_DATA Ta Xr BIO_set_buffer_read_data 3 +.It Dv BIO_C_SET_FD Ta Xr BIO_set_fd 3 +.It Dv BIO_C_SET_FILE_PTR Ta Xr BIO_set_fp 3 +.It Dv BIO_C_SET_MD Ta Xr BIO_set_md 3 +.It Dv BIO_C_SET_MD_CTX Ta Xr BIO_set_md_ctx 3 +.It Dv BIO_C_SET_NBIO Ta Xr BIO_set_nbio 3 +.It Dv BIO_C_SET_SSL Ta Xr BIO_set_ssl 3 +.It Dv BIO_C_SET_SSL_RENEGOTIATE_BYTES Ta Xr BIO_set_ssl_renegotiate_bytes 3 +.It Dv BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT Ta Xr BIO_set_ssl_renegotiate_timeout 3 +.It Dv BIO_C_SET_WRITE_BUF_SIZE Ta Xr BIO_set_write_buf_size 3 +.It Dv BIO_C_SHUTDOWN_WR Ta Xr BIO_shutdown_wr 3 +.It Dv BIO_C_SSL_MODE Ta Xr BIO_set_ssl_mode 3 +.It Dv BIO_CTRL_DGRAM_CONNECT Ta Xr BIO_ctrl_dgram_connect 3 +.It Dv BIO_CTRL_DGRAM_GET_PEER Ta Xr BIO_dgram_get_peer 3 +.It Dv BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP Ta Xr BIO_dgram_recv_timedout 3 +.It Dv BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP Ta Xr BIO_dgram_send_timedout 3 +.It Dv BIO_CTRL_DGRAM_SET_CONNECTED Ta Xr BIO_ctrl_set_connected 3 +.It Dv BIO_CTRL_DGRAM_SET_PEER Ta Xr BIO_dgram_set_peer 3 +.It Dv BIO_CTRL_DUP Ta Xr BIO_dup_state 3 +.It Dv BIO_CTRL_EOF Ta Fn BIO_eof +.It Dv BIO_CTRL_FLUSH Ta Fn BIO_flush +.It Dv BIO_CTRL_GET_CALLBACK Ta Fn BIO_get_info_callback +.It Dv BIO_CTRL_GET_CLOSE Ta Fn BIO_get_close +.It Dv BIO_CTRL_INFO Ta Xr BIO_get_mem_data 3 +.It Dv BIO_CTRL_PENDING Ta Fn BIO_pending +.It Dv BIO_CTRL_RESET Ta Fn BIO_reset +.It Dv BIO_CTRL_SET_CALLBACK Ta Fn BIO_set_info_callback +.It Dv BIO_CTRL_SET_CLOSE Ta Fn BIO_set_close +.It Dv BIO_CTRL_WPENDING Ta Fn BIO_wpending +.El +.Pp +A few +.Fa cmd +constants serve more than one macro each +and are documented in the following manual pages: +.Bl -column BIO_C_SET_BUFF_SIZE BIO_s_connect(3) -offset 3n +.It Fa cmd No constant Ta manual page +.It Dv BIO_C_GET_CONNECT Ta Xr BIO_s_connect 3 +.It Dv BIO_C_SET_ACCEPT Ta Xr BIO_s_accept 3 +.It Dv BIO_C_SET_BUFF_SIZE Ta Xr BIO_f_buffer 3 +.It Dv BIO_C_SET_CONNECT Ta Xr BIO_s_connect 3 +.It Dv BIO_C_SET_FILENAME Ta Xr BIO_s_file 3 +.El +.Pp +Some +.Fa cmd +constants are not associated with any macros. +They are documented in the following manual pages: +.Bl -column BIO_CTRL_DGRAM_SET_RECV_TIMEOUT BIO_dgram_recv_timedout(3)\ + -offset 3n +.It Fa cmd No constant Ta manual page +.\" The following constants are intentionally undocumented because +.\" BIO_f_asn1 has been removed from the public API. +.\" .It Dv BIO_C_GET_EX_ARG Ta Xr BIO_f_asn1 3 +.\" .It Dv BIO_C_SET_EX_ARG Ta Xr BIO_f_asn1 3 +.It Dv BIO_CTRL_DGRAM_GET_FALLBACK_MTU Ta Xr BIO_dgram_set_peer 3 +.It Dv BIO_CTRL_DGRAM_GET_MTU Ta Xr BIO_dgram_set_peer 3 +.It Dv BIO_CTRL_DGRAM_GET_RECV_TIMEOUT Ta Xr BIO_dgram_recv_timedout 3 +.It Dv BIO_CTRL_DGRAM_GET_SEND_TIMEOUT Ta Xr BIO_dgram_send_timedout 3 +.It Dv BIO_CTRL_DGRAM_SET_MTU Ta Xr BIO_dgram_set_peer 3 +.It Dv BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT Ta Xr BIO_dgram_recv_timedout 3 +.It Dv BIO_CTRL_DGRAM_SET_RECV_TIMEOUT Ta Xr BIO_dgram_recv_timedout 3 +.It Dv BIO_CTRL_DGRAM_SET_SEND_TIMEOUT Ta Xr BIO_dgram_send_timedout 3 +.It Dv BIO_CTRL_DGRAM_MTU_EXCEEDED Ta Xr BIO_s_datagram 3 +.It Dv BIO_CTRL_POP Ta Xr BIO_pop 3 +.It Dv BIO_CTRL_PUSH Ta Xr BIO_push 3 +.El +.Sh RETURN VALUES +The meaning of the return values of +.Fn BIO_ctrl , +.Fn BIO_callback_ctrl , +and +.Fn BIO_int_ctrl +depends on both the type of +.Fa b +and on the +.Fa cmd . +If +.Fa b +is a +.Dv NULL +pointer, no action occurs and 0 is returned. +The return value \-2 usually indicates a fatal error. +In particular, it is returned if the +.Fa cmd +is unsupported by the type of +.Fa b . +.Pp +.Fn BIO_callback_ctrl +and +.Fn BIO_set_info_callback +return 1 on success, 0 if +.Fa b +is +.Dv NULL +or to indicate failure of a valid +.Fa cmd , +or \-2 if the +.Fa cmd +is not supported by +.Fa b . +.Pp +.Fn BIO_ptr_ctrl +returns +.Dv NULL +if the +.Fn BIO_ctrl +call returns a negative value or does not change +.Pf * Fa parg , +or the pointer it puts into +.Pf * Fa parg +otherwise. +.Pp +.Fn BIO_int_ctrl +returns the return value of +.Fn BIO_ctrl . +.Pp +.Fn BIO_reset +normally returns 1 for success and 0 or -1 for failure. +File BIOs are an exception, returning 0 for success and -1 for failure. +.Pp +.Fn BIO_seek +and +.Fn BIO_tell +both return the current file position on success +and -1 for failure, except file BIOs which for +.Fn BIO_seek +always return 0 for success and -1 for failure. +.Pp +.Fn BIO_flush +returns 1 for success and 0 or -1 for failure. +.Pp +.Fn BIO_eof +returns 1 if EOF has been reached or 0 otherwise. +.Pp +.Fn BIO_set_close +always returns 1. +.Pp +.Fn BIO_get_close +returns the close flag value +.Dv BIO_CLOSE +or +.Dv BIO_NOCLOSE . +.Pp +.Fn BIO_pending , +.Fn BIO_ctrl_pending , +.Fn BIO_wpending , +and +.Fn BIO_ctrl_wpending +return the amount of pending data. +.Pp +.Fn BIO_get_info_callback +returns 1 on success, including when the type of +.Fa b +supports an info callback but none is installed, +0 if +.Fa b +is +.Dv NULL +or \-2 if the type of +.Fa b +does not support an info callback. +.Pp +If a callback was installed in +.Fa b +using +.Xr BIO_set_callback_ex 3 +or +.Xr BIO_set_callback 3 , +it can modify the return values of all these functions. +.Sh NOTES +Because it can write data, +.Fn BIO_flush +may return 0 or -1 indicating that the call should be retried later +in a similar manner to +.Xr BIO_write 3 . +The +.Xr BIO_should_retry 3 +call should be used and appropriate action taken if the call fails. +.Pp +The return values of +.Fn BIO_pending +and +.Fn BIO_wpending +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 +.Vt FILE +structure's internal buffers but it is not possible +to determine this in a portable way. +For other types of BIO they may not be supported. +.Pp +If they do not internally handle a particular +.Fn BIO_ctrl +operation, filter BIOs 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 +.Fn BIO_seek , +but this may still succeed if the chain ends +in a FILE or file descriptor BIO. +.Pp +Source/sink BIOs return a 0 if they do not recognize the +.Fn BIO_ctrl +operation. +.Sh SEE ALSO +.Xr BIO_meth_new 3 , +.Xr BIO_new 3 +.Sh HISTORY +.Fn BIO_ctrl , +.Fn BIO_reset , +.Fn BIO_flush , +.Fn BIO_eof , +.Fn BIO_set_close , +.Fn BIO_get_close , +and +.Fn BIO_pending +first appeared in SSLeay 0.6.0. +.Fn BIO_wpending +first appeared in SSLeay 0.8.1. +.Fn BIO_ptr_ctrl , +.Fn BIO_int_ctrl , +.Fn BIO_get_info_callback +and +.Fn BIO_set_info_callback +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_seek +and +.Fn BIO_tell +first appeared in SSLeay 0.9.1. +.Fn BIO_ctrl_pending +and +.Fn BIO_ctrl_wpending +first appeared in OpenSSL 0.9.4. +These functions have been available since +.Ox 2.6 . +.Pp +.Fn BIO_callback_ctrl +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn bio_info_cb +first appeared with a more complicated prototype in OpenSSL 0.9.6 +and has been available since +.Ox 2.9 . +.Pp +.Fn BIO_info_cb +first appeared in OpenSSL 1.1.0h and has been available since +.Ox 6.3 . +.Sh 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 +.Fn BIO_seek +on a file BIO for a successful operation. diff --git a/static/openbsd/man3/BIO_dump.3 b/static/openbsd/man3/BIO_dump.3 new file mode 100644 index 00000000..2c06c8cc --- /dev/null +++ b/static/openbsd/man3/BIO_dump.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: BIO_dump.3,v 1.6 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt BIO_DUMP 3 +.Os +.Sh NAME +.Nm BIO_dump , +.Nm BIO_dump_indent +.Nd hexadecimal printout of arbitrary byte arrays +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft int +.Fo BIO_dump +.Fa "BIO *b" +.Fa "const char *s" +.Fa "int len" +.Fc +.Ft int +.Fo BIO_dump_indent +.Fa "BIO *b" +.Fa "const char *s" +.Fa "int len" +.Fa "int indent" +.Fc +.Sh DESCRIPTION +.Fn BIO_dump +prints +.Fa len +bytes starting at +.Fa s +to +.Fa bio +in hexadecimal format. +.Pp +The first column of output contains the index, in the byte array starting at +.Fa s , +of the first byte shown on the respective output line, expressed as a +four-digit hexadecimal number starting at 0000, followed by a dash. +After the dash, sixteen bytes of data are printed as two-digit +hexadecimal numbers, respecting the order in which they appear in +the array +.Fa s . +Another dash is printed after the eighth column. +.Pp +To the right of the hexadecimal representation of the bytes, +the same bytes are printed again, this time as ASCII characters. +Non-printable ASCII characters are replaced with dots. +.Pp +Trailing space characters and NUL bytes are omitted from the main table. +If there are any, an additional line is printed, consisting of the +.Fa len +argument as a four-digit hexadecimal number, a dash, and the fixed string +.Qq . +.Pp +.Fn BIO_dump_indent +is similar except that +.Fa indent +space characters are prepended to each output line. +If +.Fa indent +is 7 or more, the number of data columns is reduced such that the +total width of the output does not exceed 79 characters per line. +.Sh RETURN VALUES +On success these functions return the total number of bytes written by +.Xr BIO_write 3 +or +.Xr fwrite 3 . +If a failure occurs at any point when writing, these +functions will stop after having potentially written out partial results, +and return -1. +.Sh SEE ALSO +.Xr hexdump 1 , +.Xr BIO_new 3 , +.Xr BIO_write 3 +.Sh HISTORY +.Fn BIO_dump +first appeared in SSLeay 0.6.5 and has been available since +.Ox 2.4 . +.Pp +.Fn BIO_dump_indent +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . diff --git a/static/openbsd/man3/BIO_dup_chain.3 b/static/openbsd/man3/BIO_dup_chain.3 new file mode 100644 index 00000000..ad753e71 --- /dev/null +++ b/static/openbsd/man3/BIO_dup_chain.3 @@ -0,0 +1,142 @@ +.\" $OpenBSD: BIO_dup_chain.3,v 1.3 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2022 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 $Mdocdate: June 8 2025 $ +.Dt BIO_DUP_CHAIN 3 +.Os +.Sh NAME +.Nm BIO_dup_chain , +.Nm BIO_dup_state +.Nd copy a BIO chain +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft BIO * +.Fn BIO_dup_chain "BIO *b" +.Ft long +.Fn BIO_dup_state "BIO *b" "BIO *new_bio" +.Sh DESCRIPTION +.Fn BIO_dup_chain +copies the chain starting at +.Fa b +by iteratively copying +.Fa b +and all the BIOs following it +and joining the copies in the same order as in the original chain. +The copying operation is neither a deep copy nor a shallow copy. +.Pp +Some parts of the state of each BIO are copied, +in particular with respect to the values returned by +.Xr BIO_get_init 3 , +.Xr BIO_test_flags 3 , +and +.Xr BIO_get_shutdown 3 . +.\" XXX new_bio->num = bio->num; +Other parts of the state of the BIOs are not copied +but instead initialized to 0, +in particular with respect to the values returned by +.Xr BIO_number_read 3 , +.Xr BIO_number_written 3 , +and +.Xr BIO_get_retry_reason 3 . +The custom data pointer that can be used by custom BIO types +and that can be retrieved with +.Xr BIO_get_data 3 +is set to +.Dv NULL +in the copied BIO objects rather than copied. +The reference count of each BIO in the copied chain is set to 1. +.Pp +For each BIO in the chain, copying the data that was set with +.Xr BIO_set_ex_data 3 +is attempted, which may involve calling application-defined +callback functions. +.Pp +The following pointers are copied +rather than creating deep copies of the objects pointed to: +.Bl -bullet +.It +The +.Fa type +pointer used for creating each BIO with +.Xr BIO_new 3 , +implying that functions like +.Xr BIO_method_name 3 +return pointers to the same strings for the BIOs in the copied chain, +and that these strings are not copied. +.It +All function pointers, in particular those installed with +.Xr BIO_set_callback_ex 3 +and +.Xr BIO_get_callback_ex 3 . +.It +The pointer installed with +.Xr BIO_set_callback_arg 3 , +which implies that for BIOs using +.Xr BIO_debug_callback 3 , +those in the copied chain use the same BIOs for debugging output +as the corresponding ones in the original chain, +and none of the debugging output BIOs are copied. +.El +.Pp +.Fn BIO_dup_state +is a macro that calls +.Xr BIO_ctrl 3 +with a +.Fa cmd +argument of +.Dv BIO_CTRL_DUP . +It is automatically called for each BIO during +.Fn BIO_dup_chain +after the copied BIO is initialized and data copied into it, +but before the data set with +.Xr BIO_set_ex_data 3 +is copied into the new BIO and before it is linked into the new chain. +.Pp +This control operation may modify the operation of +.Fn BIO_dup_chain +for particular types of BIOs contained in the chain, +for example initializing or copying additional data. +For BIO types provided by the library, such additional effects +are documented in the respective manual pages, in particular in +.Xr BIO_f_buffer 3 , +.Xr BIO_f_cipher 3 , +.Xr BIO_f_md 3 , +.Xr BIO_f_ssl 3 , +.Xr BIO_s_bio 3 , +and +.Xr BIO_s_connect 3 . +.Sh RETURN VALUES +.Fn BIO_dup_chain +returns a pointer to the newly allocated copy of the BIO +.Fa b +on success or +.Dv NULL +on failure . +.Pp +.Fn BIO_dup_state +returns 1 on success or a value less than or equal to zero on failure. +.Sh SEE ALSO +.Xr BIO_get_data 3 , +.Xr BIO_new 3 , +.Xr BIO_next 3 , +.Xr BIO_push 3 +.Sh HISTORY +.Fn BIO_dup_chain +and +.Fn BIO_dup_state +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BIO_f_base64.3 b/static/openbsd/man3/BIO_f_base64.3 new file mode 100644 index 00000000..f652dac1 --- /dev/null +++ b/static/openbsd/man3/BIO_f_base64.3 @@ -0,0 +1,149 @@ +.\" $OpenBSD: BIO_f_base64.3,v 1.16 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL fc1d88f0 Wed Jul 2 22:42:40 2014 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2003, 2005, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_F_BASE64 3 +.Os +.Sh NAME +.Nm BIO_f_base64 +.\" .Nm EVP_ENCODE_LENGTH and +.\" .Nm EVP_DECODE_LENGTH are intentionally undocumented +.\" because they are internal implementation details of BIO_f_base64(3) +.\" and practically unused outside evp/bio_b64.c. +.Nd base64 BIO filter +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.In openssl/evp.h +.Ft const BIO_METHOD * +.Fo BIO_f_base64 +.Fa void +.Fc +.Sh DESCRIPTION +.Fn BIO_f_base64 +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 +.Xr BIO_gets 3 +or +.Xr BIO_puts 3 . +.Pp +.Xr BIO_flush 3 +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 +To encode the data all on one line and to expect the data to be all +on one line, initialize the base64 BIO as follows: +.Bd -literal -offset indent +BIO *b64 = BIO_new(BIO_f_base64()); +BIO_set_flags(b64, BIO_FLAGS_BASE64_NO_NL); +.Ed +.Sh RETURN VALUES +.Fn BIO_f_base64 +returns the base64 BIO method. +.Pp +When called on a base64 BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_BASE64 +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq base64 encoding . +.Sh EXAMPLES +Base64 encode the string "hello, world\en" +and write the result to standard output: +.Bd -literal -offset indent +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); +.Ed +.Pp +Read Base64-encoded data from standard input +and write the decoded data to standard output: +.Bd -literal -offset indent +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); +.Ed +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr EVP_EncodeInit 3 +.Sh HISTORY +.Fn BIO_f_base64 +first appeared in SSLeay 0.6.5 and has been available since +.Ox 2.4 . +.Sh BUGS +The ambiguity of EOF in base64-encoded data can cause additional +data following the base64-encoded block to be misinterpreted. +.Pp +There should be some way of specifying a test that the BIO can perform +to reliably determine EOF (for example a MIME boundary). diff --git a/static/openbsd/man3/BIO_f_buffer.3 b/static/openbsd/man3/BIO_f_buffer.3 new file mode 100644 index 00000000..28c4f316 --- /dev/null +++ b/static/openbsd/man3/BIO_f_buffer.3 @@ -0,0 +1,263 @@ +.\" $OpenBSD: BIO_f_buffer.3,v 1.18 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2010, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_F_BUFFER 3 +.Os +.Sh NAME +.Nm BIO_f_buffer , +.Nm BIO_get_buffer_num_lines , +.Nm BIO_set_read_buffer_size , +.Nm BIO_set_write_buffer_size , +.Nm BIO_set_buffer_size , +.Nm BIO_set_buffer_read_data +.\" .Nm BIO_buffer_get_num_lines and +.\" .Nm BIO_CTRL_GET are intentionally undocumented. +.\" Contrary to what bio.h says, they do not *not* get some "IO type", +.\" whatever that is supposed to be, but are NOOPs, and nothing uses them. +.Nd buffering BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fo BIO_f_buffer +.Fa void +.Fc +.Ft long +.Fo BIO_get_buffer_num_lines +.Fa "BIO *b" +.Fc +.Ft long +.Fo BIO_set_read_buffer_size +.Fa "BIO *b" +.Fa "long size" +.Fc +.Ft long +.Fo BIO_set_write_buffer_size +.Fa "BIO *b" +.Fa "long size" +.Fc +.Ft long +.Fo BIO_set_buffer_size +.Fa "BIO *b" +.Fa "long size" +.Fc +.Ft long +.Fo BIO_set_buffer_read_data +.Fa "BIO *b" +.Fa "void *buf" +.Fa "long num" +.Fc +.Sh DESCRIPTION +.Fn BIO_f_buffer +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 +.Xr BIO_gets 3 +and +.Xr BIO_puts 3 +are supported. +.Pp +Calling +.Xr BIO_reset 3 +on a buffering BIO clears any buffered data. +.Pp +.Fn BIO_get_buffer_num_lines +returns the number of lines currently buffered. +.Pp +.Fn BIO_set_read_buffer_size , +.Fn BIO_set_write_buffer_size , +and +.Fn BIO_set_buffer_size +set the read, write or both read and write buffer sizes to +.Fa size . +The initial buffer size is +.Dv DEFAULT_BUFFER_SIZE , +currently 4096. +Any attempt to reduce the buffer size below +.Dv DEFAULT_BUFFER_SIZE +is ignored. +Any buffered data is cleared when the buffer is resized. +.Pp +.Fn BIO_set_buffer_read_data +clears the read buffer and fills it with +.Fa num +bytes of +.Fa buf . +If +.Fa num +is larger than the current buffer size, the buffer is expanded. +.Pp +Buffering BIOs implement +.Xr BIO_gets 3 +by using +.Xr BIO_read 3 +operations on the next BIO in the chain. +By prepending a buffering BIO to a chain +it is therefore possible to provide the functionality of +.Xr BIO_gets 3 +if the following BIOs do not support it (for example SSL BIOs). +.Pp +Data is only written to the next BIO in the chain +when the write buffer fills or when +.Xr BIO_flush 3 +is called. +It is therefore important to call +.Xr BIO_flush 3 +whenever any pending data should be written +such as when removing a buffering BIO using +.Xr BIO_pop 3 . +.Xr BIO_flush 3 +may need to be retried if the ultimate source/sink BIO is non-blocking. +.Pp +When a chain containing a buffering BIO is copied with +.Xr BIO_dup_chain 3 , +.Fn BIO_set_read_buffer_size +and +.Fn BIO_set_write_buffer_size +are called internally to automatically copy both buffer sizes from the +original BIO object to the new one. +.Pp +.Xr BIO_ctrl 3 +.Fa cmd +arguments correspond to macros as follows: +.Bl -column BIO_C_GET_BUFF_NUM_LINES BIO_get_buffer_num_lines() -offset 3n +.It Fa cmd No constant Ta corresponding macro +.It Dv BIO_C_GET_BUFF_NUM_LINES Ta Fn BIO_get_buffer_num_lines +.It Dv BIO_C_SET_BUFF_READ_DATA Ta Fn BIO_set_buffer_read_data +.It Dv BIO_C_SET_BUFF_SIZE Ta Fn BIO_set_buffer_size +.It Dv BIO_CTRL_FLUSH Ta Xr BIO_flush 3 +.It Dv BIO_CTRL_PENDING Ta Xr BIO_pending 3 +.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 +.It Dv BIO_CTRL_WPENDING Ta Xr BIO_wpending 3 +.El +.Pp +The +.Fa cmd +constant +.Dv BIO_C_SET_BUFF_SIZE +is special. +It is also used for +.Xr BIO_int_ctrl 3 +with the following +.Fa iarg +arguments: +.Bl -column BIO_C_SET_BUFF_SIZE iarg BIO_set_write_buffer_size() -offset 3n +.It Fa cmd No constant Ta Fa iarg Ta corresponding macro +.It Dv BIO_C_SET_BUFF_SIZE Ta 0 Ta Fn BIO_set_read_buffer_size +.It Ta 1 Ta Fn BIO_set_write_buffer_size +.El +.Sh RETURN VALUES +.Fn BIO_f_buffer +returns the buffering BIO method. +.Pp +When called on a buffering BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_BUFFER +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq buffer . +.Pp +.Fn BIO_get_buffer_num_lines +returns the number of lines buffered (may be 0). +.Pp +.Fn BIO_set_read_buffer_size , +.Fn BIO_set_write_buffer_size , +and +.Fn BIO_set_buffer_size +return 1 if the buffer was successfully resized or 0 for failure. +.Pp +.Fn BIO_set_buffer_read_data +returns 1 if the data was set correctly or 0 if there was an error. +.Sh SEE ALSO +.Xr BIO_ctrl 3 , +.Xr BIO_flush 3 , +.Xr BIO_new 3 , +.Xr BIO_pop 3 , +.Xr BIO_reset 3 +.Sh HISTORY +.Fn BIO_f_buffer +first appeared in SSLeay 0.6.0. +.Fn BIO_get_buffer_num_lines +and +.Fn BIO_set_buffer_size +first appeared in SSLeay 0.6.5. +.Fn BIO_set_read_buffer_size +and +.Fn BIO_set_write_buffer_size +first appeared in SSLeay 0.8.0. +.Fn BIO_set_buffer_read_data +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BIO_f_cipher.3 b/static/openbsd/man3/BIO_f_cipher.3 new file mode 100644 index 00000000..3f7fe7bf --- /dev/null +++ b/static/openbsd/man3/BIO_f_cipher.3 @@ -0,0 +1,210 @@ +.\" $OpenBSD: BIO_f_cipher.3,v 1.17 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2003, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_F_CIPHER 3 +.Os +.Sh NAME +.Nm BIO_f_cipher , +.Nm BIO_set_cipher , +.Nm BIO_get_cipher_status , +.Nm BIO_get_cipher_ctx +.\" .Nm BIO_CTRL_SET is intentionally undocumented because it has no effect. +.Nd cipher BIO filter +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.In openssl/evp.h +.Ft const BIO_METHOD * +.Fo BIO_f_cipher +.Fa void +.Fc +.Ft int +.Fo BIO_set_cipher +.Fa "BIO *b" +.Fa "const EVP_CIPHER *cipher" +.Fa "unsigned char *key" +.Fa "unsigned char *iv" +.Fa "int enc" +.Fc +.Ft long +.Fo BIO_get_cipher_status +.Fa "BIO *b" +.Fc +.Ft long +.Fo BIO_get_cipher_ctx +.Fa "BIO *b" +.Fa "EVP_CIPHER_CTX **pctx" +.Fc +.Sh DESCRIPTION +.Fn BIO_f_cipher +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 +.Xr EVP_CipherInit 3 , +.Xr EVP_CipherUpdate 3 , +and +.Xr EVP_CipherFinal 3 . +.Pp +Cipher BIOs do not support +.Xr BIO_gets 3 +or +.Xr BIO_puts 3 . +.Pp +.Xr BIO_flush 3 +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 +.Fn BIO_set_cipher +sets the cipher of BIO +.Fa b +to +.Fa cipher +using key +.Fa key +and IV +.Fa iv . +.Fa enc +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. +.Fn BIO_get_cipher_status +is a +.Xr BIO_ctrl 3 +macro which can be called to determine +whether the decryption operation was successful. +.Pp +.Fn BIO_get_cipher_ctx +is a +.Xr BIO_ctrl 3 +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 +.Fn BIO_set_cipher +is not flexible enough for the applications needs. +.Pp +When a chain containing a cipher BIO is copied with +.Xr BIO_dup_chain 3 , +the cipher context is automatically copied from the existing BIO object +to the new one and the init flag that can be retrieved with +.Xr BIO_get_init 3 +is set to 1. +.Pp +When encrypting, +.Xr BIO_flush 3 +must 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 signalled +by a zero return value from the read operation. +A successful decrypt followed by EOF +will also return zero for the final read. +.Fn BIO_get_cipher_status +should be called to determine if the decrypt was successful. +.Pp +As always, if +.Xr BIO_gets 3 +or +.Xr BIO_puts 3 +support is needed, then it can be achieved +by preceding the cipher BIO with a buffering BIO. +.Pp +.Xr BIO_ctrl 3 +.Fa cmd +arguments correspond to macros as follows: +.Bl -column BIO_C_GET_CIPHER_STATUS BIO_get_cipher_status() -offset 3n +.It Fa cmd No constant Ta corresponding macro +.It Dv BIO_C_GET_CIPHER_CTX Ta Fn BIO_get_cipher_ctx +.It Dv BIO_C_GET_CIPHER_STATUS Ta Fn BIO_get_cipher_status +.It Dv BIO_CTRL_FLUSH Ta Xr BIO_flush 3 +.It Dv BIO_CTRL_PENDING Ta Xr BIO_pending 3 +.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 +.It Dv BIO_CTRL_WPENDING Ta Xr BIO_wpending 3 +.El +.Sh RETURN VALUES +.Fn BIO_f_cipher +returns the cipher BIO method. +.Pp +When called on a cipher BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_CIPHER +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq cipher . +.Pp +.Fn BIO_set_cipher +returns 1 on success and 0 on error. +.Pp +.Fn BIO_get_cipher_status +returns 1 for a successful decrypt and 0 for failure. +.Pp +.Fn BIO_get_cipher_ctx +currently always returns 1. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn BIO_f_cipher , +.Fn BIO_set_cipher , +and +.Fn BIO_get_cipher_status +first appeared in SSLeay 0.6.5 and have been available since +.Ox 2.4 . +.Pp +.Fn BIO_get_cipher_ctx +first appeared in SSLeay 0.9.1 and has been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/BIO_f_md.3 b/static/openbsd/man3/BIO_f_md.3 new file mode 100644 index 00000000..ba5a0d9b --- /dev/null +++ b/static/openbsd/man3/BIO_f_md.3 @@ -0,0 +1,367 @@ +.\" $OpenBSD: BIO_f_md.3,v 1.16 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022, 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2006, 2009, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_F_MD 3 +.Os +.Sh NAME +.Nm BIO_f_md , +.Nm BIO_set_md , +.Nm BIO_get_md , +.Nm BIO_get_md_ctx , +.Nm BIO_set_md_ctx +.Nd message digest BIO filter +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.In openssl/evp.h +.Ft const BIO_METHOD * +.Fo BIO_f_md +.Fa void +.Fc +.Ft long +.Fo BIO_set_md +.Fa "BIO *b" +.Fa "EVP_MD *md" +.Fc +.Ft long +.Fo BIO_get_md +.Fa "BIO *b" +.Fa "EVP_MD **mdp" +.Fc +.Ft long +.Fo BIO_get_md_ctx +.Fa "BIO *b" +.Fa "EVP_MD_CTX **mdcp" +.Fc +.Ft long +.Fo BIO_set_md_ctx +.Fa "BIO *b" +.Fa "EVP_MD_CTX *mdc" +.Fc +.Sh DESCRIPTION +.Fn BIO_f_md +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 +.Xr EVP_DigestInit 3 , +.Xr EVP_DigestUpdate 3 , +and +.Xr EVP_DigestFinal 3 . +.Pp +.Fn BIO_set_md +sets the message digest of +.Fa b +to +.Fa md +and initializes it using +.Xr EVP_DigestInit_ex 3 . +Calling this function is required before any data is passed through +.Fa b . +.Pp +.Fn BIO_get_md +places a pointer to the digest method of +.Fa b +into +.Pf * Fa mdp . +.Pp +Any data written or read through a digest BIO using +.Xr BIO_read 3 +and +.Xr BIO_write 3 +is digested. +.Pp +.Xr BIO_gets 3 , +if its +.Sy size +parameter is large enough, +finishes the digest calculation and returns the digest value. +.Xr BIO_puts 3 +is +not supported. +If an application needs to call +.Xr BIO_gets 3 +or +.Xr BIO_puts 3 +through a chain containing digest BIOs, +this can be done by prepending a buffering BIO. +.Pp +After the digest has been retrieved from a digest BIO, call +.Xr BIO_reset 3 +to reinitialize it and any BIOs following it in its chain +before passing any more data through it. +If no subsequent BIOs require reinitialization, +.Fn BIO_set_md +can be used instead of +.Xr BIO_reset 3 . +.Pp +.Fn BIO_get_md_ctx +places a pointer to the digest context of +.Fa b +into +.Pf * Fa mdcp +and marks the BIO as initialized without actually initializing it. +Unless +.Fn BIO_set_md +was already called on +.Fa b , +the caller becomes responsible for initializing the digest context with +.Xr EVP_DigestInit_ex 3 . +.Pp +The context returned by +.Fn BIO_get_md_ctx +can be used in calls to +.Xr EVP_DigestFinal 3 +and also in the signature routines +.Xr EVP_SignFinal 3 +and +.Xr EVP_VerifyFinal 3 . +.Pp +The context returned by +.Fn BIO_get_md_ctx +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 +.Fn BIO_set_md_ctx +replaces the digest context of +.Fa b +with +.Fa mdc . +Calling this function is usually not necessary +because creating a digest BIO with +.Xr BIO_new 3 +automatically creates a digest context and stores it internally. +Before calling +.Fn BIO_set_md_ctx , +the caller has to retrieve the old context using +.Fn BIO_get_md_ctx , +and the caller also becomes responsible for calling +.Xr EVP_MD_CTX_free 3 +on the old context. +Unless +.Fa mdc +is already initialized, the caller needs to initialize it after calling +.Fn BIO_set_md_ctx +using either +.Fn BIO_set_md +or +.Xr EVP_DigestInit 3 . +.Pp +When a chain containing a message digest BIO is copied with +.Xr BIO_dup_chain 3 , +.Xr EVP_MD_CTX_copy_ex 3 +is called internally to automatically copy the message digest context +from the existing BIO object to the new one, +and the init flag that can be retrieved with +.Xr BIO_get_init 3 +is set to 1. +.Pp +.Xr BIO_ctrl 3 +.Fa cmd +arguments correspond to macros as follows: +.Bl -column BIO_C_GET_MD_CTX "corresponding macro" -offset 3n +.It Fa cmd No constant Ta corresponding macro +.It Dv BIO_C_GET_MD Ta Fn BIO_get_md +.It Dv BIO_C_GET_MD_CTX Ta Fn BIO_get_md_ctx +.It Dv BIO_C_SET_MD Ta Fn BIO_set_md +.It Dv BIO_C_SET_MD_CTX Ta Fn BIO_set_md_ctx +.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 +.El +.Sh RETURN VALUES +.Fn BIO_f_md +returns the digest BIO method. +.Pp +When called on a message digest BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_MD +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq message digest . +.Pp +.Fn BIO_set_md +returns 1 on success or 0 if +.Xr EVP_DigestInit_ex 3 +fails. +.Pp +.Fn BIO_get_md +and +.Fn BIO_set_md_ctx +return 1 on success or 0 if +.Fa b +is not initialized. +.Pp +.Fn BIO_get_md_ctx +returns 1 on success or 0 on failure, +but the current implementation cannot actually fail. +.Sh EXAMPLES +The following example creates a BIO chain containing a SHA-1 and MD5 +digest BIO and passes the string "Hello World" through it. +Error checking has been omitted for clarity. +.Bd -literal -offset 2n +BIO *bio, *mdtmp; +const 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)); +.Ed +.Pp +The next example digests data by reading through a chain instead: +.Bd -literal -offset 2n +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); +.Ed +.Pp +This next example retrieves the message digests from a BIO chain +and outputs them. +This could be used with the examples above. +.Bd -literal -offset 2n +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_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); +.Ed +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr EVP_DigestInit 3 +.Sh HISTORY +.Fn BIO_f_md , +.Fn BIO_set_md , +and +.Fn BIO_get_md +first appeared in SSLeay 0.6.0. +.Fn BIO_get_md_ctx +first appeared in SSLeay 0.8.1. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_set_md_ctx +first appeared in OpenSSL 0.9.7e and has been available since +.Ox 3.8 . +.Pp +Before OpenSSL 1.0.0, the call to +.Fn BIO_get_md_ctx +would only work if the +.Vt BIO +had been initialized, for example by calling +.Fn BIO_set_md . +.Sh BUGS +The lack of support for +.Xr BIO_puts 3 +and the non-standard behaviour of +.Xr BIO_gets 3 +could be regarded as anomalous. +It could be argued that +.Xr BIO_gets 3 +and +.Xr BIO_puts 3 +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 +.Xr BIO_ctrl 3 +call. diff --git a/static/openbsd/man3/BIO_f_null.3 b/static/openbsd/man3/BIO_f_null.3 new file mode 100644 index 00000000..ea75a242 --- /dev/null +++ b/static/openbsd/man3/BIO_f_null.3 @@ -0,0 +1,100 @@ +.\" $OpenBSD: BIO_f_null.3,v 1.13 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_F_NULL 3 +.Os +.Sh NAME +.Nm BIO_f_null +.\" .Nm BIO_f_nbio_test is intentionally undocumented +.\" because it exposes absurd functionality that is unused +.\" except in openssl(1) s_client/s_server -nbio_test. +.Nd null filter +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fo BIO_f_null +.Fa void +.Fc +.Sh DESCRIPTION +.Fn BIO_f_null +returns the null filter BIO method. +This is a filter BIO that does nothing. +As may be apparent, a null filter BIO is not particularly useful. +.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. +.Pp +A chain containing a null filter BIO cannot be copied with +.Xr BIO_dup_chain 3 , +and any attempt to do so fails and returns +.Dv NULL . +.Sh RETURN VALUES +.Fn BIO_f_null +returns the null filter BIO method. +.Pp +When called on a null filter BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_NULL_FILTER +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq NULL filter , +not to be confused with a NUL string nor with a +.Dv NULL pointer . +.Sh SEE ALSO +.Xr BIO_new 3 +.Sh HISTORY +.Fn BIO_f_null +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BIO_f_ssl.3 b/static/openbsd/man3/BIO_f_ssl.3 new file mode 100644 index 00000000..e23a15e1 --- /dev/null +++ b/static/openbsd/man3/BIO_f_ssl.3 @@ -0,0 +1,610 @@ +.\" $OpenBSD: BIO_f_ssl.3,v 1.17 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL f672aee4 Feb 9 11:52:40 2016 -0500 +.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2003, 2009, 2014-2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_F_SSL 3 +.Os +.Sh NAME +.Nm BIO_f_ssl , +.Nm BIO_set_ssl , +.Nm BIO_get_ssl , +.Nm BIO_set_ssl_mode , +.Nm BIO_set_ssl_renegotiate_bytes , +.Nm BIO_get_num_renegotiates , +.Nm BIO_set_ssl_renegotiate_timeout , +.Nm BIO_new_ssl , +.Nm BIO_new_ssl_connect , +.Nm BIO_new_buffer_ssl_connect , +.Nm BIO_ssl_copy_session_id , +.Nm BIO_ssl_shutdown , +.Nm BIO_do_handshake +.Nd SSL BIO +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/bio.h +.In openssl/ssl.h +.Ft const BIO_METHOD * +.Fn BIO_f_ssl void +.Ft long +.Fo BIO_set_ssl +.Fa "BIO *b" +.Fa "SSL *ssl" +.Fa "long c" +.Fc +.Ft long +.Fo BIO_get_ssl +.Fa "BIO *b" +.Fa "SSL *sslp" +.Fc +.Ft long +.Fo BIO_set_ssl_mode +.Fa "BIO *b" +.Fa "long client" +.Fc +.Ft long +.Fo BIO_set_ssl_renegotiate_bytes +.Fa "BIO *b" +.Fa "long num" +.Fc +.Ft long +.Fo BIO_set_ssl_renegotiate_timeout +.Fa "BIO *b" +.Fa "long seconds" +.Fc +.Ft long +.Fo BIO_get_num_renegotiates +.Fa "BIO *b" +.Fc +.Ft BIO * +.Fn BIO_new_ssl "SSL_CTX *ctx" "int client" +.Ft BIO * +.Fn BIO_new_ssl_connect "SSL_CTX *ctx" +.Ft BIO * +.Fn BIO_new_buffer_ssl_connect "SSL_CTX *ctx" +.Ft int +.Fn BIO_ssl_copy_session_id "BIO *to" "BIO *from" +.Ft void +.Fn BIO_ssl_shutdown "BIO *bio" +.Ft long +.Fn BIO_do_handshake "BIO *b" +.Sh DESCRIPTION +.Fn BIO_f_ssl +returns the +.Vt SSL +.Vt BIO +method. +This is a filter +.Vt BIO +which is a wrapper around the OpenSSL +.Vt SSL +routines adding a +.Vt BIO +.Dq flavor +to SSL I/O. +.Pp +I/O performed on an +.Vt SSL +.Vt BIO +communicates using the SSL protocol with +the +.Vt SSL Ns 's +read and write +.Vt BIO Ns s . +If an SSL connection is not established then an attempt is made to establish +one on the first I/O call. +.Pp +If a +.Vt BIO +is appended to an +.Vt SSL +.Vt BIO +using +.Xr BIO_push 3 , +it is automatically used as the +.Vt SSL +.Vt BIO Ns 's read and write +.Vt BIO Ns s . +.Pp +Calling +.Xr BIO_reset 3 +on an +.Vt SSL +.Vt BIO +closes down any current SSL connection by calling +.Xr SSL_shutdown 3 . +.Xr BIO_reset 3 +is then sent to the next +.Vt BIO +in the chain; this will typically disconnect the underlying transport. +The +.Vt SSL +.Vt BIO +is then reset to the initial accept or connect state. +.Pp +If the close flag is set when an +.Vt SSL +.Vt BIO +is freed then the internal +.Vt SSL +structure is also freed using +.Xr SSL_free 3 . +.Pp +.Fn BIO_set_ssl +sets the internal +.Vt SSL +pointer of +.Vt BIO +.Fa b +to +.Fa ssl +using +the close flag +.Fa c . +.Pp +.Fn BIO_get_ssl +retrieves the +.Vt SSL +pointer of +.Vt BIO +.Fa b ; +it can then be manipulated using the standard SSL library functions. +.Pp +.Fn BIO_set_ssl_mode +sets the +.Vt SSL +.Vt BIO +mode to +.Fa client . +If +.Fa client +is 1, client mode is set. +If +.Fa client +is 0, server mode is set. +.Pp +.Fn BIO_set_ssl_renegotiate_bytes +sets the renegotiate byte count to +.Fa num . +When set, after every +.Fa num +bytes of I/O (read and write) the SSL session is automatically renegotiated. +.Fa num +must be at least 512 bytes. +.Pp +.Fn BIO_set_ssl_renegotiate_timeout +sets the renegotiate timeout to +.Fa seconds . +When the renegotiate timeout elapses, the session is automatically renegotiated. +.Pp +.Fn BIO_get_num_renegotiates +returns the total number of session renegotiations due to I/O or timeout. +.Pp +.Fn BIO_new_ssl +allocates an +.Vt SSL +.Vt BIO +using +.Vt SSL_CTX +.Va ctx +and using client mode if +.Fa client +is nonzero. +.Pp +.Fn BIO_new_ssl_connect +creates a new +.Vt BIO +chain consisting of an +.Vt SSL +.Vt BIO +(using +.Fa ctx ) +followed by a connect BIO. +.Pp +.Fn BIO_new_buffer_ssl_connect +creates a new +.Vt BIO +chain consisting of a buffering +.Vt BIO , +an +.Vt SSL +.Vt BIO +(using +.Fa ctx ) +and a connect +.Vt BIO . +.Pp +.Fn BIO_ssl_copy_session_id +copies an SSL session id between +.Vt BIO +chains +.Fa from +and +.Fa to . +It does this by locating the +.Vt SSL +.Vt BIO Ns s +in each chain and calling +.Xr SSL_copy_session_id 3 +on the internal +.Vt SSL +pointer. +.Pp +.Fn BIO_ssl_shutdown +closes down an SSL connection on +.Vt BIO +chain +.Fa bio . +It does this by locating the +.Vt SSL +.Vt BIO +in the +chain and calling +.Xr SSL_shutdown 3 +on its internal +.Vt SSL +pointer. +.Pp +.Fn BIO_do_handshake +attempts to complete an SSL handshake on the supplied +.Vt BIO +and establish the SSL connection. +It returns 1 if the connection was established successfully. +A zero or negative value is returned if the connection could not be +established; the call +.Xr BIO_should_retry 3 +should be used for non blocking connect +.Vt BIO Ns s +to determine if the call should be retried. +If an SSL connection has already been established, this call has no effect. +.Pp +When a chain containing an SSL BIO is copied with +.Xr BIO_dup_chain 3 , +.Xr SSL_dup 3 +is called internally to copy the +.Vt SSL +object from the existing BIO object to the new BIO object, +and the internal data related to +.Fn BIO_set_ssl_renegotiate_bytes +and +.Fn BIO_set_ssl_renegotiate_timeout +is also copied. +.Pp +.Vt SSL +.Vt BIO Ns s +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 +.Xr BIO_read 3 +operation. +One case where this happens is when step up occurs. +.Pp +In OpenSSL 0.9.6 and later the SSL flag +.Dv SSL_AUTO_RETRY +can be set to disable this behaviour. +In other words, when this flag is set an +.Vt SSL +.Vt BIO +using a blocking transport will never request a retry. +.Pp +Since unknown +.Xr BIO_ctrl 3 +operations are sent through filter +.Vt BIO Ns s , +the server name and port can be set using +.Xr BIO_set_conn_hostname 3 +and +.Xr BIO_set_conn_port 3 +on the +.Vt BIO +returned by +.Fn BIO_new_ssl_connect +without having to locate the connect +.Vt BIO +first. +.Pp +Applications do not have to call +.Fn BIO_do_handshake +but may wish to do so to separate the handshake process from other I/O +processing. +.Pp +.Fn BIO_set_ssl , +.Fn BIO_get_ssl , +.Fn BIO_set_ssl_mode , +.Fn BIO_set_ssl_renegotiate_bytes , +.Fn BIO_set_ssl_renegotiate_timeout , +.Fn BIO_get_num_renegotiates , +and +.Fn BIO_do_handshake +are implemented as macros. +.Sh RETURN VALUES +.Fn BIO_f_ssl +returns a pointer to a static +.Vt BIO_METHOD +structure. +.Pp +When called on an SSL BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_SSL +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq ssl . +.Pp +.Fn BIO_set_ssl , +.Fn BIO_get_ssl , +.Fn BIO_set_ssl_mode , +.Fn BIO_set_ssl_renegotiate_bytes , +.Fn BIO_set_ssl_renegotiate_timeout , +and +.Fn BIO_get_num_renegotiates +return 1 on success or a value less than or equal to 0 +if an error occurred. +.Pp +.Fn BIO_new_ssl , +.Fn BIO_new_ssl_connect , +and +.Fn BIO_new_buffer_ssl_connect +returns a pointer to a newly allocated +.Vt BIO +chain or +.Dv NULL +if an error occurred. +.Pp +.Fn BIO_ssl_copy_session_id +returns 1 on success or 0 on error. +.Pp +.Fn BIO_do_handshake +returns 1 if the connection was established successfully +or a value less than or equal to 0 otherwise. +.Sh 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 +.Xr BIO_s_connect 3 . +.Bd -literal +BIO *sbio, *out; +int len; +char tmpbuf[1024]; +SSL_CTX *ctx; +SSL *ssl; + +ERR_load_crypto_strings(); +ERR_load_SSL_strings(); +OpenSSL_add_all_algorithms(); + +/* + * We would seed the PRNG here if the platform didn't do it automatically + */ + +ctx = SSL_CTX_new(SSLv23_client_method()); + +/* + * We'd normally set some stuff like the verify paths and mode here because + * as things stand this will connect to any server whose certificate is + * signed by any CA. + */ + +sbio = BIO_new_ssl_connect(ctx); + +BIO_get_ssl(sbio, &ssl); + +if (!ssl) { + fprintf(stderr, "Can't locate SSL pointer\en"); + /* whatever ... */ +} + +/* Don't want any retries */ +SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); + +/* We might want to do other things with ssl here */ + +BIO_set_conn_hostname(sbio, "localhost: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); + /* whatever ... */ +} + +if (BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error establishing SSL connection\en"); + ERR_print_errors_fp(stderr); + /* whatever ... */ +} + +/* 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); +.Ed +.Pp +Here is a simple server example. +It makes use of a buffering +.Vt BIO +to allow lines to be read from the +.Vt SSL +.Vt BIO +using +.Xr BIO_gets 3 . +It creates a pseudo web page containing the actual request from a client and +also echoes the request to standard output. +.Bd -literal +BIO *sbio, *bbio, *acpt, *out; +int len; +char tmpbuf[1024]; +SSL_CTX *ctx; +SSL *ssl; + +ctx = SSL_CTX_new(SSLv23_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); + return 0; +} + +/* + * Might do other things here like setting verify locations and DH and/or + * RSA temporary key callbacks + */ + +/* New SSL BIO setup as server */ +sbio = BIO_new_ssl(ctx,0); + +BIO_get_ssl(sbio, &ssl); + +if (!ssl) { + fprintf(stderr, "Can't locate SSL pointer\en"); + /* whatever ... */ +} + +/* Don't want any retries */ +SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); + +/* Create the buffering BIO */ + +bbio = BIO_new(BIO_f_buffer()); + +/* Add to chain */ +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 'swallowed' 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); + +/* Wait for incoming connection */ +if (BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error setting up accept BIO\en"); + ERR_print_errors_fp(stderr); + return 0; +} + +/* 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); + return 0; +} + +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] == '\er') || (tmpbuf[0] == '\en')) + break; +} + +BIO_puts(sbio, "--------------------------------------------------\er\en"); +BIO_puts(sbio, "\er\en"); + +/* Since there is a buffering BIO present we had better flush it */ +BIO_flush(sbio); + +BIO_free_all(sbio); +.Ed +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 +.Sh HISTORY +.Fn BIO_f_ssl , +.Fn BIO_set_ssl , +and +.Fn BIO_get_ssl +first appeared in SSLeay 0.6.0. +.Fn BIO_set_ssl_mode , +.Fn BIO_new_ssl , +and +.Fn BIO_ssl_copy_session_id +first appeared in SSLeay 0.8.0. +.Fn BIO_ssl_shutdown +and +.Fn BIO_do_handshake +first appeared in SSLeay 0.8.1. +.Fn BIO_set_ssl_renegotiate_bytes , +.Fn BIO_get_num_renegotiates , +.Fn BIO_set_ssl_renegotiate_timeout , +.Fn BIO_new_ssl_connect , +and +.Fn BIO_new_buffer_ssl_connect +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BIO_find_type.3 b/static/openbsd/man3/BIO_find_type.3 new file mode 100644 index 00000000..88f36032 --- /dev/null +++ b/static/openbsd/man3/BIO_find_type.3 @@ -0,0 +1,272 @@ +.\" $OpenBSD: BIO_find_type.3,v 1.13 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 1cb7eff4 Sep 10 13:56:40 2019 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021, 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2013, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_FIND_TYPE 3 +.Os +.Sh NAME +.Nm BIO_find_type , +.Nm BIO_next , +.Nm BIO_method_type , +.Nm BIO_method_name +.Nd BIO chain traversal +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft BIO * +.Fo BIO_find_type +.Fa "BIO *bio" +.Fa "int type" +.Fc +.Ft BIO * +.Fo BIO_next +.Fa "BIO *bio" +.Fc +.Ft int +.Fo BIO_method_type +.Fa "const BIO *bio" +.Fc +.Ft const char * +.Fo BIO_method_name +.Fa "const BIO *bio" +.Fc +.Fd #define BIO_TYPE_NONE 0 +.Fd #define BIO_TYPE_START 128 +.Sh DESCRIPTION +.Fn BIO_find_type +searches for a BIO matching the given +.Fa type +in the chain starting at +.Fa bio . +If the least significant byte of the +.Fa type +argument is non-zero, only exact matches of the +.Fa type +are accepted. +Otherwise, a match only requires that any of the bits set in the +.Fa type +argument is also set in the candidate BIO. +.Pp +Types with a least significant byte in the range from 0 to +.Dv BIO_TYPE_START , +inclusive, are reserved for BIO types built into the library. +Types with a least significant byte greater than +.Dv BIO_TYPE_START +are available for user-defined BIO types; see +.Xr BIO_get_new_index 3 +for details. +.Pp +.Fn BIO_next +returns the next BIO in the chain after +.Fa bio . +This function can be used to traverse all BIOs in a chain +or in conjunction with +.Fn BIO_find_type +to find all BIOs of a certain type. +.Pp +.Fn BIO_method_type +returns the type of the given +.Fa bio . +.Pp +.Fn BIO_method_name +returns an ASCII string representing the type of the +.Fa bio . +.Pp +The following are the built-in source/sink BIO types +that operate on file descriptors. +They all have both of the bits +.Dv BIO_TYPE_SOURCE_SINK +and +.Dv BIO_TYPE_DESCRIPTOR +but not the bit +.Dv BIO_TYPE_FILTER +set in their type constant. +.Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3) +.It Fa type No constant Ta Em name No string Ta Vt BIO_METHOD +.It Dv BIO_TYPE_ACCEPT Ta socket accept Ta Xr BIO_s_accept 3 +.It Dv BIO_TYPE_CONNECT Ta socket connect Ta Xr BIO_s_connect 3 +.It Dv BIO_TYPE_DGRAM Ta datagram socket Ta Xr BIO_s_datagram 3 +.It Dv BIO_TYPE_FD Ta file descriptor Ta Xr BIO_s_fd 3 +.It Dv BIO_TYPE_SOCKET Ta socket Ta Xr BIO_s_socket 3 +.El +.Pp +The following are the built-in source/sink BIO types +that do not directly operate on file descriptors. +They all have the bit +.Dv BIO_TYPE_SOURCE_SINK +but not the bits +.Dv BIO_TYPE_DESCRIPTOR +and +.Dv BIO_TYPE_FILTER +set in their type constant. +.Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3) +.It Fa type No constant Ta Em name No string Ta Vt BIO_METHOD +.It Dv BIO_TYPE_BIO Ta BIO pair Ta Xr BIO_s_bio 3 +.It Dv BIO_TYPE_FILE Ta FILE pointer Ta Xr BIO_s_file 3 +.It Dv BIO_TYPE_MEM Ta memory buffer Ta Xr BIO_s_mem 3 +.It Dv BIO_TYPE_NULL Ta NULL Ta Xr BIO_s_null 3 +.El +.Pp +The following are the built-in filter BIO types. +They all have the bit +.Dv BIO_TYPE_FILTER +but not the bits +.Dv BIO_TYPE_SOURCE_SINK +and +.Dv BIO_TYPE_DESCRIPTOR +set in their type constant. +.Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3) +.It Fa type No constant Ta Em name No string Ta Vt BIO_METHOD +.\" BIO_TYPE_ASN1 is intentionally undocumented because BIO_f_asn1 was +.\" removed from the public API. +.\" .It Dv BIO_TYPE_ASN1 Ta asn1 Ta Xr BIO_f_asn1 3 +.It Dv BIO_TYPE_BASE64 Ta base64 encoding Ta Xr BIO_f_base64 3 +.It Dv BIO_TYPE_BUFFER Ta buffer Ta Xr BIO_f_buffer 3 +.It Dv BIO_TYPE_CIPHER Ta cipher Ta Xr BIO_f_cipher 3 +.It Dv BIO_TYPE_MD Ta message digest Ta Xr BIO_f_md 3 +.It Dv BIO_TYPE_NULL_FILTER Ta NULL filter Ta Xr BIO_f_null 3 +.It Dv BIO_TYPE_SSL Ta ssl Ta Xr BIO_f_ssl 3 +.El +.Pp +The constants +.Dv BIO_TYPE_BER , +.Dv BIO_TYPE_PROXY_CLIENT , +and +.Dv BIO_TYPE_PROXY_SERVER +do not correspond to any BIO types implemented by the library and are +not intended to be used for application-defined types, either. +The constants +.Dv BIO_TYPE_COMP , +.Dv BIO_TYPE_LINEBUFFER , +and +.Dv BIO_TYPE_NBIO_TEST +corresponds to a deprecated BIO types that are intentionally undocumented. +.Pp +If a variable in an application program is intended +to store a BIO type but temporarily does not refer to any BIO +or refers to a BIO of an unknown type, setting the variable to +.Dv BIO_TYPE_NONE +is recommended. +.Sh RETURN VALUES +.Fn BIO_find_type +returns the next matching BIO or +.Dv NULL +if +.Fa bio +is a +.Dv NULL +pointer or if no matching BIO is found. +.Pp +.Fn BIO_next +returns the next BIO or +.Dv NULL +if +.Fa bio +is a +.Dv NULL +pointer or points to the last BIO in a chain. +.Pp +.Fn BIO_method_type +returns one of the +.Dv BIO_TYPE_* +constants. +.Pp +.Fn BIO_method_name +returns an internal pointer to a string. +.Sh EXAMPLES +Traverse a chain looking for digest BIOs: +.Bd -literal -offset 2n +BIO *btmp; + +btmp = in_bio; /* in_bio is the chain to search through */ +while (btmp != NULL) { + 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); +} +.Ed +.Sh SEE ALSO +.Xr BIO_meth_new 3 , +.Xr BIO_new 3 +.Sh HISTORY +.Fn BIO_method_type +and +.Fn BIO_method_name +first appeared in SSLeay 0.6.0. +.Fn BIO_find_type +first appeared in SSLeay 0.6.6. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_next +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . diff --git a/static/openbsd/man3/BIO_get_data.3 b/static/openbsd/man3/BIO_get_data.3 new file mode 100644 index 00000000..26783929 --- /dev/null +++ b/static/openbsd/man3/BIO_get_data.3 @@ -0,0 +1,407 @@ +.\" $OpenBSD: BIO_get_data.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2022 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. +.\" +.\" The original file was written by Matt Caswell . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_GET_DATA 3 +.Os +.Sh NAME +.Nm BIO_set_data , +.Nm BIO_get_data , +.Nm BIO_set_flags , +.Nm BIO_clear_flags , +.Nm BIO_test_flags , +.Nm BIO_get_flags , +.Nm BIO_set_retry_read , +.Nm BIO_set_retry_write , +.Nm BIO_set_retry_special , +.Nm BIO_clear_retry_flags , +.Nm BIO_get_retry_flags , +.Nm BIO_copy_next_retry , +.Nm BIO_set_init , +.Nm BIO_get_init , +.Nm BIO_set_shutdown , +.Nm BIO_get_shutdown +.Nd manage BIO state information +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft void +.Fo BIO_set_data +.Fa "BIO *a" +.Fa "void *ptr" +.Fc +.Ft void * +.Fo BIO_get_data +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_set_flags +.Fa "BIO *a" +.Fa "int flags" +.Fc +.Ft void +.Fo BIO_clear_flags +.Fa "BIO *a" +.Fa "int flags" +.Fc +.Ft int +.Fo BIO_test_flags +.Fa "const BIO *a" +.Fa "int flags" +.Fc +.Ft int +.Fo BIO_get_flags +.Fa "const BIO *a" +.Fc +.Ft void +.Fo BIO_set_retry_read +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_set_retry_write +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_set_retry_special +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_clear_retry_flags +.Fa "BIO *a" +.Fc +.Ft int +.Fo BIO_get_retry_flags +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_copy_next_retry +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_set_init +.Fa "BIO *a" +.Fa "int init" +.Fc +.Ft int +.Fo BIO_get_init +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_set_shutdown +.Fa "BIO *a" +.Fa "int shutdown" +.Fc +.Ft int +.Fo BIO_get_shutdown +.Fa "BIO *a" +.Fc +.Sh DESCRIPTION +These functions are mainly useful when implementing a custom BIO. +.Pp +The +.Fn BIO_set_data +function associates the custom data pointed to by +.Fa ptr +with the +.Fa "BIO a" . +This data can subsequently be retrieved via a call to +.Fn BIO_get_data . +This can be used by custom BIOs for storing implementation specific +information. +.Pp +.Fn BIO_set_flags +sets all the bits contained in the +.Fa flags +argument in the flags stored in +.Fa a . +The value of a flag neither changes when it is already set in +.Fa a +nor when it is unset in the +.Fa flags +argument. +.Pp +.Fn BIO_clear_flags +clears all the bits contained in the +.Fa flags +argument from the flags stored in +.Fa a . +The value of a flag neither changes when it is already unset in +.Fa a +nor when it is unset in the +.Fa flags +argument. +.Pp +.Fn BIO_test_flags +checks whether any of the bits contained in the +.Fa flags +argument are set in the flags stored in +.Fa a . +Application programs usually call macros like those documented in +.Xr BIO_should_retry 3 +rather than calling +.Fn BIO_test_flags +directly. +Flag bits correspond to accessor macros as follows: +.Pp +.Bl -tag -width BIO_FLAGS_SHOULD_RETRY -compact +.It Dv BIO_FLAGS_READ +.Xr BIO_should_read 3 +.It Dv BIO_FLAGS_WRITE +.Xr BIO_should_write 3 +.It Dv BIO_FLAGS_IO_SPECIAL +.Xr BIO_should_io_special 3 +.It Dv BIO_FLAGS_RWS +.Xr BIO_retry_type 3 +.It Dv BIO_FLAGS_SHOULD_RETRY +.Xr BIO_should_retry 3 +.It Dv BIO_FLAGS_BASE64_NO_NL +see +.Xr BIO_f_base64 3 +.It Dv BIO_FLAGS_MEM_RDONLY +see +.Xr BIO_s_mem 3 +.El +.Pp +In particular, +.Dv BIO_FLAGS_RWS +is the bitwise OR of +.Dv BIO_FLAGS_READ , +.Dv BIO_FLAGS_WRITE , +and +.Dv BIO_FLAGS_IO_SPECIAL . +.Pp +.Fn BIO_set_retry_read , +.Fn BIO_set_retry_write , +and +.Fn BIO_set_retry_special +set the +.Dv BIO_FLAGS_READ , +.Dv BIO_FLAGS_WRITE , +and +.Dv BIO_FLAGS_IO_SPECIAL +flag bit in +.Fa a , +respectively. +They all set the +.Dv BIO_FLAGS_SHOULD_RETRY +flag bit, too. +.Pp +.Fn BIO_clear_retry_flags +clears the flag bits +.Dv BIO_FLAGS_READ , +.Dv BIO_FLAGS_WRITE , +.Dv BIO_FLAGS_IO_SPECIAL , +and +.Dv BIO_FLAGS_SHOULD_RETRY +in +.Fa a . +.Pp +.Fn BIO_copy_next_retry +copies retry-related state data from the BIO that follows +.Fa a +in its chain to +.Fa a , +that is, the data accessible with +.Fn BIO_get_retry_flags +and +.Xr BIO_get_retry_reason 3 . +Flags which are already set in +.Fa a +are not cleared. +Before calling +.Fn BIO_copy_next_retry , +making sure that +.Fa a +is not the last BIO in its chain is the responsibility of the caller, +for example by checking that +.Xr BIO_next 3 +does not return +.Dv NULL . +.Pp +The +.Fn BIO_set_init +function sets the +.Fa init +flag in +.Fa a +to the specified value. +A non-zero 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 be complete until +additional steps have been taken, for example through calling custom +ctrls. +.Pp +The +.Fn BIO_set_shutdown +and +.Fn BIO_get_shutdown +functions are low-level interfaces to forcefully set and get the +.Fa shutdown +flag of +.Fa a , +circumventing type-dependent sanity checks, +exclusively intended for implementing a new BIO type. +The +.Fa shutdown +argument must be either +.Dv BIO_CLOSE +or +.Dv BIO_NOCLOSE . +When merely using a +.Vt BIO +object, call +.Xr BIO_set_close 3 +and +.Xr BIO_get_close 3 +instead. +.Pp +.Fn BIO_get_flags , +.Fn BIO_set_retry_read , +.Fn BIO_set_retry_write , +.Fn BIO_set_retry_special , +.Fn BIO_clear_retry_flags , +and +.Fn BIO_get_retry_flags +are implemented as macros. +.Sh RETURN VALUES +.Fn BIO_get_data +returns a pointer to the implementation specific custom data associated +with +.Fa a , +or +.Dv NULL +if none is set. +.Pp +.Fn BIO_test_flags +returns the bitwise AND of the +.Fa flags +argument and the flags stored in +.Fa a . +Consequently, it returns a non-zero value +if and only if at least one of the requested +.Fa flags +is set. +.Pp +.Fn BIO_get_flags +returns all the flags currently stored in +.Fa a . +.Pp +.Fn BIO_get_retry_flags +returns the bitwise AND of +.Pq Dv BIO_FLAGS_RWS | BIO_FLAGS_SHOULD_RETRY +and the flags stored in +.Fa a . +.Pp +.Fn BIO_get_init +returns the value of the init flag of +.Fa a . +.Pp +.Fn BIO_get_shutdown +returns the value previously set with +.Fn BIO_set_shutdown +or with +.Xr BIO_set_close 3 . +.Sh SEE ALSO +.Xr BIO_meth_new 3 , +.Xr BIO_new 3 , +.Xr BIO_set_close 3 , +.Xr BIO_should_retry 3 +.Sh HISTORY +.Fn BIO_set_flags , +.Fn BIO_clear_flags , +.Fn BIO_set_retry_read , +.Fn BIO_set_retry_write , +.Fn BIO_set_retry_special , +.Fn BIO_clear_retry_flags , +and +.Fn BIO_get_retry_flags +first appeared in SSLeay 0.8.0, +.Fn BIO_copy_next_retry +in SSLeay 0.8.1, and +.Fn BIO_get_flags +in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_test_flags +first appeared in OpenSSL 0.9.8e and has been available since +.Ox 4.5 . +.Pp +.Fn BIO_set_data , +.Fn BIO_get_data , +.Fn BIO_set_init , +.Fn BIO_set_shutdown , +and +.Fn BIO_get_shutdown +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +.Pp +.Fn BIO_get_init +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/BIO_get_ex_new_index.3 b/static/openbsd/man3/BIO_get_ex_new_index.3 new file mode 100644 index 00000000..13d20e14 --- /dev/null +++ b/static/openbsd/man3/BIO_get_ex_new_index.3 @@ -0,0 +1,199 @@ +.\" $OpenBSD: BIO_get_ex_new_index.3,v 1.18 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Rich Salz . +.\" Copyright (c) 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm BIO_get_ex_new_index , +.Nm BIO_set_ex_data , +.Nm BIO_get_ex_data , +.Nm BIO_set_app_data , +.Nm BIO_get_app_data , +.Nm UI_get_ex_new_index , +.Nm UI_set_ex_data , +.Nm UI_get_ex_data , +.Nm X509_get_ex_new_index , +.Nm X509_set_ex_data , +.Nm X509_get_ex_data , +.Nm EC_KEY_get_ex_new_index , +.Nm EC_KEY_get_ex_data , +.Nm EC_KEY_set_ex_data +.Nd application-specific data +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.In openssl/ui.h +.In openssl/x509.h +.In openssl/ec.h +.Ft int +.Fo TYPE_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo TYPE_set_ex_data +.Fa "TYPE *d" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft void * +.Fo TYPE_get_ex_data +.Fa "TYPE *d" +.Fa "int idx" +.Fc +.Ft int +.Fo TYPE_set_app_data +.Fa "TYPE *d" +.Fa "void *arg" +.Fc +.Ft void * +.Fo TYPE_get_app_data +.Fa "TYPE *d" +.Fc +.Sh DESCRIPTION +In the description here, +.Vt TYPE +is used a placeholder for any of the OpenSSL datatypes listed in +.Xr CRYPTO_get_ex_new_index 3 . +.Pp +These functions handle application-specific data in OpenSSL data +structures. +Their usage is identical to that of +.Xr RSA_get_ex_new_index 3 , +.Xr RSA_set_ex_data 3 , +and +.Xr RSA_get_ex_data 3 . +.Pp +.Fn TYPE_get_ex_new_index +is a macro that calls +.Xr CRYPTO_get_ex_new_index 3 +with the correct index value. +.Pp +.Fn TYPE_set_ex_data +is a function that calls +.Xr CRYPTO_set_ex_data 3 +with an offset into the opaque ex_data part of the +.Vt TYPE +object. +.Pp +.Fn TYPE_get_ex_data +is a function that calls +.Xr CRYPTO_get_ex_data 3 +with an offset into the opaque ex_data part of the +.Vt TYPE +object. +.Pp +.Fn TYPE_set_app_data +and +.Fn TYPE_get_app_data +are deprecated wrapper macros that call +.Fn TYPE_set_ex_data +and +.Fn TYPE_get_ex_data +with +.Fa idx +set to 0. +.Sh RETURN VALUES +.Fn TYPE_get_new_ex_index +returns a new index on success or \-1 on error. +.Pp +.Fn TYPE_set_ex_data +and +.Fn TYPE_set_app_data +return 1 on success or 0 on error. +.Pp +.Fn TYPE_get_ex_data +and +.Fn TYPE_get_app_data +return the application data or +.Dv NULL +if an error occurred. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr CRYPTO_get_ex_new_index 3 , +.Xr RSA_get_ex_new_index 3 , +.Xr X509_new 3 +.Sh HISTORY +.Fn BIO_set_app_data +and +.Fn BIO_get_app_data +first appeared in SSLeay 0.8.1. +.Fn BIO_get_ex_new_index , +.Fn BIO_set_ex_data , +and +.Fn BIO_get_ex_data +first appeared in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_get_ex_new_index , +.Fn X509_set_ex_data , +and +.Fn X509_get_ex_data +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn UI_get_ex_new_index , +.Fn UI_set_ex_data , +and +.Fn UI_get_ex_data +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EC_KEY_get_ex_new_index , +.Fn EC_KEY_set_ex_data , +and +.Fn EC_KEY_get_ex_data +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.5 . diff --git a/static/openbsd/man3/BIO_meth_new.3 b/static/openbsd/man3/BIO_meth_new.3 new file mode 100644 index 00000000..98feac5b --- /dev/null +++ b/static/openbsd/man3/BIO_meth_new.3 @@ -0,0 +1,368 @@ +.\" $OpenBSD: BIO_meth_new.3,v 1.6 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018 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. +.\" +.\" The original file was written by Matt Caswell +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_METH_NEW 3 +.Os +.Sh NAME +.Nm BIO_get_new_index , +.Nm BIO_meth_new , +.Nm BIO_meth_free , +.Nm BIO_meth_get_write , +.Nm BIO_meth_set_write , +.Nm BIO_meth_get_read , +.Nm BIO_meth_set_read , +.Nm BIO_meth_get_puts , +.Nm BIO_meth_set_puts , +.Nm BIO_meth_get_gets , +.Nm BIO_meth_set_gets , +.Nm BIO_meth_get_ctrl , +.Nm BIO_meth_set_ctrl , +.Nm BIO_meth_get_create , +.Nm BIO_meth_set_create , +.Nm BIO_meth_get_destroy , +.Nm BIO_meth_set_destroy , +.Nm BIO_meth_get_callback_ctrl , +.Nm BIO_meth_set_callback_ctrl +.Nd manipulate BIO_METHOD structures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft int +.Fn BIO_get_new_index void +.Ft BIO_METHOD * +.Fo BIO_meth_new +.Fa "int type" +.Fa "const char *name" +.Fc +.Ft void +.Fo BIO_meth_free +.Fa "BIO_METHOD *biom" +.Fc +.Ft int +.Fn "(*BIO_meth_get_write(const BIO_METHOD *biom))" "BIO *" "const char *" int +.Ft int +.Fo BIO_meth_set_write +.Fa "BIO_METHOD *biom" +.Fa "int (*write)(BIO *, const char *, int)" +.Fc +.Ft int +.Fn "(*BIO_meth_get_read(const BIO_METHOD *biom))" "BIO *" "char *" int +.Ft int +.Fo BIO_meth_set_read +.Fa "BIO_METHOD *biom" +.Fa "int (*read)(BIO *, char *, int)" +.Fc +.Ft int +.Fn "(*BIO_meth_get_puts(const BIO_METHOD *biom))" "BIO *" "const char *" +.Ft int +.Fo BIO_meth_set_puts +.Fa "BIO_METHOD *biom" +.Fa "int (*puts)(BIO *, const char *)" +.Fc +.Ft int +.Fn "(*BIO_meth_get_gets(const BIO_METHOD *biom))" "BIO *" "char *" int +.Ft int +.Fo BIO_meth_set_gets +.Fa "BIO_METHOD *biom" +.Fa "int (*gets)(BIO *, char *, int)" +.Fc +.Ft long +.Fn "(*BIO_meth_get_ctrl(const BIO_METHOD *biom))" "BIO *" int long "void *" +.Ft int +.Fo BIO_meth_set_ctrl +.Fa "BIO_METHOD *biom" +.Fa "long (*ctrl)(BIO *, int, long, void *)" +.Fc +.Ft int +.Fn "(*BIO_meth_get_create(const BIO_METHOD *biom))" "BIO *" +.Ft int +.Fo BIO_meth_set_create +.Fa "BIO_METHOD *biom" +.Fa "int (*create)(BIO *)" +.Fc +.Ft int +.Fn "(*BIO_meth_get_destroy(const BIO_METHOD *biom))" "BIO *" +.Ft int +.Fo BIO_meth_set_destroy +.Fa "BIO_METHOD *biom" +.Fa "int (*destroy)(BIO *)" +.Fc +.Ft long +.Fo "(*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))" +.Fa "BIO *" +.Fa int +.Fa "BIO_info_cb *" +.Fc +.Ft int +.Fo BIO_meth_set_callback_ctrl +.Fa "BIO_METHOD *biom" +.Fa "long (*callback_ctrl)(BIO *, int, BIO_info_cb *)" +.Fc +.Sh DESCRIPTION +The +.Vt BIO_METHOD +structure stores function pointers implementing a +.Vt BIO +type. +See +.Xr BIO_new 3 +for more information about +.Vt BIO +objects. +.Pp +.Fn BIO_meth_new +creates a new +.Vt BIO_METHOD +structure. +It requires a unique integer +.Fa type ; +use +.Fn BIO_get_new_index +to get the value for +.Fa type . +Currently, the user can only create up to 127 different BIO types, and +.Fa type +is limited to the range 129\(en255. +The +.Fa name +pointer is stored in the structure and will not be freed by +.Fn BIO_meth_free . +.Pp +The standard BIO types are listed in +.In openssl/bio.h . +Some examples include +.Dv BIO_TYPE_BUFFER +and +.Dv BIO_TYPE_CIPHER . +The +.Fa type +of filter BIOs should have the +.Dv BIO_TYPE_FILTER +bit set. +Source/sink BIOs should have the +.Dv BIO_TYPE_SOURCE_SINK +bit set. +File descriptor based BIOs (e.g. socket, fd, connect, accept etc.\&) +should additionally have the +.Dv BIO_TYPE_DESCRIPTOR +bit set. +See +.Xr BIO_find_type 3 +for more information. +.Pp +.Fn BIO_meth_free +is an alias for +.Xr free 3 . +.Pp +.Fn BIO_meth_get_write , +.Fn BIO_meth_set_write , +.Fn BIO_meth_get_read , +and +.Fn BIO_meth_set_read +get and set the functions +.Fa write +and +.Fa read +used for writing and reading arbitrary length data to and from the +.Vt BIO . +These functions are called from +.Xr BIO_write 3 +and +.Xr BIO_read 3 , +respectively. +The parameters and return values of +.Fa write +and +.Fa read +have the same meaning as for +.Xr BIO_write 3 +and +.Xr BIO_read 3 . +.Pp +.Fn BIO_meth_get_puts +and +.Fn BIO_meth_set_puts +get and set the function +.Fa puts +used for writing a NUL-terminated string to the +.Vt BIO . +This function is called from +.Xr BIO_puts 3 . +The parameters and the return value of +.Fa puts +have the same meaning as for +.Xr BIO_puts 3 . +.Pp +.Fn BIO_meth_get_gets +and +.Fn BIO_meth_set_gets +get and set the function +.Fa gets +used for reading a line of data from the +.Vt BIO . +This function is called from +.Xr BIO_gets 3 . +The parameters and the return value of +.Fa gets +have the same meaning as for +.Xr BIO_gets 3 . +.Pp +.Fn BIO_meth_get_ctrl +and +.Fn BIO_meth_set_ctrl +get and set the function +.Fa ctrl +used for processing control messages in the +.Vt BIO . +This function is called from +.Xr BIO_ctrl 3 . +The parameters and return value of +.Fa ctrl +have the same meaning as for +.Xr BIO_ctrl 3 . +.Pp +.Fn BIO_meth_get_create +and +.Fn BIO_meth_set_create +get and set a function +.Fa create +used while initializing a new instance of the +.Vt BIO . +This function is called from +.Xr BIO_new 3 . +The +.Xr BIO_new 3 +function allocates the memory for the new +.Vt BIO , +and a pointer to this newly allocated structure is passed +as the parameter to +.Fa create . +.Pp +.Fn BIO_meth_get_destroy +and +.Fn BIO_meth_set_destroy +get and set a function +.Fa destroy +used while destroying an instance of a +.Vt BIO . +This function is called from +.Xr BIO_free 3 . +A pointer to the +.Vt BIO +to be destroyed is passed as the parameter. +The +.Fa destroy +function is intended to perform clean-up specific to the +.Vt BIO +.Fa type . +The memory for the +.Vt BIO +itself must not be freed by this function. +.Pp +.Fn BIO_meth_get_callback_ctrl +and +.Fn BIO_meth_set_callback_ctrl +get and set the function +.Fa callback_ctrl +used for processing callback control messages in the +.Vt BIO . +This function is called from +.Xr BIO_callback_ctrl 3 . +The parameters and return value of +.Fa callback_ctrl +have the same meaning as for +.Xr BIO_callback_ctrl 3 . +.Sh RETURN VALUES +.Fn BIO_get_new_index +returns the new BIO type value or \-1 if an error occurs. +.Pp +.Fn BIO_meth_new +returns the new +.Vt BIO_METHOD +structure or +.Dv NULL +if an error occurs. +.Pp +The +.Fn BIO_meth_set_* +functions return 1 on success or 0 on error. +Currently, they cannot fail. +.Pp +The +.Fn BIO_meth_get_* +functions return function pointers. +.Sh SEE ALSO +.Xr BIO_ctrl 3 , +.Xr BIO_find_type 3 , +.Xr BIO_new 3 , +.Xr BIO_read 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/BIO_new.3 b/static/openbsd/man3/BIO_new.3 new file mode 100644 index 00000000..f0079948 --- /dev/null +++ b/static/openbsd/man3/BIO_new.3 @@ -0,0 +1,280 @@ +.\" $OpenBSD: BIO_new.3,v 1.29 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL man3/BIO_new.pod fb46be03 Feb 26 11:51:31 2016 +0000 +.\" OpenSSL man7/bio.pod 631c37be Dec 12 16:56:50 2017 +0100 +.\" partial merge up to: +.\" OpenSSL man3/BIO_new.pod e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_NEW 3 +.Os +.Sh NAME +.Nm BIO_new , +.Nm BIO_up_ref , +.Nm BIO_set , +.Nm BIO_free , +.Nm BIO_vfree , +.Nm BIO_free_all +.Nd construct and destruct I/O abstraction objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft BIO * +.Fo BIO_new +.Fa "const BIO_METHOD *type" +.Fc +.Ft int +.Fo BIO_up_ref +.Fa "BIO *a" +.Fc +.Ft int +.Fo BIO_set +.Fa "BIO *a" +.Fa "const BIO_METHOD *type" +.Fc +.Ft int +.Fo BIO_free +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_vfree +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_free_all +.Fa "BIO *a" +.Fc +.Sh DESCRIPTION +A +.Vt BIO +is an I/O abstraction object, hiding many of the underlying I/O +details from an application. +If an application uses BIOs for its I/O, it can transparently handle +SSL connections, unencrypted network connections, and file I/O. +.Pp +The +.Fn BIO_new +function constructs a new +.Vt BIO +using the method +.Fa type +and sets its reference count to 1. +There are two groups of BIO types, source/sink BIOs and filter BIOs. +.Pp +Source/sink BIOs provide input or consume output. +Examples include socket BIOs and file BIOs. +.Pp +Filter BIOs take data from one BIO and pass it through to another, +or to the application, forming a chain of BIOs. +The data may be left unmodified (for example by a message digest BIO) +or translated (for example by an encryption BIO). +The effect of a filter BIO may change according to the I/O operation +it is performing: for example an encryption BIO encrypts data +if it is written to and decrypts data if it is read from. +.Pp +Some BIOs (such as memory BIOs) can be used immediately after calling +.Fn BIO_new . +Others (such as file BIOs) need some additional initialization, and +utility functions exists to construct and initialize such BIOs. +.Pp +Normally the +.Fa type +argument is supplied by a function which returns a pointer to a +.Vt BIO_METHOD . +There is a naming convention for such functions: +the methods for source/sink BIOs are called +.Fn BIO_s_* +and those for filter BIOs +.Fn BIO_f_* . +.Pp +.Fn BIO_up_ref +increments the reference count of +.Fa a +by 1. +.Pp +.Fn BIO_set +is a deprecated function to initialize an unused +.Vt BIO +structure located in static memory or on the stack, +to set its method to +.Fa type , +and to set its reference count to 1. +It must not be called on +.Vt BIO +objects created with +.Fn BIO_new , +nor on objects that were already used. +.Pp +.Fn BIO_free +and +.Fn BIO_vfree +decrement the reference count of +.Fa a +by 1, and if the reference count reaches 0, they destruct the single +.Vt BIO +.Fa a , +which may also have some effect on the +underlying I/O structure, for example it may close the file being +referred to under certain circumstances. +If +.Fa a +is a +.Dv NULL +pointer, no action occurs. +If +.Fn BIO_free +is called on a BIO chain, it destructs at most one BIO, +resulting in a memory leak. +.Pp +.Fn BIO_free_all +calls +.Fn BIO_free +on +.Fa a +and on all following +.Vt BIO +objects in the chain. +As soon as the reference count of a +.Vt BIO +is still non-zero after calling +.Fn BIO_free +on it, the function +.Fn BIO_free_all +returns right away and refrains from freeing the remaining +.Vt BIO +objects in the chain. +It does not halt if an error occurs +destructing an individual BIO in the chain. +If +.Fa a +is a +.Dv NULL +pointer, no action occurs. +Calling +.Fn BIO_free_all +on a single BIO has the same effect as +.Fn BIO_vfree . +.Pp +Common I/O functions are documented in +.Xr BIO_read 3 . +Forming chains is explained in +.Xr BIO_push 3 ; +inspecting them is explained in +.Xr BIO_find_type 3 . +For more details about the different kinds of BIOs, see the individual +.Vt BIO_METHOD +manual pages. +.Sh RETURN VALUES +.Fn BIO_new +returns a newly constructed +.Vt BIO +object or +.Dv NULL +on failure. +.Pp +.Fn BIO_up_ref , +.Fn BIO_set , +and +.Fn BIO_free +return 1 for success or 0 for failure. +.Sh EXAMPLES +Create a memory BIO: +.Pp +.Dl BIO *mem = BIO_new(BIO_s_mem()); +.Sh SEE ALSO +.Xr BIO_accept 3 , +.Xr BIO_ctrl 3 , +.Xr BIO_dump 3 , +.Xr BIO_dup_chain 3 , +.Xr BIO_f_base64 3 , +.Xr BIO_f_buffer 3 , +.Xr BIO_f_cipher 3 , +.Xr BIO_f_md 3 , +.Xr BIO_f_null 3 , +.Xr BIO_f_ssl 3 , +.Xr BIO_find_type 3 , +.Xr BIO_get_ex_new_index 3 , +.Xr BIO_meth_new 3 , +.Xr BIO_new_CMS 3 , +.Xr BIO_printf 3 , +.Xr BIO_push 3 , +.Xr BIO_read 3 , +.Xr BIO_s_accept 3 , +.Xr BIO_s_bio 3 , +.Xr BIO_s_connect 3 , +.Xr BIO_s_datagram 3 , +.Xr BIO_s_fd 3 , +.Xr BIO_s_file 3 , +.Xr BIO_s_mem 3 , +.Xr BIO_s_null 3 , +.Xr BIO_s_socket 3 , +.Xr BIO_set_callback 3 , +.Xr BIO_set_data 3 , +.Xr BIO_should_retry 3 , +.Xr BUF_MEM_new 3 , +.Xr crypto 3 +.Sh HISTORY +.Fn BIO_new , +.Fn BIO_set , +and +.Fn BIO_free +first appeared in SSLeay 0.6.0. +.Fn BIO_free_all +first appeared in SSLeay 0.6.6. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_vfree +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Pp +.Fn BIO_up_ref +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/BIO_new_CMS.3 b/static/openbsd/man3/BIO_new_CMS.3 new file mode 100644 index 00000000..0279f704 --- /dev/null +++ b/static/openbsd/man3/BIO_new_CMS.3 @@ -0,0 +1,142 @@ +.\" $OpenBSD: BIO_new_CMS.3,v 1.10 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bfc Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_NEW_CMS 3 +.Os +.Sh NAME +.Nm BIO_new_CMS +.Nd CMS streaming filter BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft BIO * +.Fo BIO_new_CMS +.Fa "BIO *out" +.Fa "CMS_ContentInfo *cms" +.Fc +.Sh DESCRIPTION +.Fn BIO_new_CMS +returns a streaming filter +.Vt BIO +chain based on +.Fa cms . +The output of the filter is written to +.Fa out . +Any data written to the chain is automatically translated +to a BER format CMS structure of the appropriate type. +.Pp +The chain returned by this function behaves like a standard filter +.Vt 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, +.Xr BIO_flush 3 +must be called to finalise the structure. +.Pp +The +.Dv CMS_STREAM +flag must be included in the corresponding +.Fa flags +parameter of the +.Fa cms +creation function. +.Pp +If an application wishes to write additional data to +.Fa out , +BIOs should be removed from the chain using +.Xr BIO_pop 3 +and freed with +.Xr BIO_free 3 +until +.Fa out +is reached. +If no additional data needs to be written, +.Xr BIO_free_all 3 +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 application's responsibility +to set the inner content type of any outer +.Vt 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 +.Xr BIO_f_buffer 3 +buffering BIO will prevent this. +.Sh RETURN VALUES +.Fn BIO_new_CMS +returns a +.Vt BIO +chain when successful or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_encrypt 3 , +.Xr CMS_sign 3 +.Sh HISTORY +.Fn BIO_new_CMS +first appeared in OpenSSL 1.0.0 +and has been available since +.Ox 6.7 . +.Sh BUGS +There is currently no corresponding inverse BIO +which can decode a CMS structure on the fly. diff --git a/static/openbsd/man3/BIO_printf.3 b/static/openbsd/man3/BIO_printf.3 new file mode 100644 index 00000000..6df31ad2 --- /dev/null +++ b/static/openbsd/man3/BIO_printf.3 @@ -0,0 +1,47 @@ +.\" $OpenBSD: BIO_printf.3,v 1.5 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL 2ca2e917 Mon Mar 20 16:25:22 2017 -0400 +.\" +.\" Copyright (c) 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 $Mdocdate: June 8 2025 $ +.Dt BIO_PRINTF 3 +.Os +.Sh NAME +.Nm BIO_printf +.Nd formatted output to a BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft int +.Fo BIO_printf +.Fa "BIO *bio" +.Fa "const char *format" +.Fa ... +.Fc +.Sh DESCRIPTION +.Fn BIO_printf +is a wrapper around +.Xr vfprintf 3 , +sending the output to the specified +.Fa bio . +.Sh RETURN VALUES +These functions return the number of bytes written, +or -1 if an error occurs. +.Sh SEE ALSO +.Xr BIO_new 3 +.Sh HISTORY +.Fn BIO_printf +first appeared in SSLeay 0.6.5 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BIO_push.3 b/static/openbsd/man3/BIO_push.3 new file mode 100644 index 00000000..21b798a5 --- /dev/null +++ b/static/openbsd/man3/BIO_push.3 @@ -0,0 +1,336 @@ +.\" $OpenBSD: BIO_push.3,v 1.15 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL doc/man3/BIO_push.pod 791bfd91 Nov 19 20:38:27 2021 +0100 +.\" OpenSSL doc/man7/bio.pod 1cb7eff4 Sep 10 13:56:40 2019 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_PUSH 3 +.Os +.Sh NAME +.Nm BIO_push , +.Nm BIO_pop , +.Nm BIO_set_next +.Nd manipulate BIO chains +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft BIO * +.Fo BIO_push +.Fa "BIO *b" +.Fa "BIO *new_tail" +.Fc +.Ft BIO * +.Fo BIO_pop +.Fa "BIO *b" +.Fc +.Ft void +.Fo BIO_set_next +.Fa "BIO *b" +.Fa "BIO *new_tail" +.Fc +.Sh DESCRIPTION +BIOs can be joined together to form chains. +A chain normally consists of one or more filter BIOs +and one source/sink BIO at the end. +Data read from or written to the first BIO traverses the chain +to the end. +.Pp +Every BIO is a member of exactly one chain. +It is either at the beginning of its chain +or there is exactly one preceding BIO. +It is either at the end of its chain +or there is exactly one following BIO. +If there is neither a preceding nor a following BIO, +it can be regarded as a chain with one member. +Every chain has exactly one beginning and exactly one end. +.Pp +.Fn BIO_push +appends the chain starting at +.Fa new_tail +to the end of the chain that contains +.Fa b . +Unless +.Fa b +is +.Dv NULL , +it then calls +.Xr BIO_ctrl 3 +on +.Fa b +with an argument of +.Dv BIO_CTRL_PUSH . +If +.Fa b +or +.Fa new_tail +is +.Dv NULL , +nothing is appended. +.Pp +In LibreSSL, if +.Fa new_tail +is not at the beginning of its chain, +the head of that chain up to but not including +.Fa new_tail +is cut off and becomes a separate chain. +For portability, it is best to make sure that +.Fa new_tail +is at the beginning of its chain before calling +.Fn BIO_push . +.Pp +.Fn BIO_pop +removes the BIO +.Fa b +from its chain. +Despite the word +.Dq pop +in the function name, +.Fa b +can be at the beginning, in the middle, or at the end of its chain. +Before removal, +.Xr BIO_ctrl 3 +is called on +.Fa b +with an argument of +.Dv BIO_CTRL_POP . +The removed BIO +.Fa b +becomes the only member of its own chain and can thus be freed +or attached to a different chain. +If +.Fa b +is +.Dv NULL , +no action occurs. +.Pp +.Fn BIO_set_next +appends the chain starting with +.Fa new_tail +to the chain ending with +.Fa b . +.Pp +In LibreSSL, if +.Fa new_tail +is not at the beginning of its chain, +the head of that chain up to but not including +.Fa new_tail +is cut off and becomes a separate chain, +and if +.Fa b +is not at the end of its chain, +the tail of that chain starting after +.Fa b +is cut off and becomes a separate chain. +.Pp +For portability, it is best to make sure that +.Fa b +is at the end of its chain and that +.Fa new_tail +is at the beginning of its chain before calling +.Fn BIO_set_next +and to avoid calling +.Fn BIO_pop +on +.Fa new_tail +afterwards. +.Pp +In LibreSSL, the only built-in BIO type for which +.Xr BIO_ctrl 3 +calls with an argument of +.Dv BIO_CTRL_PUSH +or +.Dv BIO_CTRL_POP +have any effect is +.Xr BIO_f_ssl 3 . +.Sh RETURN VALUES +.Fn BIO_push +returns +.Fa b +if it is not +.Dv NULL +or +.Fa new_tail +if it is. +.Pp +.Fn BIO_pop +returns the BIO that followed +.Fa b +in its chain, or +.Dv NULL +if +.Fa b +is +.Dv NULL +or was at the end of its chain. +.Sh EXAMPLES +For these examples suppose +.Sy md1 +and +.Sy md2 +are digest BIOs, +.Sy b64 +is a Base64 BIO and +.Sy f +is a file BIO (see +.Xr BIO_f_md 3 , +.Xr BIO_f_base64 3 , +and +.Xr BIO_s_file 3 , +respectively). +.Pp +If the call +.Pp +.Dl BIO_push(b64, f); +.Pp +is made then the new chain will be +.Sy b64-f . +After making the calls +.Bd -literal -offset indent +BIO_push(md2, b64); +BIO_push(md1, md2); +.Ed +.Pp +the new chain is +.Sy md1-md2-b64-f . +Data written to +.Sy md1 +will be digested +by +.Sy md1 +and +.Sy md2 , +Base64-encoded and written to +.Sy f . +.Pp +It should be noted that reading causes data to pass +in the reverse direction. +That is, data is read from +.Sy f , +Base64-decoded and digested by +.Sy md1 +and +.Sy md2 . +If this call is made: +.Pp +.Dl BIO_pop(md2); +.Pp +The call will return +.Sy b64 +and the new chain will be +.Sy md1-b64-f ; +data can be written to +.Sy md1 +as before. +.Sh SEE ALSO +.Xr BIO_find_type 3 , +.Xr BIO_new 3 , +.Xr BIO_read 3 +.Sh HISTORY +.Fn BIO_push +first appeared in SSLeay 0.6.0. +.Fn BIO_pop +first appeared in SSLeay 0.6.4. +Both functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_set_next +first appeared in OpenSSL 1.1.0 +and has been available since +.Ox 7.1 . +.Sh CAVEATS +Creating a cyclic chain results in undefined behavior. +For example, infinite recursion or infinite loops may ensue. +.Pp +If it is unknown whether +.Fa b +and +.Fa new_tail +are already members of the same chain and whether joining them would +create a cycle, the calling code can use the following safe idiom: +.Bd -literal -offset indent +BIO *btest; + +for (btest = new_tail; btest != NULL; btest = BIO_next(btest)) + if (btest == b) + /* Bail out because this would create a cycle. */ +BIO_push(b, new_tail); /* This is now safe. */ +.Ed +.Pp +The same idiom can be used with +.Fn BIO_set_next +instead of +.Fn BIO_push . +.Pp +Often, the safe idiom is not needed because it is already known that +.Fa b +and +.Fa new_tail +are not members of the same chain, for example when +.Fa b +or +.Fa new_tail +was created right before. diff --git a/static/openbsd/man3/BIO_read.3 b/static/openbsd/man3/BIO_read.3 new file mode 100644 index 00000000..2a65b185 --- /dev/null +++ b/static/openbsd/man3/BIO_read.3 @@ -0,0 +1,282 @@ +.\" $OpenBSD: BIO_read.3,v 1.12 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021, 2022 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_READ 3 +.Os +.Sh NAME +.Nm BIO_read , +.Nm BIO_number_read , +.Nm BIO_gets , +.Nm BIO_write , +.Nm BIO_puts , +.Nm BIO_indent , +.Nm BIO_number_written +.Nd BIO I/O functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft int +.Fo BIO_read +.Fa "BIO *b" +.Fa "void *buf" +.Fa "int len" +.Fc +.Ft unsigned long +.Fo BIO_number_read +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_gets +.Fa "BIO *b" +.Fa "char *buf" +.Fa "int size" +.Fc +.Ft int +.Fo BIO_write +.Fa "BIO *b" +.Fa "const void *buf" +.Fa "int len" +.Fc +.Ft int +.Fo BIO_puts +.Fa "BIO *b" +.Fa "const char *string" +.Fc +.Ft int +.Fo BIO_indent +.Fa "BIO *b" +.Fa "int indent" +.Fa "int max" +.Fc +.Ft unsigned long +.Fo BIO_number_written +.Fa "BIO *b" +.Fc +.Sh DESCRIPTION +.Fn BIO_read +attempts to read +.Fa len +bytes from +.Fa b +and places the data in +.Fa buf . +.Pp +.Fn BIO_number_read +returns the grand total of bytes read from +.Fa b +using +.Fn BIO_read +so far. +Bytes read with +.Fn BIO_gets +do +.Sy not +count. +.Xr BIO_new 3 +and +.Xr BIO_set 3 +initialize the counter to 0. +When reading very large amounts of data, +the counter will eventually wrap around from +.Dv ULONG_MAX +to 0. +.Pp +.Fn BIO_gets +performs the BIOs "gets" operation and places the data in +.Fa buf . +Usually this operation will attempt to read a line of data +from the BIO of maximum length +.Fa size No \- 1 . +There are exceptions to this however, for example +.Fn BIO_gets +on a digest BIO will calculate and return the digest +and other BIOs may not support +.Fn BIO_gets +at all. +The returned string is always NUL-terminated. +.Pp +.Fn BIO_write +attempts to write +.Fa len +bytes from +.Fa buf +to +.Fa b . +.Pp +.Fn BIO_puts +attempts to write the NUL-terminated +.Fa string +to +.Fa b . +.Pp +.Fn BIO_indent +attempts to write +.Fa indent +space characters to +.Fa b , +but not more than +.Fa max +characters. +.Pp +.Fn BIO_number_written +returns the grand total of bytes written to +.Fa b +using +.Fn BIO_write , +.Fn BIO_puts , +and +.Fn BIO_indent +so far. +.Xr BIO_new 3 +and +.Xr BIO_set 3 +initialize the counter to 0. +When writing very large amounts of data, +the counter will eventually wrap around from +.Dv ULONG_MAX +to 0. +.Pp +One technique sometimes used with blocking sockets +is to use a system call (such as +.Xr select 2 , +.Xr poll 2 +or equivalent) to determine when data is available and then call +.Xr read 2 +to read the data. +The equivalent with BIOs (that is call +.Xr select 2 +on the underlying I/O structure and then call +.Fn BIO_read +to read the data) should +.Em not +be used because a single call to +.Fn BIO_read +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 +.Xr select 2 +(or equivalent) should be combined with non-blocking I/O +so successive reads will request a retry instead of blocking. +.Pp +See +.Xr BIO_should_retry 3 +for details of how to determine the cause of a retry and other I/O issues. +.Pp +If the +.Fn BIO_gets +function is not supported by a BIO then it is possible to +work around this by adding a buffering BIO +.Xr BIO_f_buffer 3 +to the chain. +.Sh RETURN VALUES +.Fn BIO_indent +returns 1 if successful, even if nothing was written, +or 0 if writing fails. +.Pp +.Fn BIO_number_read +and +.Fn BIO_number_written +return a number of bytes or 0 if +.Fa b +is a +.Dv NULL +pointer. +.Pp +The 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. +The trailing NUL is not included in the length returned by +.Fn BIO_gets . +.Pp +A 0 or \-1 return is not necessarily an indication of an error. +In particular when the source/sink is non-blocking 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. +.Sh SEE ALSO +.Xr BIO_meth_new 3 , +.Xr BIO_new 3 , +.Xr BIO_should_retry 3 +.Sh HISTORY +.Fn BIO_read , +.Fn BIO_gets , +.Fn BIO_write , +and +.Fn BIO_puts +first appeared in SSLeay 0.6.0. +.Fn BIO_number_read +and +.Fn BIO_number_written +first appeared in SSLeay 0.6.5. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_indent +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.4 . diff --git a/static/openbsd/man3/BIO_s_accept.3 b/static/openbsd/man3/BIO_s_accept.3 new file mode 100644 index 00000000..c5a8f6d2 --- /dev/null +++ b/static/openbsd/man3/BIO_s_accept.3 @@ -0,0 +1,415 @@ +.\" $OpenBSD: BIO_s_accept.3,v 1.17 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL c03726ca Thu Aug 27 12:28:08 2015 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2014, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_S_ACCEPT 3 +.Os +.Sh NAME +.Nm BIO_s_accept , +.Nm BIO_set_accept_port , +.Nm BIO_get_accept_port , +.Nm BIO_new_accept , +.Nm BIO_set_nbio_accept , +.Nm BIO_set_accept_bios , +.Nm BIO_set_bind_mode , +.Nm BIO_get_bind_mode , +.Nm BIO_do_accept +.Nd accept BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fo BIO_s_accept +.Fa void +.Fc +.Ft long +.Fo BIO_set_accept_port +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Ft char * +.Fo BIO_get_accept_port +.Fa "BIO *b" +.Fc +.Ft BIO * +.Fo BIO_new_accept +.Fa "const char *host_port" +.Fc +.Ft long +.Fo BIO_set_nbio_accept +.Fa "BIO *b" +.Fa "int n" +.Fc +.Ft long +.Fo BIO_set_accept_bios +.Fa "BIO *b" +.Fa "char *bio" +.Fc +.Ft long +.Fo BIO_set_bind_mode +.Fa "BIO *b" +.Fa "long mode" +.Fc +.Ft long +.Fo BIO_get_bind_mode +.Fa "BIO *b" +.Fa "long dummy" +.Fc +.Fd #define BIO_BIND_NORMAL 0 +.Fd #define BIO_BIND_REUSEADDR_IF_UNUSED 1 +.Fd #define BIO_BIND_REUSEADDR 2 +.Ft long +.Fo BIO_do_accept +.Fa "BIO *b" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_accept +returns the accept BIO method. +This is a wrapper round the platform's TCP/IP socket +.Xr accept 2 +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 +.Xr BIO_puts 3 +but not +.Xr BIO_gets 3 . +.Pp +If the close flag is set on an accept BIO, then any active +connection on that chain is shut down and the socket closed when +the BIO is freed. +.Pp +Calling +.Xr BIO_reset 3 +on an accept BIO will close any active connection and reset the BIO +into a state where it awaits another incoming connection. +.Pp +.Xr BIO_get_fd 3 +and +.Xr BIO_set_fd 3 +can be called to retrieve or set the accept socket. +See +.Xr BIO_s_fd 3 . +.Pp +.Fn BIO_set_accept_port +uses the string +.Fa name +to set the accept port. +The port is represented as a string of the form +.Ar host : Ns Ar port , +where +.Ar host +is the interface to use and +.Ar port +is the port. +The host can be +.Qq * , +which is interpreted as meaning any interface; +.Ar port +has the same syntax as the port specified in +.Xr BIO_set_conn_port 3 +for connect BIOs. +It can be a numerical port string or a string to look up using +.Xr getservbyname 3 +and a string table. +.Pp +.Fn BIO_new_accept +combines +.Xr BIO_new 3 +and +.Fn BIO_set_accept_port +into a single call. +It creates a new accept BIO with port +.Fa host_port . +.Pp +.Fn BIO_set_nbio_accept +sets the accept socket to blocking mode (the default) if +.Fa n +is 0 or non-blocking mode if +.Fa n +is 1. +.Pp +.Fn BIO_set_accept_bios +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 +.Fn BIO_set_bind_mode +and +.Fn BIO_get_bind_mode +set and retrieve the current bind mode. +If +.Dv BIO_BIND_NORMAL Pq the default +is set, then another socket cannot be bound to the same port. +If +.Dv BIO_BIND_REUSEADDR +is set, then other sockets can bind to the same port. +If +.Dv BIO_BIND_REUSEADDR_IF_UNUSED +is set, then an attempt is first made to use +.Dv BIO_BIN_NORMAL ; +if this fails and the port is not in use, +then a second attempt is made using +.Dv BIO_BIND_REUSEADDR . +.Pp +.Fn BIO_do_accept +serves two purposes. +When it is first called, after the accept BIO has been set up, +it will attempt to create the accept socket and bind an address to it. +Second and subsequent calls to +.Fn BIO_do_accept +will await an incoming connection, or request a retry in non-blocking mode. +.Sh 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 the 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 +.Fn BIO_set_accept_bios , +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 +.Dl connection = BIO_pop(accept); +.Pp +After this call, +.Sy connection +will contain a BIO for the recently established connection and +.Sy accept +will now be a single BIO again which can be used +to await further incoming connections. +If no further connections will be accepted, the +.Sy accept +can be freed using +.Xr BIO_free 3 . +.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 +.Xr BIO_pop 3 +(see above) and freeing up the accept BIO after the initial connection. +.Pp +If the underlying accept socket is non-blocking and +.Fn BIO_do_accept +is called to await an incoming connection, it is possible for +.Xr BIO_should_io_special 3 +with the reason +.Dv 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 +.Xr BIO_ctrl 3 +.Fa cmd +and +.Fa larg +arguments correspond to macros as follows: +.Bl -column BIO_C_DO_STATE_MACHINE larg BIO_get_accept_port(3) -offset 3n +.It Fa cmd No constant Ta Fa larg Ta corresponding macro +.It Dv BIO_C_DO_STATE_MACHINE Ta 0 Ta Fn BIO_do_accept +.It Dv BIO_C_GET_ACCEPT Ta 0 Ta Fn BIO_get_accept_port +.It Dv BIO_C_GET_BIND_MODE Ta 0 Ta Fn BIO_get_bind_mode +.It Dv BIO_C_GET_FD Ta 0 Ta Xr BIO_get_fd 3 +.It Dv BIO_C_SET_ACCEPT Ta 0 Ta Fn BIO_set_accept_port +.It Ta 1 Ta Fn BIO_set_nbio_accept +.It Ta 2 Ta Fn BIO_set_accept_bios +.It Dv BIO_C_SET_FD Ta Fa fd Ta Xr BIO_set_fd 3 +.It Dv BIO_C_SET_NBIO Ta Fa n Ta Xr BIO_set_nbio 3 +.It Dv BIO_C_SET_BIND_MODE Ta Fa mode Ta Fn BIO_set_bind_mode +.It Dv BIO_CTRL_GET_CLOSE Ta 0 Ta Xr BIO_get_close 3 +.It Dv BIO_CTRL_RESET Ta 0 Ta Xr BIO_reset 3 +.It Dv BIO_CTRL_SET_CLOSE Ta Fa flag Ta Xr BIO_set_close 3 +.El +.Sh RETURN VALUES +When called on an accept BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_ACCEPT +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq socket accept . +.Pp +.Fn BIO_do_accept , +.Fn BIO_set_accept_port , +.Fn BIO_set_nbio_accept , +.Fn BIO_set_accept_bios , +and +.Fn BIO_set_bind_mode +return 1 for success or 0 or -1 for failure. +.Pp +.Fn BIO_get_accept_port +returns the port as a string or +.Dv NULL +on error. +.Pp +.Fn BIO_get_bind_mode +returns the set of BIO_BIND flags or -1 on failure. +.Pp +.Fn BIO_new_accept +returns a +.Vt BIO +or +.Dv NULL +on error. +.Sh EXAMPLES +This example accepts two connections on port 4444, +sends messages down each and finally closes both down. +.Bd -literal -offset 2n +BIO *abio, *cbio, *cbio2; +ERR_load_crypto_strings(); +abio = BIO_new_accept("4444"); + +/* First call to BIO_accept() sets up accept BIO */ +if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error setting up accept\en"); + ERR_print_errors_fp(stderr); + exit(0); +} + +/* Wait for incoming connection */ +if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\en"); + ERR_print_errors_fp(stderr); + exit(0); +} +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(0); +} +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); +.Ed +.Sh SEE ALSO +.Xr BIO_new 3 +.Sh HISTORY +.Fn BIO_s_accept , +.Fn BIO_set_accept_port , +.Fn BIO_new_accept , +.Fn BIO_set_accept_bios , +and +.Fn BIO_do_accept +first appeared in SSLeay 0.8.0. +.Fn BIO_set_nbio_accept +and +.Fn BIO_get_accept_port +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_set_bind_mode +and +.Fn BIO_get_bind_mode +first appeared in SSLeay 0.9.1 and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/BIO_s_bio.3 b/static/openbsd/man3/BIO_s_bio.3 new file mode 100644 index 00000000..6590ff81 --- /dev/null +++ b/static/openbsd/man3/BIO_s_bio.3 @@ -0,0 +1,417 @@ +.\" $OpenBSD: BIO_s_bio.3,v 1.21 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by +.\" Lutz Jaenicke , +.\" Dr. Stephen Henson , +.\" Bodo Moeller , +.\" and Richard Levitte . +.\" Copyright (c) 2000, 2002, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_S_BIO 3 +.Os +.Sh NAME +.Nm BIO_s_bio , +.Nm BIO_make_bio_pair , +.Nm BIO_destroy_bio_pair , +.Nm BIO_shutdown_wr , +.Nm BIO_set_write_buf_size , +.Nm BIO_get_write_buf_size , +.Nm BIO_new_bio_pair , +.Nm BIO_get_write_guarantee , +.Nm BIO_ctrl_get_write_guarantee , +.Nm BIO_get_read_request , +.Nm BIO_ctrl_get_read_request , +.Nm BIO_ctrl_reset_read_request +.Nd BIO pair BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fo BIO_s_bio +.Fa void +.Fc +.Ft int +.Fo BIO_make_bio_pair +.Fa "BIO *b1" +.Fa "BIO *b2" +.Fc +.Ft int +.Fo BIO_destroy_bio_pair +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_shutdown_wr +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_set_write_buf_size +.Fa "BIO *b" +.Fa "long size" +.Fc +.Ft size_t +.Fo BIO_get_write_buf_size +.Fa "BIO *b" +.Fa "long size" +.Fc +.Ft int +.Fo BIO_new_bio_pair +.Fa "BIO **bio1" +.Fa "size_t writebuf1" +.Fa "BIO **bio2" +.Fa "size_t writebuf2" +.Fc +.Ft int +.Fo BIO_get_write_guarantee +.Fa "BIO *b" +.Fc +.Ft size_t +.Fo BIO_ctrl_get_write_guarantee +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_get_read_request +.Fa "BIO *b" +.Fc +.Ft size_t +.Fo BIO_ctrl_get_read_request +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_ctrl_reset_read_request +.Fa "BIO *b" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_bio +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 be 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 +.Xr BIO_read 3 +will read data from the buffer or request a retry if no data is available. +.Pp +Calls to +.Xr BIO_write 3 +will place data in the buffer or request a retry if the buffer is full. +.Pp +The standard calls +.Xr BIO_ctrl_pending 3 +and +.Xr BIO_ctrl_wpending 3 +can be used to determine the amount of pending data +in the read or write buffer. +.Pp +.Xr BIO_reset 3 +clears any data in the write buffer. +.Pp +.Fn BIO_make_bio_pair +joins two separate BIOs into a connected pair. +.Pp +.Fn BIO_destroy_pair +destroys the association between two connected BIOs. +Freeing up any half of the pair will automatically destroy the association. +.Pp +.Fn BIO_shutdown_wr +is used to close down a BIO +.Fa b . +After this call no further writes on BIO +.Fa b +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 +.Fn BIO_set_write_buf_size +sets the write buffer size of BIO +.Fa b +to +.Fa size . +If the size is not initialized, a default value is used. +This is currently 17K, sufficient for a maximum size TLS record. +When a chain containing a BIO pair is copied with +.Xr BIO_dup_chain 3 , +the write buffer size is automatically copied +from the original BIO object to the new one. +.Pp +.Fn BIO_get_write_buf_size +returns the size of the write buffer. +.Pp +.Fn BIO_new_bio_pair +combines the calls to +.Xr BIO_new 3 , +.Fn BIO_make_bio_pair +and +.Fn BIO_set_write_buf_size +to create a connected pair of BIOs +.Fa bio1 +and +.Fa bio2 +with write buffer sizes +.Fa writebuf1 +and +.Fa writebuf2 . +If either size is zero, then the default size is used. +.Fn BIO_new_bio_pair +does not check whether +.Fa bio1 +or +.Fa bio2 +point to some other BIO; the values are overwritten and +.Xr BIO_free 3 +is not called. +.Pp +.Fn BIO_get_write_guarantee +and +.Fn BIO_ctrl_get_write_guarantee +return the maximum length of data +that can be currently written to the BIO. +Writes larger than this value will return a value from +.Xr BIO_write 3 +less than the amount requested or if the buffer is full request a retry. +.Fn BIO_ctrl_get_write_guarantee +is a function whereas +.Fn BIO_get_write_guarantee +is a macro. +.Pp +.Fn BIO_get_read_request +and +.Fn BIO_ctrl_get_read_request +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 +.Fn BIO_get_read_request +never returns an amount larger than that returned by +.Fn BIO_get_write_guarantee . +.Pp +.Fn BIO_ctrl_reset_read_request +can also be used to reset the value returned by +.Fn BIO_get_read_request +to zero. +.Pp +Both halves of a BIO pair should be freed. +Even if one half is implicitly freed due to a +.Xr BIO_free_all 3 +or +.Xr SSL_free 3 +call, the other half still 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 +.Xr BIO_pending 3 +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 +.Xr select 2 ) +due to a request and +.Xr BIO_should_read 3 +being true. +.Pp +To see why this is important, +consider a case where a request is sent using +.Xr BIO_write 3 +and a response read with +.Xr BIO_read 3 , +this can occur during a TLS/SSL handshake for example. +.Xr BIO_write 3 +will succeed and place data in the write buffer. +.Xr BIO_read 3 +will initially fail and +.Xr BIO_should_read 3 +will be true. +If the application then waits for data to become available +on the underlying transport before flushing the write buffer, +it will never succeed because the request was never sent. +.Pp +.Xr BIO_eof 3 +is true if no data is in the peer BIO and the peer BIO has been shutdown. +.Pp +.Xr BIO_ctrl 3 +.Fa cmd +arguments correspond to macros as follows: +.Bl -column BIO_C_GET_WRITE_GUARANTEE BIO_ctrl_reset_read_request() -offset 3n +.It Fa cmd No constant Ta corresponding macro +.It Dv BIO_C_DESTROY_BIO_PAIR Ta Fn BIO_destroy_bio_pair +.It Dv BIO_C_GET_READ_REQUEST Ta Fn BIO_get_read_request +.It Dv BIO_C_GET_WRITE_BUF_SIZE Ta Fn BIO_get_write_buf_size +.It Dv BIO_C_GET_WRITE_GUARANTEE Ta Fn BIO_get_write_guarantee +.It Dv BIO_C_MAKE_BIO_PAIR Ta Fn BIO_make_bio_pair +.It Dv BIO_C_RESET_READ_REQUEST Ta Fn BIO_ctrl_reset_read_request +.It Dv BIO_C_SET_WRITE_BUF_SIZE Ta Fn BIO_set_write_buf_size +.It Dv BIO_C_SHUTDOWN_WR Ta Fn BIO_shutdown_wr +.It Dv BIO_CTRL_EOF Ta Xr BIO_eof 3 +.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3 +.It Dv BIO_CTRL_PENDING Ta Xr BIO_pending 3 +.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 +.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3 +.It Dv BIO_CTRL_WPENDING Ta Xr BIO_wpending 3 +.El +.Sh RETURN VALUES +.Fn BIO_new_bio_pair +returns 1 on success, with the new BIOs available in +.Fa bio1 +and +.Fa bio2 , +or 0 on failure, with NULL pointers stored into the locations for +.Fa bio1 +and +.Fa bio2 . +Check the error stack for more information. +.Pp +When called on a BIO pair BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_BIO +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq BIO pair . +.\" XXX More return values need to be added here. +.Sh EXAMPLES +The BIO pair can be used to have full control +over the network access of an application. +The application can call +.Xr select 2 +on the socket as required without having to go through the SSL interface. +.Bd -literal -offset 2n +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); +\&... +.Ed +.Pp +As the BIO pair will only buffer the data and never directly access +the connection, it behaves non-blocking 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 +.Xr BIO_ctrl_pending 3 +to find out whether data is buffered in the BIO +and must be transferred to the network. +Use +.Fn BIO_ctrl_get_read_request +to find out how many bytes must be written into the buffer before the +SSL operations can successfully be continued. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr BIO_read 3 , +.Xr BIO_should_retry 3 , +.Xr ssl 3 , +.Xr SSL_set_bio 3 +.Sh HISTORY +.Fn BIO_s_bio , +.Fn BIO_make_bio_pair , +.Fn BIO_destroy_bio_pair , +.Fn BIO_set_write_buf_size , +.Fn BIO_get_write_buf_size , +.Fn BIO_new_bio_pair , +.Fn BIO_get_write_guarantee , +.Fn BIO_ctrl_get_write_guarantee , +.Fn BIO_get_read_request , +and +.Fn BIO_ctrl_reset_read_request +first appeared in OpenSSL 0.9.4 and have been available since +.Ox 2.6 . +.Pp +.Fn BIO_ctrl_reset_read_request +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn BIO_shutdown_wr +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Sh CAVEATS +As the data is buffered, SSL operations may return with an +.Dv ERROR_SSL_WANT_READ +condition, but there is still data in the write buffer. +An application must not rely on the error value of the SSL operation +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. diff --git a/static/openbsd/man3/BIO_s_connect.3 b/static/openbsd/man3/BIO_s_connect.3 new file mode 100644 index 00000000..ca7ee6d9 --- /dev/null +++ b/static/openbsd/man3/BIO_s_connect.3 @@ -0,0 +1,504 @@ +.\" $OpenBSD: BIO_s_connect.3,v 1.20 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 0e474b8b Nov 1 15:45:49 2015 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_S_CONNECT 3 +.Os +.Sh NAME +.Nm BIO_s_connect , +.Nm BIO_new_connect , +.Nm BIO_set_conn_hostname , +.Nm BIO_set_conn_port , +.Nm BIO_set_conn_ip , +.Nm BIO_set_conn_int_port , +.Nm BIO_get_conn_hostname , +.Nm BIO_get_conn_port , +.Nm BIO_get_conn_ip , +.Nm BIO_get_conn_int_port , +.Nm BIO_set_nbio , +.Nm BIO_do_connect +.Nd connect BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fo BIO_s_connect +.Fa void +.Fc +.Ft BIO * +.Fo BIO_new_connect +.Fa "const char *name" +.Fc +.Ft long +.Fo BIO_set_conn_hostname +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Ft long +.Fo BIO_set_conn_port +.Fa "BIO *b" +.Fa "char *port" +.Fc +.Ft long +.Fo BIO_set_conn_ip +.Fa "BIO *b" +.Fa "char *ip" +.Fc +.Ft long +.Fo BIO_set_conn_int_port +.Fa "BIO *b" +.Fa "char *port" +.Fc +.Ft char * +.Fo BIO_get_conn_hostname +.Fa "BIO *b" +.Fc +.Ft char * +.Fo BIO_get_conn_port +.Fa "BIO *b" +.Fc +.Ft char * +.Fo BIO_get_conn_ip +.Fa "BIO *b" +.Fc +.Ft long +.Fo BIO_get_conn_int_port +.Fa "BIO *b" +.Fc +.Ft long +.Fo BIO_set_nbio +.Fa "BIO *b" +.Fa "long n" +.Fc +.Ft long +.Fo BIO_do_connect +.Fa "BIO *b" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_connect +returns the connect BIO method. +This is a wrapper around the platform's 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 +.Xr BIO_puts 3 +but not +.Xr BIO_gets 3 . +.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 +.Xr BIO_reset 3 +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 +.Xr BIO_get_fd 3 +places the underlying socket in +.Fa c +if it is not +.Dv NULL +and also returns the socket. +If +.Fa c +is not +.Dv NULL , +it should be of type +.Vt "int *" . +.Pp +.Xr BIO_set_info_callback 3 +and +.Xr BIO_callback_ctrl 3 +with a +.Fa cmd +of +.Dv BIO_CTRL_SET_CALLBACK +save the pointer to the +.Fa cb +function internally in +.Fa b +and +.Xr BIO_get_info_callback 3 +retrieves this function pointer. +If such an info callback is installed, it is invoked whenever +a state change or error occurs in the connect BIO state machine. +The arguments of the callback include the new +.Fa state +in case of a state change or the old +.Fa state +in case of an error and the value +.Fa res +that the state machine would return to whatever operation invoked it +if no info callback had been installed. +If an info callback is installed, the state machine +returns the return value of the info callback instead. +Consequently, the info callback is supposed to usually return +.Fa res . +The precise effect of the return value depends on which operation +the state machine was invoked from. +Usually, \-1 is used to indicate failure and return values less than +or equal to zero abort the operation in question, whereas positive +values indicate success and allow the operation to proceed. +.Pp +The +.Fa state +constants passed to the callback are named according to +which operation needs to be performed next. +They are listed here in the order the states are passed through: +.Pp +.Bl -tag -width BIO_CONN_S_BLOCKED_CONNECT -offset 3n -compact +.It Dv BIO_CONN_S_BEFORE +The BIO is idle and no connection has been initiated yet. +.It Dv BIO_CONN_S_GET_IP +The hostname to connect to needs to be converted to an IP address. +.It Dv BIO_CONN_S_GET_PORT +The service name to connect to needs to be converted to a TCP port number. +.It Dv BIO_CONN_S_CREATE_SOCKET +The TCP socket needs to be created with the +.Xr socket 2 +system call. +.It Dv BIO_CONN_S_NBIO +Socket options may need to be set using +.Xr fcntl 2 +and +.Xr setsockopt 2 . +.It Dv BIO_CONN_S_CONNECT +The connection needs to be initiated with the +.Xr connect 2 +system call. +.It Dv BIO_CONN_S_BLOCKED_CONNECT +The +.Xr connect 2 +system call would have blocked and needs to be tried again. +.It Dv BIO_CONN_S_OK +The connection has been established and can now be used to transfer data. +.El +.Pp +.Fn BIO_set_conn_hostname +uses the string +.Fa name +to set the hostname. +The hostname can be an IP address. +The hostname can also include the port in the form +.Ar hostname : Ns Ar port . +It is also acceptable to use the forms +.Ar hostname Ns / Ns Pa any/other/path +or +.Ar hostname : Ns Ar port Ns / Ns Pa any/other/path . +.Pp +.Fn BIO_set_conn_port +sets the port to +.Fa port . +.Fa port +is looked up as a service using +.Xr getaddrinfo 3 . +.Pp +.Fn BIO_set_conn_ip +sets the IP address to +.Fa ip +using binary form i.e. four bytes specifying the IP address +in big-endian form. +.Pp +.Fn BIO_set_conn_int_port +sets the port using +.Fa port . +.Fa port +should +be of type +.Vt "int *" . +.Pp +.Fn BIO_get_conn_hostname +returns the hostname of the connect BIO or +.Dv NULL +if the BIO is initialized but no hostname is set. +This return value is an internal pointer which should not be modified. +.Pp +.Fn BIO_get_conn_port +returns the port as a string. +This return value is an internal pointer which should not be modified. +.Pp +.Fn BIO_get_conn_ip +returns the IP address in binary form. +.Pp +.Fn BIO_get_conn_int_port +returns the port as an +.Vt int . +.Pp +.Fn BIO_set_nbio +sets the non-blocking I/O flag to +.Fa n . +If +.Fa n +is zero then blocking I/O is set. +If +.Fa n +is 1 then non-blocking I/O is set. +Blocking I/O is the default. +The call to +.Fn BIO_set_nbio +should be made before the connection is established +because non-blocking I/O is set during the connect process. +.Pp +.Fn BIO_new_connect +combines +.Xr BIO_new 3 +and +.Fn BIO_set_conn_hostname +into a single call. +It creates a new connect BIO with +.Fa name . +.Pp +.Fn BIO_do_connect +attempts to connect the supplied BIO. +It returns 1 if the connection was established successfully. +A zero or negative value is returned if the connection +could not be established. +The call +.Xr BIO_should_retry 3 +should be used for non-blocking connect BIOs +to determine if the call should be retried. +.Pp +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 host name then this will +override any value set with +.Fn BIO_set_conn_port . +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 +.Sq \&: +character in the passed hostname and either indicating an error +or truncating the string at that point. +.Pp +The values returned by +.Fn BIO_get_conn_hostname , +.Fn BIO_get_conn_port , +.Fn BIO_get_conn_ip , +and +.Fn BIO_get_conn_int_port +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 +.Fn BIO_do_connect +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 +In addition to +.Xr BIO_should_read 3 +and +.Xr BIO_should_write 3 +it is also possible for +.Xr BIO_should_io_special 3 +to be true during the initial connection process with the reason +.Dv BIO_RR_CONNECT . +If this is returned, it 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 +When a chain containing a connect BIO is copied with +.Xr BIO_dup_chain 3 , +.Fn BIO_set_conn_hostname , +.Fn BIO_set_conn_port , +.Fn BIO_set_nbio , +and +.Xr BIO_set_info_callback 3 +are called internally to automatically copy the hostname, port, +non-blocking I/O flag, and info callback from the original BIO object +to the new one. +.Pp +.Xr BIO_ctrl 3 +.Fa cmd +and +.Fa larg +arguments correspond to macros as follows: +.Bl -column BIO_C_DO_STATE_MACHINE larg BIO_get_conn_hostname(3) -offset 3n +.It Fa cmd No constant Ta Fa larg Ta corresponding macro +.It Dv BIO_C_DO_STATE_MACHINE Ta 0 Ta Fn BIO_do_connect +.It Dv BIO_C_GET_CONNECT Ta 0 Ta Fn BIO_get_conn_hostname +.It Ta 1 Ta Fn BIO_get_conn_port +.It Ta 2 Ta Fn BIO_get_conn_ip +.It Ta 3 Ta Fn BIO_get_conn_int_port +.It Dv BIO_C_GET_FD Ta 0 Ta Xr BIO_get_fd 3 +.It Dv BIO_C_SET_CONNECT Ta 0 Ta Fn BIO_set_conn_hostname +.It Ta 1 Ta Fn BIO_set_conn_port +.It Ta 2 Ta Fn BIO_set_conn_ip +.It Ta 3 Ta Fn BIO_set_conn_int_port +.It Dv BIO_C_SET_NBIO Ta Fa n Ta Fn BIO_set_nbio +.It Dv BIO_CTRL_GET_CLOSE Ta 0 Ta Xr BIO_get_close 3 +.It Dv BIO_CTRL_RESET Ta 0 Ta Xr BIO_reset 3 +.It Dv BIO_CTRL_SET_CLOSE Ta Fa flag Ta Xr BIO_set_close 3 +.El +.Sh RETURN VALUES +.Fn BIO_s_connect +returns the connect BIO method. +.Pp +When called on a connect BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_CONNECT +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq socket connect . +.Pp +.Xr BIO_get_fd 3 +returns the socket or -1 if the BIO has not been initialized. +.Pp +.Fn BIO_set_conn_hostname , +.Fn BIO_set_conn_port , +.Fn BIO_set_conn_ip , +and +.Fn BIO_set_conn_int_port +always return 1. +.Pp +.Fn BIO_get_conn_hostname +returns the connected hostname or +.Dv NULL +if none is set. +.Pp +.Fn BIO_get_conn_port +returns a string representing the connected port or +.Dv NULL +if not set. +.Pp +.Fn BIO_get_conn_ip +returns a pointer to the connected IP address in binary form +or all zeros if not set. +.Pp +.Fn BIO_get_conn_int_port +returns the connected port or 0 if none was set. +.Pp +.Fn BIO_set_nbio +always returns 1. +.Pp +.Fn BIO_do_connect +returns 1 if the connection was successfully +established and 0 or -1 if the connection failed. +.Sh EXAMPLES +This example connects to a webserver on the local host and attempts +to retrieve a page and copy the result to standard output. +.Bd -literal -offset 2n +BIO *cbio, *out; +int len; +char tmpbuf[1024]; + +ERR_load_crypto_strings(); +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); + /* whatever ... */ +} +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); +.Ed +.Sh SEE ALSO +.Xr BIO_new 3 +.Sh HISTORY +.Fn BIO_s_connect , +.Fn BIO_new_connect , +.Fn BIO_set_nbio , +and +.Fn BIO_do_connect +first appeared in SSLeay 0.8.0. +.Fn BIO_set_conn_hostname , +.Fn BIO_set_conn_port , +.Fn BIO_set_conn_ip , +.Fn BIO_set_conn_int_port , +.Fn BIO_get_conn_hostname , +.Fn BIO_get_conn_port , +.Fn BIO_get_conn_ip , +and +.Fn BIO_get_conn_int_port +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BIO_s_datagram.3 b/static/openbsd/man3/BIO_s_datagram.3 new file mode 100644 index 00000000..bbe80b25 --- /dev/null +++ b/static/openbsd/man3/BIO_s_datagram.3 @@ -0,0 +1,574 @@ +.\" $OpenBSD: BIO_s_datagram.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2022 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 $Mdocdate: June 8 2025 $ +.Dt BIO_S_DATAGRAM 3 +.Os +.Sh NAME +.Nm BIO_s_datagram , +.Nm BIO_new_dgram , +.Nm BIO_dgram_set_peer , +.Nm BIO_ctrl_dgram_connect , +.Nm BIO_dgram_get_peer , +.Nm BIO_ctrl_set_connected , +.Nm BIO_dgram_recv_timedout , +.Nm BIO_dgram_send_timedout , +.Nm BIO_dgram_non_fatal_error +.\" .Nm BIO_CTRL_DGRAM_QUERY_MTU and +.\" .Nm BIO_CTRL_DGRAM_MTU_DISCOVER are intentionally undocumented. +.\" They are almost unused, and OpenBSD does not appear to support them. +.Nd datagram socket BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fn BIO_s_datagram void +.Ft BIO * +.Fo BIO_new_dgram +.Fa "int fd" +.Fa "int close_flag" +.Fc +.Ft int +.Fo BIO_dgram_set_peer +.Fa "BIO *b" +.Fa "struct sockaddr *sa" +.Fc +.Ft int +.Fo BIO_ctrl_dgram_connect +.Fa "BIO *b" +.Fa "struct sockaddr *sa" +.Fc +.Ft int +.Fo BIO_dgram_get_peer +.Fa "BIO *b" +.Fa "struct sockaddr *sa" +.Fc +.Ft int +.Fo BIO_ctrl_set_connected +.Fa "BIO *b" +.Fa "long argl" +.Fa "struct sockaddr *sa" +.Fc +.Ft int +.Fn BIO_dgram_recv_timedout "BIO *b" +.Ft int +.Fn BIO_dgram_send_timedout "BIO *b" +.Ft int +.Fn BIO_dgram_non_fatal_error "int errnum" +.Sh DESCRIPTION +.Fn BIO_s_datagram +returns the datagram socket BIO method. +The usual application is to transmit data using the IPv4 or IPv6 +.Xr udp 4 +protocol. +.Pp +When called on a datagram socket BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_DGRAM +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq datagram socket . +.Ss Constructors and destructors +.Xr BIO_new 3 +allocates a new datagram socket BIO object and initializes all its data +to zero, including the datagram socket file descriptor, the peer address, +the init flag that can be retrieved with +.Xr BIO_get_init 3 , +the connected flag, the MTU, and all timeout and error information. +The reference count and the close flag are set to 1. +.Pp +.Fn BIO_new_dgram +allocates and initializes a new datagram socket BIO object with +.Xr BIO_new 3 , +sets the datagram socket file descriptor and the close flag +according to its arguments, and sets the init flag to 1. +.Pp +If the reference count reaches 0 in +.Xr BIO_free 3 +and the close and init flags are set, +.Xr shutdown 2 +and +.Xr close 2 +are called on the datagram socket file descriptor before freeing the +storage used by the BIO object. +.Pp +When a chain containing a datagram socket BIO is copied with +.Xr BIO_dup_chain 3 , +the datagram socket file descriptor, the init flag, the close flag, +the flags accessible with +.Xr BIO_test_flags 3 , +and any data that was set with +.Xr BIO_set_ex_data 3 +are automatically copied from the original BIO object to the new one, +but the peer address, the connected flag, the MTU and all timeout and +error information are not copied but instead initialized to zero. +.Ss Initialization and configuration +If the close flag is set in +.Fa b , +.Xr BIO_set_fd 3 +clears all flags that are set in +.Fa b +and if the init flag was set, it calls +.Xr shutdown 2 +and +.Xr close 2 +on the previously assigned file descriptor. +In any case, +.Xr BIO_set_fd 3 +then sets the new file descriptor and the new close flag according to +its arguments and sets the init flag to 1. +.Pp +If the init flag is set in +.Fa b , +.Xr BIO_get_fd 3 +returns its datagram socket file descriptor, and unless the +.Fa c +argument is a +.Dv NULL +pointer, it also stores the file descriptor in +.Pf * Fa c . +If the init flag is not set, +.Xr BIO_get_fd 3 +fails and returns \-1. +.Pp +.Xr BIO_set_close 3 +sets the close flag in +.Fa b +to the +.Fa flag +argument. +.Xr BIO_get_close 3 +returns the value of the close flag from +.Fa b . +.Pp +For datagram socket BIO objects, +the shutdown flag is the same flag as the close flag. +Consequently, +.Xr BIO_set_shutdown 3 +has the same effect as +.Xr BIO_set_close 3 +and +.Xr BIO_get_shutdown 3 +has the same effect as +.Xr BIO_get_close 3 . +.Pp +.Fn BIO_dgram_set_peer +copies +.Fa sa +as the peer address into +.Fa b . +.Pp +.Fn BIO_ctrl_dgram_connect +does exactly the same as +.Fn BIO_dgram_set_peer . +Its name is even more misleading than the name of +.Fn BIO_ctrl_set_connected . +In addition to what is said there, +.Fn BIO_ctrl_dgram_connect +does not even set the connected flag in +.Fa b . +.Pp +.Fn BIO_dgram_get_peer +copies the peer address from +.Fa b +to +.Pf * Fa sa . +Before calling this function, the caller has to make sure +that the peer address is indeed set in +.Fa b +and that sufficient memory is available starting at +.Fa sa +to copy a complete +.Vt struct sockaddr , +.Vt struct sockaddr_in , +or +.Vt struct sockaddr_in6 +to that place, depending on which address family +.Fa b +is currently used for. +.Pp +Unless +.Fa sa +is +.Dv NULL , +.Fn BIO_ctrl_set_connected +sets the connected flag in +.Fa b +and copies +.Fa sa +as the peer address into +.Fa b . +If +.Fa sa +is +.Dv NULL , +.Fn BIO_ctrl_set_connected +clears the connected flag and the peer address in +.Fa b . +Considering that communication using a datagram protocol is connectionless, +the name of this function is misleading. +It is neither establishing or terminating a connection nor changing +anything with respect to the state of the datagram socket, but merely +modifying some purely informational data in the wrapping BIO object. +The additional +.Fa argl +argument is passed through to the callbacks documented in +.Xr BIO_set_callback 3 +if any such callbacks are installed, but it is otherwise ignored. +.Pp +.Xr BIO_ctrl 3 +with a +.Fa cmd +of +.Dv BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT +interprets the +.Fa parg +argument as a pointer to a +.Vt struct timeval +and sets the read timeout to the specified absolute UTC time. +.Pp +.Xr BIO_ctrl 3 +with a +.Fa cmd +of +.Dv BIO_CTRL_DGRAM_SET_RECV_TIMEOUT , +.Dv BIO_CTRL_DGRAM_GET_RECV_TIMEOUT , +.Dv BIO_CTRL_DGRAM_SET_SEND_TIMEOUT , +or +.Dv BIO_CTRL_DGRAM_GET_SEND_TIMEOUT +interprets the +.Fa parg +argument as a pointer to a +.Vt struct timeval +and calls +.Xr setsockopt 2 +or +.Xr getsockopt 2 +on the datagram socket file descriptor of +.Fa b +with an argument of +.Dv SO_RCVTIMEO +or +.Dv SO_SNDTIMEO , +respectively. +.Dv BIO_CTRL_DGRAM_SET_RECV_TIMEOUT +and +.Dv BIO_CTRL_DGRAM_SET_SEND_TIMEOUT +return 1 on success, +.Dv BIO_CTRL_DGRAM_GET_RECV_TIMEOUT +and +.Dv BIO_CTRL_DGRAM_GET_SEND_TIMEOUT +the number of bytes written to +.Pf * Fa parg . +All four return \-1 on failure. +Remember that +.Xr BIO_read 3 +may actually use a shorter timeout when +.Dv BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT +is in effect. +.Pp +.Xr BIO_ctrl 3 +with a +.Fa cmd +of +.Dv BIO_CTRL_DGRAM_GET_FALLBACK_MTU +returns 1232 if the peer address is an IPv6 address that is not IPv4 mapped +or 548 otherwise. +Making sure that a peer address is set before issuing this command +is the responsibility of the caller. +.Pp +.Xr BIO_ctrl 3 +with a +.Fa cmd +of +.Dv BIO_CTRL_DGRAM_SET_MTU +sets the MTU attribute of +.Fa b +to the value of the +.Fa larg +argument and also returns that argument. +.Xr BIO_ctrl 3 +with a +.Fa cmd +of +.Dv BIO_CTRL_DGRAM_GET_MTU +returns the MTU attribute of +.Fa b +or 0 if it was not set. +.Pp +.Xr BIO_ctrl 3 +with a +.Fa cmd +of +.Dv BIO_CTRL_DGRAM_MTU_EXCEEDED +returns 1 if the most recent non-fatal failure of +.Xr BIO_read 3 +or +.Xr BIO_write 3 +was caused by +.Er EMSGSIZE +or 0 otherwise. +This command also clears the +.Xr errno 2 +value that was saved internally for this particular purpose, so that +issuing the same command again will return 0 until the next +.Er EMSGSIZE +failure occurs. +.Pp +.Fn BIO_dgram_recv_timedout +and +.Fn BIO_dgram_send_timedout +check whether the most recent non-fatal failure of +.Xr BIO_read 3 +or +.Xr BIO_write 3 +was caused by +.Er EAGAIN . +Despite having different names, both functions do exactly the same, +and both inspect the most recent non-fatal I/O failure, no matter +whether it occurred during a receive or send operation. +Both functions also clear the +.Xr errno 2 +value that was saved internally for this particular purpose, +so that calling these functions again will return 0 until the next +.Er EAGAIN +failure occurs. +.Pp +Datagram socket BIOs do not support +.Xr BIO_eof 3 , +.Xr BIO_get_mem_data 3 , +.Xr BIO_pending 3 , +.Xr BIO_reset 3 , +.Xr BIO_seek 3 , +.Xr BIO_tell 3 , +and +.Xr BIO_wpending 3 , +and attempting any such operation results in failure +and returns a value of 0. +.Pp +Control commands correspond to accessor functions as follows: +.Pp +.Bl -tag -width BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP -compact +.It Dv BIO_C_GET_FD +.Xr BIO_get_fd 3 +.It Dv BIO_C_SET_FD +.Xr BIO_set_fd 3 +.It Dv BIO_CTRL_DGRAM_CONNECT +.Fn BIO_ctrl_dgram_connect Pq deprecated +.It Dv BIO_CTRL_DGRAM_GET_PEER +.Fn BIO_dgram_get_peer +.It BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP +.Fn BIO_dgram_recv_timedout +.It BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP +.Fn BIO_dgram_send_timedout +.It Dv BIO_CTRL_DGRAM_SET_CONNECTED +.Fn BIO_ctrl_set_connected +.It Dv BIO_CTRL_DGRAM_SET_PEER +.Fn BIO_dgram_set_peer +.It Dv BIO_CTRL_GET_CLOSE +.Xr BIO_get_close 3 +.It Dv BIO_CTRL_SET_CLOSE +.Xr BIO_set_close 3 +.El +.Ss Input and output operations +.Xr BIO_read 3 +attempts to read up to +.Fa len +bytes into +.Fa buf +from the datagram socket file descriptor using +.Xr recvfrom 2 . +If a read timeout is set, +.Xr setsockopt 2 +is used with an argument of +.Dv SO_RCVTIMEO +to temporarily shorten the timeout on the datagram socket during the +.Xr recvfrom 2 +call such that it returns before the read timeout expires. +.Pp +If +.Xr recvfrom 2 +succeeds and the connected flag is not yet set, +.Xr BIO_read 3 +also copies the peer address received from +.Xr recvfrom 2 +into +.Fa b . +.Pp +If +.Xr recvfrom 2 +is attempted, +.Xr BIO_read 3 +clears the flags +.Dv BIO_FLAGS_WRITE +and +.Dv BIO_FLAGS_IO_SPECIAL +in +.Fa b +and clears or sets the flags +.Dv BIO_FLAGS_READ +and +.Dv BIO_FLAGS_SHOULD_RETRY +as appropriate. +.Pp +If the connected flag is set in +.Fa b , +.Xr BIO_write 3 +attempts to +.Xr write 2 +.Fa len +bytes from +.Fa buf +to the datagram socket file descriptor. +If the connected flag is not set, it attempts to transmit +.Fa len +bytes from +.Fa buf +to the peer using +.Xr sendto 2 . +.Pp +If +.Xr write 2 +or +.Xr sendto 2 +is attempted, +.Xr BIO_write 3 +clears the flags +.Dv BIO_FLAGS_READ +and +.Dv BIO_FLAGS_IO_SPECIAL +in +.Fa b +and clears or sets the flags +.Dv BIO_FLAGS_WRITE +and +.Dv BIO_FLAGS_SHOULD_RETRY +as appropriate. +.Pp +The effect of +.Xr BIO_puts 3 +is similar to the effect of +.Xr BIO_write 3 +with a +.Fa len +argument of +.Fn strlen string . +.Pp +Datagram socket BIOs do not support +.Xr BIO_gets 3 . +Calling this function fails and returns \-2. +.Pp +.Xr BIO_flush 3 +has no effect on a datagram socket BIO. +It always succeeds and returns 1. +.Sh RETURN VALUES +.Fn BIO_s_datagram +returns the datagram socket BIO method. +.Pp +.Fn BIO_new_dgram +returns a newly allocated datagram socket BIO object or +.Dv NULL +on failure. +.Pp +.Fn BIO_dgram_set_peer , +.Fn BIO_ctrl_dgram_connect , +and +.Fn BIO_ctrl_set_connected +return 1 on success or a value less than or equal to zero on failure. +They can only fail if +.Fa b +is not a datagram socket BIO object. +.Pp +.Fn BIO_dgram_get_peer +returns the number of bytes copied to +.Fa sa +or a value less than or equal to zero on failure. +It can only fail if +.Fa b +is not a datagram socket BIO object. +.Pp +.Fn BIO_dgram_recv_timedout +and +.Fn BIO_dgram_send_timedout +return 1 if the most recent non-fatal I/O error was caused by +.Er EAGAIN +or 0 otherwise. +.Pp +.Fn BIO_dgram_non_fatal_error +returns 1 if +.Fa errnum +is +.Er EAGAIN , +.Er EALREADY , +.Er EINPROGRESS , +or +.Er EINTR +or 0 otherwise, even if +.Fa errnum +is 0. +.Sh SEE ALSO +.Xr close 2 , +.Xr getsockopt 2 , +.Xr recvfrom 2 , +.Xr sendto 2 , +.Xr shutdown 2 , +.Xr BIO_ctrl 3 , +.Xr BIO_get_init 3 , +.Xr BIO_new 3 , +.Xr BIO_read 3 , +.Xr BIO_s_connect 3 , +.Xr BIO_set_fd 3 , +.Xr BIO_should_retry 3 , +.Xr udp 4 +.Sh HISTORY +.Fn BIO_s_datagram , +.Fn BIO_new_dgram , +.Fn BIO_dgram_set_peer , +.Fn BIO_ctrl_dgram_connect , +.Fn BIO_ctrl_set_connected , +.Fn BIO_dgram_recv_timedout , +.Fn BIO_dgram_send_timedout , +and +.Fn BIO_dgram_non_fatal_error +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn BIO_dgram_get_peer +first appeared in OpenSSL 0.9.8m and has been available since +.Ox 4.9 . +.Sh BUGS +If +.Xr getsockopt 2 +or +.Xr setsockopt 2 +fails during +.Xr BIO_read 3 , +the library prints an error message to standard error output +but otherwise ignores the problem, thus possibly using unintended +timeout values. +.Pp +.Xr BIO_read 3 +and +.Xr BIO_write 3 +may clear the global variable +.Xr errno 2 +before attempting the +.Xr recvfrom 2 +or +.Xr sendto 2 +system call but may not clear it if they fail before reaching this point. diff --git a/static/openbsd/man3/BIO_s_fd.3 b/static/openbsd/man3/BIO_s_fd.3 new file mode 100644 index 00000000..b1165f30 --- /dev/null +++ b/static/openbsd/man3/BIO_s_fd.3 @@ -0,0 +1,291 @@ +.\" $OpenBSD: BIO_s_fd.3,v 1.14 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_S_FD 3 +.Os +.Sh NAME +.Nm BIO_s_fd , +.Nm BIO_set_fd , +.Nm BIO_get_fd , +.Nm BIO_new_fd , +.Nm BIO_fd_non_fatal_error , +.Nm BIO_fd_should_retry +.Nd file descriptor BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fo BIO_s_fd +.Fa "void" +.Fc +.Ft long +.Fo BIO_set_fd +.Fa "BIO *b" +.Fa "int fd" +.Fa "long close_flag" +.Fc +.Ft long +.Fo BIO_get_fd +.Fa "BIO *b" +.Fa "int *c" +.Fc +.Ft BIO * +.Fo BIO_new_fd +.Fa "int fd" +.Fa "int close_flag" +.Fc +.Ft int +.Fn BIO_fd_non_fatal_error "int errnum" +.Ft int +.Fn BIO_fd_should_retry "int retval" +.Sh DESCRIPTION +.Fn BIO_s_fd +returns the file descriptor BIO method. +This is a wrapper around the platform's file descriptor routines such as +.Xr read 2 +and +.Xr write 2 . +.Pp +.Xr BIO_read 3 +and +.Xr BIO_write 3 +read or write the underlying descriptor. +.Xr BIO_puts 3 +is supported but +.Xr BIO_gets 3 +is not. +.Pp +If the close flag is set, +.Xr close 2 +is called on the underlying file descriptor when the +.Vt BIO +is freed. +.Pp +.Xr BIO_reset 3 +attempts to set the file pointer to the start of the file using +.Fn lseek fd 0 0 . +.Pp +.Xr BIO_seek 3 +sets the file pointer to position +.Fa ofs +from start of file using +.Fn lseek fd ofs 0 . +.Pp +.Xr BIO_tell 3 +returns the current file position by calling +.Fn lseek fd 0 1 . +.Pp +.Fn BIO_set_fd +sets the file descriptor of +.Vt BIO +.Fa b +to +.Fa fd +and the close flag to +.Fa close_flag . +.Pp +.Fn BIO_get_fd +places the file descriptor in +.Fa c +if it is not +.Dv NULL +and also returns the file descriptor. +.Pp +.Fn BIO_new_fd +returns a file descriptor BIO using +.Fa fd +and +.Fa close_flag . +.Pp +.Fn BIO_fd_non_fatal_error +determines whether the error status code +.Fa errnum +represents a recoverable error. +.Fn BIO_fd_should_retry +determines whether a recoverable error occurred by inspecting both +.Xr errno 2 +and +.Fa retval , +which is supposed to usually be +the return value of a previously called function like +.Xr BIO_read 3 +or +.Xr BIO_write 3 . +These two functions are mostly used internally; in application code, +it is usually easier and more robust to use +.Xr BIO_should_retry 3 , +which works for any BIO type. +.Pp +The behaviour of +.Xr BIO_read 3 +and +.Xr BIO_write 3 +depends on the behavior of the platform's +.Xr read 2 +and +.Xr write 2 +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 +.Xr BIO_read 3 +and +.Xr BIO_should_retry 3 +manual pages. +.Pp +File descriptor BIOs should not be used for socket I/O. +Use socket BIOs instead. +.Pp +.Xr BIO_ctrl 3 +.Fa cmd +arguments correspond to macros as follows: +.Bl -column BIO_CTRL_GET_CLOSE BIO_get_close(3) -offset 3n +.It Fa cmd No constant Ta corresponding macro +.It Dv BIO_C_FILE_SEEK Ta Xr BIO_seek 3 +.It Dv BIO_C_FILE_TELL Ta Xr BIO_tell 3 +.It Dv BIO_C_GET_FD Ta Fn BIO_get_fd +.It Dv BIO_C_SET_FD Ta Fn BIO_set_fd +.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3 +.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 +.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3 +.El +.Sh RETURN VALUES +.Fn BIO_s_fd +returns the file descriptor BIO method. +.Pp +When called on a file descriptor BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_FD +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq file descriptor . +.Pp +.Fn BIO_set_fd +always returns 1. +.Pp +.Fn BIO_get_fd +returns the file descriptor or -1 if the +.Vt BIO +has not been initialized. +.Pp +.Fn BIO_new_fd +returns the newly allocated +.Vt BIO +or +.Dv NULL +if an error occurred. +.Pp +.Fn BIO_fd_non_fatal_error +returns 1 if +.Fa errnum +is +.Dv EAGAIN , +.Dv EALREADY , +.Dv EINPROGRESS , +.Dv EINTR , +or +.Dv ENOTCONN +and 0 otherwise, even if +.Fa errnum +is 0. +.Pp +.Fn BIO_fd_should_retry +returns 1 if +.Fn BIO_fd_non_fatal_error errno +is 1 and +.Fa retval +is either 0 or \-1, or 0 otherwise. +.Sh EXAMPLES +This is a file descriptor BIO version of "Hello World": +.Bd -literal -offset indent +BIO *out; +out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE); +BIO_printf(out, "Hello World\en"); +BIO_free(out); +.Ed +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr BIO_read 3 , +.Xr BIO_s_socket 3 , +.Xr BIO_seek 3 , +.Xr BIO_should_retry 3 +.Sh HISTORY +.Fn BIO_s_fd , +.Fn BIO_set_fd , +and +.Fn BIO_get_fd +first appeared in SSLeay 0.6.0, +.Fn BIO_fd_should_retry +in SSLeay 0.6.5, and +.Fn BIO_new_fd +and +.Fn BIO_fd_non_fatal_error +in SSLeay 0.8.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BIO_s_file.3 b/static/openbsd/man3/BIO_s_file.3 new file mode 100644 index 00000000..d59e157c --- /dev/null +++ b/static/openbsd/man3/BIO_s_file.3 @@ -0,0 +1,378 @@ +.\" $OpenBSD: BIO_s_file.3,v 1.18 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2010 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_S_FILE 3 +.Os +.Sh NAME +.Nm BIO_s_file , +.Nm BIO_new_file , +.Nm BIO_new_fp , +.Nm BIO_set_fp , +.Nm BIO_get_fp , +.Nm BIO_read_filename , +.Nm BIO_write_filename , +.Nm BIO_append_filename , +.Nm BIO_rw_filename +.\" Nm BIO_CTRL_SET_FILENAME is unused and intentionally undocumented. +.Nd FILE BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fo BIO_s_file +.Fa void +.Fc +.Ft BIO * +.Fo BIO_new_file +.Fa "const char *filename" +.Fa "const char *mode" +.Fc +.Ft BIO * +.Fo BIO_new_fp +.Fa "FILE *stream" +.Fa "int flags" +.Fc +.Ft long +.Fo BIO_set_fp +.Fa "BIO *b" +.Fa "FILE *fp" +.Fa "int flags" +.Fc +.Ft long +.Fo BIO_get_fp +.Fa "BIO *b" +.Fa "FILE **fpp" +.Fc +.Ft long +.Fo BIO_read_filename +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Ft long +.Fo BIO_write_filename +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Ft long +.Fo BIO_append_filename +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Ft long +.Fo BIO_rw_filename +.Fa "BIO *b" +.Fa "char *name" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_file +returns the BIO file method. +As its name implies, it is a wrapper around the stdio +.Vt FILE +structure and it is a source/sink BIO. +.Pp +Calls to +.Xr BIO_read 3 +and +.Xr BIO_write 3 +read and write data to the underlying stream. +.Xr BIO_gets 3 +and +.Xr BIO_puts 3 +are supported on file BIOs. +.Pp +.Xr BIO_flush 3 +on a file BIO calls the +.Xr fflush 3 +function on the wrapped stream. +.Pp +.Xr BIO_reset 3 +attempts to change the file pointer to the start of file using +.Fn fseek stream 0 0 . +.Pp +.Xr BIO_seek 3 +sets the file pointer to position +.Fa ofs +from the start of the file using +.Fn fseek stream ofs 0 . +.Pp +.Xr BIO_eof 3 +calls +.Xr feof 3 . +.Pp +Setting the +.Dv BIO_CLOSE +flag calls +.Xr fclose 3 +on the stream when the BIO is freed. +.Pp +.Fn BIO_new_file +creates a new file BIO with mode +.Fa mode . +The meaning of +.Fa mode +is the same as for the stdio function +.Xr fopen 3 . +The +.Dv BIO_CLOSE +flag is set on the returned BIO. +.Pp +.Fn BIO_new_fp +creates a file BIO wrapping +.Fa stream . +Flags can be: +.Dv BIO_CLOSE , BIO_NOCLOSE Pq the close flag , +.Dv BIO_FP_TEXT +(sets the underlying stream to text mode, default is binary: +this only has any effect under Win32). +.Pp +.Fn BIO_set_fp +sets the file pointer of a file BIO to +.Fa fp . +.Fa flags +has the same meaning as in +.Fn BIO_new_fp . +.Pp +.Fn BIO_get_fp +retrieves the file pointer of a file BIO. +.Pp +.Xr BIO_seek 3 +sets the position pointer to +.Fa offset +bytes from the start of file. +.Pp +.Xr BIO_tell 3 +returns the value of the position pointer. +.Pp +.Fn BIO_read_filename , +.Fn BIO_write_filename , +.Fn BIO_append_filename , +and +.Fn BIO_rw_filename +set the file BIO +.Fa b +to use file +.Fa name +for reading, writing, append or read write respectively. +.Pp +When wrapping stdout, stdin, or stderr, the underlying stream +should not normally be closed, so the +.Dv 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, +.Fn BIO_new_files +reserves for the filename argument to be UTF-8 encoded. +In other words, if you have to make it work in a multi-lingual +environment, encode file names in UTF-8. +.Pp +The following +.Xr BIO_ctrl 3 +.Fa cmd +constants correspond to macros: +.Bl -column BIO_C_GET_FILE_PTR "corresponding macro" -offset 3n +.It Fa cmd No constant Ta corresponding macro +.It Dv BIO_C_FILE_SEEK Ta Xr BIO_seek 3 +.It Dv BIO_C_FILE_TELL Ta Xr BIO_tell 3 +.It Dv BIO_C_GET_FILE_PTR Ta Fn BIO_get_fp +.It Dv BIO_C_SET_FILE_PTR Ta Fn BIO_set_fp +.It Dv BIO_C_SET_FILENAME Ta various, see below +.It Dv BIO_CTRL_EOF Ta Xr BIO_eof 3 +.It Dv BIO_CTRL_FLUSH Ta Xr BIO_flush 3 +.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3 +.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 +.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3 +.El +.Pp +The meaning of +.Dv BIO_C_SET_FILENAME +depends on the flags passed in the +.Xr BIO_ctrl 3 +.Fa larg +argument: +.Bl -column "BIO_CLOSE | BIO_FP_READ | BIO_FP_WRITE" "BIO_append_filename()"\ + -offset 3n +.It Fa larg No argument Ta corresponding macro +.It Dv BIO_CLOSE | BIO_FP_READ Ta Fn BIO_read_filename +.It Dv BIO_CLOSE | BIO_FP_WRITE Ta Fn BIO_write_filename +.It Dv BIO_CLOSE | BIO_FP_APPEND Ta Fn BIO_append_filename +.It Dv BIO_CLOSE | BIO_FP_READ | BIO_FP_WRITE Ta Fn BIO_rw_filename +.El +.Sh RETURN VALUES +.Fn BIO_s_file +returns the file BIO method. +.Pp +.Fn BIO_new_file +and +.Fn BIO_new_fp +return a file BIO or +.Dv NULL +if an error occurred. +.Pp +When called on a file BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_FILE +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq FILE pointer . +.Pp +.Fn BIO_set_fp +and +.Fn BIO_get_fp +return 1 for success or 0 for failure (although the current +implementation never returns 0). +.Pp +.Xr BIO_seek 3 +returns the same value as the underlying +.Xr fseek 3 +function: 0 for success or -1 for failure. +.Pp +.Xr BIO_tell 3 +returns the current file position. +.Pp +.Fn BIO_read_filename , +.Fn BIO_write_filename , +.Fn BIO_append_filename , +and +.Fn BIO_rw_filename +return 1 for success or 0 for failure. +.Sh EXAMPLES +File BIO "hello world": +.Bd -literal -offset indent +BIO *bio_out; +bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); +BIO_printf(bio_out, "Hello World\en"); +.Ed +.Pp +Alternative technique: +.Bd -literal -offset indent +BIO *bio_out; +bio_out = BIO_new(BIO_s_file()); +if(bio_out == NULL) /* Error ... */ +if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ +BIO_printf(bio_out, "Hello World\en"); +.Ed +.Pp +Write to a file: +.Bd -literal -offset indent +BIO *out; +out = BIO_new_file("filename.txt", "w"); +if(!out) /* Error occurred */ +BIO_printf(out, "Hello World\en"); +BIO_free(out); +.Ed +.Pp +Alternative technique: +.Bd -literal -offset indent +BIO *out; +out = BIO_new(BIO_s_file()); +if(out == NULL) /* Error ... */ +if(!BIO_write_filename(out, "filename.txt")) /* Error ... */ +BIO_printf(out, "Hello World\en"); +BIO_free(out); +.Ed +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr BIO_read 3 , +.Xr BIO_seek 3 +.Sh HISTORY +.Fn BIO_s_file , +.Fn BIO_set_fp , +.Fn BIO_get_fp , +.Fn BIO_read_filename , +.Fn BIO_write_filename , +and +.Fn BIO_append_filename +first appeared in SSLeay 0.6.0. +.Fn BIO_new_file +and +.Fn BIO_new_fp +first appeared in SSLeay 0.8.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_rw_filename +first appeared in SSLeay 0.9.1 and has been available since +.Ox 2.6 . +.Sh BUGS +.Xr BIO_reset 3 +and +.Xr BIO_seek 3 +are implemented using +.Xr fseek 3 +on the underlying stream. +The return value for +.Xr fseek 3 +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. diff --git a/static/openbsd/man3/BIO_s_mem.3 b/static/openbsd/man3/BIO_s_mem.3 new file mode 100644 index 00000000..61b9a9c7 --- /dev/null +++ b/static/openbsd/man3/BIO_s_mem.3 @@ -0,0 +1,322 @@ +.\" $OpenBSD: BIO_s_mem.3,v 1.21 2026/03/10 05:50:11 tb Exp $ +.\" full merge up to: OpenSSL 8711efb4 Mon Apr 20 11:33:12 2009 +0000 +.\" selective merge up to: OpenSSL 36359cec Mar 7 14:37:23 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: March 10 2026 $ +.Dt BIO_S_MEM 3 +.Os +.Sh NAME +.Nm BIO_s_mem , +.Nm BIO_set_mem_eof_return , +.Nm BIO_get_mem_data , +.Nm BIO_set_mem_buf , +.Nm BIO_get_mem_ptr , +.Nm BIO_new_mem_buf +.Nd memory BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fo BIO_s_mem +.Fa "void" +.Fc +.Ft long +.Fo BIO_set_mem_eof_return +.Fa "BIO *b" +.Fa "int v" +.Fc +.Ft long +.Fo BIO_get_mem_data +.Fa "BIO *b" +.Fa "char **pp" +.Fc +.Ft long +.Fo BIO_set_mem_buf +.Fa "BIO *b" +.Fa "BUF_MEM *bm" +.Fa "int c" +.Fc +.Ft long +.Fo BIO_get_mem_ptr +.Fa "BIO *b" +.Fa "BUF_MEM **pp" +.Fc +.Ft BIO * +.Fo BIO_new_mem_buf +.Fa "const void *buf" +.Fa "int len" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_mem +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 +.Vt BUF_MEM +structure which is extended as appropriate to accommodate the stored data. +.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. +To find out whether a memory BIO is read only, +.Xr BIO_test_flags 3 +can be called with an argument of +.Dv BIO_FLAGS_MEM_RDONLY . +.Pp +Memory BIOs support +.Xr BIO_gets 3 +and +.Xr BIO_puts 3 . +.Pp +If the +.Dv BIO_CLOSE +flag is set when a memory BIO is freed, the underlying +.Dv BUF_MEM +structure is also freed. +.Pp +Calling +.Xr BIO_reset 3 +on a read/write memory BIO clears any data in it. +On a read only BIO it restores the BIO to its original state +and the read only data can be read again. +.Pp +.Xr BIO_eof 3 +is true if no data is in the BIO. +.Pp +.Xr BIO_ctrl_pending 3 +returns the number of bytes currently stored. +.Pp +.Fn BIO_set_mem_eof_return +sets the behaviour of memory BIO +.Fa b +when it is empty. +If +.Fa v +is zero, then an empty memory BIO will return EOF: +it will return zero and +.Fn BIO_should_retry +will be false. +If +.Fa v +is non-zero then it will return +.Fa v +when it is empty and it will set the read retry flag: +.Fn BIO_read_retry +is true. +To avoid ambiguity with a normal positive return value +.Fa v +should be set to a negative value, typically -1. +.Pp +.Fn BIO_get_mem_data +sets +.Pf * Fa pp +to a pointer to the start of the memory BIO's data +and returns the total amount of data available. +.Pp +.Fn BIO_set_mem_buf +sets the internal BUF_MEM structure to +.Fa bm +and sets the close flag to +.Fa c . +That is, +.Fa c +should be either +.Dv BIO_CLOSE +or +.Dv BIO_NOCLOSE . +.Pp +.Fn BIO_get_mem_ptr +places the underlying +.Vt BUF_MEM +structure in +.Pf * Fa pp . +.Pp +.Fn BIO_new_mem_buf +creates a memory BIO using +.Fa len +bytes of data at +.Fa buf . +If +.Fa len +is -1, then +.Fa buf +is assumed to be NUL terminated and its length is determined by +.Xr strlen 3 . +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 +.Em not +copied first, so the supplied area of memory must be unchanged +until the BIO is freed. +.Pp +Writes to memory BIOs will always succeed if memory is available: +their size can grow indefinitely. +.Pp +.Xr BIO_ctrl 3 +.Fa cmd +arguments correspond to macros as follows: +.Bl -column BIO_C_SET_BUF_MEM_EOF_RETURN BIO_set_mem_eof_return() -offset 3n +.It Fa cmd No constant Ta corresponding macro +.It Dv BIO_C_GET_BUF_MEM_PTR Ta Fn BIO_get_mem_ptr +.It Dv BIO_C_SET_BUF_MEM Ta Fn BIO_set_mem_buf +.It Dv BIO_C_SET_BUF_MEM_EOF_RETURN Ta Fn BIO_set_mem_eof_return +.It Dv BIO_CTRL_EOF Ta Xr BIO_eof 3 +.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3 +.It Dv BIO_CTRL_INFO Ta Fn BIO_get_mem_data +.It Dv BIO_CTRL_PENDING Ta Xr BIO_pending 3 +.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 +.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3 +.It Dv BIO_CTRL_WPENDING Ta Xr BIO_wpending 3 +.El +.Sh RETURN VALUES +.Fn BIO_s_mem +returns a pointer to a static object. +.Pp +When called on a memory BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_MEM +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq memory buffer . +.Pp +.Fn BIO_set_mem_eof_return , +.Fn BIO_set_mem_buf , +and +.Fn BIO_get_mem_ptr +return 1 on success or a value less than or equal to 0 if an error occurred. +.Pp +.Fn BIO_get_mem_data +returns the number of bytes available for reading at +.Pf * Fa ptr +on success, or a value less than or equal to zero if an error occurs. +Error conditions include that +.Fa b +is +.Dv NULL , +no data is available, or any error of +.Xr BIO_ctrl 3 , +including error returns of a callback called with a +.Dv BIO_CB_CTRL +or +.Dv BIO_CB_CTRL Ns | Ns BIO_CB_RETURN +operation. +.Pp +.Fn BIO_new_mem_buf +returns a newly allocated +.Vt BIO +object on success or +.Dv NULL +on error. +.Sh EXAMPLES +Create a memory BIO and write some data to it: +.Bd -literal -offset indent +BIO *mem = BIO_new(BIO_s_mem()); +BIO_puts(mem, "Hello World\en"); +.Ed +.Pp +Create a read only memory BIO: +.Bd -literal -offset indent +char data[] = "Hello World"; +BIO *mem; +mem = BIO_new_mem_buf(data, -1); +.Ed +.Pp +Extract the +.Vt BUF_MEM +structure from a memory BIO and then free up the BIO: +.Bd -literal -offset indent +BUF_MEM *bptr; +BIO_get_mem_ptr(mem, &bptr); +/* Make sure BIO_free() leaves BUF_MEM alone. */ +BIO_set_close(mem, BIO_NOCLOSE); +BIO_free(mem); +.Ed +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr BUF_MEM_new 3 +.Sh HISTORY +.Fn BIO_s_mem +first appeared in SSLeay 0.6.0. +.Fn BIO_set_mem_buf +and +.Fn BIO_get_mem_ptr +first appeared in SSLeay 0.6.5. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_set_mem_eof_return +and +.Fn BIO_get_mem_data +first appeared in SSLeay 0.9.1 and have been available since +.Ox 2.6 . +.Pp +.Fn BIO_new_mem_buf +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Sh CAVEATS +Do not manually switch a writable memory BIO to read-only mode: calling +.Xr BIO_set_flags 3 +with an argument of +.Dv BIO_FLAGS_MEM_RDONLY +will ultimately result in a memory leak when the BIO object is +finally handed to +.Xr BIO_free 3 . +It might also cause security issues because it prevents +.Xr BIO_reset 3 +from clearing the data. +.Sh BUGS +There should be an option to set the maximum size of a memory BIO. +.Pp +There should be a way to "rewind" a read/write BIO without destroying +its contents. diff --git a/static/openbsd/man3/BIO_s_null.3 b/static/openbsd/man3/BIO_s_null.3 new file mode 100644 index 00000000..7198797b --- /dev/null +++ b/static/openbsd/man3/BIO_s_null.3 @@ -0,0 +1,101 @@ +.\" $OpenBSD: BIO_s_null.3,v 1.12 2025/07/16 18:10:53 tb Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: July 16 2025 $ +.Dt BIO_S_NULL 3 +.Os +.Sh NAME +.Nm BIO_s_null +.Nd null data sink +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fo BIO_s_null +.Fa void +.Fc +.Sh DESCRIPTION +.Fn BIO_s_null +returns the null sink BIO method. +Data written to the null sink is discarded, reads return EOF. +.Pp +A null sink BIO behaves in a similar manner to the +.Xr null 4 +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 +.Fn BIO_s_null +returns the null sink BIO method. +.Pp +When called on a null sink BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_NULL +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq NULL , +not to be confused with a NUL string nor with a +.Dv NULL +pointer. +.Sh SEE ALSO +.Xr BIO_new 3 +.Sh HISTORY +.Fn BIO_s_null +first appeared in SSLeay 0.6.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BIO_s_socket.3 b/static/openbsd/man3/BIO_s_socket.3 new file mode 100644 index 00000000..aebf399b --- /dev/null +++ b/static/openbsd/man3/BIO_s_socket.3 @@ -0,0 +1,126 @@ +.\" $OpenBSD: BIO_s_socket.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL bbdc9c98 Oct 19 22:02:21 2000 +0000 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_S_SOCKET 3 +.Os +.Sh NAME +.Nm BIO_s_socket , +.Nm BIO_new_socket +.Nd socket BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft const BIO_METHOD * +.Fo BIO_s_socket +.Fa void +.Fc +.Ft BIO * +.Fo BIO_new_socket +.Fa "int sock" +.Fa "int close_flag" +.Fc +.Sh DESCRIPTION +.Fn BIO_s_socket +returns the socket BIO method. +This is a wrapper around the platform's socket routines. +.Pp +.Xr BIO_read 3 +and +.Xr BIO_write 3 +read or write the underlying socket. +.Xr BIO_puts 3 +is supported but +.Xr BIO_gets 3 +is not. +.Pp +If the close flag is set, then the socket is shut down and closed +when the BIO is freed. +.Pp +.Fn BIO_new_socket +returns a socket BIO using +.Fa sock +and +.Fa close_flag . +.Pp +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 +.Fn BIO_s_socket +returns the socket BIO method. +.Pp +.Fn BIO_new_socket +returns the newly allocated BIO or +.Dv NULL +if an error occurred. +.Pp +When called on a socket BIO object, +.Xr BIO_method_type 3 +returns the constant +.Dv BIO_TYPE_SOCKET +and +.Xr BIO_method_name 3 +returns a pointer to the static string +.Qq socket . +.Sh SEE ALSO +.Xr BIO_get_fd 3 , +.Xr BIO_new 3 +.Sh HISTORY +.Fn BIO_s_socket +first appeared in SSLeay 0.6.0. +.Fn BIO_new_socket +first appeared in SSLeay 0.8.0. +Both functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BIO_set_callback.3 b/static/openbsd/man3/BIO_set_callback.3 new file mode 100644 index 00000000..f3f40cba --- /dev/null +++ b/static/openbsd/man3/BIO_set_callback.3 @@ -0,0 +1,397 @@ +.\" $OpenBSD: BIO_set_callback.3,v 1.13 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2022 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_SET_CALLBACK 3 +.Os +.Sh NAME +.Nm BIO_callback_fn_ex , +.Nm BIO_set_callback_ex , +.Nm BIO_get_callback_ex , +.Nm BIO_callback_fn , +.Nm BIO_set_callback , +.Nm BIO_get_callback , +.Nm BIO_set_callback_arg , +.Nm BIO_get_callback_arg , +.Nm BIO_debug_callback +.\" The following three macros are intentionally undocumented because +.\" they are unused and would only cause obfuscation if they were used. +.\" .Nm BIO_CB_return +.\" .Nm BIO_cb_pre +.\" .Nm BIO_cb_post +.Nd BIO callback functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft typedef long +.Fo (*BIO_callback_fn_ex) +.Fa "BIO *b" +.Fa "int oper" +.Fa "const char *argp" +.Fa "size_t len" +.Fa "int argi" +.Fa "long argl" +.Fa "int ret" +.Fa "size_t *processed" +.Fc +.Ft void +.Fo BIO_set_callback_ex +.Fa "BIO *b" +.Fa "BIO_callback_fn_ex cb_ex" +.Fc +.Ft BIO_callback_fn_ex +.Fo BIO_get_callback_ex +.Fa "const BIO *b" +.Fc +.Ft typedef long +.Fo (*BIO_callback_fn) +.Fa "BIO *b" +.Fa "int oper" +.Fa "const char *argp" +.Fa "int argi" +.Fa "long argl" +.Fa "long ret" +.Fc +.Ft void +.Fo BIO_set_callback +.Fa "BIO *b" +.Fa "BIO_callback_fn cb" +.Fc +.Ft BIO_callback_fn +.Fo BIO_get_callback +.Fa "BIO *b" +.Fc +.Ft void +.Fo BIO_set_callback_arg +.Fa "BIO *b" +.Fa "char *pointer" +.Fc +.Ft char * +.Fo BIO_get_callback_arg +.Fa "const BIO *b" +.Fc +.Ft long +.Fo BIO_debug_callback +.Fa "BIO *bio" +.Fa "int oper" +.Fa "const char *argp" +.Fa "int argi" +.Fa "long argl" +.Fa "long ret" +.Fc +.Sh DESCRIPTION +.Fn BIO_set_callback_ex +and +.Fn BIO_get_callback_ex +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 +.Fn BIO_set_callback +and +.Fn BIO_get_callback +are deprecated functions that set and retrieve the old-style BIO callback, +which is only used if no new-style callback is set with +.Fn BIO_set_callback_ex . +.Pp +.Fn BIO_set_callback_arg +stores the +.Fa pointer +internally in +.Fa b +and +.Fn BIO_get_callback_arg +retrieves it from +.Fa b . +The name of these two functions is badly misleading: the +.Fa pointer +is never passed as an argument to any callback function. +But of course, callback functions can call +.Fn BIO_get_callback_arg +and access the pointer, just like any other code can. +.Pp +.Fn BIO_debug_callback +is a standard debugging callback which prints +out information related to each BIO operation. +If +.Fn BIO_set_callback_arg +was called with a +.Pf non- Dv NULL +argument, information is sent to the BIO pointed to by the +.Fa pointer ; +otherwise, standard error output is used. +.Pp +The arguments of the callback functions are as follows: +.Bl -tag -width Ds +.It Fa b +The BIO the callback is attached to. +.It Fa oper +The operation being performed, which is one of +.Dv BIO_CB_CTRL , +.Dv BIO_CB_FREE , +.Dv BIO_CB_GETS , +.Dv BIO_CB_PUTS , +.Dv BIO_CB_READ , +or +.Dv BIO_CB_WRITE . +For some operations, the callback is called twice, +once before and once after the actual operation. +The latter case has +.Fa oper +OR'ed with +.Dv BIO_CB_RETURN . +.It Fa argp , argi , argl +The meaning of these three arguments depends on the value of +.Fa oper , +that is on the operation being performed. +.It Fa len +The length of the data requested to be read or written. +This is only useful if +.Fa oper +is +.Dv BIO_CB_READ , +.Dv BIO_CB_WRITE , +or +.Dv BIO_CB_GETS . +.It Fa ret +When +.Fa oper +does not include +.Dv BIO_CB_RETURN , +i.e. when the callback is invoked before an operation, +the value passed into the callback via +.Fa ret +is always 1. +In this case, if the callback returns a negative value, the library +aborts the requested operation and instead returns the negative +return value from the callback to the application. +If the callback returns a non-negative value, that return value is +ignored by the library, and the operation is performed normally. +.Pp +When +.Fa oper +includes +.Dv BIO_CB_RETURN , +i.e. when the callback is invoked after an operation, +the value passed into the callback via +.Fa ret +is the return value that the operation would return to the application +if no callback were present. +When a callback is present, the operation only passes this value +to the callback and instead of it returns the return value of the +callback to the application. +.It Fa processed +The location pointed to is updated with the number of bytes +actually read or written. +Only used for +.Dv BIO_CB_READ , +.Dv BIO_CB_WRITE , +.Dv BIO_CB_GETS , +and +.Dv BIO_CB_PUTS . +.El +.Pp +The callback should normally simply return +.Fa ret +when it has finished processing, unless it specifically wishes to +abort the operation or to modify the value returned to the application. +.Pp +The callbacks are called as follows: +.Bl -tag -width 1n +.It \&In Fn BIO_free "BIO *b" : +.Bd -literal +before the free operation: +cb_ex(b, BIO_CB_FREE, NULL, 0, 0, 0, 1, NULL) +or cb(b, BIO_CB_FREE, NULL, 0, 0, 1) +.Ed +.It \&In Fn BIO_read "BIO *b" "void *out" "int outl" : +.Bd -literal +before the read operation: +cb_ex(b, BIO_CB_READ, out, outl, 0, 0, 1, NULL) +or cb(b, BIO_CB_READ, out, outl, 0, 1) + +after the read operation: +cb_ex(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes) +or cb(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0, ret) +.Ed +.It \&In Fn BIO_write "BIO *b" "const void *in" "int inl" : +.Bd -literal +before the write operation: +cb_ex(b, BIO_CB_WRITE, in, inl, 0, 0, 1, NULL) +or cb(b, BIO_CB_WRITE, in, inl, 0, 1) + +after the write operation: +cb_ex(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0, 0, ret, &bytes) +or cb(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0, ret) +.Ed +.It \&In Fn BIO_gets "BIO *b" "char *out" "int outl" : +.Bd -literal +before the read operation: +cb_ex(b, BIO_CB_GETS, out, outl, 0, 0, 1, NULL) +or cb(b, BIO_CB_GETS, out, outl, 0, 1) + +after the read operation: +cb_ex(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes) +or cb(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0, ret) +.Ed +.It \&In Fn BIO_puts "BIO *b" "const char *in" : +.Bd -literal +before the write operation: +cb_ex(b, BIO_CB_PUTS, in, 0, 0, 0, 1, NULL) +or cb(b, BIO_CB_PUTS, in, 0, 0, 1) + +after the write operation: +cb_ex(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0, 0, ret, &bytes) +or cb(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0, ret) +.Ed +.It \&In Fn BIO_ctrl "BIO *b" "int cmd" "long larg" "void *parg" : +.Bd -literal +before the control operation: +cb_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1, NULL) +or cb(b, BIO_CB_CTRL, parg, cmd, larg, 1) + +after the control operation: +cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL) +or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret) +.Ed +.It \&In Fn BIO_callback_ctrl "BIO *b" "int cmd" "BIO_info_cb *fp" : +.Bd -literal +before the control operation: +cb_ex(b, BIO_CB_CTRL, fp, 0, cmd, 0, 1, NULL) +or cb(b, BIO_CB_CTRL, fp, cmd, 0, 1) + +after the control operation: +cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, fp, 0, cmd, 0, ret, NULL) +or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, fp, cmd, 0, ret) +.Ed +.El +.Sh RETURN VALUES +.Fn BIO_get_callback_ex +returns a pointer to the function +.Fa cb_ex +previously installed with +.Fn BIO_set_callback_cb , +or +.Dv NULL +if no such callback was installed. +.Pp +.Fn BIO_get_callback +returns a pointer to the function +.Fa cb +previously installed with +.Fn BIO_set_callback , +or +.Dv NULL +if no such callback was installed. +.Pp +.Fn BIO_get_callback_arg +returns the +.Fa pointer +previously set with +.Fn BIO_set_callback_arg , +or +.Dv NULL +if no such pointer was set. +.Pp +.Fn BIO_debug_callback +returns +.Fa ret +if the bit +.Dv BIO_CB_RETURN +is set in +.Fa cmd , +or 1 otherwise. +.Sh EXAMPLES +The +.Fn BIO_debug_callback +function is a good example. +Its source is in the file +.Pa crypto/bio/bio_cb.c . +.Sh SEE ALSO +.Xr BIO_new 3 +.Sh HISTORY +.Fn BIO_set_callback , +.Fn BIO_get_callback , +.Fn BIO_set_callback_arg , +and +.Fn BIO_debug_callback +first appeared in SSLeay 0.6.0. +.Fn BIO_get_callback_arg +first appeared in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_callback_fn +first appeared in OpenSSL 1.1.0. +.Fn BIO_callback_fn_ex , +.Fn BIO_set_callback_ex , +and +.Fn BIO_get_callback_ex +first appeared in OpenSSL 1.1.1. +These functions have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/BIO_should_retry.3 b/static/openbsd/man3/BIO_should_retry.3 new file mode 100644 index 00000000..4a0948ff --- /dev/null +++ b/static/openbsd/man3/BIO_should_retry.3 @@ -0,0 +1,302 @@ +.\" $OpenBSD: BIO_should_retry.3,v 1.12 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" selective merge up to: OpenSSL 57fd5170 May 13 11:24:11 2018 +0200 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2010, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BIO_SHOULD_RETRY 3 +.Os +.Sh NAME +.Nm BIO_should_read , +.Nm BIO_should_write , +.Nm BIO_should_io_special , +.Nm BIO_retry_type , +.Nm BIO_should_retry , +.Nm BIO_get_retry_BIO , +.Nm BIO_get_retry_reason , +.Nm BIO_set_retry_reason +.Nd BIO retry functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bio.h +.Ft int +.Fo BIO_should_read +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_should_write +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_should_io_special +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_retry_type +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_should_retry +.Fa "BIO *b" +.Fc +.Fd #define BIO_FLAGS_READ 0x01 +.Fd #define BIO_FLAGS_WRITE 0x02 +.Fd #define BIO_FLAGS_IO_SPECIAL 0x04 +.Fd #define BIO_FLAGS_RWS \e +.Fd \& (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL) +.Fd #define BIO_FLAGS_SHOULD_RETRY 0x08 +.Ft BIO * +.Fo BIO_get_retry_BIO +.Fa "BIO *bio" +.Fa "int *reason" +.Fc +.Ft int +.Fo BIO_get_retry_reason +.Fa "BIO *bio" +.Fc +.Ft void +.Fo BIO_set_retry_reason +.Fa "BIO *bio" +.Fa "int reason" +.Fc +.Sh DESCRIPTION +These functions determine why a BIO is not able to read or write data. +They will typically be called after a failed +.Xr BIO_read 3 +or +.Xr BIO_write 3 +call. +.Pp +.Fn BIO_should_retry +returns 1 if the call that produced this condition should be retried +at a later time, or 0 if an error occurred. +.Pp +.Fn BIO_should_read +returns 1 if the cause of the retry condition is that a BIO needs +to read data, or 0 otherwise. +.Pp +.Fn BIO_should_write +returns 1 if the cause of the retry condition is that a BIO needs +to write data, or 0 otherwise. +.Pp +.Fn BIO_should_io_special +returns 1 if some special condition (i.e. a reason other than reading +or writing) is the cause of the retry condition, or 0 otherwise. +.Pp +.Fn BIO_retry_type +returns the bitwise OR of one or more of the flags +.Dv BIO_FLAGS_READ , +.Dv BIO_FLAGS_WRITE , +and +.Dv BIO_FLAGS_IO_SPECIAL +representing the cause of the current retry condition, +or 0 if there is no retry condition. +Current BIO types only set one of the flags at a time. +.Pp +.Fn BIO_get_retry_BIO +determines the precise reason for the special condition. +It walks the BIO chain starting at +.Fa bio +and returns the BIO that caused this condition. +If there is no special condition, +.Fa bio +itself is returned. +If +.Fa reason +is not a +.Dv NULL +pointer, +.Pf * Fa reason +is set to one of the following reason codes: +.Bl -tag -width 1n -offset 3n +.It 0 +There is no special condition. +.It Dv BIO_RR_ACCEPT +.Xr accept 2 +would have blocked. +This can occur for BIOs created from +.Xr BIO_s_accept 3 +or +.Xr BIO_f_ssl 3 . +.It Dv BIO_RR_CONNECT +.Xr connect 2 +would have blocked. +This can occur for BIOs created from +.Xr BIO_s_connect 3 +or +.Xr BIO_f_ssl 3 . +.It Dv BIO_RR_SSL_X509_LOOKUP +An application callback set by +.Xr SSL_CTX_set_client_cert_cb 3 +has asked to be called again. +This can occur for BIOs created from +.Xr BIO_f_ssl 3 . +.El +.Pp +.Fn BIO_get_retry_reason +returns one of the above reason codes for a special condition that occurred in +.Fa bio . +It does not walk the chain and returns 0 if no special condition occurred in +.Fa bio +itself. +.Pp +.Fn BIO_set_retry_reason +sets the retry reason for a special condition for the given +.Fa bio . +It is intended to be called by functions implementing a BIO type +rather than by functions merely using BIOs. +.Pp +.Fn BIO_should_retry , +.Fn BIO_should_read , +.Fn BIO_should_write , +.Fn BIO_should_io_special , +and +.Fn BIO_retry_type +are implemented as macros. +.Pp +If +.Fn BIO_should_retry +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 +.Xr BIO_read 3 +on a socket BIO returns 0 and +.Fn BIO_should_retry +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 +.Fn BIO_should_retry +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 +.Xr BIO_read 3 . +An application can retry the failed call immediately +or avoid this situation by setting +.Dv 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 +.Fn BIO_should_read +is true then a call to +.Xr select 2 +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 +.Xr select 2 +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 +.Xr select 2 +(or equivalent) call. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr BIO_read 3 +.Sh HISTORY +.Fn BIO_should_read , +.Fn BIO_should_write , +.Fn BIO_retry_type , +and +.Fn BIO_should_retry +first appeared in SSLeay 0.6.0. +.Fn BIO_should_io_special , +.Fn BIO_get_retry_BIO , +and +.Fn BIO_get_retry_reason +first appeared in SSLeay 0.8.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn BIO_set_retry_reason +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.1 . +.Sh BUGS +The OpenSSL ASN.1 functions cannot gracefully deal with non-blocking I/O: +they cannot retry after a partial read or write. +This is usually worked around by only passing the relevant data to ASN.1 +functions when the entire structure can be read or written. diff --git a/static/openbsd/man3/BN_CTX_new.3 b/static/openbsd/man3/BN_CTX_new.3 new file mode 100644 index 00000000..0d5a3e84 --- /dev/null +++ b/static/openbsd/man3/BN_CTX_new.3 @@ -0,0 +1,124 @@ +.\" $OpenBSD: BN_CTX_new.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL aafbe1cc Jun 12 23:42:08 2013 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_CTX_NEW 3 +.Os +.Sh NAME +.Nm BN_CTX_new , +.Nm BN_CTX_free +.Nd allocate and free BN_CTX structures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft BN_CTX * +.Fo BN_CTX_new +.Fa void +.Fc +.Ft void +.Fo BN_CTX_free +.Fa "BN_CTX *c" +.Fc +.Sh DESCRIPTION +A +.Vt BN_CTX +is a structure that holds +.Vt BIGNUM +temporary variables used by library functions. +Since dynamic memory allocation to create +.Vt BIGNUM Ns s +is rather expensive when used in conjunction with repeated subroutine +calls, the +.Vt BN_CTX +structure is used. +.Pp +.Fn BN_CTX_new +allocates and initializes a +.Vt BN_CTX +structure. +.Pp +.Fn BN_CTX_free +frees the components of the +.Vt BN_CTX +and, if it was created by +.Fn BN_CTX_new , +also the structure itself. +If +.Xr BN_CTX_start 3 +has been used on the +.Vt BN_CTX , +.Xr BN_CTX_end 3 +must be called before the +.Vt BN_CTX +may be freed by +.Fn BN_CTX_free . +If +.Fa c +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn BN_CTX_new +returns a pointer to the +.Vt BN_CTX . +If the allocation fails, it returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_add 3 , +.Xr BN_CTX_start 3 , +.Xr BN_new 3 +.Sh HISTORY +.Fn BN_CTX_new +and +.Fn BN_CTX_free +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BN_CTX_start.3 b/static/openbsd/man3/BN_CTX_start.3 new file mode 100644 index 00000000..27159ce9 --- /dev/null +++ b/static/openbsd/man3/BN_CTX_start.3 @@ -0,0 +1,138 @@ +.\" $OpenBSD: BN_CTX_start.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_CTX_START 3 +.Os +.Sh NAME +.Nm BN_CTX_start , +.Nm BN_CTX_get , +.Nm BN_CTX_end +.Nd use temporary BIGNUM variables +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft void +.Fo BN_CTX_start +.Fa "BN_CTX *ctx" +.Fc +.Ft BIGNUM * +.Fo BN_CTX_get +.Fa "BN_CTX *ctx" +.Fc +.Ft void +.Fo BN_CTX_end +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +These functions are used to obtain temporary +.Vt BIGNUM +variables from a +.Vt BN_CTX +(which can be created using +.Xr BN_CTX_new 3 ) +in order to save the overhead of repeatedly creating and freeing +.Vt BIGNUM Ns s +in functions that are called from inside a loop. +.Pp +A function must call +.Fn BN_CTX_start +first. +Then, +.Fn BN_CTX_get +may be called repeatedly to obtain temporary +.Vt BIGNUM Ns s . +All +.Fn BN_CTX_get +calls must be made before calling any other functions that use the +.Fa ctx +as an argument. +.Pp +Finally, +.Fn BN_CTX_end +must be called before returning from the function. +When +.Fn BN_CTX_end +is called, the +.Vt BIGNUM +pointers obtained from +.Fn BN_CTX_get +become invalid. +If +.Fa ctx +is +.Dv NULL , +no action occurs. +.Sh RETURN VALUES +.Fn BN_CTX_get +returns a pointer to the +.Vt BIGNUM , +or +.Dv NULL +on error. +Once +.Fn BN_CTX_get +has failed, the subsequent calls will return +.Dv NULL +as well, so it is sufficient to check the return value of the last +.Fn BN_CTX_get +call. +In case of an error, an error code is set which can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_CTX_new 3 , +.Xr BN_new 3 +.Sh HISTORY +.Fn BN_CTX_start , +.Fn BN_CTX_get , +and +.Fn BN_CTX_end +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/BN_add.3 b/static/openbsd/man3/BN_add.3 new file mode 100644 index 00000000..32378f69 --- /dev/null +++ b/static/openbsd/man3/BN_add.3 @@ -0,0 +1,644 @@ +.\" $OpenBSD: BN_add.3,v 1.21 2025/06/08 22:37:23 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 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. +.\" +.\" The original file was written by Ulf Moeller +.\" and Bodo Moeller . +.\" Copyright (c) 2000, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_ADD 3 +.Os +.Sh NAME +.Nm BN_add , +.Nm BN_uadd , +.Nm BN_sub , +.Nm BN_usub , +.Nm BN_mul , +.Nm BN_sqr , +.Nm BN_div , +.Nm BN_mod , +.Nm BN_nnmod , +.Nm BN_mod_add , +.Nm BN_mod_add_quick , +.Nm BN_mod_sub , +.Nm BN_mod_sub_quick , +.Nm BN_mod_mul , +.Nm BN_mod_sqr , +.Nm BN_mod_lshift , +.Nm BN_mod_lshift_quick , +.Nm BN_mod_lshift1 , +.Nm BN_mod_lshift1_quick , +.Nm BN_exp , +.Nm BN_mod_exp , +.\" The following are public, but intentionally undocumented for now: +.\" .Nm BN_mod_exp_mont , r \(== a ^ p (mod m) +.\" .Nm BN_mod_exp_mont_consttime , +.\" Maybe they should be deleted from . +.Nm BN_gcd +.Nd arithmetic operations on BIGNUMs +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft int +.Fo BN_add +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fc +.Ft int +.Fo BN_uadd +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fc +.Ft int +.Fo BN_sub +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fc +.Ft int +.Fo BN_usub +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fc +.Ft int +.Fo BN_mul +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_sqr +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_div +.Fa "BIGNUM *dv" +.Fa "BIGNUM *rem" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *d" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod +.Fa "BIGNUM *rem" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_nnmod +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_add +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_add_quick +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "const BIGNUM *m" +.Fc +.Ft int +.Fo BN_mod_sub +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_sub_quick +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "const BIGNUM *m" +.Fc +.Ft int +.Fo BN_mod_mul +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_sqr +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_lshift +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "int n" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_lshift_quick +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "int n" +.Fa "const BIGNUM *m" +.Fc +.Ft int +.Fo BN_mod_lshift1 +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_lshift1_quick +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *m" +.Fc +.Ft int +.Fo BN_exp +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *p" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_exp +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_gcd +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn BN_add +adds +.Fa a +and +.Fa b +and places the result in +.Fa r +.Pq Li r=a+b . +.Fa r +may be the same +.Vt BIGNUM +as +.Fa a +or +.Fa b . +.Pp +.Fn BN_uadd +adds the absolute values of +.Fa a +and +.Fa b +and places the result in +.Fa r +.Pq Li r=|a|+|b|\& . +.Fa r +may be the same +.Vt BIGNUM +as +.Fa a +or +.Fa b . +.Pp +.Fn BN_sub +subtracts +.Fa b +from +.Fa a +and places the result in +.Fa r +.Pq Li r=a-b . +.Fa r +may be the same +.Vt BIGNUM +as +.Fa a +or +.Fa b . +.Pp +.Fn BN_usub +subtracts the absolute value of +.Fa b +from the absolute value of +.Fa a +and places the result in +.Fa r +.Pq Li r=|a|-|b|\& . +It requires the absolute value of +.Fa a +to be greater than the absolute value of +.Fa b ; +otherwise it will fail. +.Fa r +may be the same +.Vt BIGNUM +as +.Fa a +or +.Fa b . +.Pp +.Fn BN_mul +multiplies +.Fa a +and +.Fa b +and places the result in +.Fa r +.Pq Li r=a*b . +.Fa r +may be the same +.Vt BIGNUM +as +.Fa a +or +.Fa b . +For multiplication by powers of 2, use +.Xr BN_lshift 3 . +.Pp +.Fn BN_sqr +takes the square of +.Fa a +and places the result in +.Fa r +.Pq Li r=a^2 . +.Fa r +and +.Fa a +may be the same +.Vt BIGNUM . +This function is faster than +.Fn BN_mul r a a . +.Pp +.Fn BN_div +divides +.Fa a +by +.Fa d +and places the result in +.Fa dv +and the remainder in +.Fa rem +.Pq Li dv=a/d , rem=a%d . +If the flag +.Dv BN_FLG_CONSTTIME +is set on +.Fa a +or +.Fa d , +it operates in constant time. +Either of +.Fa dv +and +.Fa rem +may be +.Dv NULL , +in which case the respective value is not returned. +The result is rounded towards zero; thus if +.Fa a +is negative, the remainder will be zero or negative. +For division by powers of 2, use +.Fn BN_rshift 3 . +.Pp +.Fn BN_mod +corresponds to +.Fn BN_div +with +.Fa dv +set to +.Dv NULL . +It is implemented as a macro. +.Pp +.Fn BN_nnmod +reduces +.Fa a +modulo +.Fa m +and places the non-negative remainder in +.Fa r . +.Pp +.Fn BN_mod_add +adds +.Fa a +to +.Fa b +modulo +.Fa m +and places the non-negative result in +.Fa r . +.Pp +.Fn BN_mod_add_quick +is a variant of +.Fn BN_mod_add +that requires +.Fa a +and +.Fa b +to both be non-negative and smaller than +.Fa m . +If any of these constraints are violated, +it silently produces wrong results. +.Pp +.Fn BN_mod_sub +subtracts +.Fa b +from +.Fa a +modulo +.Fa m +and places the non-negative result in +.Fa r . +.Pp +.Fn BN_mod_sub_quick +is a variant of +.Fn BN_mod_sub +that requires +.Fa a +and +.Fa b +to both be non-negative and smaller than +.Fa m . +If any of these constraints are violated, +it silently produces wrong results. +.Pp +.Fn BN_mod_mul +multiplies +.Fa a +by +.Fa b +and finds the non-negative remainder respective to modulus +.Fa m +.Pq Li r=(a*b)%m . +.Fa r +may be the same +.Vt BIGNUM +as +.Fa a +or +.Fa b . +For a more efficient algorithm for repeated computations using the same +modulus, see +.Xr BN_mod_mul_montgomery 3 . +.Pp +.Fn BN_mod_sqr +takes the square of +.Fa a +modulo +.Fa m +and places the result in +.Fa r . +.Pp +.Fn BN_mod_lshift +shifts +.Fa a +left by +.Fa n +bits, reduces the result modulo +.Fa m , +and places the non-negative remainder in +.Fa r +.Pq Li r=a*2^n mod m . +.Pp +.Fn BN_mod_lshift1 +shifts +.Fa a +left by one bit, reduces the result modulo +.Fa m , +and places the non-negative remainder in +.Fa r +.Pq Li r=a*2 mod m . +.Pp +.Fn BN_mod_lshift_quick +and +.Fn BN_mod_lshift1_quick +are variants of +.Fn BN_mod_lshift +and +.Fn BN_mod_lshift1 , +respectively, that require +.Fa a +to be non-negative and less than +.Fa m . +If either of these constraints is violated, they sometimes fail +and sometimes silently produce wrong results. +.Pp +.Fn BN_exp +raises +.Fa a +to the +.Fa p Ns -th +power and places the result in +.Fa r +.Pq Li r=a^p . +This function is faster than repeated applications of +.Fn BN_mul . +.Pp +.Fn BN_mod_exp +computes +.Fa a +to the +.Fa p Ns -th +power modulo +.Fa m +.Pq Li r=(a^p)%m . +If the flag +.Dv BN_FLG_CONSTTIME +is set on +.Fa p , +it operates in constant time. +This function uses less time and space than +.Fn BN_exp . +.Pp +.Fn BN_gcd +computes the greatest common divisor of +.Fa a +and +.Fa b +and places the result in +.Fa r . +.Fa r +may be the same +.Vt BIGNUM +as +.Fa a +or +.Fa b . +.Pp +For all functions, +.Fa ctx +is a previously allocated +.Vt BN_CTX +used for temporary variables; see +.Xr BN_CTX_new 3 . +.Pp +Unless noted otherwise, the result +.Vt BIGNUM +must be different from the arguments. +.Sh RETURN VALUES +For all functions, 1 is returned for success, 0 on error. +The return value should always be checked, for example: +.Pp +.Dl if (!BN_add(r,a,b)) goto err; +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_add_word 3 , +.Xr BN_CTX_new 3 , +.Xr BN_new 3 , +.Xr BN_set_bit 3 , +.Xr BN_set_flags 3 , +.Xr BN_set_negative 3 +.Sh HISTORY +.Fn BN_add , +.Fn BN_sub , +.Fn BN_mul , +.Fn BN_sqr , +.Fn BN_div , +.Fn BN_mod , +.Fn BN_mod_mul , +.Fn BN_mod_exp , +and +.Fn BN_gcd +first appeared in SSLeay 0.5.1. +.Fn BN_exp +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn BN_uadd , +.Fn BN_usub , +and the +.Fa ctx +argument to +.Fn BN_mul +first appeared in SSLeay 0.9.1 and have been available since +.Ox 2.6 . +.Pp +.Fn BN_nnmod , +.Fn BN_mod_add , +.Fn BN_mod_add_quick , +.Fn BN_mod_sub , +.Fn BN_mod_sub_quick , +.Fn BN_mod_sqr , +.Fn BN_mod_lshift , +.Fn BN_mod_lshift_quick , +.Fn BN_mod_lshift1 , +and +.Fn BN_mod_lshift1_quick +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Sh BUGS +Even if the +.Dv BN_FLG_CONSTTIME +flag is set on +.Fa a +or +.Fa b , +.Fn BN_gcd +neither fails nor operates in constant time, potentially allowing +timing side-channel attacks. +.Pp +Even if the +.Dv BN_FLG_CONSTTIME +flag is set on +.Fa p , +if the modulus +.Fa m +is even, +.Fn BN_mod_exp +does not operate in constant time, potentially allowing +timing side-channel attacks. +.Pp +If +.Dv BN_FLG_CONSTTIME +is set on +.Fa p , +.Fn BN_exp +fails instead of operating in constant time. diff --git a/static/openbsd/man3/BN_add_word.3 b/static/openbsd/man3/BN_add_word.3 new file mode 100644 index 00000000..b8b45bfb --- /dev/null +++ b/static/openbsd/man3/BN_add_word.3 @@ -0,0 +1,183 @@ +.\" $OpenBSD: BN_add_word.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 9e183d22 Mar 11 08:56:44 2017 -0500 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_ADD_WORD 3 +.Os +.Sh NAME +.Nm BN_add_word , +.Nm BN_sub_word , +.Nm BN_mul_word , +.Nm BN_div_word , +.Nm BN_mod_word +.Nd arithmetic functions on BIGNUMs with integers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft int +.Fo BN_add_word +.Fa "BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft int +.Fo BN_sub_word +.Fa "BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft int +.Fo BN_mul_word +.Fa "BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft BN_ULONG +.Fo BN_div_word +.Fa "BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft BN_ULONG +.Fo BN_mod_word +.Fa "const BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Sh DESCRIPTION +These functions perform arithmetic operations on BIGNUMs with unsigned +integers. +They are much more efficient than the normal BIGNUM arithmetic +operations. +.Pp +.Vt BN_ULONG +is a macro that expands to +.Vt unsigned long Pq = Vt uint64_t +on +.Dv _LP64 +platforms and +.Vt unsigned int Pq = Vt uint32_t +elsewhere. +.Pp +.Fn BN_add_word +adds +.Fa w +to +.Fa a +.Pq Li a+=w . +.Pp +.Fn BN_sub_word +subtracts +.Fa w +from +.Fa a +.Pq Li a-=w . +.Pp +.Fn BN_mul_word +multiplies +.Fa a +and +.Fa w +.Pq Li a*=w . +.Pp +.Fn BN_div_word +divides +.Fa a +by +.Fa w +.Pq Li a/=w +and returns the remainder. +.Pp +.Fn BN_mod_word +returns the remainder of +.Fa a +divided by +.Fa w +.Pq Li a%w . +.Pp +For +.Fn BN_div_word +and +.Fn BN_mod_word , +.Fa w +must not be 0. +.Sh RETURN VALUES +.Fn BN_add_word , +.Fn BN_sub_word , +and +.Fn BN_mul_word +return 1 for success or 0 on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Pp +.Fn BN_mod_word +and +.Fn BN_div_word +return +.Fa a Ns % Ns Fa w +on success and +.Po Vt BN_ULONG Pc Ns -1 +if an error occurred. +.Sh SEE ALSO +.Xr BN_add 3 , +.Xr BN_new 3 +.Sh HISTORY +.Fn BN_add_word , +.Fn BN_div_word , +and +.Fn BN_mod_word +first appeared in SSLeay 0.5.1. +.Fn BN_sub_word +and +.Fn BN_mul_word +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +Before 0.9.8a, the return value for +.Fn BN_div_word +and +.Fn BN_mod_word +in case of an error was 0. diff --git a/static/openbsd/man3/BN_bn2bin.3 b/static/openbsd/man3/BN_bn2bin.3 new file mode 100644 index 00000000..cf72e6dd --- /dev/null +++ b/static/openbsd/man3/BN_bn2bin.3 @@ -0,0 +1,389 @@ +.\" $OpenBSD: BN_bn2bin.3,v 1.17 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file was written by Ulf Moeller +.\" and Dr. Stephen Henson . +.\" Copyright (c) 2000, 2002, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_BN2BIN 3 +.Os +.Sh NAME +.Nm BN_bn2bin , +.Nm BN_bn2binpad , +.Nm BN_bin2bn , +.Nm BN_bn2lebinpad , +.Nm BN_lebin2bn , +.Nm BN_bn2hex , +.Nm BN_bn2dec , +.Nm BN_hex2bn , +.Nm BN_dec2bn , +.Nm BN_asc2bn , +.Nm BN_print , +.Nm BN_print_fp , +.Nm BN_bn2mpi , +.Nm BN_mpi2bn +.Nd format conversions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft int +.Fo BN_bn2bin +.Fa "const BIGNUM *a" +.Fa "unsigned char *to" +.Fc +.Ft int +.Fo BN_bn2binpad +.Fa "const BIGNUM *a" +.Fa "unsigned char *to" +.Fa "int tolen" +.Fc +.Ft BIGNUM * +.Fo BN_bin2bn +.Fa "const unsigned char *s" +.Fa "int len" +.Fa "BIGNUM *ret" +.Fc +.Ft int +.Fo BN_bn2lebinpad +.Fa "const BIGNUM *a" +.Fa "unsigned char *to" +.Fa "int tolen" +.Fc +.Ft BIGNUM * +.Fo BN_lebin2bn +.Fa "const unsigned char *s" +.Fa "int len" +.Fa "BIGNUM *ret" +.Fc +.Ft char * +.Fo BN_bn2hex +.Fa "const BIGNUM *a" +.Fc +.Ft char * +.Fo BN_bn2dec +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_hex2bn +.Fa "BIGNUM **ap" +.Fa "const char *str" +.Fc +.Ft int +.Fo BN_dec2bn +.Fa "BIGNUM **ap" +.Fa "const char *str" +.Fc +.Ft int +.Fo BN_asc2bn +.Fa "BIGNUM **ap" +.Fa "const char *str" +.Fc +.Ft int +.Fo BN_print +.Fa "BIO *fp" +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_print_fp +.Fa "FILE *fp" +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_bn2mpi +.Fa "const BIGNUM *a" +.Fa "unsigned char *to" +.Fc +.Ft BIGNUM * +.Fo BN_mpi2bn +.Fa "unsigned char *s" +.Fa "int len" +.Fa "BIGNUM *ret" +.Fc +.Sh DESCRIPTION +.Fn BN_bn2bin +converts the absolute value of +.Fa a +into big-endian form and stores it at +.Fa to . +.Fa to +must point to +.Fn BN_num_bytes a +bytes of memory. +.Pp +.Fn BN_bn2binpad +also converts the absolute value of +.Fa a +into big-endian form and stores it at +.Fa to . +.Fa tolen +indicates the length of the output buffer +.Pf * Fa to . +The result is padded with zeros if necessary. +If +.Fa tolen +is less than +.Fn BN_num_bytes a , +an error is returned. +.Pp +.Fn BN_bin2bn +converts the positive integer in big-endian form of length +.Fa len +at +.Fa s +into a +.Vt BIGNUM +and places it in +.Fa ret . +If +.Fa ret +is +.Dv NULL , +a new +.Vt BIGNUM +is created. +.Pp +.Fn BN_bn2lebinpad +and +.Fn BN_lebin2bn +are identical to +.Fn BN_bn2binpad +and +.Fn BN_bin2bn +except the buffer +.Pf * Fa to +is in little-endian format. +.Pp +.Fn BN_bn2hex +and +.Fn BN_bn2dec +return printable strings containing the hexadecimal and decimal encoding of +.Fa a +respectively. +For negative numbers, the string is prefaced with a leading minus sign. +The string must be freed later using +.Xr free 3 . +.Pp +.Fn BN_hex2bn +interprets +.Fa str +as a hexadecimal number. +The string may start with a minus sign +.Pq Sq - . +Conversion stops at the first byte that is not a hexadecimal digit. +The number is converted to a +.Vt BIGNUM +and stored in +.Pf ** Fa ap . +If +.Pf * Fa ap +is +.Dv NULL , +a new +.Vt BIGNUM +is created. +If +.Fa ap +is +.Dv NULL , +it only computes the number's length in hexadecimal digits, +also counting the leading minus sign if there is one. +A "negative zero" is converted to zero. +.Fn BN_dec2bn +is the same using the decimal system. +.Fn BN_asc2bn +infers the number base from an optional prefix. +If +.Fa str +starts with +.Qq 0x +or +.Qq 0X , +it calls +.Fn BN_hex2bn , +otherwise +.Fn BN_dec2bn . +If the number is negative, the minus sign can be given before or +after the prefix. +.Pp +.Fn BN_print +and +.Fn BN_print_fp +write the hexadecimal encoding of +.Fa a , +with a leading minus sign for negative numbers, to the +.Vt BIO +or +.Vt FILE +.Fa fp . +.Pp +.Fn BN_bn2mpi +and +.Fn BN_mpi2bn +convert +.Vt BIGNUM Ns s +from and to a format that consists of the number's 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 +a NUL byte). +.Pp +.Fn BN_bn2mpi +stores the representation of +.Fa a +at +.Fa to , +where +.Pf * Fa to +must be large enough to hold the result. +The size can be determined by calling +.Fn BN_bn2mpi a NULL . +.Pp +.Fn BN_mpi2bn +converts the +.Fa len +bytes long representation at +.Fa s +to a +.Vt BIGNUM +and stores it at +.Fa ret , +or in a newly allocated +.Vt BIGNUM +if +.Fa ret +is +.Dv NULL . +.Sh RETURN VALUES +.Fn BN_bn2bin +returns the length of the big-endian number placed at +.Fa to . +.Pp +.Fn BN_bn2binpad +and +.Fn BN_bn2lebinpad +return the number of bytes written +or \-1 if the supplied buffer is too small. +.Pp +.Fn BN_bin2bn +and +.Fn BN_lebin2bn +return the +.Vt BIGNUM , +or +.Dv NULL +on error. +.Pp +.Fn BN_bn2hex +and +.Fn BN_bn2dec +return a NUL-terminated string, or +.Dv NULL +on error. +.Fn BN_hex2bn +and +.Fn BN_dec2bn +return the number's length in hexadecimal or decimal digits, +also counting the leading minus sign if there is one, +or 0 on error, in which case no new +.Vt BIGNUM +is created. +.Fn BN_asc2bn +returns 1 on success or 0 on error, in which case no new +.Vt BIGNUM +is created. +.Pp +.Fn BN_print_fp +and +.Fn BN_print +return 1 on success, 0 on write errors. +.Pp +.Fn BN_bn2mpi +returns the length of the representation. +.Fn BN_mpi2bn +returns the +.Vt BIGNUM , +or +.Dv NULL +on error. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ASN1_INTEGER_to_BN 3 , +.Xr BN_new 3 , +.Xr BN_num_bytes 3 , +.Xr BN_zero 3 +.Sh HISTORY +.Fn BN_bn2bin , +.Fn BN_bin2bn , +and +.Fn BN_print +first appeared in SSLeay 0.5.1. +.Fn BN_print_fp +first appeared in SSLeay 0.6.0. +.Fn BN_bn2hex , +.Fn BN_bn2dec , +.Fn BN_hex2bn , +.Fn BN_dec2bn , +.Fn BN_bn2mpi , +and +.Fn BN_mpi2bn +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn BN_asc2bin +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Pp +.Fn BN_bn2binpad , +.Fn BN_bn2lebinpad , +and +.Fn BN_lebin2bn +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.0 . diff --git a/static/openbsd/man3/BN_cmp.3 b/static/openbsd/man3/BN_cmp.3 new file mode 100644 index 00000000..3837ffcd --- /dev/null +++ b/static/openbsd/man3/BN_cmp.3 @@ -0,0 +1,170 @@ +.\" $OpenBSD: BN_cmp.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 5b31b9df Aug 4 10:45:52 2021 +0300 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_CMP 3 +.Os +.Sh NAME +.Nm BN_cmp , +.Nm BN_ucmp , +.Nm BN_is_zero , +.Nm BN_is_one , +.Nm BN_is_word , +.Nm BN_abs_is_word , +.Nm BN_is_odd +.Nd BIGNUM comparison and test functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft int +.Fo BN_cmp +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fc +.Ft int +.Fo BN_ucmp +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fc +.Ft int +.Fo BN_is_zero +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_is_one +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_is_word +.Fa "const BIGNUM *a" +.Fa "const BN_ULONG w" +.Fc +.Ft int +.Fo BN_abs_is_word +.Fa "const BIGNUM *a" +.Fa "const BN_ULONG w" +.Fc +.Ft int +.Fo BN_is_odd +.Fa "const BIGNUM *a" +.Fc +.Sh DESCRIPTION +.Fn BN_cmp +compares the numbers +.Fa a +and +.Fa b . +.Fn BN_ucmp +compares their absolute values. +.Pp +.Fn BN_is_zero , +.Fn BN_is_one +and +.Fn BN_is_word +test if +.Fa a +equals 0, 1, or +.Fa w +respectively. +.Fn BN_abs_is_word +tests if the absolute value of +.Fa a +equals +.Fa w . +.Fn BN_is_odd +tests if a is odd. +.Pp +.Vt BN_ULONG +is a macro that expands to +.Vt unsigned long Pq = Vt uint64_t +on +.Dv _LP64 +platforms and +.Vt unsigned int Pq = Vt uint32_t +elsewhere. +.Sh RETURN VALUES +.Fn BN_cmp +returns -1 if +.Fa a Ns < Ns Fa b , +0 if +.Fa a Ns == Ns Fa b , +and 1 if +.Fa a Ns > Ns Fa b . +.Fn BN_ucmp +is the same using the absolute values of +.Fa a +and +.Fa b . +.Pp +.Fn BN_is_zero , +.Fn BN_is_one , +.Fn BN_is_word , +.Fn BN_abs_is_word , +and +.Fn BN_is_odd +return 1 if the condition is true, 0 otherwise. +.Sh SEE ALSO +.Xr BN_new 3 +.Sh HISTORY +.Fn BN_cmp , +.Fn BN_ucmp , +.Fn BN_is_zero , +.Fn BN_is_one , +and +.Fn BN_is_word +first appeared in SSLeay 0.5.1. +.Fn BN_is_odd +first appeared in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn BN_abs_is_word +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/BN_copy.3 b/static/openbsd/man3/BN_copy.3 new file mode 100644 index 00000000..5481431e --- /dev/null +++ b/static/openbsd/man3/BN_copy.3 @@ -0,0 +1,166 @@ +.\" $OpenBSD: BN_copy.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller +.\" and Matt Caswell . +.\" Copyright (c) 2000, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_COPY 3 +.Os +.Sh NAME +.Nm BN_copy , +.Nm BN_dup , +.Nm BN_with_flags +.Nd copy BIGNUMs +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft BIGNUM * +.Fo BN_copy +.Fa "BIGNUM *to" +.Fa "const BIGNUM *from" +.Fc +.Ft BIGNUM * +.Fo BN_dup +.Fa "const BIGNUM *from" +.Fc +.Ft void +.Fo BN_with_flags +.Fa "BIGNUM *dest" +.Fa "const BIGNUM *b" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn BN_copy +copies +.Fa from +to +.Fa to . +.Pp +.Fn BN_dup +creates a new +.Vt BIGNUM +containing the value +.Fa from . +.Pp +.Fn BN_with_flags +creates a +.Em temporary +shallow copy of +.Fa b +in +.Fa dest . +It places significant restrictions on the copied data. +Applications that do not adhere to these restrictions +may encounter unexpected side effects or crashes. +For that reason, use of this function is discouraged. +.Pp +Any flags provided in +.Fa flags +will be set in +.Fa dest +in addition to any flags already set in +.Fa b . +For example, this can be used to create a temporary copy of a +.Vt BIGNUM +with the +.Dv BN_FLG_CONSTTIME +flag set for constant time operations. +.Pp +The temporary copy in +.Fa dest +will share some internal state with +.Fa b . +For this reason, the following restrictions apply to the use of +.Fa dest : +.Bl -bullet +.It +.Fa dest +should be a newly allocated +.Vt BIGNUM +obtained via a call to +.Xr BN_new 3 . +It should not have been used for other purposes or initialised in any way. +.It +.Fa dest +must only be used in "read-only" operations, i.e. typically those +functions where the relevant parameter is declared "const". +.It +.Fa dest +must be used and freed before any further subsequent use of +.Fa b . +.El +.Sh RETURN VALUES +.Fn BN_copy +returns +.Fa to +on success or +.Dv NULL +on error. +.Fn BN_dup +returns the new +.Vt BIGNUM +or +.Dv NULL +on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_new 3 , +.Xr BN_set_flags 3 +.Sh HISTORY +.Fn BN_copy +and +.Fn BN_dup +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn BN_with_flags +first appeared in OpenSSL 0.9.7h and 0.9.8a +and has been available since +.Ox 4.0 . diff --git a/static/openbsd/man3/BN_generate_prime.3 b/static/openbsd/man3/BN_generate_prime.3 new file mode 100644 index 00000000..55eed14e --- /dev/null +++ b/static/openbsd/man3/BN_generate_prime.3 @@ -0,0 +1,376 @@ +.\" $OpenBSD: BN_generate_prime.3,v 1.26 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL f987a4dd Jun 27 10:12:08 2019 +0200 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022 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. +.\" +.\" The original file was written by Ulf Moeller +.\" Bodo Moeller , and Matt Caswell . +.\" Copyright (c) 2000, 2003, 2013, 2014, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_GENERATE_PRIME 3 +.Os +.Sh NAME +.Nm BN_is_prime_ex , +.Nm BN_is_prime_fasttest_ex , +.Nm BN_generate_prime_ex , +.Nm BN_GENCB_call , +.Nm BN_GENCB_new , +.Nm BN_GENCB_free , +.Nm BN_GENCB_set , +.Nm BN_GENCB_get_arg , +.Nm BN_GENCB_set_old +.\" Nm BN_prime_checks_for_size is intentionally undocumented +.\" because it should not be used outside of libcrypto. +.Nd generate primes and test for primality +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft int +.Fo BN_is_prime_ex +.Fa "const BIGNUM *a" +.Fa "int nchecks" +.Fa "BN_CTX *ctx" +.Fa "BN_GENCB *cb" +.Fc +.Ft int +.Fo BN_is_prime_fasttest_ex +.Fa "const BIGNUM *a" +.Fa "int nchecks" +.Fa "BN_CTX *ctx" +.Fa "int do_trial_division" +.Fa "BN_GENCB *cb" +.Fc +.Ft int +.Fo BN_generate_prime_ex +.Fa "BIGNUM *ret" +.Fa "int bits" +.Fa "int safe" +.Fa "const BIGNUM *modulus" +.Fa "const BIGNUM *remainder" +.Fa "BN_GENCB *cb" +.Fc +.Ft int +.Fo BN_GENCB_call +.Fa "BN_GENCB *cb" +.Fa "int state_code" +.Fa "int serial_number" +.Fc +.Ft BN_GENCB * +.Fn BN_GENCB_new void +.Ft void +.Fo BN_GENCB_free +.Fa "BN_GENCB *cb" +.Fc +.Ft void +.Fo BN_GENCB_set +.Fa "BN_GENCB *cb" +.Fa "int (*cb_fp)(int, int, BN_GENCB *)" +.Fa "void *cb_arg" +.Fc +.Ft void * +.Fo BN_GENCB_get_arg +.Fa "BN_GENCB *cb" +.Fc +.Pp +Deprecated: +.Pp +.Ft void +.Fo BN_GENCB_set_old +.Fa "BN_GENCB *cb" +.Fa "void (*cb_fp)(int, int, void *)" +.Fa "void *cb_arg" +.Fc +.Sh DESCRIPTION +.Fn BN_is_prime_ex +and +.Fn BN_is_prime_fasttest_ex +test whether the number +.Fa a +is prime. +In LibreSSL, both functions behave identically +and use the Baillie-Pomerance-Selfridge-Wagstaff algorithm +combined with +.Fa checks +Miller-Rabin rounds. +The +.Fa do_trial_division +argument is ignored. +.Pp +It is unknown whether any composite number exists that the +Baillie-PSW algorithm misclassifies as a prime. +Some suspect that there may be infinitely many such numbers, +but not a single one is currently known. +It is known that no such number exists below 2\(ha64. +.Pp +In order to reduce the likelihood of a composite number +passing the primality tests +.Fn BN_is_prime_fasttest_ex +and +.Fn BN_is_prime_ex , +a number of rounds of the probabilistic Miller-Rabin test is performed. +If +.Fa checks +is positive, it is used as the number of rounds; +if it is zero or the special value +.Dv BN_prime_checks , +a suitable number of rounds is calculated from the bit length of +.Fa a . +.Pp +If +.Dv NULL +is passed for the +.Fa ctx +argument, these function allocate a +.Vt BN_CTX +object internally when they need one and free it before returning. +Alternatively, to save the overhead of allocating and freeing +that object for each call, the caller can pre-allocate a +.Vt BN_CTX +object and pass it in the +.Fa ctx +argument. +.Pp +.Fn BN_generate_prime_ex +generates a pseudo-random prime number of at least bit length +.Fa bits +and places it in +.Fa ret . +Primality of +.Fa ret +is tested internally using +.Fn BN_is_prime_ex . +Consequently, for +.Fa bits +larger than 64, it is theoretically possible +that this function might place a composite number into +.Fa ret ; +the probability of such an event is unknown but very small. +.Pp +The prime may have to fulfill additional requirements for use in +Diffie-Hellman key exchange: +.Bl -bullet +.It +If +.Fa modulus +is not +.Dv NULL , +a prime is generated that fulfills the condition +.Fa ret No % Fa modulus No = Fa remainder . +If the +.Fa remainder +argument is +.Dv NULL , +1 is used as the desired remainder. +.It +If the +.Fa safe +argument is non-zero, a safe prime is generated, that is, +.Po Fa ret No \- 1 Pc Ns /2 +is also prime. +.El +.Pp +If +.Fa cb +is not +.Dv NULL , +it is used as follows: +.Bl -bullet +.It +.Fn BN_GENCB_call cb 0 serial_number +is called after generating a potential prime number. +.It +The +.Fa state_code +of 1 is reserved for callbacks during primality testing, +but LibreSSL performs no such callbacks. +.It +When +.Fa safe +is non-zero and a safe prime has been found, +.Fn BN_GENCB_call cb 2 serial_number +is called. +.It +The callers of +.Fn BN_generate_prime_ex +may call +.Fn BN_GENCB_call +with other values as described in their respective manual pages; see +.Sx SEE ALSO . +.El +.Pp +In all cases, the +.Fa serial_number +is the number of candidates that have already been discarded +for not being prime; that is, +.Fa serial_number +is 0 for the first candidate +and then incremented whenever a new candidate is generated. +.Pp +.Fn BN_GENCB_call +calls the callback function held in +.Fa cb +and passes the +.Fa state_code +and the +.Fa serial_number +as arguments. +If +.Fa cb +is +.Dv NULL +or does not contain a callback function, no action occurs. +.Pp +.Fn BN_GENCB_new +allocates a new +.Vt BN_GENCB +object. +.Pp +.Fn BN_GENCB_free +frees +.Fa cb . +If +.Fa cb +is +.Dv NULL , +no action occurs. +.Pp +.Fn BN_GENCB_set +initialises +.Fa cb +to use the callback function pointer +.Fa cb_fp +and the additional callback argument +.Fa cb_arg . +.Pp +The deprecated function +.Fn BN_GENCB_set_old +initialises +.Fa cb +to use the old-style callback function pointer +.Fa cb_fp +and the additional callback argument +.Fa cb_arg . +.Sh RETURN VALUES +.Fn BN_is_prime_ex +and +.Fn BN_is_prime_fasttest_ex +return 0 if the number is composite, 1 if it is prime with a very small +error probability, or \-1 on error. +.Pp +.Fn BN_generate_prime_ex +returns 1 on success or 0 on error. +.Pp +.Fn BN_GENCB_call +returns 1 on success, including when +.Fa cb +is +.Dv NULL +or does not contain a callback function, +or 0 on error. +.Pp +.Fn BN_GENCB_new +returns a pointer to the newly allocated +.Vt BN_GENCB +object or +.Dv NULL +if memory allocation fails. +.Pp +The callback functions pointed to by the +.Fa cb_fp +arguments are supposed to return 1 on success or 0 on error. +.Pp +.Fn BN_GENCB_get_arg +returns the +.Fa cb_arg +pointer that was previously stored in +.Fa cb +using +.Fn BN_GENCB_set +or +.Fn BN_GENCB_set_old . +.Pp +In some cases, error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_new 3 , +.Xr DH_generate_parameters 3 , +.Xr DSA_generate_parameters_ex 3 , +.Xr RSA_generate_key 3 +.Sh HISTORY +.Fn BN_generate_prime_ex , +.Fn BN_is_prime_ex , +.Fn BN_is_prime_fasttest_ex , +.Fn BN_GENCB_call , +.Fn BN_GENCB_set_old , +and +.Fn BN_GENCB_set +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn BN_GENCB_new , +.Fn BN_GENCB_free , +and +.Fn BN_GENCB_get_arg +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/BN_get_rfc3526_prime_8192.3 b/static/openbsd/man3/BN_get_rfc3526_prime_8192.3 new file mode 100644 index 00000000..41345de2 --- /dev/null +++ b/static/openbsd/man3/BN_get_rfc3526_prime_8192.3 @@ -0,0 +1,154 @@ +.\" $OpenBSD: BN_get_rfc3526_prime_8192.3,v 1.2 2025/06/08 22:40:29 schwarze Exp $ +.\" checked up to: OpenSSL DH_get_1024_160 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" Copyright (c) 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 $Mdocdate: June 8 2025 $ +.Dt BN_GET_RFC3526_PRIME_8192 3 +.Os +.Sh NAME +.Nm BN_get_rfc2409_prime_768 , +.Nm BN_get_rfc2409_prime_1024 , +.Nm BN_get_rfc3526_prime_1536 , +.Nm BN_get_rfc3526_prime_2048 , +.Nm BN_get_rfc3526_prime_3072 , +.Nm BN_get_rfc3526_prime_4096 , +.Nm BN_get_rfc3526_prime_6144 , +.Nm BN_get_rfc3526_prime_8192 +.Nd standard moduli for Diffie-Hellman key exchange +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft BIGNUM * +.Fn BN_get_rfc2409_prime_768 "BIGNUM *bn" +.Ft BIGNUM * +.Fn BN_get_rfc2409_prime_1024 "BIGNUM *bn" +.Ft BIGNUM * +.Fn BN_get_rfc3526_prime_1536 "BIGNUM *bn" +.Ft BIGNUM * +.Fn BN_get_rfc3526_prime_2048 "BIGNUM *bn" +.Ft BIGNUM * +.Fn BN_get_rfc3526_prime_3072 "BIGNUM *bn" +.Ft BIGNUM * +.Fn BN_get_rfc3526_prime_4096 "BIGNUM *bn" +.Ft BIGNUM * +.Fn BN_get_rfc3526_prime_6144 "BIGNUM *bn" +.Ft BIGNUM * +.Fn BN_get_rfc3526_prime_8192 "BIGNUM *bn" +.Sh DESCRIPTION +Each of these functions returns one specific constant Sophie Germain +prime number +.Fa p . +.Pp +If +.Fa bn +is +.Dv NULL , +a new +.Vt BIGNUM +object is created and returned. +Otherwise, the number is stored in +.Pf * Fa bn +and +.Fa bn +is returned. +.Pp +All these numbers are of the form +.Pp +.EQ +p = 2 sup s - 2 sup left ( s - 64 right ) - 1 + 2 sup 64 * +left { left [ 2 sup left ( s - 130 right ) pi right ] + offset right } +delim $$ +.EN +.Pp +where +.Ar s +is the size of the binary representation of the number in bits +and appears at the end of the function names. +As long as the offset is sufficiently small, the above form assures +that the top and bottom 64 bits of each number are all 1. +.Pp +The offsets are defined in the standards as follows: +.Bl -column "8192 = 2 * 2^12" "4743158" -offset indent +.It size Ar s Ta Ar offset +.It Ta +.It \ 768 = 3 * 2^8 Ta 149686 +.It 1024 = 2 * 2^9 Ta 129093 +.It 1536 = 3 * 2^9 Ta 741804 +.It 2048 = 2 * 2^10 Ta 124476 +.It 3072 = 3 * 2^10 Ta 1690314 +.It 4096 = 2 * 2^11 Ta 240904 +.It 6144 = 3 * 2^11 Ta 929484 +.It 8192 = 2 * 2^12 Ta 4743158 +.El +.Pp +For each of these prime numbers, the finite group of natural numbers +smaller than +.Fa p , +where the group operation is defined as multiplication modulo +.Fa p , +is used for Diffie-Hellman key exchange. +The first two of these groups are called the First Oakley Group and +the Second Oakley Group. +Obviously, all these groups are cyclic groups of order +.Fa p , +respectively, and the numbers returned by these functions are not +secrets. +.Sh RETURN VALUES +If memory allocation fails, these functions return +.Dv NULL . +That can happen even if +.Fa bn +is not +.Dv NULL . +.Sh SEE ALSO +.Xr BN_mod_exp 3 , +.Xr BN_new 3 , +.Xr BN_set_flags 3 , +.Xr DH_new 3 +.Sh STANDARDS +RFC 2409, "The Internet Key Exchange (IKE)", defines the Oakley Groups. +.Pp +RFC 2412, "The OAKLEY Key Determination Protocol", contains additional +information about these numbers. +.Pp +RFC 3526, "More Modular Exponential (MODP) Diffie-Hellman groups +for Internet Key Exchange (IKE)", defines the other six numbers. +.Sh HISTORY +.Fn BN_get_rfc2409_prime_768 , +.Fn BN_get_rfc2409_prime_1024 , +.Fn BN_get_rfc3526_prime_1536 , +.Fn BN_get_rfc3526_prime_2048 , +.Fn BN_get_rfc3526_prime_3072 , +.Fn BN_get_rfc3526_prime_4096 , +.Fn BN_get_rfc3526_prime_6144 , +and +.Fn BN_get_rfc3526_prime_8192 +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +The same functions without +.Sy BN_ +prefix first appeared in OpenSSL 0.9.8a and +.Ox 4.5 ; +they were removed in +.Ox 7.4 . +.Sh CAVEATS +As all the memory needed for storing the numbers is dynamically +allocated, the +.Dv BN_FLG_STATIC_DATA +flag is not set on the returned +.Vt BIGNUM +objects. +So be careful to not change the returned numbers. diff --git a/static/openbsd/man3/BN_kronecker.3 b/static/openbsd/man3/BN_kronecker.3 new file mode 100644 index 00000000..6a5b7ecd --- /dev/null +++ b/static/openbsd/man3/BN_kronecker.3 @@ -0,0 +1,58 @@ +.\" $OpenBSD: BN_kronecker.3,v 1.3 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2022 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 $Mdocdate: June 8 2025 $ +.Dt BN_KRONECKER 3 +.Os +.Sh NAME +.Nm BN_kronecker +.Nd Kronecker symbol +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft int +.Fo BN_kronecker +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn BN_kronecker +computes the Kronecker symbol +.Pq a | b , +which generalizes the Legendre and Jacobi symbols +for arbitrary integer numbers +.Fa b . +.Sh RETURN VALUES +.Fn BN_kronecker +returns \-1, 0, or 1 in case of success or \-2 on error. +.Sh SEE ALSO +.Xr BN_CTX_new 3 , +.Xr BN_gcd 3 , +.Xr BN_mod_sqrt 3 , +.Xr BN_new 3 +.Rs +.%A Henri Cohen +.%B A Course in Computational Algebraic Number Theory +.%I Springer +.%C Berlin +.%D 1993 +.%O Algorithm 1.4.10 +.Re +.Sh HISTORY +.Fn BN_kronecker +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/BN_mod_inverse.3 b/static/openbsd/man3/BN_mod_inverse.3 new file mode 100644 index 00000000..ce10fa21 --- /dev/null +++ b/static/openbsd/man3/BN_mod_inverse.3 @@ -0,0 +1,127 @@ +.\" $OpenBSD: BN_mod_inverse.3,v 1.14 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_MOD_INVERSE 3 +.Os +.Sh NAME +.Nm BN_mod_inverse +.Nd compute inverse modulo m +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft BIGNUM * +.Fo BN_mod_inverse +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn BN_mod_inverse +computes the inverse of +.Fa a +modulo +.Fa m +and places the result in +.Fa r , +so that +.Fa r +satisfies +.Li a * r == 1 (mod m) . +If +.Fa r +is +.Dv NULL , +a new +.Vt BIGNUM +is allocated. +.Pp +If the flag +.Dv BN_FLG_CONSTTIME +is set on +.Fa a +or +.Fa m , +it operates in constant time. +.Pp +.Fa ctx +is a previously allocated +.Vt BN_CTX +used for temporary variables. +.Fa r +may be the same +.Vt BIGNUM +as +.Fa a +or +.Fa m . +.Sh RETURN VALUES +.Fn BN_mod_inverse +returns the +.Vt BIGNUM +containing the inverse, or +.Dv NULL +on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_add 3 , +.Xr BN_new 3 , +.Xr BN_set_flags 3 +.Sh HISTORY +.Fn BN_mod_inverse +first appeared in SSLeay 0.5.1 and has been available since +.Ox 2.4 . +.Pp +The +.Fa r +argument was added in SSLeay 0.9.1 and +.Ox 2.6 . diff --git a/static/openbsd/man3/BN_mod_mul_montgomery.3 b/static/openbsd/man3/BN_mod_mul_montgomery.3 new file mode 100644 index 00000000..2f9e3a53 --- /dev/null +++ b/static/openbsd/man3/BN_mod_mul_montgomery.3 @@ -0,0 +1,272 @@ +.\" $OpenBSD: BN_mod_mul_montgomery.3,v 1.17 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 6859cf74 Sep 25 13:33:28 2002 +0000 +.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 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. +.\" +.\" The original file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_MOD_MUL_MONTGOMERY 3 +.Os +.Sh NAME +.Nm BN_MONT_CTX_new , +.Nm BN_MONT_CTX_free , +.Nm BN_MONT_CTX_set , +.Nm BN_MONT_CTX_set_locked , +.Nm BN_MONT_CTX_copy , +.Nm BN_mod_mul_montgomery , +.Nm BN_from_montgomery , +.Nm BN_to_montgomery +.Nd Montgomery multiplication +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft BN_MONT_CTX * +.Fo BN_MONT_CTX_new +.Fa void +.Fc +.Ft void +.Fo BN_MONT_CTX_free +.Fa "BN_MONT_CTX *mont" +.Fc +.Ft int +.Fo BN_MONT_CTX_set +.Fa "BN_MONT_CTX *mont" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft BN_MONT_CTX * +.Fo BN_MONT_CTX_set_locked +.Fa "BN_MONT_CTX **pmont" +.Fa "int lock" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft BN_MONT_CTX * +.Fo BN_MONT_CTX_copy +.Fa "BN_MONT_CTX *to" +.Fa "const BN_MONT_CTX *from" +.Fc +.Ft int +.Fo BN_mod_mul_montgomery +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_MONT_CTX *mont" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_from_montgomery +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "BN_MONT_CTX *mont" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_to_montgomery +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "BN_MONT_CTX *mont" +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +These functions implement Montgomery multiplication. +They are used automatically when +.Xr BN_mod_exp 3 +is called with suitable input, but they may be useful when several +operations are to be performed using the same modulus. +.Pp +.Fn BN_MONT_CTX_new +allocates and initializes a +.Vt BN_MONT_CTX +structure. +.Pp +.Fn BN_MONT_CTX_set +sets up the +.Fa mont +structure from the modulus +.Fa m +by precomputing its inverse and a value R. +.Pp +.Fn BN_MONT_CTX_set_locked +is a wrapper around +.Fn BN_MONT_CTX_new +and +.Fn BN_MONT_CTX_set +that is useful if more than one thread intends to use the same +.Vt BN_MONT_CTX +and none of these threads is exclusively responsible for creating +and initializing the context. +.Fn BN_MONT_CTX_set_locked +first acquires the specified +.Fa lock +using +.Xr CRYPTO_lock 3 . +If +.Pf * Fa pmont +already differs from +.Dv NULL , +no action occurs. +Otherwise, a new +.Vt BN_MONT_CTX +is allocated with +.Fn BN_MONT_CTX_new , +set up with +.Fn BN_MONT_CTX_set , +and a pointer to it is stored in +.Pf * Fa pmont . +Finally, the +.Fa lock +is released. +.Pp +.Fn BN_MONT_CTX_copy +copies the +.Vt BN_MONT_CTX +.Fa from +to +.Fa to . +.Pp +.Fn BN_MONT_CTX_free +frees the components of the +.Vt BN_MONT_CTX , +and, if it was created by +.Fn BN_MONT_CTX_new , +also the structure itself. +If +.Fa mont +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn BN_mod_mul_montgomery +computes +.Pp +.D1 Mont Ns Po Fa a , Fa b Pc := Fa a No * Fa b No * R^-1 +.Pp +and places the result in +.Fa r . +.Pp +.Fn BN_from_montgomery +performs the Montgomery reduction +.Pp +.D1 Fa r No = Fa a No * R^-1 +.Pp +.Fn BN_to_montgomery +computes +.Pp +.D1 Mont Ns Po Fa a , No R^2 Pc = Fa a No * R +.Pp +Note that +.Fa a +must be non-negative and smaller than the modulus. +.Pp +For all functions, +.Fa ctx +is a previously allocated +.Vt BN_CTX +used for temporary variables. +.Pp +.Sy Warning : +The inputs must be reduced modulo +.Fa m , +otherwise the result will be outside the expected range. +.Sh RETURN VALUES +.Fn BN_MONT_CTX_new +returns the newly allocated +.Vt BN_MONT_CTX +or +.Dv NULL +on error. +.Pp +.Fn BN_MONT_CTX_set_locked +returns a pointer to the existing or newly created context or +.Dv NULL +on error. +.Pp +For the other functions, 1 is returned for success or 0 on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_add 3 , +.Xr BN_CTX_new 3 , +.Xr BN_new 3 , +.Xr CRYPTO_lock 3 +.Sh HISTORY +.Fn BN_MONT_CTX_new , +.Fn BN_MONT_CTX_free , +.Fn BN_MONT_CTX_set , +.Fn BN_mod_mul_montgomery , +.Fn BN_from_montgomery , +and +.Fn BN_to_montgomery +first appeared in SSLeay 0.6.1 and have been available since +.Ox 2.4 . +.Pp +.Fn BN_MONT_CTX_copy +first appeared in SSLeay 0.9.1 and has been available since +.Ox 2.6 . +.Pp +.Fn BN_MONT_CTX_set_locked +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.0 . diff --git a/static/openbsd/man3/BN_mod_sqrt.3 b/static/openbsd/man3/BN_mod_sqrt.3 new file mode 100644 index 00000000..f2cd80e6 --- /dev/null +++ b/static/openbsd/man3/BN_mod_sqrt.3 @@ -0,0 +1,112 @@ +.\" $OpenBSD: BN_mod_sqrt.3,v 1.3 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2022 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 $Mdocdate: June 8 2025 $ +.Dt BN_MOD_SQRT 3 +.Os +.Sh NAME +.Nm BN_mod_sqrt +.Nd square root in a prime field +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft BIGNUM * +.Fo BN_mod_sqrt +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *p" +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn BN_mod_sqrt +solves +.Bd -unfilled -offset indent +.EQ +r sup 2 == a ( roman mod p ) +.EN +.Ed +.Pp +for +.Fa r +in the prime field of characteristic +.Fa p +using the Tonelli-Shanks algorithm if needed +and places one of the two solutions into +.Fa r . +The other solution is +.Fa p +\- +.Fa r . +.Pp +The argument +.Fa p +is expected to be a prime number. +.Sh RETURN VALUES +In case of success, +.Fn BN_mod_sqrt +returns +.Fa r , +or a newly allocated +.Vt BIGNUM +object if the +.Fa r +argument is +.Dv NULL . +.Pp +In case of failure, +.Dv NULL +is returned. +This for example happens if +.Fa a +is not a quadratic residue or if memory allocation fails. +.Sh SEE ALSO +.Xr BN_CTX_new 3 , +.Xr BN_kronecker 3 , +.Xr BN_mod_sqr 3 , +.Xr BN_new 3 +.Rs +.%A Henri Cohen +.%B A Course in Computational Algebraic Number Theory +.%I Springer +.%C Berlin +.%D 1993 +.%O Algorithm 1.5.1 +.Re +.Sh HISTORY +.Fn BN_mod_sqrt +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Sh CAVEATS +If +.Fa p +is not prime, +.Fn BN_mod_sqrt +may succeed or fail. +If it succeeds, the square of the returned value is congruent to +.Fa a +modulo +.Fa p . +If it fails, the reason reported by +.Xr ERR_get_error 3 +is often misleading. +In particular, even if +.Fa a +is a perfect square, +.Fn BN_mod_sqrt +often reports +.Dq not a square +instead of +.Dq p is not prime . diff --git a/static/openbsd/man3/BN_new.3 b/static/openbsd/man3/BN_new.3 new file mode 100644 index 00000000..8e61a1fc --- /dev/null +++ b/static/openbsd/man3/BN_new.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: BN_new.3,v 1.33 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL man3/BN_new 2457c19d Mar 6 08:43:36 2004 +0000 +.\" selective merge up to: man3/BN_new 681acb31 Sep 29 13:10:34 2017 +0200 +.\" full merge up to: OpenSSL man7/bn 05ea606a May 20 20:52:46 2016 -0400 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2004 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_NEW 3 +.Os +.Sh NAME +.Nm BN_new , +.Nm BN_clear , +.Nm BN_free , +.Nm BN_clear_free +.Nd allocate and free BIGNUMs +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft BIGNUM * +.Fo BN_new +.Fa void +.Fc +.Ft void +.Fo BN_clear +.Fa "BIGNUM *a" +.Fc +.Ft void +.Fo BN_free +.Fa "BIGNUM *a" +.Fc +.Ft void +.Fo BN_clear_free +.Fa "BIGNUM *a" +.Fc +.Sh DESCRIPTION +The BN library performs arithmetic operations on integers of arbitrary +size. +It was written for use in public key cryptography, such as RSA 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 +.Vt BIGNUM . +It is used to hold a single large integer. +.Pp +.Fn BN_new +allocates and initializes a +.Vt BIGNUM +structure, in particular setting the value to zero and the flags to +.Dv BN_FLG_MALLOCED . +The security-relevant flag +.Dv BN_FLG_CONSTTIME +is not set by default. +.Pp +.Fn BN_clear +is used to destroy sensitive data such as keys when they are no longer +needed. +It erases the memory used by +.Fa a +and sets it to the value 0. +.Pp +.Fn BN_free +frees the components of the +.Vt BIGNUM +and, if it was created by +.Fn BN_new , +also the structure itself. +.Fn BN_clear_free +additionally overwrites the data before the memory is returned to the +system. +If +.Fa a +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn BN_new +returns a pointer to the +.Vt BIGNUM . +If the allocation fails, it returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_add 3 , +.Xr BN_add_word 3 , +.Xr BN_bn2bin 3 , +.Xr BN_cmp 3 , +.Xr BN_copy 3 , +.Xr BN_CTX_new 3 , +.Xr BN_CTX_start 3 , +.Xr BN_generate_prime 3 , +.Xr BN_get_rfc3526_prime_8192 3 , +.Xr BN_kronecker 3 , +.Xr BN_mod_inverse 3 , +.Xr BN_mod_mul_montgomery 3 , +.Xr BN_mod_sqrt 3 , +.Xr BN_num_bytes 3 , +.Xr BN_rand 3 , +.Xr BN_security_bits 3 , +.Xr BN_set_bit 3 , +.Xr BN_set_flags 3 , +.Xr BN_set_negative 3 , +.Xr BN_swap 3 , +.Xr BN_zero 3 , +.Xr crypto 3 +.Sh HISTORY +.Fn BN_new , +.Fn BN_clear , +.Fn BN_free , +and +.Fn BN_clear_free +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BN_num_bytes.3 b/static/openbsd/man3/BN_num_bytes.3 new file mode 100644 index 00000000..608bb2eb --- /dev/null +++ b/static/openbsd/man3/BN_num_bytes.3 @@ -0,0 +1,176 @@ +.\" $OpenBSD: BN_num_bytes.3,v 1.10 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 9e183d22 Mar 11 08:56:44 2017 -0500 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022 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. +.\" +.\" The original file was written by Ulf Moeller +.\" and Richard Levitte . +.\" Copyright (c) 2000, 2004 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_NUM_BYTES 3 +.Os +.Sh NAME +.Nm BN_num_bits_word , +.Nm BN_num_bits , +.Nm BN_num_bytes +.Nd get BIGNUM size +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft int +.Fo BN_num_bits_word +.Fa "BN_ULONG w" +.Fc +.Ft int +.Fo BN_num_bits +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_num_bytes +.Fa "const BIGNUM *a" +.Fc +.Sh DESCRIPTION +.Fn BN_num_bits_word +returns the number of significant bits in +.Fa w , +that is, the minimum number of digits needed to write +.Fa w +as a binary number. +Except for an argument of 0, this is +.Pp +.D1 floor(log2( Ns Fa w ) ) No + 1 . +.Pp +.Vt BN_ULONG +is a macro that expands to +.Vt unsigned long Pq = Vt uint64_t +on +.Dv _LP64 +platforms and +.Vt unsigned int Pq = Vt uint32_t +elsewhere. +.Pp +.Fn BN_num_bits +returns the number of significant bits in the value of the +.Fa "BIGNUM *a" , +following the same principle as +.Fn BN_num_bits_word . +.Pp +.Fn BN_num_bytes +is a macro that returns the number of significant bytes in +.Fa a , +i.e. the minimum number of bytes needed to store the value of +.Fa a , +that is, +.Fn BN_num_bits a +divided by eight and rounded up to the next integer number. +.Sh RETURN VALUES +.Fn BN_num_bits_word +returns the number of significant bits in +.Fa w +or 0 if +.Fa w +is 0. +The maximum return value that can occur is +.Dv BN_BITS2 , +which is 64 on +.Dv _LP64 +platforms and 32 elsewhere. +.Pp +.Fn BN_num_bits +returns the number of significant bits and +.Fn BN_num_bytes +the number of significant bytes in +.Fa a , +or 0 if the value of +.Fa a +is 0. +.Sh SEE ALSO +.Xr BN_new 3 , +.Xr BN_security_bits 3 , +.Xr DH_size 3 , +.Xr DSA_size 3 , +.Xr RSA_size 3 +.Sh HISTORY +.Fn BN_num_bytes +and +.Fn BN_num_bits +first appeared in SSLeay 0.5.1. +.Fn BN_num_bits_word +first appeared in SSLeay 0.5.2. +These functions have been available since +.Ox 2.4 . +.Sh CAVEATS +Some have tried using +.Fn BN_num_bits +on individual numbers in RSA keys, DH keys and DSA keys, and found that +they don't 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't always set the highest bits, thereby making the number of +.Em significant +bits a little smaller. +If you want to know the "key size" of such a key, use functions like +.Xr RSA_size 3 , +.Xr DH_size 3 , +and +.Xr DSA_size 3 . diff --git a/static/openbsd/man3/BN_rand.3 b/static/openbsd/man3/BN_rand.3 new file mode 100644 index 00000000..b21155af --- /dev/null +++ b/static/openbsd/man3/BN_rand.3 @@ -0,0 +1,147 @@ +.\" $OpenBSD: BN_rand.3,v 1.19 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 05ea606a May 20 20:52:46 2016 -0400 +.\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2001, 2002, 2013, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_RAND 3 +.Os +.Sh NAME +.Nm BN_rand , +.Nm BN_rand_range , +.Nm BN_pseudo_rand , +.Nm BN_pseudo_rand_range +.Nd generate pseudo-random number +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft int +.Fo BN_rand +.Fa "BIGNUM *rnd" +.Fa "int bits" +.Fa "int top" +.Fa "int bottom" +.Fc +.Ft int +.Fo BN_rand_range +.Fa "BIGNUM *rnd" +.Fa "const BIGNUM *range" +.Fc +.Sh DESCRIPTION +.Fn BN_rand +generates a cryptographically strong pseudo-random number of +.Fa bits +in length and stores it in +.Fa rnd . +If +.Fa top +is +.Dv BN_RAND_TOP_ANY , +the most significant bit of the random number can be zero. +If +.Fa top +is +.Dv BN_RAND_TOP_ONE , +the most significant bit is set to 1, and if +.Fa top +is +.Dv BN_RAND_TOP_TWO , +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 +.Pf 2* Fa bits +length. +If +.Fa bottom +is +.Dv BN_RAND_BOTTOM_ODD , +the number will be odd; +if it is +.Dv BN_RAND_BOTTOM_ANY , +it can be odd or even. +The value of +.Fa bits +must be zero or greater. +If +.Fa bits +is +1 then +.Fa top +cannot be +.Dv BN_RAND_TOP_TWO . +.Pp +.Fn BN_rand_range +generates a cryptographically strong pseudo-random number +.Fa rnd +in the range 0 <= +.Fa rnd No < Fa range . +.Pp +.Fn BN_pseudo_rand +is a deprecated alias for +.Fn BN_rand , +and +.Fn BN_pseudo_rand_range +for +.Fn BN_rand_range . +.Sh RETURN VALUES +The functions return 1 on success, 0 on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_new 3 +.Sh HISTORY +.Fn BN_rand +first appeared in SSLeay 0.5.1 and has been available since +.Ox 2.4 . +.Pp +The +.Fa top +== -1 case and the function +.Fn BN_rand_range +first appeared in OpenSSL 0.9.6a and have been available since +.Ox 3.0 . diff --git a/static/openbsd/man3/BN_set_bit.3 b/static/openbsd/man3/BN_set_bit.3 new file mode 100644 index 00000000..c13122b7 --- /dev/null +++ b/static/openbsd/man3/BN_set_bit.3 @@ -0,0 +1,217 @@ +.\" $OpenBSD: BN_set_bit.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_SET_BIT 3 +.Os +.Sh NAME +.Nm BN_set_bit , +.Nm BN_clear_bit , +.Nm BN_is_bit_set , +.Nm BN_mask_bits , +.Nm BN_lshift , +.Nm BN_lshift1 , +.Nm BN_rshift , +.Nm BN_rshift1 +.Nd bit operations on BIGNUMs +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft int +.Fo BN_set_bit +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_clear_bit +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_is_bit_set +.Fa "const BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_mask_bits +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_lshift +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_lshift1 +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_rshift +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_rshift1 +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fc +.Sh DESCRIPTION +.Fn BN_set_bit +sets bit +.Fa n +in +.Fa a +to 1 +.Pq Li a|=(1<>n) . +An error occurs if +.Fa a +already is shorter than +.Fa n +bits. +.Pp +.Fn BN_lshift +shifts +.Fa a +left by +.Fa n +bits and places the result in +.Fa r +.Pq Li r=a*2^n . +Note that +.Fa n +must be non-negative. +.Fn BN_lshift1 +shifts +.Fa a +left by one and places the result in +.Fa r +.Pq Li r=2*a . +.Pp +.Fn BN_rshift +shifts +.Fa a +right by +.Fa n +bits and places the result in +.Fa r +.Pq Li r=a/2^n . +Note that +.Fa n +must be non-negative. +.Fn BN_rshift1 +shifts +.Fa a +right by one and places the result in +.Fa r +.Pq Li r=a/2 . +.Pp +For the shift functions, +.Fa r +and +.Fa a +may be the same variable. +.Sh RETURN VALUES +.Fn BN_is_bit_set +returns 1 if the bit is set, 0 otherwise. +.Pp +All other functions return 1 for success, 0 on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_add 3 , +.Xr BN_new 3 , +.Xr BN_num_bytes 3 , +.Xr BN_set_negative 3 , +.Xr BN_zero 3 +.Sh HISTORY +.Fn BN_set_bit , +.Fn BN_clear_bit , +.Fn BN_is_bit_set , +.Fn BN_mask_bits , +.Fn BN_lshift , +.Fn BN_lshift1 , +.Fn BN_rshift , +and +.Fn BN_rshift1 +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/BN_set_flags.3 b/static/openbsd/man3/BN_set_flags.3 new file mode 100644 index 00000000..eb4840a5 --- /dev/null +++ b/static/openbsd/man3/BN_set_flags.3 @@ -0,0 +1,161 @@ +.\" $OpenBSD: BN_set_flags.3,v 1.7 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 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 $Mdocdate: June 8 2025 $ +.Dt BN_SET_FLAGS 3 +.Os +.Sh NAME +.Nm BN_set_flags , +.Nm BN_get_flags +.Nd enable and inspect flags on BIGNUM objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft void +.Fo BN_set_flags +.Fa "BIGNUM *b" +.Fa "int flags" +.Fc +.Ft int +.Fo BN_get_flags +.Fa "const BIGNUM *b" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn BN_set_flags +enables the given +.Fa flags +on +.Fa b . +The +.Fa flags +argument can contain zero or more of the following constants OR'ed +together: +.Bl -tag -width Ds +.It Dv BN_FLG_CONSTTIME +If this flag is set on the divident +.Fa a +or the divisor +.Fa d +in +.Xr BN_div 3 , +on the exponent +.Fa p +in +.Xr BN_mod_exp 3 , +or on the divisor +.Fa a +or the modulus +.Fa n +in +.Xr BN_mod_inverse 3 , +these functions select algorithms with an execution time independent +of the respective numbers, to avoid exposing sensitive information +to timing side-channel attacks. +.Pp +This flag is off by default for +.Vt BIGNUM +objects created with +.Xr BN_new 3 . +.It Dv BN_FLG_MALLOCED +If this flag is set, +.Xr BN_free 3 +and +.Xr BN_clear_free 3 +will not only clear and free the components of +.Fa b , +but also +.Fa b +itself. +This flag is set internally by +.Xr BN_new 3 . +Setting it manually on an existing +.Vt BIGNUM +object is usually a bad idea and can cause calls to +.Xr free 3 +with bogus arguments. +.It Dv BN_FLG_STATIC_DATA +If this flag is set, +.Xr BN_clear_free 3 +will neither clear nor free the memory used for storing the number. +Consequently, setting it manually on an existing +.Vt BIGNUM +object is usually a terrible idea that can cause both disclosure +of secret data and memory leaks. +This flag is automatically set on the constant +.Vt BIGNUM +object returned by +.Xr BN_value_one 3 . +.El +.Pp +.Fn BN_get_flags +interprets +.Fa flags +as a bitmask and returns those of the given flags that are set in +.Fa b , +OR'ed together, or 0 if none of the given +.Fa flags +is set. +The +.Fa flags +argument has the same syntax as for +.Fn BN_set_flags . +.Sh RETURN VALUES +.Fn BN_get_flags +returns zero or more of the above constants, OR'ed together. +.Sh SEE ALSO +.Xr BN_mod_exp 3 , +.Xr BN_mod_inverse 3 , +.Xr BN_new 3 , +.Xr BN_with_flags 3 +.Sh HISTORY +.Fn BN_set_flags +and +.Fn BN_get_flags +first appeared in SSLeay 0.9.1 and have been available since +.Ox 2.6 . +.Sh CAVEATS +No public interface exists to clear a flag once it is set. +So think twice before using +.Fn BN_set_flags . +.Sh BUGS +Even if the +.Dv BN_FLG_CONSTTIME +flag is set on +.Fa a +or +.Fa b , +.Fn BN_gcd +neither fails nor operates in constant time, potentially allowing +timing side-channel attacks. +.Pp +Even if the +.Dv BN_FLG_CONSTTIME +flag is set on +.Fa p , +if the modulus +.Fa m +is even, +.Xr BN_mod_exp 3 +does not operate in constant time, potentially allowing +timing side-channel attacks. +.Pp +If +.Dv BN_FLG_CONSTTIME +is set on +.Fa p , +.Fn BN_exp +fails instead of operating in constant time. diff --git a/static/openbsd/man3/BN_set_negative.3 b/static/openbsd/man3/BN_set_negative.3 new file mode 100644 index 00000000..579bcf21 --- /dev/null +++ b/static/openbsd/man3/BN_set_negative.3 @@ -0,0 +1,64 @@ +.\" $OpenBSD: BN_set_negative.3,v 1.7 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt BN_SET_NEGATIVE 3 +.Os +.Sh NAME +.Nm BN_set_negative , +.Nm BN_is_negative +.Nd change and inspect the sign of a BIGNUM +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft void +.Fo BN_set_negative +.Fa "BIGNUM *b" +.Fa "int n" +.Fc +.Ft int +.Fo BN_is_negative +.Fa "const BIGNUM *b" +.Fc +.Sh DESCRIPTION +.Fn BN_set_negative +sets +.Fa b +to negative if both +.Fa b +and +.Fa n +are non-zero, otherwise it sets it to positive. +.Pp +.Fn BN_is_negative +tests the sign of +.Fa b . +.Sh RETURN VALUES +.Fn BN_is_negative +returns 1 if +.Fa b +is negative or 0 otherwise. +.Sh SEE ALSO +.Xr BN_add 3 , +.Xr BN_new 3 , +.Xr BN_set_bit 3 , +.Xr BN_zero 3 +.Sh HISTORY +.Fn BN_set_negative +and +.Fn BN_is_negative +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/BN_swap.3 b/static/openbsd/man3/BN_swap.3 new file mode 100644 index 00000000..a6a5fa95 --- /dev/null +++ b/static/openbsd/man3/BN_swap.3 @@ -0,0 +1,149 @@ +.\" $OpenBSD: BN_swap.3,v 1.7 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 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. +.\" +.\" The original file was written by Bodo Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BN_SWAP 3 +.Os +.Sh NAME +.Nm BN_swap , +.Nm BN_consttime_swap +.Nd exchange BIGNUMs +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft void +.Fo BN_swap +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fc +.Ft void +.Fo BN_consttime_swap +.Fa "BN_ULONG condition" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "int nwords" +.Fc +.Sh DESCRIPTION +.Fn BN_swap +and +.Fn BN_consttime_swap +exchange the values of +.Fa a +and +.Fa b . +.Pp +.Fn BN_swap +implements this by exchanging the pointers to the data buffers of +.Fa a +and +.Fa b +and also exchanging the values of the +.Dv BN_FLG_STATIC_DATA +bits. +Consequently, the operation is fast and execution time does not depend +on any properties of the two numbers. +However, execution time obviously differs between swapping (by calling +this function) and not swapping (by not calling this function). +.Pp +.Fn BN_consttime_swap +only performs the exchange if the +.Fa condition +is non-zero; otherwise, it has no effect. +It implements the exchange by exchanging the contents of the data +buffers rather than the pointers to the data buffers. +This is slower, but implemented in such a way that the execution time +is not only independent of the properties of the two numbers, but also +independent of the +.Fa condition +argument, i.e. the same for swapping or not swapping. +Execution time does however grow in an approximately linear manner with the +.Fa nwords +argument. +.Pp +.Fn BN_consttime_swap +calls +.Xr abort 3 +if at least one of +.Fa a +or +.Fa b +has fewer than +.Fa nwords +data words allocated or more than +.Fa nwords +data words are currently in use in at least one of them. +.Sh SEE ALSO +.Xr BN_new 3 , +.Xr BN_set_flags 3 +.Sh HISTORY +.Fn BN_swap +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Pp +.Fn BN_consttime_swap +first appeared in OpenSSL 1.0.1g and has been available since +.Ox 5.6 . diff --git a/static/openbsd/man3/BN_zero.3 b/static/openbsd/man3/BN_zero.3 new file mode 100644 index 00000000..d94a2a10 --- /dev/null +++ b/static/openbsd/man3/BN_zero.3 @@ -0,0 +1,174 @@ +.\" $OpenBSD: BN_zero.3,v 1.16 2025/12/15 12:09:46 tb Exp $ +.\" full merge up to: OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" selective merge up to: OpenSSL b713c4ff Jan 22 14:41:09 2018 -0500 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021, 2022 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. +.\" +.\" The original file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2001, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: December 15 2025 $ +.Dt BN_ZERO 3 +.Os +.Sh NAME +.Nm BN_zero , +.Nm BN_one , +.Nm BN_value_one , +.Nm BN_set_word , +.Nm BN_get_word +.Nd BIGNUM assignment operations +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.Ft void +.Fo BN_zero +.Fa "BIGNUM *a" +.Fc +.Ft int +.Fo BN_one +.Fa "BIGNUM *a" +.Fc +.Ft const BIGNUM * +.Fo BN_value_one +.Fa void +.Fc +.Ft int +.Fo BN_set_word +.Fa "BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft BN_ULONG +.Fo BN_get_word +.Fa "const BIGNUM *a" +.Fc +.Sh DESCRIPTION +.Vt BN_ULONG +is a macro that expands to an unsigned integral type optimized +for the most efficient implementation on the local platform. +It is +.Vt unsigned long Pq = Vt uint64_t +on +.Dv _LP64 +platforms and +.Vt unsigned int Pq = Vt uint32_t +elsewhere. +.Pp +.Fn BN_zero , +.Fn BN_one , +and +.Fn BN_set_word +set +.Fa a +to the values 0, 1 and +.Fa w +respectively. +.Pp +.Fn BN_value_one +returns a +.Vt BIGNUM +constant of value 1. +This constant is useful for comparisons and assignments. +.Sh RETURN VALUES +.Fn BN_get_word +returns the value +.Fa a , +or (BN_ULONG)\-1 if +.Fa a +cannot be represented as a +.Vt BN_ULONG . +.Pp +.Fn BN_one +and +.Fn BN_set_word +return 1 on success, 0 otherwise. +.Fn BN_value_one +returns the constant. +.Sh SEE ALSO +.Xr BN_bn2bin 3 , +.Xr BN_new 3 , +.Xr BN_set_bit 3 , +.Xr BN_set_negative 3 +.Sh HISTORY +.Fn BN_zero , +.Fn BN_one , +.Fn BN_value_one , +and +.Fn BN_set_word +first appeared in SSLeay 0.5.1. +.Fn BN_get_word +first appeared in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . +.Sh BUGS +Someone might change the constant. +.Pp +If the value of a +.Vt BIGNUM +is equal to a +.Vt BN_ULONG +with all bits set, the return value of +.Fn BN_get_word +collides with return value used to indicate errors. +.Pp +.Vt BN_ULONG +should probably be a typedef rather than a macro. diff --git a/static/openbsd/man3/BUF_MEM_new.3 b/static/openbsd/man3/BUF_MEM_new.3 new file mode 100644 index 00000000..ef9e473c --- /dev/null +++ b/static/openbsd/man3/BUF_MEM_new.3 @@ -0,0 +1,154 @@ +.\" $OpenBSD: BUF_MEM_new.3,v 1.20 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL doc/crypto/buffer.pod 18edda0f Sep 20 03:28:54 2000 +0000 +.\" not merged: 74924dcb, 58e3457a, 21b0fa91, 7644a9ae +.\" OpenSSL doc/crypto/BUF_MEM_new.pod 53934822 Jun 9 16:39:19 2016 -0400 +.\" not merged: c952780c, 91da5e77 +.\" OpenSSL doc/man3/BUF_MEM_new.pod 498180de Dec 12 15:35:09 2016 +0300 +.\" +.\" This file was written by Ralf S. Engelschall . +.\" Copyright (c) 1999, 2000, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt BUF_MEM_NEW 3 +.Os +.Sh NAME +.Nm BUF_MEM_new , +.Nm BUF_MEM_free , +.Nm BUF_MEM_grow , +.Nm BUF_MEM_grow_clean +.Nd simple character arrays structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/buffer.h +.Ft BUF_MEM * +.Fo BUF_MEM_new +.Fa void +.Fc +.Ft void +.Fo BUF_MEM_free +.Fa "BUF_MEM *a" +.Fc +.Ft int +.Fo BUF_MEM_grow +.Fa "BUF_MEM *str" +.Fa "size_t len" +.Fc +.Ft int +.Fo BUF_MEM_grow_clean +.Fa "BUF_MEM *str" +.Fa "size_t len" +.Fc +.Sh DESCRIPTION +The buffer library handles simple character arrays. +Buffers are used for various purposes in the library, most notably +memory BIOs. +.Pp +The library uses the +.Vt BUF_MEM +structure defined in buffer.h: +.Bd -literal +typedef struct buf_mem_st { + size_t length; /* current number of bytes */ + char *data; + size_t max; /* size of buffer */ +} BUF_MEM; +.Ed +.Pp +.Fa length +is the current size of the buffer in bytes; +.Fa max +is the amount of memory allocated to the buffer. +There are three functions which handle these and one miscellaneous function. +.Pp +.Fn BUF_MEM_new +allocates a new buffer of zero size. +.Pp +.Fn BUF_MEM_free +frees up an already existing buffer. +The data is zeroed before freeing up in case the buffer contains +sensitive data. +If +.Fa a +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn BUF_MEM_grow +changes the size of an already existing buffer to +.Fa len . +Any data already in the buffer is preserved if it increases in size. +.Pp +.Fn BUF_MEM_grow_clean +is similar to +.Fn BUF_MEM_grow , +but it sets any freed or additionally allocated memory to zero. +.Sh RETURN VALUES +.Fn BUF_MEM_new +returns the buffer or +.Dv NULL +on error. +.Pp +.Fn BUF_MEM_grow +and +.Fn BUF_MEM_grow_clean +return zero on error or the new size (i.e.\& +.Fa len ) . +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr BIO_s_mem 3 +.Sh HISTORY +.Fn BUF_MEM_new , +.Fn BUF_MEM_free , +and +.Fn BUF_MEM_grow +first appeared in SSLeay 0.6.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn BUF_MEM_grow_clean +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/CMAC_Init.3 b/static/openbsd/man3/CMAC_Init.3 new file mode 100644 index 00000000..b1b62a63 --- /dev/null +++ b/static/openbsd/man3/CMAC_Init.3 @@ -0,0 +1,274 @@ +.\" $OpenBSD: CMAC_Init.3,v 1.10 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: June 8 2025 $ +.Dt CMAC_INIT 3 +.Os +.Sh NAME +.Nm CMAC_CTX_new , +.Nm CMAC_Init , +.Nm CMAC_Update , +.Nm CMAC_Final , +.Nm CMAC_CTX_copy , +.Nm CMAC_CTX_get0_cipher_ctx , +.Nm CMAC_CTX_cleanup , +.Nm CMAC_CTX_free +.Nd Cipher-based message authentication code +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cmac.h +.Ft CMAC_CTX * +.Fn CMAC_CTX_new void +.Ft int +.Fo CMAC_Init +.Fa "CMAC_CTX *ctx" +.Fa "const void *key" +.Fa "size_t key_len" +.Fa "const EVP_CIPHER *cipher" +.Fa "ENGINE *engine" +.Fc +.Ft int +.Fo CMAC_Update +.Fa "CMAC_CTX *ctx" +.Fa "const void *in_data" +.Fa "size_t in_len" +.Fc +.Ft int +.Fo CMAC_Final +.Fa "CMAC_CTX *ctx" +.Fa "unsigned char *out_mac" +.Fa "size_t *out_len" +.Fc +.Ft int +.Fo CMAC_CTX_copy +.Fa "CMAC_CTX *out_ctx" +.Fa "CMAC_CTX *in_ctx" +.Fc +.Ft EVP_CIPHER_CTX * +.Fn CMAC_CTX_get0_cipher_ctx "CMAC_CTX *ctx" +.Ft void +.Fn CMAC_CTX_cleanup "CMAC_CTX *ctx" +.Ft void +.Fn CMAC_CTX_free "CMAC_CTX *ctx" +.Sh DESCRIPTION +CMAC is a message authentication code algorithm that can employ an +arbitrary block cipher using a symmetric key. +.Pp +The present manual page describes low-level functions implementing CMAC. +Instead of using these functions directly, +application programs normally call +.Xr EVP_PKEY_new_CMAC_key 3 +and then pass the resulting +.Vt EVP_PKEY +object to +.Xr EVP_DigestSignInit 3 . +.Pp +The CMAC API is object-oriented. +Calculating a message authentication code requires a +.Vt CMAC_CTX +object. +Usually, the functions +.Fn CMAC_CTX_new , +.Fn CMAC_Init , +.Fn CMAC_Update , +.Fn CMAC_Final , +and +.Fn CMAC_CTX_free +need to be called in this order. +.Pp +.Fn CMAC_CTX_new +allocates a new +.Vt CMAC_CTX +object, initializes the embedded +.Vt EVP_CIPHER_CTX +object, and marks the object itself as uninitialized. +.Pp +.Fn CMAC_Init +selects the given block +.Fa cipher +for use by +.Fa ctx . +Functions to obtain suitable +.Vt EVP_CIPHER +objects are listed in the CIPHER LISTING section of the +.Xr EVP_EncryptInit 3 +manual page. +Unless +.Fa key +is +.Dv NULL , +.Fn CMAC_Init +also initializes +.Fa ctx +for use with the given symmetric +.Fa key +that is +.Fa key_len +bytes long. +In particular, it calculates and internally stores the two subkeys +and initializes +.Fa ctx +for subsequently feeding in data with +.Fn CMAC_Update . +The +.Fa engine +argument is ignored; passing +.Dv NULL +is recommended. +.Pp +If +.Fa ctx +is already initialized, +.Fn CMAC_Init +can be called again with +.Fa key +and +.Fa cipher +both set to +.Dv NULL +and +.Fa key_len +set to 0. +In that case, any data already processed is discarded and +.Fa ctx +is re-initialized to start reading data anew. +.Pp +.Fn CMAC_Update +processes +.Fa in_len +bytes of input data pointed to by +.Fa in_data . +Depending on the number of input bytes already cached in +.Fa ctx , +on +.Fa in_len , +and on the block size, this may encrypt zero or more blocks. +Unless +.Fa in_len +is zero, this function leaves at least one byte and at most one +block of input cached but unprocessed inside the +.Fa ctx +object. +.Fn CMAC_Update +can be called multiple times +to concatenate several chunks of input data of varying sizes. +.Pp +.Fn CMAC_Final +stores the length of the message authentication code in bytes, +which equals the cipher block size, into +.Pf * Fa out_len . +Unless +.Fa out_mac +is +.Dv NULL , +it encrypts the last block, padding it if required, and copies the +resulting message authentication code to +.Fa out_mac . +The caller is responsible for providing a buffer of sufficient size. +.Pp +.Fn CMAC_CTX_copy +performs a deep copy of the already initialized +.Fa in_ctx +into +.Fa out_ctx . +.Pp +.Fn CMAC_CTX_cleanup +zeros out both subkeys and all temporary data in +.Fa ctx +and in the embedded +.Vt EVP_CIPHER_CTX +object, frees all allocated memory associated with it, +except for +.Fa ctx +itself, and marks it as uninitialized, +such that it can be reused for subsequent +.Fn CMAC_Init . +.Pp +.Fn CMAC_CTX_free +calls +.Fn CMAC_CTX_cleanup , +then frees +.Fa ctx +itself. +If +.Fa ctx +is +.Dv NULL , +no action occurs. +.Sh RETURN VALUES +.Fn CMAC_CTX_new +returns the new context object or +.Dv NULL +in case of failure. +It succeeds unless memory is exhausted. +.Pp +.Fn CMAC_Init , +.Fn CMAC_Update , +.Fn CMAC_Final , +and +.Fn CMAC_CTX_copy +return 1 on success or 0 on failure. +.Fn CMAC_Init +fails if initializing the embedded +.Vt EVP_CIPHER_CTX +object fails. +The others fail if +.Fa in_ctx +is uninitialized. +.Fn CMAC_Update +and +.Fn CMAC_Final +also fail if encrypting a block fails, and +.Fn CMAC_CTX_copy +if copying the embedded +.Vt EVP_CIPHER_CTX +object fails, which can for example happen when memory is exhausted. +.Pp +.Fn CMAC_CTX_get0_cipher_ctx +returns an internal pointer to the +.Vt EVP_CIPHER_CTX +object that is embedded in +.Fa ctx . +.Sh ERRORS +The CMAC code itself does not use the +.In openssl/err.h +framework, so in general, the reasons for failure cannot be found out with +.Xr ERR_get_error 3 . +However, since the +.Xr EVP_EncryptInit 3 +functions are used internally, entries may still get pushed onto +the error stack in some cases of failure. +.Sh SEE ALSO +.Xr EVP_aes_128_cbc 3 , +.Xr EVP_DigestSignInit 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_PKEY_new_CMAC_key 3 , +.Xr HMAC 3 +.Sh STANDARDS +.Rs +.%A Morris Dworkin +.%T "Recommendation for Block Cipher Modes of Operation:\ + The CMAC Mode for Authentication" +.%I National Institute of Standards and Technology +.%R NIST Special Publication 800-38B +.%U https://doi.org/10.6028/NIST.SP.800-38B +.%C Gaithersburg, Maryland +.%D May 2005, updated October 6, 2016 +.Re +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.1 +and have been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/CMS_ContentInfo_new.3 b/static/openbsd/man3/CMS_ContentInfo_new.3 new file mode 100644 index 00000000..61152119 --- /dev/null +++ b/static/openbsd/man3/CMS_ContentInfo_new.3 @@ -0,0 +1,136 @@ +.\" $OpenBSD: CMS_ContentInfo_new.3,v 1.7 2025/12/20 11:51:28 tb Exp $ +.\" Copyright (c) 2019 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 $Mdocdate: December 20 2025 $ +.Dt CMS_CONTENTINFO_NEW 3 +.Os +.Sh NAME +.Nm CMS_ContentInfo_new , +.Nm CMS_ContentInfo_free , +.Nm CMS_ContentInfo_print_ctx , +.Nm CMS_ReceiptRequest_new , +.Nm CMS_ReceiptRequest_free +.Nd Cryptographic Message Syntax data structures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fn CMS_ContentInfo_new void +.Ft void +.Fn CMS_ContentInfo_free "CMS_ContentInfo *cms" +.Ft int +.Fo CMS_ContentInfo_print_ctx +.Fa "BIO *out" +.Fa "CMS_ContentInfo *cms" +.Fa "int indent" +.Fa "const ASN1_PCTX *pctx" +.Fc +.Ft CMS_ReceiptRequest * +.Fn CMS_ReceiptRequest_new void +.Ft void +.Fn CMS_ReceiptRequest_free "CMS_ReceiptRequest *rr" +.Sh DESCRIPTION +.Fn CMS_ContentInfo_new +allocates and initializes an empty +.Vt CMS_ContentInfo +object, representing an ASN.1 +.Vt ContentInfo +structure defined in RFC 5652 section 3. +It can hold a pointer to an ASN.1 OBJECT IDENTIFIER +and a pointer to either a +.Vt SignedData , +.Vt EnvelopedData , +.Vt DigestedData , +.Vt EncryptedData , +.Vt AuthenticatedData , +or +.Vt CompressedData +object or to an arbitrary ASN.1 object. +.Fn CMS_ContentInfo_free +frees +.Fa cms . +.Pp +.Fn CMS_ContentInfo_print_ctx +prints a human readable representation of +.Fa cms +to +.Fa out . +.Pp +.Fn CMS_ReceiptRequest_new +allocates and initializes an empty +.Vt CMS_ReceiptRequest +object, representing an ASN.1 +.Vt ReceiptRequest +structure defined in RFC 2634 section 2.7. +It can contain a content identifier, a list of recipients requested +to return a signed receipt, and a list of users to send the receipt to. +.Fn CMS_ReceiptRequest_free +frees +.Fa rr . +.Sh RETURN VALUES +.Fn CMS_ContentInfo_new +and +.Fn CMS_ReceiptRequest_new +return the new +.Vt CMS_ContentInfo +or +.Vt CMS_ReceiptRequest +object, respectively, or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr BIO_new_CMS 3 , +.Xr CMS_add0_cert 3 , +.Xr CMS_add1_recipient_cert 3 , +.Xr CMS_add1_signer 3 , +.Xr CMS_compress 3 , +.Xr CMS_decrypt 3 , +.Xr CMS_encrypt 3 , +.Xr CMS_final 3 , +.Xr CMS_get0_RecipientInfos 3 , +.Xr CMS_get0_SignerInfos 3 , +.Xr CMS_get0_type 3 , +.Xr CMS_get1_ReceiptRequest 3 , +.Xr CMS_sign 3 , +.Xr CMS_sign_receipt 3 , +.Xr CMS_signed_add1_attr 3 , +.Xr CMS_uncompress 3 , +.Xr CMS_verify 3 , +.Xr CMS_verify_receipt 3 , +.Xr crypto 3 , +.Xr d2i_CMS_ContentInfo 3 , +.Xr i2d_CMS_bio_stream 3 , +.Xr PEM_read_bio_PrivateKey 3 , +.Xr PEM_write_bio_CMS_stream 3 , +.Xr SMIME_read_CMS 3 , +.Xr SMIME_write_CMS 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax, section 3: General Syntax +.Pp +RFC 3274: Compressed Data Content Type for Cryptographic Message Syntax (CMS) +.Pp +RFC 2634: Enhanced Security Services for S/MIME, +section 2.7: Receipt Request Syntax +.Sh HISTORY +.Fn CMS_ContentInfo_new , +.Fn CMS_ContentInfo_free , +.Fn CMS_ReceiptRequest_new , +and +.Fn CMS_ReceiptRequest_free +first appeared in OpenSSL 0.9.8h and +.Fn CMS_ContentInfo_print_ctx +in OpenSSL 1.0.0. +This function has been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/CMS_add0_cert.3 b/static/openbsd/man3/CMS_add0_cert.3 new file mode 100644 index 00000000..d0e9be6b --- /dev/null +++ b/static/openbsd/man3/CMS_add0_cert.3 @@ -0,0 +1,223 @@ +.\" $OpenBSD: CMS_add0_cert.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_ADD0_CERT 3 +.Os +.Sh NAME +.Nm CMS_add0_cert , +.Nm CMS_add1_cert , +.Nm CMS_get1_certs , +.Nm CMS_add0_crl , +.Nm CMS_add1_crl , +.Nm CMS_get1_crls +.Nd CMS certificate and CRL utility functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft int +.Fo CMS_add0_cert +.Fa "CMS_ContentInfo *cms" +.Fa "X509 *certificate" +.Fc +.Ft int +.Fo CMS_add1_cert +.Fa "CMS_ContentInfo *cms" +.Fa "X509 *certificate" +.Fc +.Ft STACK_OF(X509) * +.Fo CMS_get1_certs +.Fa "CMS_ContentInfo *cms" +.Fc +.Ft int +.Fo CMS_add0_crl +.Fa "CMS_ContentInfo *cms" +.Fa "X509_CRL *crl" +.Fc +.Ft int +.Fo CMS_add1_crl +.Fa "CMS_ContentInfo *cms" +.Fa "X509_CRL *crl" +.Fc +.Ft STACK_OF(X509_CRL) * +.Fo CMS_get1_crls +.Fa "CMS_ContentInfo *cms" +.Fc +.Sh DESCRIPTION +.Fn CMS_add0_cert +adds the +.Fa certificate +to the +.Fa certificates +field of +.Fa cms +if it is of the type +.Vt SignedData +or to the +.Fa originatorInfo.certs +field if it is of the type +.Vt EnvelopedData . +.Fn CMS_add1_cert +does the same and also increments the reference count of the +.Fa certificate +with +.Xr X509_up_ref 3 +in case of success. +.Pp +.Fn CMS_get1_certs +returns all certificates in +.Fa cms . +.Pp +.Fn CMS_add0_crl +adds the +.Fa crl +to the +.Fa crls +field of +.Fa cms +if it is of the type +.Vt SignedData +or to the +.Fa originatorInfo.crls +field if it is of the type +.Vt EnvelopedData . +.Fn CMS_add1_crl +does the same and also increments the reference count of the +.Fa crl +with +.Xr X509_CRL_up_ref 3 +in case of success. +.Pp +.Fn CMS_get1_crls +returns any CRLs in +.Fa cms . +.Pp +An error occurs if +.Fa cms +is of any type other than +.Vt SignedData +or +.Vt EnvelopedData . +.Pp +The same +.Fa certificate +or +.Fa crl +must not be added to the same +.Fa cms +structure more than once. +.Sh RETURN VALUES +.Fn CMS_add0_cert , +.Fn CMS_add1_cert , +.Fn CMS_add0_crl , +and +.Fn CMS_add1_crl +return 1 for success or 0 for failure. +.Pp +.Fn CMS_get1_certs +and +.Fn CMS_get1_crls +return the STACK of certificates or CRLs or +.Dv NULL +if there are none or an error occurs. +Possible errors are that the +.Fa cms +type is invalid or memory allocation failure. +Not all errors result in an error on the error stack. +The returned stack must be freed using the appropriate +macro wrapper of +.Xr sk_pop_free 3 , +namely +.Dv sk_X509_pop_free() +or +.Dv sk_X509_CRL_pop_free() . +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_encrypt 3 , +.Xr CMS_final 3 , +.Xr CMS_sign 3 , +.Xr ERR_get_error 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax +.Bl -dash -compact -offset indent +.It +section 5.1: SignedData Type +.It +section 6.1: EnvelopedData Type +.El +.Sh HISTORY +.Fn CMS_add0_cert , +.Fn CMS_add1_cert , +.Fn CMS_get1_certs , +.Fn CMS_add0_crl , +and +.Fn CMS_get1_crls +first appeared in OpenSSL 0.9.8h and +.Fn CMS_add1_crl +in OpenSSL 1.0.0. +These functions have been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/CMS_add1_recipient_cert.3 b/static/openbsd/man3/CMS_add1_recipient_cert.3 new file mode 100644 index 00000000..7c0c3fae --- /dev/null +++ b/static/openbsd/man3/CMS_add1_recipient_cert.3 @@ -0,0 +1,201 @@ +.\" $OpenBSD: CMS_add1_recipient_cert.3,v 1.8 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_ADD1_RECIPIENT_CERT 3 +.Os +.Sh NAME +.Nm CMS_add1_recipient_cert , +.Nm CMS_add0_recipient_key +.Nd add recipients to a CMS EnvelopedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft CMS_RecipientInfo * +.Fo CMS_add1_recipient_cert +.Fa "CMS_ContentInfo *cms" +.Fa "X509 *certificate" +.Fa "unsigned int flags" +.Fc +.Ft CMS_RecipientInfo * +.Fo CMS_add0_recipient_key +.Fa "CMS_ContentInfo *cms" +.Fa "int nid" +.Fa "unsigned char *key" +.Fa "size_t keylen" +.Fa "unsigned char *id" +.Fa "size_t idlen" +.Fa "ASN1_GENERALIZEDTIME *date" +.Fa "ASN1_OBJECT *otherTypeId" +.Fa "ASN1_TYPE *otherType" +.Fc +.Sh DESCRIPTION +These functions add a new +.Vt RecipientInfo +structure to the +.Fa recipientInfos +field of the +.Vt EnvelopedData +structure +.Fa cms , +which should have been obtained from an initial call to +.Xr CMS_encrypt 3 +with the flag +.Dv CMS_PARTIAL +set. +.Pp +.Fn CMS_add1_recipient_cert +adds the recipient +.Fa certificate +as a +.Vt KeyTransRecipientInfo +structure. +.Pp +.Fn CMS_add0_recipient_key +adds the symmetric +.Fa key +of length +.Fa keylen +using the wrapping algorithm +.Fa nid , +the identifier +.Fa id +of length +.Fa idlen , +and the optional values +.Fa date , +.Fa otherTypeId +and +.Fa otherType +as a +.Vt KEKRecipientInfo +structure. +.Pp +The main purpose of these functions is to provide finer control over a CMS +.Vt EnvelopedData +structure where the simpler +.Xr CMS_encrypt 3 +function defaults are not appropriate, +for example if one or more +.Vt KEKRecipientInfo +structures need to be added. +New attributes can also be added using the returned +.Vt CMS_RecipientInfo +structure and the CMS attribute utility functions. +.Pp +By default, recipient certificates are identified using issuer +name and serial number. +If the flag +.Dv CMS_USE_KEYID +is set, the subject key identifier value is used 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 +.Fa nid , +specifically +.Dv NID_id_aes128_wrap , +.Dv NID_id_aes192_wrap , +and +.Dv NID_id_aes256_wrap . +If +.Fa nid +is set to +.Dv NID_undef , +then an AES wrap algorithm will be used consistent with +.Fa keylen . +.Sh RETURN VALUES +.Fn CMS_add1_recipient_cert +and +.Fn CMS_add0_recipient_key +return an internal pointer to the +.Vt CMS_RecipientInfo +structure just added or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_encrypt 3 , +.Xr CMS_final 3 , +.Xr ERR_get_error 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax +.Bl -dash -compact -offset indent +.It +section 6.1: EnvelopedData Type +.It +section 6.2.1: KeyTransRecipientInfo Type +.It +section 6.2.3: KEKRecipientInfo Type +.El +.Sh HISTORY +.Fn CMS_add1_recipient_cert +and +.Fn CMS_add0_recipient_key +first appeared in OpenSSL 0.9.8h +and have been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/CMS_add1_signer.3 b/static/openbsd/man3/CMS_add1_signer.3 new file mode 100644 index 00000000..68bdb12c --- /dev/null +++ b/static/openbsd/man3/CMS_add1_signer.3 @@ -0,0 +1,250 @@ +.\" $OpenBSD: CMS_add1_signer.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_ADD1_SIGNER 3 +.Os +.Sh NAME +.Nm CMS_add1_signer , +.Nm CMS_SignerInfo_sign +.Nd add a signer to a CMS SignedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft CMS_SignerInfo * +.Fo CMS_add1_signer +.Fa "CMS_ContentInfo *cms" +.Fa "X509 *signcert" +.Fa "EVP_PKEY *pkey" +.Fa "const EVP_MD *md" +.Fa "unsigned int flags" +.Fc +.Ft int +.Fo CMS_SignerInfo_sign +.Fa "CMS_SignerInfo *si" +.Fc +.Sh DESCRIPTION +.Fn CMS_add1_signer +adds a signer with certificate +.Fa signcert +and private key +.Fa pkey +using message digest +.Fa md +to the +.Fa signerInfos +field of the +.Vt SignedData +structure +.Fa cms , +which should have been obtained from an initial call to +.Xr CMS_sign 3 +with the flag +.Dv CMS_PARTIAL +set, or which can be a valid +.Vt SignedData +structure in the case of re-signing. +.Pp +If +.Fa md +is +.Dv NULL , +the default digest for the public key algorithm of +.Fa pkey +is used. +.Pp +Unless the +.Dv CMS_REUSE_DIGEST +flag is set, the +.Fa cms +structure remains incomplete and must be finalized either by streaming +(if applicable) or by a call to +.Xr CMS_final 3 . +.Pp +The main purpose of +.Fn CMS_add1_signer +is to provide finer control over a CMS +.Vt SignedData +structure where the simpler +.Xr CMS_sign 3 +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 +.Vt CMS_SignerInfo +structure and the CMS attribute utility functions or the CMS signed +receipt request functions. +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter: +.Bl -tag -width Ds +.It Dv CMS_REUSE_DIGEST +Attempt to copy the content digest value from one of the existing +.Vt CMS_SignerInfo +structures in +.Fa cms +while adding another signer. +An error occurs if a matching digest value cannot be found to copy. +The +.Fa cms +structure will be valid and finalized when this flag is set. +.It Dv CMS_PARTIAL +If this flag is set in addition to +.Dv CMS_REUSE_DIGEST , +the returned +.Vt CMS_SignerInfo +structure will not be finalized so additional attributes can be added. +In this case an explicit call to +.Fn CMS_SignerInfo_sign +is needed to finalize it. +.It Dv CMS_NOCERTS +Do not add the signer's certificate to the +.Fa certificates +field of +.Fa cms . +The signer's certificate must still be supplied in the +.Fa signcert +parameter though. +This flag can reduce the size of the signature if the signer's certificate can +be obtained by other means, for example from a previously signed message. +.It Dv CMS_NOATTR +Leave the +.Fa signedAttrs +field of the returned +.Vt CMS_SignedData +structure empty. +By default, several CMS +.Vt SignedAttributes +are added, including the signing time, the CMS content type, +and the supported list of ciphers in an +.Vt SMIMECapabilities +attribute. +.It Dv CMS_NOSMIMECAP +Omit just the +.Vt SMIMECapabilities +attribute. +.It Dv CMS_USE_KEYID +Use the subject key identifier value to identify signing certificates. +An error occurs if the signing certificate does not have a subject key +identifier extension. +By default, issuer name and serial number are used instead. +.El +.Pp +If present, the +.Vt SMIMECapabilities +attribute indicates support for the +following algorithms in preference order: 256-bit AES, +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. +.Pp +The +.Fn CMS_SignerInfo_sign +function explicitly signs +.Fa si . +Its main use is when the +.Dv CMS_REUSE_DIGEST +and +.Dv CMS_PARTIAL +flags were both set in the call to +.Fn CMS_add1_signer +that created +.Fa si . +.Sh RETURN VALUES +.Fn CMS_add1_signer +returns an internal pointer to the new +.Vt CMS_SignerInfo +structure just added or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_final 3 , +.Xr CMS_sign 3 , +.Xr ERR_get_error 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax, section 5.1: SignedData Type +.Pp +RFC 8419: Use of Edwards-Curve Digital Signature Algorithm (EdDSA) Signatures +in the Cryptographic Message Syntax (CMS) +.Pp +RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME) +Version\ 4.0 Message Specification +.Bl -dash -compact -offset indent +.It +section 2.5: Attributes and the SignerInfo Type +.It +section 2.5.2: SMIMECapabilities Attribute +.El +.Sh HISTORY +.Fn CMS_add1_signer +and +.Fn CMS_SignerInfo_sign +first appeared in OpenSSL 0.9.8h +and have been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/CMS_compress.3 b/static/openbsd/man3/CMS_compress.3 new file mode 100644 index 00000000..9026837f --- /dev/null +++ b/static/openbsd/man3/CMS_compress.3 @@ -0,0 +1,171 @@ +.\" $OpenBSD: CMS_compress.3,v 1.8 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_COMPRESS 3 +.Os +.Sh NAME +.Nm CMS_compress +.Nd create a CMS CompressedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo CMS_compress +.Fa "BIO *in" +.Fa "int comp_nid" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_compress +creates and returns a CMS +.Vt CompressedData +structure. +.Pp +.Fa comp_nid +is the compression algorithm to use or +.Dv NID_undef +to use the default algorithm. +Currently, the default algorithm +.Dv NID_zlib_compression +is the only supported algorithm. +If zlib support is not compiled in, +.Fn CMS_compress +always returns an error. +.Pp +.Fa in +provides the content to be compressed. +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter: +.Bl -tag -width Ds +.It Dv CMS_TEXT +Prepend MIME headers for type text/plain to the data. +.It Dv CMS_BINARY +Do not translate the supplied content into MIME canonical format, +even though that is required by the S/MIME specifications. +This option should be used if the supplied data is in binary format. +Otherwise, the translation will corrupt it. +If +.Dv CMS_BINARY +is set, +.Dv CMS_TEXT +is ignored. +.It Dv CMS_STREAM +Return a partial +.Vt CMS_ContentInfo +structure suitable for streaming I/O: no data is read from +.Fa in . +Several functions including +.Xr SMIME_write_CMS 3 , +.Xr i2d_CMS_bio_stream 3 , +or +.Xr PEM_write_bio_CMS_stream 3 +can be used to finalize the structure. +Alternatively, finalization can be performed by obtaining the streaming +ASN1 +.Vt BIO +directly using +.Xr BIO_new_CMS 3 . +Outputting the contents of the +.Vt CMS_ContentInfo +structure via a function that does not +properly finalize it will give unpredictable results. +.It Dv CMS_DETACHED +Do not include the compressed data in the +.Vt CMS_ContentInfo +structure. +This is rarely used in practice and is not supported by +.Xr SMIME_write_CMS 3 . +.El +.Pp +Additional compression parameters such as the zlib compression level +cannot currently be set. +.Sh RETURN VALUES +.Fn CMS_compress +returns either a +.Vt CMS_ContentInfo +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_uncompress 3 +.Sh STANDARDS +RFC 3274: Compressed Data Content Type for Cryptographic Message Syntax (CMS) +.Sh HISTORY +.Fn CMS_compress +first appeared in OpenSSL 0.9.8h +and has been available since +.Ox 6.7 . +.Pp +The +.Dv CMS_STREAM +flag first appeared in OpenSSL 1.0.0. diff --git a/static/openbsd/man3/CMS_decrypt.3 b/static/openbsd/man3/CMS_decrypt.3 new file mode 100644 index 00000000..21410980 --- /dev/null +++ b/static/openbsd/man3/CMS_decrypt.3 @@ -0,0 +1,227 @@ +.\" $OpenBSD: CMS_decrypt.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_DECRYPT 3 +.Os +.Sh NAME +.Nm CMS_decrypt , +.Nm CMS_decrypt_set1_pkey , +.Nm CMS_decrypt_set1_key +.Nd decrypt content from a CMS EnvelopedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft int +.Fo CMS_decrypt +.Fa "CMS_ContentInfo *cms" +.Fa "EVP_PKEY *private_key" +.Fa "X509 *certificate" +.Fa "BIO *dcont" +.Fa "BIO *out" +.Fa "unsigned int flags" +.Fc +.Ft int +.Fo CMS_decrypt_set1_pkey +.Fa "CMS_ContentInfo *cms" +.Fa "EVP_PKEY *private_key" +.Fa "X509 *certificate" +.Fc +.Ft int +.Fo CMS_decrypt_set1_key +.Fa "CMS_ContentInfo *cms" +.Fa "unsigned char *symmetric_key" +.Fa "size_t keylen" +.Fa "const unsigned char *id" +.Fa "size_t idlen" +.Fc +.Sh DESCRIPTION +.Fn CMS_decrypt +extracts and decrypts the content from the CMS +.Vt EnvelopedData +structure +.Fa cms +using the +.Fa private_key +and the +.Fa certificate +of the recipient. +It writes the decrypted content to +.Fa out . +.Pp +In the rare case where the compressed content is detached, pass it in via +.Fa dcont . +For normal use, set +.Fa dcont +to +.Dv NULL . +.Pp +Although the recipient's +.Fa certificate +is not needed to decrypt the data, it is needed to locate the +appropriate (of possibly several) recipients in the CMS structure. +.Pp +If the +.Fa certificate +is set to +.Dv NULL , +all possible recipients are tried. +This case however is problematic. +To thwart the MMA attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA +padding), all recipients are tried whether they succeed or not. +If no recipient succeeds, 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 +.Fn CMS_decrypt +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 +.Dv CMS_DEBUG_DECRYPT +is set, the above behaviour is modified and an error +.Em is +returned if no recipient encrypted key can be decrypted +.Em without +generating a random content encryption key. +Applications should use this flag with extreme caution +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 by looking them up in a database) and setting them in the +.Fa cms +structure in advance using the CMS utility functions such as +.Fn CMS_decrypt_set1_pkey . +In this case both +.Fa certificate +and +.Fa private_key +should be set to +.Dv NULL +when calling +.Fn CMS_decrypt +later on. +.Pp +To process +.Vt KEKRecipientInfo +types, +.Fn CMS_decrypt_set1_key +or +.Xr CMS_RecipientInfo_set0_key 3 +and +.Xr CMS_RecipientInfo_decrypt 3 +should be called before +.Fn CMS_decrypt +and +.Fa certificate +and +.Fa private_key +set to +.Dv NULL +when calling +.Fn CMS_decrypt +later on. +.Pp +If the +.Dv CMS_TEXT +bit is set in +.Fa flags , +MIME headers for type text/plain are deleted from the content. +If the content is not of type text/plain, an error occurs. +.Sh RETURN VALUES +.Fn CMS_decrypt , +.Fn CMS_decrypt_set1_pkey , +and +.Fn CMS_decrypt_set1_key +return 1 for success or 0 for failure. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_encrypt 3 , +.Xr CMS_get0_RecipientInfos 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax (CMS) +.Bl -dash -compact -offset indent +.It +section 6.1: EnvelopedData Type +.It +section 6.2.3: KEKRecipientInfo Type +.El +.Sh HISTORY +.Fn CMS_decrypt , +.Fn CMS_decrypt_set1_pkey , +and +.Fn CMS_decrypt_set1_key +first appeared in OpenSSL 0.9.8h +and have been available since +.Ox 6.7 . +.Sh BUGS +The lack of single pass processing and the need to hold all data in +memory as mentioned in +.Xr CMS_verify 3 +also applies to +.Fn CMS_decrypt . diff --git a/static/openbsd/man3/CMS_encrypt.3 b/static/openbsd/man3/CMS_encrypt.3 new file mode 100644 index 00000000..5eda8838 --- /dev/null +++ b/static/openbsd/man3/CMS_encrypt.3 @@ -0,0 +1,192 @@ +.\" $OpenBSD: CMS_encrypt.3,v 1.8 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_ENCRYPT 3 +.Os +.Sh NAME +.Nm CMS_encrypt +.Nd create a CMS EnvelopedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo CMS_encrypt +.Fa "STACK_OF(X509) *certificates" +.Fa "BIO *in" +.Fa "const EVP_CIPHER *cipher" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_encrypt +creates a CMS +.Vt EnvelopedData +structure, encrypting the content provided by +.Fa in . +.Pp +The recipient +.Fa certificates +are added as +.Vt KeyTransRecipientInfo +structures by calling the function +.Xr CMS_add1_recipient_cert 3 +internally. +Only certificates carrying RSA, Diffie-Hellman or EC keys are supported +by this function. +The +.Fa certificates +argument can be set to +.Dv NULL +if the +.Dv CMS_PARTIAL +flag is set and recipients are added later using +.Xr CMS_add1_recipient_cert 3 +or +.Xr CMS_add0_recipient_key 3 . +.Pp +.Fa cipher +is the symmetric cipher to use. +It must support ASN.1 encoding of its parameters. +.Xr EVP_des_ede3_cbc 3 +(triple DES) is the algorithm of choice for S/MIME use because most +clients support it. +.Pp +Many browsers implement a "sign and encrypt" option which is simply an +S/MIME +.Vt 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 +.Fn CMS_encrypt . +.Pp +The following flags can be passed in the +.Fa flags +parameter: +.Bl -tag -width Ds +.It Dv CMS_TEXT +MIME headers for type text/plain are prepended to the data. +.It Dv CMS_BINARY +Do not translate the supplied content into MIME canonical format +even though that is required by the S/MIME specifications. +This option should be used if the supplied data is in binary format. +Otherwise, the translation will corrupt it. +If +.Dv CMS_BINARY +is set, then +.Dv CMS_TEXT +is ignored. +.It Dv CMS_USE_KEYID +Use the subject key identifier value to identify recipient certificates. +An error occurs if all recipient certificates do not have a subject key +identifier extension. +By default, issuer name and serial number are used instead. +.It Dv CMS_STREAM +Return a partial +.Vt CMS_ContentInfo +structure suitable for streaming I/O: no data is read from the BIO +.Fa in . +Several functions including +.Xr SMIME_write_CMS 3 , +.Xr i2d_CMS_bio_stream 3 , +or +.Xr PEM_write_bio_CMS_stream 3 +can be used to finalize the structure. +Alternatively, finalization can be performed by obtaining the streaming +ASN1 +.Vt BIO +directly using +.Xr BIO_new_CMS 3 . +Outputting the content of the returned +.Vt CMS_ContentInfo +structure via a function that does not properly finalize it +will give unpredictable results. +.It Dv CMS_PARTIAL +Return a partial +.Vt CMS_ContentInfo +structure to which additional recipients and attributes can +be added before finalization. +.It Dv CMS_DETACHED +Omit the data being encrypted from the +.Vt CMS_ContentInfo +structure. +This is rarely used in practice and is not supported by +.Xr SMIME_write_CMS 3 . +.El +.Sh RETURN VALUES +.Fn CMS_encrypt +returns either a +.Vt CMS_ContentInfo +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_add0_cert 3 , +.Xr CMS_add1_recipient_cert 3 , +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_decrypt 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax (CMS) +.Bl -dash -compact -offset indent +.It +section 6.1: EnvelopedData Type +.It +section 6.2.1: KeyTransRecipientInfo Type +.El +.Sh HISTORY +.Fn CMS_encrypt +first appeared in OpenSSL 0.9.8h +and has been available since +.Ox 6.7 . +.Pp +The +.Dv CMS_STREAM +flag first appeared in OpenSSL 1.0.0. diff --git a/static/openbsd/man3/CMS_final.3 b/static/openbsd/man3/CMS_final.3 new file mode 100644 index 00000000..f2b5755f --- /dev/null +++ b/static/openbsd/man3/CMS_final.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: CMS_final.3,v 1.7 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 25ccb589 Jul 1 02:02:06 2019 +0800 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_FINAL 3 +.Os +.Sh NAME +.Nm CMS_final +.Nd finalise a CMS_ContentInfo structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft int +.Fo CMS_final +.Fa "CMS_ContentInfo *cms" +.Fa "BIO *data" +.Fa "BIO *dcont" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_final +finalises the structure +.Fa cms . +Its purpose is to perform any operations necessary on +.Fa cms +(digest computation for example) and set the appropriate fields. +The parameter +.Fa data +contains the content to be processed. +The +.Fa dcont +parameter contains a +.Vt BIO +to write content to after processing: this is +only used with detached data and will usually be set to +.Dv NULL . +.Pp +This function will normally be called when the +.Dv CMS_PARTIAL +flag is used. +It should only be used when streaming is not performed because the +streaming I/O functions perform finalisation operations internally. +.Sh RETURN VALUES +.Fn CMS_final +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_encrypt 3 , +.Xr CMS_sign 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_final +first appeared in OpenSSL 0.9.8h +and has been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/CMS_get0_RecipientInfos.3 b/static/openbsd/man3/CMS_get0_RecipientInfos.3 new file mode 100644 index 00000000..beb54bdc --- /dev/null +++ b/static/openbsd/man3/CMS_get0_RecipientInfos.3 @@ -0,0 +1,329 @@ +.\" $OpenBSD: CMS_get0_RecipientInfos.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_GET0_RECIPIENTINFOS 3 +.Os +.Sh NAME +.Nm CMS_get0_RecipientInfos , +.Nm CMS_RecipientInfo_type , +.Nm CMS_RecipientInfo_ktri_get0_signer_id , +.Nm CMS_RecipientInfo_ktri_cert_cmp , +.Nm CMS_RecipientInfo_set0_pkey , +.Nm CMS_RecipientInfo_kekri_get0_id , +.Nm CMS_RecipientInfo_kekri_id_cmp , +.Nm CMS_RecipientInfo_set0_key , +.Nm CMS_RecipientInfo_decrypt , +.Nm CMS_RecipientInfo_encrypt +.Nd CMS EnvelopedData RecipientInfo routines +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft STACK_OF(CMS_RecipientInfo) * +.Fo CMS_get0_RecipientInfos +.Fa "CMS_ContentInfo *cms" +.Fc +.Ft int +.Fo CMS_RecipientInfo_type +.Fa "CMS_RecipientInfo *ri" +.Fc +.Ft int +.Fo CMS_RecipientInfo_ktri_get0_signer_id +.Fa "CMS_RecipientInfo *ri" +.Fa "ASN1_OCTET_STRING **keyid" +.Fa "X509_NAME **issuer" +.Fa "ASN1_INTEGER **sno" +.Fc +.Ft int +.Fo CMS_RecipientInfo_ktri_cert_cmp +.Fa "CMS_RecipientInfo *ri" +.Fa "X509 *certificate" +.Fc +.Ft int +.Fo CMS_RecipientInfo_set0_pkey +.Fa "CMS_RecipientInfo *ri" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo CMS_RecipientInfo_kekri_get0_id +.Fa "CMS_RecipientInfo *ri" +.Fa "X509_ALGOR **palg" +.Fa "ASN1_OCTET_STRING **pid" +.Fa "ASN1_GENERALIZEDTIME **pdate" +.Fa "ASN1_OBJECT **potherid" +.Fa "ASN1_TYPE **pothertype" +.Fc +.Ft int +.Fo CMS_RecipientInfo_kekri_id_cmp +.Fa "CMS_RecipientInfo *ri" +.Fa "const unsigned char *id" +.Fa "size_t idlen" +.Fc +.Ft int +.Fo CMS_RecipientInfo_set0_key +.Fa "CMS_RecipientInfo *ri" +.Fa "unsigned char *key" +.Fa "size_t keylen" +.Fc +.Ft int +.Fo CMS_RecipientInfo_decrypt +.Fa "CMS_ContentInfo *cms" +.Fa "CMS_RecipientInfo *ri" +.Fc +.Ft int +.Fo CMS_RecipientInfo_encrypt +.Fa "CMS_ContentInfo *cms" +.Fa "CMS_RecipientInfo *ri" +.Fc +.Sh DESCRIPTION +.Fn CMS_get0_RecipientInfos +returns all the +.Vt RecipientInfo +structures associated with the +.Vt EnvelopedData +structure +.Fa cms . +.Pp +.Fn CMS_RecipientInfo_type +returns the type of +.Fa ri : +.Bl -column CMS_RECIPINFO_TRANS for -compact +.It Dv CMS_RECIPINFO_TRANS Ta for Ta Vt KeyTransRecipientInfo , +.It Dv CMS_RECIPINFO_AGREE Ta for Ta Vt KeyAgreeRecipientInfo , +.It Dv CMS_RECIPINFO_KEK Ta for Ta Vt KEKRecipientInfo , +.It Dv CMS_RECIPINFO_PASS Ta for Ta Vt PasswordRecipientinfo , No or +.It Dv CMS_RECIPINFO_OTHER Ta for Ta Vt OtherRecipientInfo . +.El +.Pp +.Fn CMS_RecipientInfo_ktri_get0_signer_id +retrieves the certificate +.Vt RecipientIdentifier +associated with the +.Vt KeyTransRecipientInfo +structure +.Fa ri . +Either the +.Vt SubjectKeyIdentifier +will be set in +.Fa keyid +or both issuer name and serial number in +.Fa issuer +and +.Fa sno . +.Pp +.Fn CMS_RecipientInfo_ktri_cert_cmp +compares the +.Fa certificate +against the +.Vt KeyTransRecipientInfo +structure +.Fa ri . +.Pp +.Fn CMS_RecipientInfo_set0_pkey +associates the private key +.Fa pkey +with the +.Vt KeyTransRecipientInfo +structure +.Fa ri . +.Pp +.Fn CMS_RecipientInfo_kekri_get0_id +retrieves the key information from the +.Vt KEKRecipientInfo +structure +.Fa ri . +Fields are copied out as follows: +.Bl -column keyEncryptionAlgorithm to -compact +.It Fa keyEncryptionAlgorithm Ta to Ta Pf * Fa palg , +.It Fa keyIdentifier Ta to Ta Pf * Fa pid , +.It Fa date Ta to Ta Pf * Fa pdate Pq optional , +.It Fa other.keyAttrId Ta to Ta Pf * Fa potherid Pq optional , +.It Fa other.keyAttr Ta to Ta Pf * Fa pothertype Pq optional . +.El +Where a field is optional and absent, +.Dv NULL +is written to the corresponding parameter. +Parameters the application is not interested in can be set to +.Dv NULL . +.Pp +.Fn CMS_RecipientInfo_kekri_id_cmp +compares the identifier in the +.Fa id +and +.Fa idlen +parameters against the +.Fa keyIdentifier +field of the +.Vt KEKRecipientInfo +structure +.Fa ri . +.Pp +.Fn CMS_RecipientInfo_set0_key +associates the symmetric +.Fa key +of length +.Fa keylen +with the +.Vt KEKRecipientInfo +structure +.Fa ri . +.Pp +.Fn CMS_RecipientInfo_decrypt +attempts to decrypt the +.Vt RecipientInfo +structure +.Fa ri +in +.Fa cms . +A key must have been associated with +.Fa ri +first. +.Pp +.Fn CMS_RecipientInfo_encrypt +attempts to encrypt the +.Vt RecipientInfo +structure +.Fa ri +in +.Fa cms . +A key must have been associated with +.Fa ri +first and the content encryption key must be available, +for example by a previous call to +.Fn CMS_RecipientInfo_decrypt . +.Pp +The main purpose of these functions is to enable an application to +lookup recipient keys using any appropriate technique when the simpler +method of +.Xr CMS_decrypt 3 +is not appropriate. +.Pp +In typical usage, an application retrieves all +.Vt CMS_RecipientInfo +structures using +.Fn CMS_get0_RecipientInfos +and checks the type of each using +.Fn CMS_RecipientInfo_type . +Depending on the type, the +.Vt CMS_RecipientInfo +structure can be ignored or its key identifier data retrieved using +an appropriate function. +If the corresponding secret or private key can be obtained by any +appropriate means, it can then be associated with the structure and +.Fn CMS_RecipientInfo_decrypt +called. +If successful, +.Xr CMS_decrypt 3 +can be called with a +.Dv NULL +key to decrypt the enveloped content. +.Pp +The function +.Fn CMS_RecipientInfo_encrypt +can be used to add a new recipient to an existing enveloped data +structure. +Typically an application will first decrypt an appropriate +.Vt CMS_RecipientInfo +structure to make the content encrypt key available. +It will then add a new recipient using a function such as +.Xr CMS_add1_recipient_cert 3 +and finally encrypt the content encryption key using +.Fn CMS_RecipientInfo_encrypt . +.Sh RETURN VALUES +.Fn CMS_get0_RecipientInfos +returns an internal pointer to all the +.Vt CMS_RecipientInfo +structures, or +.Dv NULL +if an error occurs. +.Pp +.Fn CMS_RecipientInfo_type +returns an integer constant. +.Pp +.Fn CMS_RecipientInfo_ktri_get0_signer_id , +.Fn CMS_RecipientInfo_set0_pkey , +.Fn CMS_RecipientInfo_kekri_get0_id , +.Fn CMS_RecipientInfo_set0_key , +.Fn CMS_RecipientInfo_decrypt , +and +.Fn CMS_RecipientInfo_encrypt +return 1 for success or 0 if an error occurs. +.Pp +.Fn CMS_RecipientInfo_ktri_cert_cmp +and +.Fn CMS_RecipientInfo_kekri_id_cmp +return 0 when +.Fa ri +matches or non-zero otherwise. +.Pp +Any error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_decrypt 3 +.Sh STANDARDS +RFC 5652 Cryptographic Message Syntax (CMS): +.Bl -dash -compact -offset indent +.It +section 6.1: EnvelopedData Type +.It +section 6.2: RecipientInfo Type +.It +section 6.2.1: KeyTransRecipientInfo Type +.It +section 6.2.3: KEKRecipientInfo Type +.El +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8h, +except that +.Fn CMS_RecipientInfo_encrypt +first appeared in OpenSSL 1.0.2. +They have been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/CMS_get0_SignerInfos.3 b/static/openbsd/man3/CMS_get0_SignerInfos.3 new file mode 100644 index 00000000..f141508e --- /dev/null +++ b/static/openbsd/man3/CMS_get0_SignerInfos.3 @@ -0,0 +1,215 @@ +.\" $OpenBSD: CMS_get0_SignerInfos.3,v 1.10 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_GET0_SIGNERINFOS 3 +.Os +.Sh NAME +.Nm CMS_get0_SignerInfos , +.Nm CMS_SignerInfo_get_version , +.Nm CMS_SignerInfo_get0_signer_id , +.Nm CMS_SignerInfo_get0_signature , +.Nm CMS_SignerInfo_cert_cmp , +.Nm CMS_SignerInfo_set1_signer_cert +.Nd CMS SignedData signer functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft STACK_OF(CMS_SignerInfo) * +.Fo CMS_get0_SignerInfos +.Fa "CMS_ContentInfo *cms" +.Fc +.Ft int +.Fo CMS_SignerInfo_get_version +.Fa "CMS_SignerInfo *si" +.Fa "long *version" +.Fc +.Ft int +.Fo CMS_SignerInfo_get0_signer_id +.Fa "CMS_SignerInfo *si" +.Fa "ASN1_OCTET_STRING **keyid" +.Fa "X509_NAME **issuer" +.Fa "ASN1_INTEGER **sno" +.Fc +.Ft ASN1_OCTET_STRING * +.Fo CMS_SignerInfo_get0_signature +.Fa "CMS_SignerInfo *si" +.Fc +.Ft int +.Fo CMS_SignerInfo_cert_cmp +.Fa "CMS_SignerInfo *si" +.Fa "X509 *certificate" +.Fc +.Ft void +.Fo CMS_SignerInfo_set1_signer_cert +.Fa "CMS_SignerInfo *si" +.Fa "X509 *signer" +.Fc +.Sh DESCRIPTION +.Fn CMS_get0_SignerInfos +returns all the +.Vt SignerInfo +structures associated with the +.Vt SignedData +structure +.Fa cms . +.Pp +.Fn CMS_SignerInfo_get_version +sets +.Pf * Fa version +to the syntax version number of the +.Vt SignerInfo +structure +.Fa si . +.Pp +.Fn CMS_SignerInfo_get0_signer_id +retrieves the certificate +.Vt SignerIdentifier +associated with the +.Vt SignerInfo +structure +.Fa si . +Either the +.Vt SubjectKeyIdentifier +will be set in +.Fa keyid +or both issuer name and serial number in +.Fa issuer +and +.Fa sno . +.Pp +.Fn CMS_SignerInfo_get0_signature +retrieves the +.Fa signature +field of +.Fa si . +The application program is allowed to modify the data pointed to. +.Pp +.Fn CMS_SignerInfo_cert_cmp +compares the +.Fa certificate +against the signer identifier of +.Fa si . +.Pp +.Fn CMS_SignerInfo_set1_signer_cert +sets the signer certificate of +.Fa si +to +.Fa signer . +.Pp +The main purpose of these functions is to enable an application to +look up signer certificates using any appropriate technique when the +simpler method of +.Xr CMS_verify 3 +is not appropriate. +.Pp +In typical usage, an application retrieves all +.Vt CMS_SignerInfo +structures using +.Fn CMS_get0_SignerInfos +and retrieves 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 +.Fn CMS_SignerInfo_set1_signer_cert . +Once all signer certificates have been set, +.Xr CMS_verify 3 +can be used. +.Sh RETURN VALUES +.Fn CMS_get0_SignerInfos +returns an internal pointer to all the +.Vt CMS_SignerInfo +structures, or +.Dv NULL +if there are no signers or if +.Fa cms +is not of the type +.Vt SignedData . +.Pp +.Fn CMS_SignerInfo_get_version +always succeeds and returns 1. +.Pp +.Fn CMS_SignerInfo_get0_signer_id +returns 1 for success or 0 for failure. +.Pp +.Fn CMS_SignerInfo_get0_signature +returns an internal pointer to the signature. +.Pp +.Fn CMS_SignerInfo_cert_cmp +returns 0 for a match or non-zero otherwise. +.Pp +Any error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_signed_add1_attr 3 , +.Xr CMS_verify 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax (CMS) +.Bl -dash -compact -offset indent +.It +section 5.1: SignedData Type +.It +section 5.3: SignerInfo Type +.El +.Sh HISTORY +.Fn CMS_get0_SignerInfos , +.Fn CMS_SignerInfo_get0_signer_id , +.Fn CMS_SignerInfo_cert_cmp , +and +.Fn CMS_SignerInfo_set1_signer_cert +first appeared in OpenSSL 0.9.8h and +.Fn CMS_SignerInfo_get0_signature +in OpenSSL 1.0.2. +These functions have been available since +.Ox 6.7 . +.Pp +.Fn CMS_SignerInfo_get_version +first appeared in +.Ox 7.4 . diff --git a/static/openbsd/man3/CMS_get0_type.3 b/static/openbsd/man3/CMS_get0_type.3 new file mode 100644 index 00000000..5547de49 --- /dev/null +++ b/static/openbsd/man3/CMS_get0_type.3 @@ -0,0 +1,227 @@ +.\" $OpenBSD: CMS_get0_type.3,v 1.10 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 72a7a702 Feb 26 14:05:09 2019 +0000 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_GET0_TYPE 3 +.Os +.Sh NAME +.Nm CMS_get0_type , +.Nm CMS_get_version , +.Nm CMS_set1_eContentType , +.Nm CMS_get0_eContentType , +.Nm CMS_get0_content +.Nd get and set CMS content types and content +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft const ASN1_OBJECT * +.Fo CMS_get0_type +.Fa "const CMS_ContentInfo *cms" +.Fc +.Ft int +.Fo CMS_get_version +.Fa "const CMS_ContentInfo *cms" +.Fa "long *version" +.Fc +.Ft int +.Fo CMS_set1_eContentType +.Fa "CMS_ContentInfo *cms" +.Fa "const ASN1_OBJECT *oid" +.Fc +.Ft const ASN1_OBJECT * +.Fo CMS_get0_eContentType +.Fa "CMS_ContentInfo *cms" +.Fc +.Ft ASN1_OCTET_STRING ** +.Fo CMS_get0_content +.Fa "CMS_ContentInfo *cms" +.Fc +.Sh DESCRIPTION +.Fn CMS_get0_type +returns the content type of the +.Vt ContentInfo +structure +.Fa cms . +The +.Vt ASN1_OBJECT +value returned can be converted to an integer NID value using +.Xr OBJ_obj2nid 3 . +The following content types are identified by the following NIDs: +.Pp +.Bl -column AuthenticatedData NID_id_smime_ct_compressedData -compact +.It Vt SignedData Ta Dv NID_pkcs7_signed +.It Vt EnvelopedData Ta Dv NID_pkcs7_enveloped +.It Vt DigestedData Ta Dv NID_pkcs7_digest +.It Vt EncryptedData Ta Dv NID_pkcs7_encrypted +.It Vt AuthenticatedData Ta Dv NID_id_smime_ct_authData +.It Vt CompressedData Ta Dv NID_id_smime_ct_compressedData +.It arbitrary data Ta Dv NID_pkcs7_data +.El +.Pp +The +.Vt SignedData , +.Vt DigestedData , +.Vt AuthenticatedData , +and +.Vt CompressedData +types contain a field +.Fa encapContentInfo +to allow embedding content, and +.Vt EnvelopedData +and +.Vt EncryptedData +contain a field +.Fa encryptedContentInfo +for that purpose. +The type of the embedded content to be stored in that field can be +set with the function +.Fn CMS_set1_eContentType , +to be called on +.Fa cms +structures returned from functions such as +.Xr CMS_sign 3 +or +.Xr CMS_encrypt 3 +with the +.Dv CMS_PARTIAL +flag set and +.Em before +the structure is finalised; otherwise the results are undefined. +.Fn CMS_set1_eContentType +copies the supplied +.Fa oid , +so it should be freed up after use. +.Pp +.Fn CMS_get_version +sets +.Pf * Fa version +to the syntax version number of the +.Vt ContentInfo +structure +.Fa cms . +The version is a number between 0 and 5 and is defined for all the +above content types except for arbitrary data. +For arbitrary data and unsupported content types +.Fn CMS_get_version +fails and the content of +.Pf * Fa version +is unspecified. +.Pp +.Fn CMS_get0_eContentType +returns the type of the embedded content. +.Pp +.Fn CMS_get0_content +returns a pointer to the storage location where the pointer to the +embedded content is stored. +That means that for example after +.Pp +.Dl ASN1_OCTET_STRING **pconf = CMS_get0_content(cms); +.Pp +.Pf * Va pconf +could be +.Dv NULL +if there is no embedded content. +Applications can access, modify or create the embedded content in a +.Vt CMS_ContentInfo +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 +.Fn CMS_get0_type +and +.Fn CMS_get0_eContentType +return internal pointers to +.Vt OBJECT IDENTIFIER +structures. +.Pp +.Fn CMS_get_version +returns 1 on success and 0 on failure. +.Pp +.Fn CMS_get0_content +returns an internal pointer to the storage location where the pointer +to the embedded content is stored. +.Pp +.Fn CMS_set1_eContentType +returns 1 for success or 0 if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr d2i_CMS_ContentInfo 3 , +.Xr SMIME_read_CMS 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax +.Pp +RFC 3274: Compressed Data Content Type for Cryptographic Message Syntax (CMS) +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8h +and have been available since +.Ox 6.7 . +.Pp +.Fn CMS_get_version +first appeared in +.Ox 7.4 . diff --git a/static/openbsd/man3/CMS_get1_ReceiptRequest.3 b/static/openbsd/man3/CMS_get1_ReceiptRequest.3 new file mode 100644 index 00000000..17a14c47 --- /dev/null +++ b/static/openbsd/man3/CMS_get1_ReceiptRequest.3 @@ -0,0 +1,199 @@ +.\" $OpenBSD: CMS_get1_ReceiptRequest.3,v 1.8 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_GET1_RECEIPTREQUEST 3 +.Os +.Sh NAME +.Nm CMS_ReceiptRequest_create0 , +.Nm CMS_add1_ReceiptRequest , +.Nm CMS_get1_ReceiptRequest , +.Nm CMS_ReceiptRequest_get0_values +.Nd CMS signed receipt request functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft CMS_ReceiptRequest * +.Fo CMS_ReceiptRequest_create0 +.Fa "unsigned char *id" +.Fa "int idlen" +.Fa "int allorfirst" +.Fa "STACK_OF(GENERAL_NAMES) *receiptList" +.Fa "STACK_OF(GENERAL_NAMES) *receiptsTo" +.Fc +.Ft int +.Fo CMS_add1_ReceiptRequest +.Fa "CMS_SignerInfo *si" +.Fa "CMS_ReceiptRequest *rr" +.Fc +.Ft int +.Fo CMS_get1_ReceiptRequest +.Fa "CMS_SignerInfo *si" +.Fa "CMS_ReceiptRequest **prr" +.Fc +.Ft void +.Fo CMS_ReceiptRequest_get0_values +.Fa "CMS_ReceiptRequest *rr" +.Fa "ASN1_STRING **pcid" +.Fa "int *pallorfirst" +.Fa "STACK_OF(GENERAL_NAMES) **plist" +.Fa "STACK_OF(GENERAL_NAMES) **prto" +.Fc +.Sh DESCRIPTION +.Fn CMS_ReceiptRequest_create0 +creates a new +.Vt ReceiptRequest +structure. +The +.Fa signedContentIdentifier +field is set using +.Fa id +and +.Fa idlen , +or it is set to 32 bytes of pseudo random data if +.Fa id +is +.Dv NULL . +If +.Fa receiptList +is +.Dv NULL , +the +.Fa allOrFirstTier +option in the +.Fa receiptsFrom +field is set to the value of the +.Fa allorfirst +argument. +If +.Fa receiptList +is not +.Dv NULL , +the +.Fa receiptList +option in the +.Fa receiptsFrom +field is used. +The +.Fa receiptsTo +argument specifies the value of the +.Fa receiptsTo +field. +.Pp +.Fn CMS_add1_ReceiptRequest +adds a BER-encoded copy of +.Fa rr +to +.Fa si . +.Pp +.Fn CMS_get1_ReceiptRequest +looks for a signed receipt request in +.Fa si . +If any is found, it is decoded and written to +.Fa prr . +.Pp +.Fn CMS_ReceiptRequest_get0_values +retrieves the values of a receipt request. +The +.Fa signedContentIdentifier +is copied to +.Fa pcid . +If the +.Fa allOrFirstTier +option is used in the +.Fa receiptsFrom +field, its value is copied to +.Fa pallorfirst ; +otherwise the +.Fa receiptList +field is copied to +.Fa plist . +The +.Fa receiptsTo +field is copied to +.Fa prto . +.Pp +The contents of a signed receipt should only be considered meaningful if +the corresponding +.Vt CMS_ContentInfo +structure can be successfully verified using +.Xr CMS_verify 3 . +.Sh RETURN VALUES +.Fn CMS_ReceiptRequest_create0 +returns the new signed receipt request structure or +.Dv NULL +if an error occurred. +.Pp +.Fn CMS_add1_ReceiptRequest +returns 1 for success or 0 if an error occurred. +.Pp +.Fn CMS_get1_ReceiptRequest +returns 1 is a signed receipt request is found and decoded. +It returns 0 if a signed receipt request is not present or -1 if it is +present but malformed. +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_sign 3 , +.Xr CMS_sign_receipt 3 , +.Xr CMS_verify 3 , +.Xr CMS_verify_receipt 3 , +.Xr ERR_get_error 3 +.Sh STANDARDS +RFC 2634: Enhanced Security Services for S/MIME, +section 2.7: Receipt Request Syntax +.Sh HISTORY +.Fn CMS_ReceiptRequest_create0 , +.Fn CMS_add1_ReceiptRequest , +.Fn CMS_get1_ReceiptRequest , +and +.Fn CMS_ReceiptRequest_get0_values +first appeared in OpenSSL 0.9.8h +and have been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/CMS_sign.3 b/static/openbsd/man3/CMS_sign.3 new file mode 100644 index 00000000..82f9ff98 --- /dev/null +++ b/static/openbsd/man3/CMS_sign.3 @@ -0,0 +1,247 @@ +.\" $OpenBSD: CMS_sign.3,v 1.13 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_SIGN 3 +.Os +.Sh NAME +.Nm CMS_sign +.Nd create a CMS SignedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo CMS_sign +.Fa "X509 *signcert" +.Fa "EVP_PKEY *pkey" +.Fa "STACK_OF(X509) *certs" +.Fa "BIO *data" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_sign +creates and returns a CMS +.Vt SignedData +structure. +.Fa signcert +is the certificate to sign with, +.Fa pkey +is the corresponding private key. +.Fa certs +is an optional additional set of certificates to include in the CMS +structure (for example any intermediate CAs in the chain). +Any or all of these parameters can be +.Dv NULL . +.Pp +The data to be signed is read from +.Fa data . +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +argument: +.Bl -tag -width Ds +.It Dv CMS_TEXT +Prepend MIME headers for the type text/plain to the data. +Many S/MIME clients expect the signed content to include valid MIME +headers. +.It Dv CMS_NOCERTS +Do not include the signer's certificate in the +.Vt CMS_ContentInfo +structure. +The signer's certificate must still be supplied in the +.Fa signcert +parameter though. +This can reduce the size of the signature if the signer's certificate can +be obtained by other means, for example from a previously signed message. +.It Dv CMS_DETACHED +Omit the data being signed from the +.Vt CMS_ContentInfo +structure. +This is used for +.Vt CMS_ContentInfo +detached signatures which are used in S/MIME plaintext signed messages +for example. +.It Dv CMS_BINARY +Do not translate the supplied content into MIME canonical format +even though that is required by the S/MIME specifications. +This option should be used if the supplied data is in binary format. +Otherwise the translation will corrupt it. +.It Dv CMS_NOATTR +Do not add any +.Vt SignedAttributes . +By default, the +.Fa signerInfos +field includes several CMS +.Vt SignedAttributes +including the signing time, the CMS content type, +and the supported list of ciphers in an +.Vt SMIMECapabilities +attribute. +.It Dv CMS_NOSMIMECAP +Omit just the +.Vt SMIMECapabilities . +If present, the SMIMECapabilities attribute indicates support for the +following algorithms in preference order: 256-bit AES, +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. +.It Dv CMS_USE_KEYID +Use the subject key identifier value to identify signing certificates. +An error occurs if the signing certificate does not have a subject key +identifier extension. +By default, issuer name and serial number are used instead. +.It Dv CMS_STREAM +Only initialize the returned +.Vt CMS_ContentInfo +structure to prepare it for performing the signing operation. +The signing is however +.Em not +performed and the data to be signed is not read from the +.Fa data +parameter. +Signing is deferred until after the data has been written. +In this way, data can be signed in a single pass. +The returned +.Vt CMS_ContentInfo +structure is +.Em not +complete and outputting its contents via a function that does not +properly finalize the +.Vt CMS_ContentInfo +structure will give unpredictable results. +Several functions including +.Xr SMIME_write_CMS 3 , +.Xr i2d_CMS_bio_stream 3 , +or +.Xr PEM_write_bio_CMS_stream 3 +finalize the structure. +Alternatively, finalization can be performed by obtaining the streaming +ASN1 +.Vt BIO +directly using +.Xr BIO_new_CMS 3 . +.It Dv CMS_PARTIAL +Output a partial +.Vt CMS_ContentInfo +structure to which additional signers and capabilities can be +added before finalization. +.El +.Pp +If a signer is specified, it will use the default digest for the signing +algorithm. +This is SHA-1 for both RSA and DSA keys. +.Pp +If +.Fa signcert +and +.Fa pkey +are +.Dv NULL , +then a certificates only CMS structure is output. +.Pp +The function +.Fn CMS_sign +is a basic CMS signing function whose output will be suitable for many +purposes. +For finer control of the output format the +.Fa certs , +.Fa signcert +and +.Fa pkey +parameters can all be +.Dv NULL +and the +.Dv CMS_PARTIAL +flag set. +Then one or more signers can be added using the function +.Xr CMS_add1_signer 3 , +non default digests can be used and custom attributes added. +.Xr CMS_final 3 +must then be called to finalize the structure if streaming is not +enabled. +.Sh RETURN VALUES +.Fn CMS_sign +returns either a valid +.Vt CMS_ContentInfo +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_add0_cert 3 , +.Xr CMS_add1_signer 3 , +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_final 3 , +.Xr CMS_sign_receipt 3 , +.Xr CMS_verify 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax (CMS) +.Bl -dash -compact -offset indent +.It +section 5.1: SignedData Type +.It +section 5.3: SignerInfo Type +.El +.Pp +RFC 8419: Use of Edwards-Curve Digital Signature Algorithm (EdDSA) Signatures +in the Cryptographic Message Syntax (CMS) +.Pp +RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME) +Version\ 4.0 Message Specification, +section 2.5.2: SMIMECapabilities Attribute +.Sh HISTORY +.Fn CMS_sign +first appeared in OpenSSL 0.9.8h +and has been available since +.Ox 6.7 . +.Sh BUGS +Some attributes such as counter signatures are not supported. diff --git a/static/openbsd/man3/CMS_sign_receipt.3 b/static/openbsd/man3/CMS_sign_receipt.3 new file mode 100644 index 00000000..7702ab36 --- /dev/null +++ b/static/openbsd/man3/CMS_sign_receipt.3 @@ -0,0 +1,120 @@ +.\" $OpenBSD: CMS_sign_receipt.3,v 1.9 2025/12/20 08:40:47 tb Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: December 20 2025 $ +.Dt CMS_SIGN_RECEIPT 3 +.Os +.Sh NAME +.Nm CMS_sign_receipt +.Nd create a CMS signed receipt +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo CMS_sign_receipt +.Fa "CMS_SignerInfo *si" +.Fa "X509 *signcert" +.Fa "EVP_PKEY *pkey" +.Fa "STACK_OF(X509) *certs" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_sign_receipt +creates a new CMS +.Vt SignedData +structure containing a signed +.Vt Receipt +as its embedded content. +.Fa si +is the +.Vt SignerInfo +structure containing the signed receipt request. +.Fa signcert +is the certificate to sign with, +.Fa pkey +is the corresponding private key. +.Fa certs +is an optional additional set of certificates to include in the CMS +structure (for example any intermediate CAs in the chain). +.Pp +This function behaves in a similar way to +.Xr CMS_sign 3 +except that the +.Fa flags +values +.Dv CMS_DETACHED , +.Dv CMS_BINARY , +.Dv CMS_NOATTR , +.Dv CMS_TEXT , +and +.Dv CMS_STREAM +are not supported since they do not make sense in the context of +signed receipts. +.Sh RETURN VALUES +.Fn CMS_sign_receipt +returns either a valid +.Vt CMS_ContentInfo +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_get1_ReceiptRequest 3 , +.Xr CMS_sign 3 , +.Xr CMS_verify_receipt 3 +.Sh STANDARDS +RFC 2634: Enhanced Security Services for S/MIME, section 2.8: Receipt Syntax +.Sh HISTORY +.Fn CMS_sign_receipt +first appeared in OpenSSL 0.9.8h +and has been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/CMS_signed_add1_attr.3 b/static/openbsd/man3/CMS_signed_add1_attr.3 new file mode 100644 index 00000000..10a959bb --- /dev/null +++ b/static/openbsd/man3/CMS_signed_add1_attr.3 @@ -0,0 +1,361 @@ +.\" $OpenBSD: CMS_signed_add1_attr.3,v 1.7 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2024 Job Snijders +.\" Copyright (c) 2024 Theo Buehler +.\" Copyright (c) 2021 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 $Mdocdate: June 13 2025 $ +.Dt CMS_SIGNED_ADD1_ATTR 3 +.Os +.Sh NAME +.Nm CMS_signed_add1_attr , +.Nm CMS_signed_add1_attr_by_NID , +.Nm CMS_signed_add1_attr_by_OBJ , +.Nm CMS_signed_add1_attr_by_txt , +.Nm CMS_signed_delete_attr , +.Nm CMS_signed_get0_data_by_OBJ , +.Nm CMS_signed_get_attr , +.Nm CMS_signed_get_attr_by_NID , +.Nm CMS_signed_get_attr_by_OBJ , +.Nm CMS_signed_get_attr_count , +.Nm CMS_unsigned_add1_attr , +.Nm CMS_unsigned_add1_attr_by_NID , +.Nm CMS_unsigned_add1_attr_by_OBJ , +.Nm CMS_unsigned_add1_attr_by_txt , +.Nm CMS_unsigned_delete_attr , +.Nm CMS_unsigned_get0_data_by_OBJ , +.Nm CMS_unsigned_get_attr , +.Nm CMS_unsigned_get_attr_by_NID , +.Nm CMS_unsigned_get_attr_by_OBJ , +.Nm CMS_unsigned_get_attr_count +.Nd change signed and unsigned attributes of a CMS SignerInfo object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft int +.Fo CMS_signed_add1_attr +.Fa "CMS_SignerInfo *si" +.Fa "X509_ATTRIBUTE *attr" +.Fc +.Ft int +.Fo CMS_signed_add1_attr_by_NID +.Fa "CMS_SignerInfo *si" +.Fa "int nid" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft int +.Fo CMS_signed_add1_attr_by_OBJ +.Fa "CMS_SignerInfo *si" +.Fa "const ASN1_OBJECT *obj" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft int +.Fo CMS_signed_add1_attr_by_txt +.Fa "CMS_SignerInfo *si" +.Fa "const char *attrname" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft X509_ATTRIBUTE * +.Fo CMS_signed_delete_attr +.Fa "CMS_SignerInfo *si" +.Fa "int loc" +.Fc +.Ft void * +.Fo CMS_signed_get0_data_by_OBJ +.Fa "CMS_SignerInfo *si" +.Fa "const ASN1_OBJECT *oid" +.Fa "int start_after" +.Fa "int type" +.Fc +.Ft X509_ATTRIBUTE * +.Fo CMS_signed_get_attr +.Fa "const CMS_SignerInfo *si" +.Fa "int loc" +.Fc +.Ft int +.Fo CMS_signed_get_attr_by_NID +.Fa "const CMS_SignerInfo *si" +.Fa "int nid" +.Fa "int start_after" +.Fc +.Ft int +.Fo CMS_signed_get_attr_by_OBJ +.Fa "const CMS_SignerInfo *si" +.Fa "const ASN1_OBJECT *obj" +.Fa "int start_after" +.Fc +.Ft int +.Fo CMS_signed_get_attr_count +.Fa "const CMS_SignerInfo *si" +.Fc +.Ft int +.Fo CMS_unsigned_add1_attr +.Fa "CMS_SignerInfo *si" +.Fa "X509_ATTRIBUTE *attr" +.Fc +.Ft int +.Fo CMS_unsigned_add1_attr_by_NID +.Fa "CMS_SignerInfo *si" +.Fa "int nid" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft int +.Fo CMS_unsigned_add1_attr_by_OBJ +.Fa "CMS_SignerInfo *si" +.Fa "const ASN1_OBJECT *obj" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft int +.Fo CMS_unsigned_add1_attr_by_txt +.Fa "CMS_SignerInfo *si" +.Fa "const char *attrname" +.Fa "int type" +.Fa "const void *bytes" +.Fa "int len" +.Fc +.Ft X509_ATTRIBUTE * +.Fo CMS_unsigned_delete_attr +.Fa "CMS_SignerInfo *si" +.Fa "int loc" +.Fc +.Ft void * +.Fo CMS_unsigned_get0_data_by_OBJ +.Fa "CMS_SignerInfo *si" +.Fa "ASN1_OBJECT *oid" +.Fa "int start_after" +.Fa "int type" +.Fc +.Ft X509_ATTRIBUTE * +.Fo CMS_unsigned_get_attr +.Fa "const CMS_SignerInfo *si" +.Fa "int loc" +.Fc +.Ft int +.Fo CMS_unsigned_get_attr_by_NID +.Fa "const CMS_SignerInfo *si" +.Fa "int nid" +.Fa "int start_after" +.Fc +.Ft int +.Fo CMS_unsigned_get_attr_by_OBJ +.Fa "const CMS_SignerInfo *si" +.Fa "const ASN1_OBJECT *obj" +.Fa "int start_after" +.Fc +.Ft int +.Fo CMS_unsigned_get_attr_count +.Fa "const CMS_SignerInfo *si" +.Fc +.Sh DESCRIPTION +A +.Em CMS_SignerInfo +object has two optional sets of X.501 attributes: +a set of signed attributes in the +.Fa signedAttrs +array and a set of unsigned attributes in the +.Fa unsignedAttrs +array. +The +.Fn CMS_signed_* +and +.Fn CMS_unsigned_* +functions are similar, except +.Fn CMS_signed_* +modifies the +.Vt CMS_SignerInfo +object's set of signed attributes and +.Fn CMS_unsigned_* +modifies the +.Vt CMS_SignerInfo +object's set of unsigned attributes. +For brevity only the +.Fn CMS_signed_* +functions are described below. +.Pp +.Fn CMS_signed_add1_attr +appends a deep copy of +.Fa attr +to the +.Fa signedAttrs +array of +.Fa si , +allocating a new array if necessary. +.Pp +.Fn CMS_signed_add1_attr_by_NID , +.Fn CMS_signed_add1_attr_by_OBJ , +and +.Fn CMS_signed_add1_attr_by_txt +create a new X.501 Attribute object using +.Xr X509_ATTRIBUTE_create_by_NID 3 , +.Xr X509_ATTRIBUTE_create_by_OBJ 3 , +or +.Xr X509_ATTRIBUTE_create_by_txt 3 , +respectively, +and append it to the +.Fa signedAttrs +array of +.Fa si . +.Pp +.Fn CMS_signed_delete_attr +deletes the element with the zero-based +.Fa loc +in +.Fa signedAttrs +of +.Fa si . +.Pp +.Fn CMS_signed_get0_data_by_OBJ , +.Fn CMS_signed_get_attr_by_NID , +and +.Fn CMS_signed_get_attr_by_OBJ +search the array starting after the index +.Fa start_after . +They fail if no matching object is found. +.Fn CMS_signed_get0_data_by_OBJ +also fails if the data is not of the requested +.Fa type . +.Pp +Additionally, the +.Fa start_after +argument of +.Fn CMS_signed_get0_data_by_OBJ +is interpreted in a special way. +If +.Fa start_after +is \-2 or smaller, the function also fails if the +.Fa signedAttrs +array of +.Fa si , +contains more than one matching object. +If +.Fa start_after +is \-3 or smaller, it also fails unless the matching object contains exactly +one value. +.Pp +.Fn CMS_signed_get_attr +returns the array element at the zero-based +.Fa loc . +It fails if the +.Fa loc +argument is negative or greater than or equal to the number of objects in the +array. +.Pp +.Fn CMS_signed_get_attr_count +returns the number of objects currently stored in the +.Fa signedAttrs +array of +.Fa si . +.Sh RETURN VALUES +.Fn CMS_signed_add1_attr , +.Fn CMS_signed_add1_attr_by_NID , +.Fn CMS_signed_add1_attr_by_OBJ , +.Fn CMS_signed_add1_attr_by_txt , +.Fn CMS_unsigned_add1_attr , +.Fn CMS_unsigned_add1_attr_by_NID , +.Fn CMS_unsigned_add1_attr_by_OBJ , +and +.Fn CMS_unsigned_add1_attr_by_txt +return 1 for success or 0 if an error occurs. +.Pp +.Fn CMS_signed_delete_attr +returns the deleted element or +.Dv NULL +if the +.Fa signedAttrs +array is +.Dv NULL , +or if the requested +.Fa loc +argument is negative, or greater than or equal to the number of objects in it. +.Pp +.Fn CMS_unsigned_delete_attr +returns the deleted element or +.Dv NULL +if the +.Fa unsignedAttrs +array is +.Dv NULL , +or if the requested +.Fa loc +argument is negative, or greater than or equal to the number of objects in it. +.Pp +.Fn CMS_signed_get0_data_by_OBJ +and +.Fn CMS_unsigned_get0_data_by_OBJ +return an internal pointer to the data contained in the value of the first +object that has an index greater than +.Fa start_after +and a type matching +.Fa type , +or NULL on failure. +.Pp +.Fn CMS_signed_get_attr +and +.Fn CMS_unsigned_get_attr +return an internal pointer or NULL on failure. +.Pp +.Fn CMS_signed_get_attr_by_NID , +.Fn CMS_signed_get_attr_by_OBJ , +.Fn CMS_unsigned_get_attr_by_NID , +and +.Fn CMS_unsigned_get_attr_by_OBJ +return the index of the first object in the array that has an index greater than +.Fa start_after +and a type matching +.Fa nid +or +.Fa oid , +respectively, or \-1 on failure. +In addition, +.Fn CMS_signed_get_attr_by_OBJ +and +.Fn CMS_unsigned_get_attr_by_OBJ +return \-2 if +.Xr OBJ_nid2obj 3 +fails on the requested +.Fa nid . +.Pp +.Fn CMS_signed_get_attr_count +and +.Fn CMS_unsigned_get_attr_count +return the number of array elements or \-1 on failure. +.Sh SEE ALSO +.Xr CMS_add1_signer 3 , +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_get0_SignerInfos 3 , +.Xr OBJ_nid2obj 3 , +.Xr X509_ATTRIBUTE_create_by_OBJ 3 , +.Xr X509_ATTRIBUTE_new 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax (CMS) +.Bl -dash -compact -offset indent +.It +section 5.3: SignerInfo Type +.It +section 11: Useful Attributes +.El +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.9 and have been available since +.Ox 6.6 . diff --git a/static/openbsd/man3/CMS_uncompress.3 b/static/openbsd/man3/CMS_uncompress.3 new file mode 100644 index 00000000..2a5e2f59 --- /dev/null +++ b/static/openbsd/man3/CMS_uncompress.3 @@ -0,0 +1,116 @@ +.\" $OpenBSD: CMS_uncompress.3,v 1.8 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_UNCOMPRESS 3 +.Os +.Sh NAME +.Nm CMS_uncompress +.Nd uncompress a CMS CompressedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft int +.Fo CMS_uncompress +.Fa "CMS_ContentInfo *cms" +.Fa "BIO *dcont" +.Fa "BIO *out" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_uncompress +extracts and uncompresses the content of a CMS +.Vt CompressedData +structure +.Fa cms +and writes it to +.Fa out . +.Pp +In the rare case where the compressed content is detached, +pass it in via +.Fa dcont . +For normal use, set +.Fa dcont +to +.Dv NULL . +.Pp +The only currently supported compression algorithm is zlib: if the +structure indicates the use of any other algorithm, an error is returned. +If zlib support is not compiled in, +.Fn CMS_uncompress +always returns an error. +.Pp +If the +.Dv CMS_TEXT +bit is set in +.Fa flags , +MIME headers for type text/plain are deleted from the content. +If the content is not of type text/plain, an error is returned. +.Sh RETURN VALUES +.Fn CMS_uncompress +returns 1 for success or 0 for failure. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_compress 3 , +.Xr CMS_ContentInfo_new 3 +.Sh STANDARDS +RFC 3274: Compressed Data Content Type for Cryptographic Message Syntax (CMS) +.Sh HISTORY +.Fn CMS_uncompress +first appeared in OpenSSL 0.9.8h +and has been available since +.Ox 6.7 . +.Sh BUGS +The lack of single pass processing and the need to hold all data in +memory as mentioned in +.Xr CMS_verify 3 +also applies to +.Fn CMS_uncompress . diff --git a/static/openbsd/man3/CMS_verify.3 b/static/openbsd/man3/CMS_verify.3 new file mode 100644 index 00000000..a8803b05 --- /dev/null +++ b/static/openbsd/man3/CMS_verify.3 @@ -0,0 +1,231 @@ +.\" $OpenBSD: CMS_verify.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CMS_VERIFY 3 +.Os +.Sh NAME +.Nm CMS_verify , +.Nm CMS_get0_signers +.Nd verify a CMS SignedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft int +.Fo CMS_verify +.Fa "CMS_ContentInfo *cms" +.Fa "STACK_OF(X509) *certs" +.Fa "X509_STORE *store" +.Fa "BIO *indata" +.Fa "BIO *out" +.Fa "unsigned int flags" +.Fc +.Ft STACK_OF(X509) * +.Fo CMS_get0_signers +.Fa "CMS_ContentInfo *cms" +.Fc +.Sh DESCRIPTION +.Fn CMS_verify +verifies the CMS +.Vt SignedData +structure +.Fa cms . +.Fa certs +is a set of certificates in which to search for the signing +certificate(s). +.Fa store +is a trusted certificate store used for chain verification. +.Fa indata +is the detached content if the content is not present in +.Fa cms . +The content is written to +.Fa out +if it is not +.Dv NULL . +.Pp +.Fn CMS_get0_signers +retrieves the signing certificate(s) from +.Fa cms . +It may only be called after a successful +.Fn CMS_verify +operation. +The signers must be freed with +.Fn sk_X509_free . +.Pp +Normally the verify process proceeds as follows. +.Pp +Initially some sanity checks are performed on +.Fa cms . +There must be at least one signature on the data. +If the content is detached, +.Fa indata +cannot be +.Dv NULL . +.Pp +An attempt is made to locate all the signing certificate(s), first +looking in the +.Fa certs +parameter (if it is not +.Dv NULL ) +and then looking in any certificates contained in the +.Fa cms +structure itself. +If any signing certificate cannot be located, the operation fails. +.Pp +Each signing certificate is chain verified using the +.Sy smimesign +purpose and the supplied trusted certificate +.Fa store . +Any internal certificates in the message are used as untrusted CAs. +If CRL checking is enabled in +.Fa store , +any internal CRLs are used in addition to attempting to look them up in +.Fa store . +If any chain verify fails, an error code is returned. +.Pp +Finally the signed content is read (and written to +.Fa out +if it is not +.Dv NULL ) +and the signature is checked. +.Pp +If all signatures verify correctly, then the function is successful. +.Pp +Any of the following +.Fa flags +(OR'ed together) can be passed to change the default verify behaviour: +.Bl -tag -width Ds +.It Dv CMS_NOINTERN +Do not use the certificates in the message itself when +locating the signing certificate(s). +This means that all the signing certificates must be in the +.Fa certs +parameter. +.It Dv CMS_NOCRL +If CRL checking is enabled in +.Fa store , +then any CRLs in the message itself are ignored. +.It Dv CMS_TEXT +MIME headers for type text/plain are deleted from the content. +If the content is not of type text/plain, an error is returned. +.It Dv CMS_NO_SIGNER_CERT_VERIFY +Do not verify signing certificates. +.It Dv CMS_NO_ATTR_VERIFY +Do not check the signed attributes signature. +.It Dv CMS_NO_CONTENT_VERIFY +Do not check the content digest. +.El +.Pp +One application of +.Dv CMS_NOINTERN +is to only accept messages signed by a small number of certificates. +The acceptable certificates would be passed in the +.Fa certs +parameter. +In this case, if the signer is not one of the certificates supplied in +.Fa certs , +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 signers certificates +manually using the signed data utility functions. +.Pp +Care should be taken when modifying the default verify behaviour, for +example setting +.Dv CMS_NO_CONTENT_VERIFY +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 +.Fa out +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 +.Fn CMS_verify +returns 1 for a successful verification or 0 if an error occurred. +.Pp +.Fn CMS_get0_signers +returns all signers or +.Dv NULL +if an error occurred. +The signers must be freed with +.Fn sk_X509_free . +.Pp +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_get0_SignerInfos 3 , +.Xr CMS_sign 3 , +.Xr CMS_verify_receipt 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax (CMS), +section 5.1: SignedData Type +.Pp +RFC 8419: Use of Edwards-Curve Digital Signature Algorithm (EdDSA) Signatures +in the Cryptographic Message Syntax (CMS) +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8h +and have been available since +.Ox 6.7 . +.Sh BUGS +The trusted certificate store is not searched for the signing certificate. +This is primarily due to the inadequacies of the current +.Vt X509_STORE +functionality. +.Pp +The lack of single pass processing means that the signed content must +all be held in memory if it is not detached. diff --git a/static/openbsd/man3/CMS_verify_receipt.3 b/static/openbsd/man3/CMS_verify_receipt.3 new file mode 100644 index 00000000..738d976c --- /dev/null +++ b/static/openbsd/man3/CMS_verify_receipt.3 @@ -0,0 +1,111 @@ +.\" $OpenBSD: CMS_verify_receipt.3,v 1.9 2025/12/20 08:40:47 tb Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: December 20 2025 $ +.Dt CMS_VERIFY_RECEIPT 3 +.Os +.Sh NAME +.Nm CMS_verify_receipt +.Nd verify a CMS signed receipt +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft int +.Fo CMS_verify_receipt +.Fa "CMS_ContentInfo *rcms" +.Fa "CMS_ContentInfo *ocms" +.Fa "STACK_OF(X509) *certs" +.Fa "X509_STORE *store" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_verify_receipt +verifies a CMS signed receipt. +.Fa rcms +is the signed receipt to verify. +.Fa ocms +is the original +.Vt SignedData +structure containing the receipt request. +.Fa certs +is a set of certificates in which to search for the signing certificate. +.Fa store +is a trusted certificate store (used for chain verification). +.Pp +This function behaves in a similar way to +.Xr CMS_verify 3 +except that the +.Fa flags +values +.Dv CMS_DETACHED , +.Dv CMS_BINARY , +.Dv CMS_TEXT , +and +.Dv CMS_STREAM +are not supported since they do not make sense in the context of signed +receipts. +.Sh RETURN VALUES +.Fn CMS_verify_receipt +returns 1 for a successful verification or 0 if an error occurred. +.Pp +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_get1_ReceiptRequest 3 , +.Xr CMS_sign_receipt 3 , +.Xr CMS_verify 3 +.Sh STANDARDS +RFC 2634: Enhanced Security Services for S/MIME, section 2.8: Receipt Syntax +.Sh HISTORY +.Fn CMS_verify_receipt +first appeared in OpenSSL 0.9.8h +and has been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/CONF_modules_free.3 b/static/openbsd/man3/CONF_modules_free.3 new file mode 100644 index 00000000..ab299bcb --- /dev/null +++ b/static/openbsd/man3/CONF_modules_free.3 @@ -0,0 +1,101 @@ +.\" $OpenBSD: CONF_modules_free.3,v 1.7 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2004, 2006 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CONF_MODULES_FREE 3 +.Os +.Sh NAME +.Nm CONF_modules_free , +.Nm CONF_modules_finish , +.Nm CONF_modules_unload +.Nd OpenSSL configuration cleanup functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/conf.h +.Ft void +.Fo CONF_modules_free +.Fa void +.Fc +.Ft void +.Fo CONF_modules_finish +.Fa void +.Fc +.Ft void +.Fo CONF_modules_unload +.Fa "int all" +.Fc +.Sh DESCRIPTION +.Fn CONF_modules_free +closes down and frees up all memory allocated by all configuration +modules. +Normally applications will only call this function +at application exit to tidy up any configuration performed. +.Pp +.Fn CONF_modules_finish +calls the configuration +.Sy finish +handler of each configuration module to free up any configuration +that module may have performed. +.Pp +.Fn CONF_modules_unload +finishes and unloads configuration modules. +If +.Fa all +is set to 1, the builtin modules will be unloaded as well. +.Sh SEE ALSO +.Xr CONF_modules_load_file 3 , +.Xr OPENSSL_config 3 +.Sh HISTORY +.Fn CONF_modules_free , +.Fn CONF_modules_finish , +and +.Fn CONF_modules_unload +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/CONF_modules_load_file.3 b/static/openbsd/man3/CONF_modules_load_file.3 new file mode 100644 index 00000000..78cfc32f --- /dev/null +++ b/static/openbsd/man3/CONF_modules_load_file.3 @@ -0,0 +1,277 @@ +.\" $OpenBSD: CONF_modules_load_file.3,v 1.16 2025/06/09 12:43:53 schwarze Exp $ +.\" full merge up to: e9b77246 Jan 20 19:58:49 2017 +0100 +.\" selective merge up to: d090fc00 Feb 26 13:11:10 2019 +0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 9 2025 $ +.Dt CONF_MODULES_LOAD_FILE 3 +.Os +.Sh NAME +.Nm CONF_modules_load_file , +.Nm CONF_modules_load , +.Nm X509_get_default_cert_area +.Nd OpenSSL configuration functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/conf.h +.Ft int +.Fo CONF_modules_load_file +.Fa "const char *filename" +.Fa "const char *appname" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo CONF_modules_load +.Fa "const CONF *cnf" +.Fa "const char *appname" +.Fa "unsigned long flags" +.Fc +.In openssl/x509.h +.Ft const char * +.Fn X509_get_default_cert_area void +.Sh DESCRIPTION +The function +.Fn CONF_modules_load_file +configures OpenSSL using the file +.Fa filename +in +.Xr openssl.cnf 5 +format and the application name +.Fa appname . +If +.Fa filename +is +.Dv NULL , +the standard OpenSSL configuration file +.Pa /etc/ssl/openssl.cnf +is used. +If +.Fa appname +is +.Dv NULL , +the standard OpenSSL application name +.Qq openssl_conf +is used. +The behaviour can be customized using +.Fa flags . +.Pp +See the +.Sx EXAMPLES +section for additional functions that may need to be called. +Calling configuration functions in the right order for the intended +effect can be tricky because many configuration functions internally +call each other. +.Pp +.Fn CONF_modules_load +is identical to +.Fn CONF_modules_load_file +except it reads configuration information from +.Fa cnf . +.Pp +The following +.Fa flags +are currently recognized: +.Bl -tag -width Ds +.It Dv CONF_MFLAGS_IGNORE_ERRORS +Ignore errors returned by individual configuration modules. +By default, the first module error is considered fatal and no further +modules are loaded. +.It Dv CONF_MFLAGS_SILENT +Do not add any error information. +By default, all module errors add error information to the error queue. +.It Dv CONF_MFLAGS_NO_DSO +Disable loading of configuration modules from DSOs. +This flag is provided for compatibility and has no effect. +.It Dv CONF_MFLAGS_IGNORE_MISSING_FILE +Let +.Fn CONF_modules_load_file +ignore missing configuration files. +By default, a missing configuration file returns an error. +.It CONF_MFLAGS_DEFAULT_SECTION +If +.Fa appname +is not +.Dv NULL +but does not exist, fall back to the default section +.Qq openssl_conf . +.El +.Pp +By using +.Fn CONF_modules_load_file +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 +.Dv CONF_MFLAGS_IGNORE_MISSING_FILE +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 may continue. +In other cases an application might consider a configuration file +error fatal and exit immediately. +.Pp +Applications can use the +.Fn CONF_modules_load +function if they wish to load a configuration file themselves and +have finer control over how errors are treated. +.Sh RETURN VALUES +.Fn CONF_modules_load_file +and +.Fn CONF_modules_load +return 1 for success and zero or a 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). +.Pp +.Fn X509_get_default_cert_area +returns a pointer to the constant string +.Qq "/etc/ssl" . +.Sh FILES +.Bl -tag -width /etc/ssl/openssl.cnf -compact +.It Pa /etc/ssl +standard configuration directory +.It Pa /etc/ssl/openssl.cnf +standard configuration file +.El +.Sh EXAMPLES +Load a configuration file and print out any errors and exit (missing +file considered fatal): +.Bd -literal +if (CONF_modules_load_file(NULL, NULL, 0) <= 0) { + fprintf(stderr, "FATAL: error loading configuration file\en"); + ERR_print_errors_fp(stderr); + exit(1); +} +.Ed +.Pp +Load default configuration file using the section indicated +by "myapp", tolerate missing files, but exit on other errors: +.Bd -literal +if (CONF_modules_load_file(NULL, "myapp", + CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { + fprintf(stderr, "FATAL: error loading configuration file\en"); + ERR_print_errors_fp(stderr); + exit(1); +} +.Ed +.Pp +Load custom configuration file and section instead of the standard one, +only print warnings on error, missing configuration file ignored: +.Bd -literal +OPENSSL_no_config(); +if (CONF_modules_load_file("/something/app.cnf", "myapp", + CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { + fprintf(stderr, "WARNING: error loading configuration file\en"); + ERR_print_errors_fp(stderr); +} +.Ed +.Pp +In the previous example, the call to +.Xr OPENSSL_no_config 3 +is required first to suppress automatic loading +of the standard configuration file. +.Pp +Load and parse configuration file manually, custom error handling: +.Bd -literal +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(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); +} +.Ed +.Sh SEE ALSO +.Xr CONF_modules_free 3 , +.Xr ERR 3 , +.Xr OPENSSL_config 3 +.Sh HISTORY +.Fn X509_get_default_cert_area +first appeared in SSLeay 0.4.1 and has been available since +.Ox 2.4 . +.Pp +.Fn CONF_modules_load_file +and +.Fn CONF_modules_load +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/CRYPTO_lock.3 b/static/openbsd/man3/CRYPTO_lock.3 new file mode 100644 index 00000000..7877dd58 --- /dev/null +++ b/static/openbsd/man3/CRYPTO_lock.3 @@ -0,0 +1,122 @@ +.\" $OpenBSD: CRYPTO_lock.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL doc/crypto/threads.pod fb552ac6 Sep 30 23:43:01 2009 +0000 +.\" +.\" Copyright (c) 2019 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 $Mdocdate: June 8 2025 $ +.Dt CRYPTO_LOCK 3 +.Os +.Sh NAME +.Nm CRYPTO_lock , +.Nm CRYPTO_w_lock , +.Nm CRYPTO_w_unlock , +.Nm CRYPTO_r_lock , +.Nm CRYPTO_r_unlock , +.Nm CRYPTO_add +.Nd thread support +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/crypto.h +.Ft void +.Fo CRYPTO_lock +.Fa "int mode" +.Fa "int type" +.Fa "const char *file" +.Fa "int line" +.Fc +.Ft int +.Fo CRYPTO_add +.Fa "int *p" +.Fa "int amount" +.Fa "int type" +.Fc +.Bd -literal +#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__) +.Ed +.Sh DESCRIPTION +These functions are obsolete. +.Pp +.Fn CRYPTO_lock +locks or unlocks a mutex lock. +.Pp +.Fa mode +is a bitfield describing what should be done with the lock. +For each call, either +.Dv CRYPTO_LOCK +or +.Dv CRYPTO_UNLOCK +must be included. +In the LibreSSL implementation, +.Dv CRYPTO_READ +and +.Dv CRYPTO_WRITE +are ignored. +.Pp +.Fa type +is a number in the range 0 <= +.Fa type No < Dv CRYPTO_NUM_LOCKS +identifying a particular lock. +Currently, the value of +.Dv CRYPTO_NUM_LOCKS +is 41. +.Pp +The +.Ar file +and +.Ar line +arguments are ignored. +.Pp +In the LibreSSL implementation, +.Fn CRYPTO_lock +is a wrapper around +.Xr pthread_mutex_lock 3 +and +.Xr pthread_mutex_unlock 3 . +.Pp +.Fn CRYPTO_add +locks the lock number +.Fa type , +adds +.Fa amount +to +.Pf * Fa p , +and unlocks the lock number +.Fa type +again. +.Sh RETURN VALUES +.Fn CRYPTO_add +returns the new value of +.Pf * Fa p . +.Sh SEE ALSO +.Xr crypto 3 +.Sh HISTORY +.Fn CRYPTO_lock , +.Fn CRYPTO_w_lock , +.Fn CRYPTO_w_unlock , +.Fn CRYPTO_r_lock , +and +.Fn CRYPTO_r_unlock +first appeared in SSLeay 0.6.0. +.Fn CRYPTO_add +first appeared in SSLeay 0.6.2. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/CRYPTO_memcmp.3 b/static/openbsd/man3/CRYPTO_memcmp.3 new file mode 100644 index 00000000..fbe092cb --- /dev/null +++ b/static/openbsd/man3/CRYPTO_memcmp.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: CRYPTO_memcmp.3,v 1.2 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 1075139c Jun 24 09:18:48 2019 +1000 +.\" +.\" This file was written by Pauli . +.\" Copyright (c) 2019 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt CRYPTO_MEMCMP 3 +.Os +.Sh NAME +.Nm CRYPTO_memcmp +.Nd constant time memory comparison +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/crypto.h +.Ft int +.Fo CRYPTO_memcmp +.Fa "const void *a" +.Fa "const void *b" +.Fa "size_t len" +.Fc +.Sh DESCRIPTION +.Fn CRYPTO_memcmp +compares the +.Fa len +bytes pointed to by +.Fa a +and +.Fa b +for equality. +It takes an amount of time dependent on +.Fa len , +but independent of the contents of the memory regions pointed to by +.Fa a +and +.Fa b . +.Sh RETURN VALUES +.Fn CRYPTO_memcmp +returns 0 if the content of the memory regions is equal +or non-zero otherwise. +.Sh HISTORY +.Fn CRYPTO_memcmp +first appeared in OpenSSL 1.0.1d and has been available since +.Ox 5.6 . +.Sh BUGS +Unlike +.Xr memcmp 3 +and +.Xr timingsafe_memcmp 3 , +this function cannot be used to order the two memory regions. +In the current implementation, the return value is always greater +than or equal to 0. diff --git a/static/openbsd/man3/CRYPTO_set_ex_data.3 b/static/openbsd/man3/CRYPTO_set_ex_data.3 new file mode 100644 index 00000000..57cdbfb4 --- /dev/null +++ b/static/openbsd/man3/CRYPTO_set_ex_data.3 @@ -0,0 +1,565 @@ +.\" $OpenBSD: CRYPTO_set_ex_data.3,v 1.16 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2023 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 $Mdocdate: June 8 2025 $ +.Dt CRYPTO_SET_EX_DATA 3 +.Os +.Sh NAME +.Nm CRYPTO_get_ex_new_index , +.Nm CRYPTO_EX_new , +.Nm CRYPTO_EX_free , +.Nm CRYPTO_EX_dup , +.Nm CRYPTO_new_ex_data , +.Nm CRYPTO_set_ex_data , +.Nm CRYPTO_get_ex_data , +.Nm CRYPTO_free_ex_data +.Nd low-level functions for application specific data +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/crypto.h +.Ft int +.Fo CRYPTO_get_ex_new_index +.Fa "int class_index" +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft typedef int +.Fo CRYPTO_EX_new +.Fa "void *parent" +.Fa "void *data" +.Fa "CRYPTO_EX_DATA *ad" +.Fa "int idx" +.Fa "long argl" +.Fa "void *argp" +.Fc +.Ft typedef void +.Fo CRYPTO_EX_free +.Fa "void *parent" +.Fa "void *data" +.Fa "CRYPTO_EX_DATA *ad" +.Fa "int idx" +.Fa "long argl" +.Fa "void *argp" +.Fc +.Ft typedef int +.Fo CRYPTO_EX_dup +.Fa "CRYPTO_EX_DATA *to" +.Fa "const CRYPTO_EX_DATA *from" +.Fa "void *datap" +.Fa "int idx" +.Fa "long argl" +.Fa "void *argp" +.Fc +.Ft int +.Fo CRYPTO_new_ex_data +.Fa "int class_index" +.Fa "void *parent" +.Fa "CRYPTO_EX_DATA *ad" +.Fc +.Ft int +.Fo CRYPTO_set_ex_data +.Fa "CRYPTO_EX_DATA *ad" +.Fa "int idx" +.Fa "void *data" +.Fc +.Ft void * +.Fo CRYPTO_get_ex_data +.Fa "CRYPTO_EX_DATA *ad" +.Fa "int idx" +.Fc +.Ft void +.Fo CRYPTO_free_ex_data +.Fa "int class_index" +.Fa "void *parent" +.Fa "CRYPTO_EX_DATA *ad" +.Fc +.Sh DESCRIPTION +The library implements the functions documented in the +.Xr RSA_get_ex_new_index 3 +manual page and similar functions for other parent object types +using the functions documented in the present manual page. +Application programs almost never need +to call the functions documented here directly. +.Pp +.Fn CRYPTO_get_ex_new_index +behaves in the same way as +.Xr RSA_get_ex_new_index 3 +except that the parent object type that the new +.Fa idx +is reserved for is not part of the function name +but instead specified by the additional +.Fa class_index +argument receiving one of the +.Dv CRYPTO_EX_INDEX_* +constants defined in +.In openssl/crypto.h . +The recommendation given in +.Xr RSA_get_ex_new_index 3 +to set the +.Fa argl +argument to 0 and the last four arguments all to +.Dv NULL +applies. +The library passes the +.Fa argl +and +.Fa argp +arguments through to the callback functions for the respective +.Fa idx , +but ignores them otherwise. +.Pp +If a function pointer is passed for the +.Fa new_func +argument, that function is called for the returned +.Fa idx +whenever a new parent object is allocated with +.Xr RSA_new 3 +or a similar function. +.Pp +If a function pointer is passed for the +.Fa free_func +argument, that function is called for the returned +.Fa idx +when a parent object is freed with +.Xr RSA_free 3 +or a similar function. +.Pp +The arguments of +.Fa new_func +and +.Fa free_func +are as follows: +.Pp +.Bl -tag -width Ds -compact +.It Fa parent +the parent object that contains the +.Fa data +.It Fa data +the +.Fa data +previously set by +.Fn CRYPTO_set_ex_data +at +.Fa idx +in +.Fa parent +.It Fa ad +the +.Vt CRYPTO_EX_DATA +subobject of the +.Fa parent +object +.It Fa idx +return value of +.Fn CRYPTO_get_ex_new_index +that set this callback +.It Fa argl +the +.Fa argl +passed to +.Fn CRYPTO_get_ex_new_index +for this +.Fa idx +.It Fa argp +the +.Fa argp +passed to +.Fn CRYPTO_get_ex_new_index +for this +.Fa idx +.El +.Pp +If a function pointer is passed for the +.Fa dup_func , +that function is supposed to be called for the returned +.Fa idx +whenever a parent object of the respective type is copied. +Actually, the only functions doing that are +.Xr BIO_dup_chain 3 , +.Xr EC_KEY_copy 3 , +and +.Xr SSL_dup 3 , +and the TLS 1.3 network stack does it internally when duplicating a +.Vt SSL_SESSION +object after receiving a new session ticket message. +Most other object types supporting ex_data do not support +copying in the first place, whereas +.Xr DSA_dup_DH 3 +and +.Xr X509_dup 3 +simply ignore +.Fa dup_func . +.Pp +The arguments of +.Fa dup_func +are as follows: +.Pp +.Bl -tag -width Ds -compact +.It Fa to +the +.Vt CRYPTO_EX_DATA +subobject of the new parent object +.It Fa from +the +.Vt CRYPTO_EX_DATA +subobject of the original parent object +.It Fa datap +a pointer to a copy of the pointer to the original ex_data +.It Fa idx +return value of +.Fn CRYPTO_get_ex_new_index +that set this callback +.It Fa argl +the +.Fa argl +passed to +.Fn CRYPTO_get_ex_new_index +for this +.Fa idx +.It Fa argp +the +.Fa argp +passed to +.Fn CRYPTO_get_ex_new_index +for this +.Fa idx +.El +.Pp +Inside +.Fa dup_func , +the +.Fa data +pointer contained in the original parent object being copied +can be accessed by casting and dereferencing +.Fa datap , +for example: +.Pp +.Dl char *orig_data = *(char **)datap; +.Pp +If the original data is copied, for example in a manner similar to +.Bd -literal -offset indent +char *new_data; +if ((new_data = strdup(orig_data)) == NULL) + return 0; +.Ed +.Pp +then the pointer to the newly allocated memory needs to be passed +back to the caller in the +.Fa datap +argument, for example: +.Bd -literal -offset indent +*(char **)datap = new_data; +return 1; +.Ed +.Pp +Calling +.Fn CRYPTO_set_ex_data to idx new_data +from inside +.Fa dup_func +has no effect because the code calling +.Fa dup_func +unconditionally calls +.Fn CRYPTO_set_ex_data to idx *datap +after +.Fa dup_func +returns successfully. +Consequently, if +.Fa dup_func +does not change +.Pf * Fa datap , +the new parent object ends up containing a pointer to the same memory +as the original parent object and any memory allocated in +.Fa dup_func +is leaked. +.Pp +When multiple callback functions are called, +they are called in increasing order of their +.Fa idx +value. +.Pp +.Fn CRYPTO_new_ex_data +is an internal function that initializes the +.Fa ad +subobject of the +.Fa parent +object, with the type of the parent object specified by the +.Fa class_index +argument. +Initialization includes calling the respective +.Fa new_func +callbacks for all reserved +.Fa idx +values that have such callbacks configured. +Despite its name, +.Fn CRYPTO_new_ex_data +does not create a new object but requires that +.Fa ad +points to an already allocated but still uninitialized object. +.Pp +.Fn CRYPTO_set_ex_data +and +.Fn CRYPTO_get_ex_data +behave in the same way as +.Xr RSA_set_ex_data 3 +and +.Xr RSA_get_ex_data 3 , +respectively, except that they do not accept a pointer +to the parent object but instead require a pointer to the +.Vt CRYPTO_EX_DATA +subobject of that parent object. +.Pp +.Fn CRYPTO_free_ex_data +is an internal function that frees any memory used inside the +.Fa ad +subobject of the +.Fa parent +object, with the type of the parent object specified by the +.Fa class_index +argument. +This includes calling the respective +.Fa free_func +callbacks for all reserved +.Fa idx +values that have such callbacks configured. +Despite its name, +.Fn CRYPTO_free_ex_data +does not free +.Fa ad +itself. +.Sh RETURN VALUES +.Fn CRYPTO_get_ex_new_index +returns a new index equal to or greater than 1 +or \-1 if memory allocation fails. +.Pp +.Fn CRYPTO_EX_new +and +.Fn CRYPTO_EX_dup +functions are supposed to return 1 on success or 0 on failure. +.Pp +.Fn CRYPTO_new_ex_data +and +.Fn CRYPTO_set_ex_data +return 1 on success or 0 if memory allocation fails. +.Pp +.Fn CRYPTO_get_ex_data +returns the application specific data or +.Dv NULL +if the parent object that contains +.Fa ad +does not contain application specific data at the given +.Fa idx . +.Sh ERRORS +After failure of +.Fn CRYPTO_get_ex_new_index , +.Fn CRYPTO_new_ex_data , +or +.Fn CRYPTO_set_ex_data , +the following diagnostic can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" +Memory allocation failed. +.El +.Pp +In a few unusual failure cases, +.Xr ERR_get_error 3 +may report different errors caused by +.Xr OPENSSL_init_crypto 3 +or even none at all. +.Pp +Even though it cannot indicate failure, +.Fn CRYPTO_free_ex_data +may occasionally also set an error code that can be retrieved with +.Xr ERR_get_error 3 . +.Pp +.Fn CRYPTO_get_ex_data +does not distinguish success from failure. +Consequently, after +.Fn CRYPTO_get_ex_data +returns +.Dv NULL , +.Xr ERR_get_error 3 +returns 0 unless there is still an earlier error in the queue. +.Sh SEE ALSO +.Xr BIO_get_ex_new_index 3 , +.Xr DH_get_ex_new_index 3 , +.Xr DSA_get_ex_new_index 3 , +.Xr RSA_get_ex_new_index 3 , +.Xr SSL_CTX_get_ex_new_index 3 , +.Xr SSL_get_ex_new_index 3 , +.Xr SSL_SESSION_get_ex_new_index 3 , +.Xr X509_STORE_CTX_get_ex_new_index 3 , +.Xr X509_STORE_get_ex_new_index 3 +.Sh HISTORY +.Fn CRYPTO_get_ex_new_index , +.Fn CRYPTO_new_ex_data , +.Fn CRYPTO_set_ex_data , +.Fn CRYPTO_get_ex_data , +and +.Fn CRYPTO_free_ex_data +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . +.Pp +.Fn CRYPTO_EX_new , +.Fn CRYPTO_EX_free , +and +.Fn CRYPTO_EX_dup +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Sh CAVEATS +If an program installs callback functions, the last call to +.Fn CRYPTO_get_ex_new_index +installing a function of a certain type for a certain +.Fa class_index +needs to be complete before the first object of that +.Fa class_index +can be created, freed, or copied, respectively. +Otherwise, incomplete initialization or cleanup will result. +.Pp +At the time +.Fa new_func +is called, the +.Fa parent +object is only partially initialized, +so trying to access any data in it is strongly discouraged. +The +.Fa data +argument is typically +.Dv NULL +in +.Fa new_func . +.Pp +At the time +.Fa free_func +is called, the +.Fa parent +object is already mostly deconstructed +and part of its content may have been cleared and freed. +Consequently, trying to access any data in +.Fa parent +is strongly discouraged. +According to the OpenSSL API documentation, the library code calling +.Fa free_func +would even be permitted to pass a +.Dv NULL +pointer for the +.Fa parent +argument. +.Pp +.Fn CRYPTO_set_ex_data +and +.Fn CRYPTO_get_ex_data +cannot reasonably be used outside the callback functions +because no API function provides access to any pointers of the type +.Vt CRYPTO_EX_DATA * . +.Pp +Inside +.Fa new_func , +calling +.Fn CRYPTO_get_ex_data +makes no sense because it always returns +.Dv NULL , +and calling +.Fn CRYPTO_set_ex_data +makes no sense because +.Fa new_func +does not have access to any meaningful +.Fa data +it could store, and the absence of application specific data at any given +.Fa idx +is already sufficiently indicated by the default return value +.Dv NULL +of +.Fn CRYPTO_get_ex_data , +.Xr RSA_get_ex_data 3 , +and similar functions. +.Pp +Inside +.Fa free_func , +calling +.Fn CRYPTO_get_ex_data +makes no sense because the return value is already available in +.Fa data , +and calling +.Fn CRYPTO_set_ex_data +makes no sense because the parent object, including any ex_data +contained in it, is already being deconstructed and will no longer +exist by the time application code regains control. +.Pp +Inside +.Fa dup_func , +calling +.Fn CRYPTO_get_ex_data +makes no sense because the return value for +.Fa from +is already available as +.Pf * Fa datap , +and the return value for +.Fa to +is +.Dv NULL . +Calling +.Fn CRYPTO_set_ex_data +makes no sense because changing +.Fa from +would cause an undesirable side effect in this context +and trying to change +.Fa to +is ineffective as explained above. +.Pp +Consequently, application code can never use +.Fn CRYPTO_set_ex_data +or +.Fn CRYPTO_get_ex_data +in a meaningful way. +.Pp +The fact that the functions documented in the present manual page +are part of the public API might create the impression +that application programs could add ex_data support +to additional object types not offering it by default. +However, for built-in object types not offering ex_support, this +is not possible because such objects do not contain the required +.Vt CRYPTO_EX_DATA +subobject. +.Pp +It is theoretically possible to add ex_data support to an +application-defined object type by adding a +.Vt CRYPTO_EX_DATA +field to the struct declaration, a call to +.Fn CRYPTO_new_ex_data +to the object constructor, and a call to +.Fn CRYPTO_free_ex_data +to the object destructor. +The OpenSSL documentation mentions that the constant +.Dv CRYPTO_EX_INDEX_APP +is reserved for this very purpose. +However, doing this would hardly be useful. +It is much more straightforward to just add +all the required data fields to the struct declaration itself. +.Sh BUGS +If +.Fa new_func +or +.Fa dup_func +fails, the failure is silently ignored by the library, potentially +resulting in an incompletely initialized object. +The application program cannot detect this kind of failure. diff --git a/static/openbsd/man3/CRYPTO_set_mem_functions.3 b/static/openbsd/man3/CRYPTO_set_mem_functions.3 new file mode 100644 index 00000000..4fc88339 --- /dev/null +++ b/static/openbsd/man3/CRYPTO_set_mem_functions.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: CRYPTO_set_mem_functions.3,v 1.3 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt CRYPTO_SET_MEM_FUNCTIONS 3 +.Os +.Sh NAME +.Nm CRYPTO_set_mem_functions , +.Nm CRYPTO_mem_ctrl , +.Nm CRYPTO_mem_leaks , +.Nm CRYPTO_mem_leaks_fp , +.Nm CRYPTO_mem_leaks_cb +.Nd legacy OpenSSL memory allocation control +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/crypto.h +.Ft int +.Fo CRYPTO_set_mem_functions +.Fa "void *(*m)(size_t, const char *, int)" +.Fa "void *(*r)(void *, size_t, const char *, int)" +.Fa "void (*f)(void *, const char *, int)" +.Fc +.Ft int +.Fo CRYPTO_mem_ctrl +.Fa "int mode" +.Fc +.Ft int +.Fo CRYPTO_mem_leaks +.Fa "BIO *b" +.Fc +.Ft int +.Fo CRYPTO_mem_leaks_fp +.Fa "FILE *fp" +.Fc +.Ft typedef int * +.Fo CRYPTO_MEM_LEAK_CB +.Fa "unsigned long" +.Fa "const char *" +.Fa int +.Fa int +.Fa "void *" +.Fc +.Ft int +.Fo CRYPTO_mem_leaks_cb +.Fa "CRYPTO_MEM_LEAK_CB *cb" +.Fc +.Sh DESCRIPTION +Do not use any of the interfaces documented here. +They are provided purely for compatibility with legacy application code. +.Pp +.Fn CRYPTO_set_mem_functions , +.Fn CRYPTO_mem_ctrl , +.Fn CRYPTO_mem_leaks , +.Fn CRYPTO_mem_leaks_fp , +and +.Fn CRYPTO_mem_leaks_cb +have no effect. +.Sh RETURN VALUES +.Fn CRYPTO_set_mem_functions +always returns 0. +.Pp +.Fn CRYPTO_mem_ctrl +always returns +.Dv CRYPTO_MEM_CHECK_OFF . +.Pp +.Fn CRYPTO_mem_leaks , +.Fn CRYPTO_mem_leaks_fp , +and +.Fn CRYPTO_mem_leaks_cb +always return -1. +.Sh SEE ALSO +.Xr crypto 3 +.Sh HISTORY +.Fn CRYPTO_mem_ctrl , +.Fn CRYPTO_mem_leaks , +and +.Fn CRYPTO_mem_leaks_fp +first appeared in SSLeay 0.6.4. +.Fn CRYPTO_set_mem_functions +first appeared in SSLeay 0.6.5. +.Fn CRYPTO_mem_leaks_cb +first appeared in SSLeay 0.6.6. +All these functions have all been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/ChaCha.3 b/static/openbsd/man3/ChaCha.3 new file mode 100644 index 00000000..54cd597f --- /dev/null +++ b/static/openbsd/man3/ChaCha.3 @@ -0,0 +1,254 @@ +.\" $OpenBSD: ChaCha.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: June 8 2025 $ +.Dt CHACHA 3 +.Os +.Sh NAME +.Nm ChaCha_set_key , +.Nm ChaCha_set_iv , +.Nm ChaCha , +.Nm CRYPTO_chacha_20 , +.Nm CRYPTO_hchacha_20 , +.Nm CRYPTO_xchacha_20 +.Nd ChaCha20 stream cipher +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/chacha.h +.Ft void +.Fo ChaCha_set_key +.Fa "ChaCha_ctx *ctx" +.Fa "const unsigned char *key" +.Fa "unsigned int keybits" +.Fc +.Ft void +.Fo ChaCha_set_iv +.Fa "ChaCha_ctx *ctx" +.Fa "const unsigned char *iv" +.Fa "const unsigned char *counter" +.Fc +.Ft void +.Fo ChaCha +.Fa "ChaCha_ctx *ctx" +.Fa "unsigned char *out" +.Fa "const unsigned char *in" +.Fa "size_t len" +.Fc +.Ft void +.Fo CRYPTO_chacha_20 +.Fa "unsigned char *out" +.Fa "const unsigned char *in" +.Fa "size_t len" +.Fa "const unsigned char key[32]" +.Fa "const unsigned char iv[8]" +.Fa "uint64_t counter" +.Fc +.Ft void +.Fo CRYPTO_hchacha_20 +.Fa "unsigned char out[32]" +.Fa "const unsigned char key[32]" +.Fa "const unsigned char iv[16]" +.Fc +.Ft void +.Fo CRYPTO_xchacha_20 +.Fa "unsigned char *out" +.Fa "const unsigned char *in" +.Fa "size_t len" +.Fa "const unsigned char key[32]" +.Fa "const unsigned char iv[24]" +.Fc +.Sh DESCRIPTION +These functions provide a low-level implementation +of the ChaCha stream cipher with 256 and 128-bit keys. +The number of rounds is hardcoded to 20; +variants with 8 or 12 rounds are not supported. +.Pp +Instead of using these functions directly, +application programs normally use the more portable +.Xr EVP_chacha20 3 +high-level interface. +.Pp +The ChaCha state is contained in the +.Vt ChaCha_ctx +structure and consists of sixteen 32-bit unsigned integers. +.Pp +For the recommended value of 256 +.Fa keybits , +.Fn ChaCha_set_key +copies 32 bytes (256 bits) from +.Fa key +to the middle eight integers of the ChaCha state, +using little endian order for each integer. +For the alternative value of 128 +.Fa keybits , +only 16 bytes (128 bits) are copied from +.Fa key +to the ChaCha state, but they are copied twice, +once to the second quarter and once to the third quarter. +The first quarter of the ChaCha state is set to four constant integers; +these constants differ depending on whether +.Fa keybits +is 128 or 256. +The last quarter of the ChaCha state remains unchanged. +.Pp +.Fn ChaCha_set_iv +copies eight bytes (64 bits) from +.Fa counter +and eight bytes (64 bits) from +.Fa iv +to the last quarter of the ChaCha state, the counter to the first +two integers and the initialization vector to the last two integers, +again in little endian order. +If +.Fa counter +is +.Dv NULL , +the two respective integers are set to 0 instead. +The first three quarters of the ChaCha state remain unchanged. +.Pp +.Fn ChaCha +encrypts +.Fa len +bytes of data from +.Fa in +to +.Fa out +using the +.Fa ctx +that was previously set up with +.Fn ChaCha_set_key +and +.Fn ChaCha_set_iv . +Providing an +.Fa out +buffer of at least +.Fa len +bytes is the responsibility of the caller. +This function can be called multiple times in a row with varying +.Fa len +arguments. +The +.Fa len +does not need to be a multiple of 64. +.Pp +.Fn CRYPTO_chacha_20 +encrypts +.Fa len +bytes of data from +.Fa in +to +.Fa out +in a one-shot operation, using the given +.Fa key +and +.Fa iv +as described for +.Fn ChaCha_set_key +and +.Fn ChaCha_set_iv +and copying the less significant half of +.Fa counter +to the first counter integer in the initial ChaCha state +and the more significant half to the second integer. +Providing an +.Fa out +buffer of at least +.Fa len +bytes is again the responsibility of the caller. +The maximum supported value for +.Fa len +is 2^32 \- 1. +.Pp +XChaCha is a variant of ChaCha designed to support longer nonces, +just like XSalsa20 is a variant of Salsa20 supporting longer nonces. +.Pp +.Fn CRYPTO_xchacha_20 +encrypts +.Fa len +bytes of data from +.Fa in +to +.Fa out +in a one-shot operation with the XChaCha algorithm, using the given +.Fa key +and +.Fa iv . +It is equivalent to +.Fn CRYPTO_chacha_20 +with the last third of +.Fa iv , +a +.Fa counter +of 0, and a key generated with +.Fn CRYPTO_hchacha_20 +from the first two thirds of +.Fa iv . +.Sh SEE ALSO +.Xr crypto 3 , +.Xr EVP_chacha20 3 +.Rs +.%A Daniel J. Bernstein +.%T ChaCha, a variant of Salsa20 +.%U https://cr.yp.to/chacha/chacha-20080128.pdf +.%C Chicago +.%D January 28, 2008 +.Re +.Rs +.%A Daniel J. Bernstein +.%T Extending the Salsa20 nonce +.%U https://cr.yp.to/snuffle/xsalsa-20110204.pdf +.%C Chicago +.%D August 22, 2017 +.Re +.Sh STANDARDS +RFC 8439: ChaCha20 and Poly1305 for IETF Protocols +.Pp +Note that the standard specifies +a 32-bit counter and a 96-bit initialization vector whereas +this implementation follows Bernstein's original specification +and uses a 64-bit counter and a 64-bit initialization vector. +.Pp +These functions are specific to LibreSSL and not provided by OpenSSL. +BoringSSL does provide +.Fn CRYPTO_chacha_20 , +but with an incompatible interface, taking a 96-bit +.Fa iv +and a 32-bit +.Fa counter . +.Sh HISTORY +.Fn ChaCha_set_key , +.Fn ChaCha_set_iv , +.Fn ChaCha , +and +.Fn CRYPTO_chacha_20 +first appeared in +.Ox 5.6 . +.\" Committed on May 1, 2014. +.\" BoringSSL added CRYPTO_chacha_20 on June 20, 2014. +.Pp +.Fn CRYPTO_hchacha_20 +and +.Fn CRYPTO_xchacha_20 +first appeared in +.Ox 6.5 . +.Sh AUTHORS +.An -nosplit +This implementation was written by +.An Daniel J. Bernstein Aq Mt djb@cr.yp.to . +The API layer was added by +.An Joel Sing Aq Mt jsing@openbsd.org +for ChaCha, and for XChaCha by +.An David Gwynne Aq Mt dlg@openbsd.org . diff --git a/static/openbsd/man3/DES_set_key.3 b/static/openbsd/man3/DES_set_key.3 new file mode 100644 index 00000000..37942850 --- /dev/null +++ b/static/openbsd/man3/DES_set_key.3 @@ -0,0 +1,788 @@ +.\" $OpenBSD: DES_set_key.3,v 1.18 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL man3/DES_random_key 521738e9 Oct 5 14:58:30 2018 -0400 +.\" +.\" -------------------------------------------------------------------------- +.\" Major patches to this file were contributed by +.\" Ulf Moeller , Ben Laurie , +.\" and Richard Levitte . +.\" -------------------------------------------------------------------------- +.\" Copyright (c) 2000, 2001, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" -------------------------------------------------------------------------- +.\" Parts of this file are derived from SSLeay documentation, +.\" which is covered by the following Copyright and license: +.\" -------------------------------------------------------------------------- +.\" +.\" Copyright (C) 1995-1998 Tim Hudson (tjh@cryptsoft.com) +.\" All rights reserved. +.\" +.\" This package is an SSL implementation written +.\" by Eric Young (eay@cryptsoft.com). +.\" The implementation was written so as to conform with Netscapes SSL. +.\" +.\" This library is free for commercial and non-commercial use as long as +.\" the following conditions are aheared to. The following conditions +.\" apply to all code found in this distribution, be it the RC4, RSA, +.\" lhash, DES, etc., code; not just the SSL code. The SSL documentation +.\" included with this distribution is covered by the same copyright terms +.\" except that the holder is Tim Hudson (tjh@cryptsoft.com). +.\" +.\" Copyright remains Eric Young's, and as such any Copyright notices in +.\" the code are not to be removed. +.\" If this package is used in a product, Eric Young should be given +.\" attribution as the author of the parts of the library used. +.\" This can be in the form of a textual message at program startup or +.\" in documentation (online or textual) provided with the package. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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 cryptographic software written by +.\" Eric Young (eay@cryptsoft.com)" +.\" The word 'cryptographic' can be left out if the rouines from the +.\" library being used are not cryptographic related :-). +.\" 4. If you include any Windows specific code (or a derivative thereof) +.\" from the apps directory (application code) you must include an +.\" acknowledgement: "This product includes software written by +.\" Tim Hudson (tjh@cryptsoft.com)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY ERIC 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 THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" The licence and distribution terms for any publically available version or +.\" derivative of this code cannot be changed. i.e. this code cannot simply be +.\" copied and put under another distribution licence +.\" [including the GNU Public Licence.] +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DES_SET_KEY 3 +.Os +.Sh NAME +.Nm DES_random_key , +.Nm DES_set_key , +.Nm DES_key_sched , +.Nm DES_set_key_checked , +.Nm DES_set_key_unchecked , +.Nm DES_set_odd_parity , +.Nm DES_is_weak_key , +.Nm DES_ecb_encrypt , +.Nm DES_ecb2_encrypt , +.Nm DES_ecb3_encrypt , +.Nm DES_ncbc_encrypt , +.Nm DES_cfb_encrypt , +.Nm DES_ofb_encrypt , +.Nm DES_pcbc_encrypt , +.Nm DES_cfb64_encrypt , +.Nm DES_ofb64_encrypt , +.Nm DES_xcbc_encrypt , +.Nm DES_ede2_cbc_encrypt , +.Nm DES_ede2_cfb64_encrypt , +.Nm DES_ede2_ofb64_encrypt , +.Nm DES_ede3_cbc_encrypt , +.Nm DES_ede3_cbcm_encrypt , +.Nm DES_ede3_cfb64_encrypt , +.Nm DES_ede3_ofb64_encrypt , +.Nm DES_cbc_cksum , +.Nm DES_quad_cksum , +.Nm DES_string_to_key , +.Nm DES_string_to_2keys , +.Nm DES_fcrypt , +.Nm DES_crypt +.Nd DES encryption +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/des.h +.Ft void +.Fo DES_random_key +.Fa "DES_cblock *ret" +.Fc +.Ft int +.Fo DES_set_key +.Fa "const_DES_cblock *key" +.Fa "DES_key_schedule *schedule" +.Fc +.Ft int +.Fo DES_key_sched +.Fa "const_DES_cblock *key" +.Fa "DES_key_schedule *schedule" +.Fc +.Ft int +.Fo DES_set_key_checked +.Fa "const_DES_cblock *key" +.Fa "DES_key_schedule *schedule" +.Fc +.Ft void +.Fo DES_set_key_unchecked +.Fa "const_DES_cblock *key" +.Fa "DES_key_schedule *schedule" +.Fc +.Ft void +.Fo DES_set_odd_parity +.Fa "DES_cblock *key" +.Fc +.Ft int +.Fo DES_is_weak_key +.Fa "const_DES_cblock *key" +.Fc +.Ft void +.Fo DES_ecb_encrypt +.Fa "const_DES_cblock *input" +.Fa "DES_cblock *output" +.Fa "DES_key_schedule *ks" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ecb2_encrypt +.Fa "const_DES_cblock *input" +.Fa "DES_cblock *output" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ecb3_encrypt +.Fa "const_DES_cblock *input" +.Fa "DES_cblock *output" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_key_schedule *ks3" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ncbc_encrypt +.Fa "const unsigned char *input" +.Fa "unsigned char *output" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_cfb_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "int numbits" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ofb_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "int numbits" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fc +.Ft void +.Fo DES_pcbc_encrypt +.Fa "const unsigned char *input" +.Fa "unsigned char *output" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_cfb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ofb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fc +.Ft void +.Fo DES_xcbc_encrypt +.Fa "const unsigned char *input" +.Fa "unsigned char *output" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "const_DES_cblock *inw" +.Fa "const_DES_cblock *outw" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede2_cbc_encrypt +.Fa "const unsigned char *input" +.Fa "unsigned char *output" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_cblock *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede2_cfb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede2_ofb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fc +.Ft void +.Fo DES_ede3_cbc_encrypt +.Fa "const unsigned char *input" +.Fa "unsigned char *output" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_key_schedule *ks3" +.Fa "DES_cblock *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede3_cbcm_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_key_schedule *ks3" +.Fa "DES_cblock *ivec1" +.Fa "DES_cblock *ivec2" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede3_cfb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_key_schedule *ks3" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede3_ofb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_key_schedule *ks3" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fc +.Ft DES_LONG +.Fo DES_cbc_cksum +.Fa "const unsigned char *input" +.Fa "DES_cblock *output" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "const_DES_cblock *ivec" +.Fc +.Ft DES_LONG +.Fo DES_quad_cksum +.Fa "const unsigned char *input" +.Fa "DES_cblock output[]" +.Fa "long length" +.Fa "int out_count" +.Fa "DES_cblock *seed" +.Fc +.Ft void +.Fo DES_string_to_key +.Fa "const char *str" +.Fa "DES_cblock *key" +.Fc +.Ft void +.Fo DES_string_to_2keys +.Fa "const char *str" +.Fa "DES_cblock *key1" +.Fa "DES_cblock *key2" +.Fc +.Ft char * +.Fo DES_fcrypt +.Fa "const char *buf" +.Fa "const char *salt" +.Fa "char *ret" +.Fc +.Ft char * +.Fo DES_crypt +.Fa "const char *buf" +.Fa "const char *salt" +.Fc +.Sh DESCRIPTION +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 +.Vt DES_key_schedule +from a key, and the second is the actual encryption. +A DES key is of type +.Vt DES_cblock . +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 +.Fn DES_random_key +generates a random key in odd parity. +.Pp +Before a DES key can be used, it must be converted into the architecture +dependent +.Vt DES_key_schedule +via the +.Fn DES_set_key_checked +or +.Fn DES_set_key_unchecked +function. +.Pp +.Fn DES_set_key_checked +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 +.Fn DES_set_key +works like +.Fn DES_set_key_checked +if the +.Em DES_check_key +flag is non-zero, otherwise like +.Fn DES_set_key_unchecked . +These functions are available for compatibility; it is recommended to +use a function that does not depend on a global variable. +.Pp +.Fn DES_set_odd_parity +sets the parity of the passed +.Fa key +to odd. +.Pp +The following routines mostly operate on an input and output stream of +.Vt DES_cblock Ns s . +.Pp +.Fn DES_ecb_encrypt +is the basic DES encryption routine that encrypts or decrypts a single +8-byte +.Vt DES_cblock +in electronic code book (ECB) mode. +It always transforms the input data, pointed to by +.Fa input , +into the output data, pointed to by the +.Fa output +argument. +If the +.Fa enc +argument is non-zero +.Pq Dv DES_ENCRYPT , +the +.Fa input +(cleartext) is encrypted into the +.Fa output +(ciphertext) using the key_schedule specified by the +.Fa schedule +argument, previously set via +.Fn DES_set_key . +If +.Fa enc +is zero +.Pq Dv DES_DECRYPT , +the +.Fa input +(now ciphertext) is decrypted into the +.Fa output +(now cleartext). +Input and output may overlap. +.Fn DES_ecb_encrypt +does not return a value. +.Pp +.Fn DES_ecb3_encrypt +encrypts/decrypts the +.Fa input +block by using three-key Triple-DES encryption in ECB mode. +This involves encrypting the input with +.Fa ks1 , +decrypting with the key schedule +.Fa ks2 , +and then encrypting with +.Fa ks3 . +This routine greatly reduces the chances of brute force breaking of DES +and has the advantage of if +.Fa ks1 , +.Fa ks2 , +and +.Fa ks3 +are the same, it is equivalent to just encryption using ECB mode and +.Fa ks1 +as the key. +.Pp +The macro +.Fn DES_ecb2_encrypt +is provided to perform two-key Triple-DES encryption by using +.Fa ks1 +for the final encryption. +.Pp +.Fn DES_ncbc_encrypt +encrypts/decrypts using the cipher-block-chaining (CBC) mode of DES. +If the +.Fa enc +argument is non-zero, the routine cipher-block-chain encrypts the +cleartext data pointed to by the +.Fa input +argument into the ciphertext pointed to by the +.Fa output +argument, using the key schedule provided by the +.Fa schedule +argument, and initialization vector provided by the +.Fa ivec +argument. +If the +.Fa length +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 +.Fn DES_xcbc_encrypt +is RSA's DESX mode of DES. +It uses +.Fa inw +and +.Fa outw +to "whiten" the encryption. +.Fa inw +and +.Fa outw +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 +.Fn DES_ede3_cbc_encrypt +implements outer triple CBC DES encryption with three keys. +This means that each DES operation inside the CBC mode is +.Qq Li C=E(ks3,D(ks2,E(ks1,M))) . +This mode is used by SSL. +.Pp +The +.Fn DES_ede2_cbc_encrypt +macro implements two-key Triple-DES by reusing +.Fa ks1 +for the final encryption. +.Qq Li C=E(ks1,D(ks2,E(ks1,M))) . +This form of Triple-DES is used by the RSAREF library. +.Pp +.Fn DES_pcbc_encrypt +encrypts/decrypts using the propagating cipher block chaining mode used +by Kerberos v4. +Its parameters are the same as +.Fn DES_ncbc_encrypt . +.Pp +.Fn DES_cfb_encrypt +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 +.Fa ivec +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 +.Fa numbits , +this function is only suggested for use when sending a small number of +characters. +.Pp +.Fn DES_cfb64_encrypt +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 +The +.Fn DES_ede3_cfb64_encrypt +function and the +.Fn DES_ede2_cfb64_encrypt +macro are the same as +.Fn DES_cfb64_encrypt +except that Triple-DES is used. +.Pp +.Fn DES_ofb_encrypt +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 +.Fa ivec +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 +.Fa numbits , +this function is only suggested for use when sending a small number +of characters. +.Pp +.Fn DES_ofb64_encrypt +is the same as +.Fn DES_cfb64_encrypt +using Output Feed Back mode. +.Pp +The +.Fn DES_ede3_ofb64_encrypt +function and the +.Fn DES_ede2_ofb64_encrypt +macro are the same as +.Fn DES_ofb64_encrypt , +using Triple-DES. +.Pp +The following functions are included in the DES library for +compatibility with the MIT Kerberos library. +.Pp +.Fn DES_cbc_cksum +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 +.Fa output . +This function is used by Kerberos v4. +Other applications should use +.Xr EVP_DigestInit 3 +etc. instead. +.Pp +.Fn DES_quad_cksum +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 +.Fa out_count , +1, 2, 3 or 4 times. +If +.Fa output +is +.Pf non- Dv NULL , +the 8 bytes generated by each pass are written into +.Fa output . +.Pp +The following are DES-based transformations: +.Pp +.Fn DES_fcrypt +is a fast version of the Unix +.Xr crypt 3 +function. +The +.Fa salt +must be two ASCII characters. +This version is different from 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. +The fourteenth byte is set to NUL. +This version takes only a small amount of space relative to other +fast crypt implementations. +It is thread safe, unlike the normal crypt. +.Pp +.Fn DES_crypt +is a faster replacement for the normal system +.Xr crypt 3 . +This function calls +.Fn DES_fcrypt +with a static array passed as the third parameter. +This emulates the normal non-thread safe semantics of +.Xr crypt 3 . +.Sh RETURN VALUES +.Fn DES_set_key , +.Fn DES_key_sched , +and +.Fn DES_set_key_checked +return 0 on success or a negative value on error. +.Pp +.Fn DES_is_weak_key +returns 1 if the passed key is a weak key or 0 if it is ok. +.Pp +.Fn DES_cbc_cksum +and +.Fn DES_quad_cksum +return a 4-byte integer representing the last 4 bytes of the checksum +of the input. +.Pp +.Fn DES_fcrypt +returns a pointer to the caller-provided buffer +.Fa ret , +and +.Fn DES_crypt +returns a pointer to a static buffer. +Both are allowed to return +.Dv NULL +to indicate failure, but currently, they cannot fail. +.Sh SEE ALSO +.Xr crypt 3 , +.Xr EVP_des_cbc 3 , +.Xr EVP_EncryptInit 3 +.Sh STANDARDS +ANSI X3.106 +.Pp +The DES library was initially written to be source code compatible +with the MIT Kerberos library. +.Sh HISTORY +.Fn DES_random_key , +.Fn DES_set_key , +.Fn DES_key_sched , +.Fn DES_set_odd_parity , +.Fn DES_is_weak_key , +.Fn DES_ecb_encrypt , +.Fn DES_cfb_encrypt , +.Fn DES_ofb_encrypt , +.Fn DES_pcbc_encrypt , +.Fn DES_cfb64_encrypt , +.Fn DES_ofb64_encrypt , +.Fn DES_ede3_cbc_encrypt , +.Fn DES_cbc_cksum , +.Fn DES_quad_cksum , +.Fn DES_string_to_key , +.Fn DES_string_to_2keys , +and +.Fn DES_crypt +appeared in SSLeay 0.4 or earlier. +.Fn DES_ncbc_encrypt +first appeared in SSLeay 0.4.2. +.Fn DES_ede2_cbc_encrypt +first appeared in SSLeay 0.4.4. +.Fn DES_ecb2_encrypt , +.Fn DES_ecb3_encrypt , +.Fn DES_ede2_cfb64_encrypt , +.Fn DES_ede2_ofb64_encrypt , +.Fn DES_ede3_cfb64_encrypt , +and +.Fn DES_ede3_ofb64_encrypt +first appeared in SSLeay 0.5.1. +.Fn DES_xcbc_encrypt +first appeared in SSLeay 0.6.2. +.Fn DES_fcrypt +first appeared in SSLeay 0.6.5. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn DES_set_key_checked +and +.Fn DES_set_key_unchecked +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +In OpenSSL 0.9.7 and +.Ox 3.2 , +all +.Sy des_ +functions were renamed to +.Sy DES_ +to avoid clashes with older versions of libdes. +.Sh AUTHORS +.An Eric Young Aq Mt eay@cryptsoft.com +.Sh CAVEATS +Single-key DES is insecure due to its short key size. +ECB mode is not suitable for most applications. +.Sh BUGS +DES_cbc_encrypt does not modify +.Fa ivec ; +use +.Fn DES_ncbc_encrypt +instead. +.Pp +.Fn DES_cfb_encrypt +and +.Fn DES_ofb_encrypt +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 input +bytes apart things get ugly! +.Pp +.Fn DES_string_to_key +is available for backward compatibility with the MIT library. +New applications should use a cryptographic hash function. +The same applies for +.Fn DES_string_to_2key . diff --git a/static/openbsd/man3/DH_generate_key.3 b/static/openbsd/man3/DH_generate_key.3 new file mode 100644 index 00000000..c3158b81 --- /dev/null +++ b/static/openbsd/man3/DH_generate_key.3 @@ -0,0 +1,123 @@ +.\" $OpenBSD: DH_generate_key.3,v 1.13 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DH_GENERATE_KEY 3 +.Os +.Sh NAME +.Nm DH_generate_key , +.Nm DH_compute_key +.Nd perform Diffie-Hellman key exchange +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dh.h +.Ft int +.Fo DH_generate_key +.Fa "DH *dh" +.Fc +.Ft int +.Fo DH_compute_key +.Fa "unsigned char *key" +.Fa "BIGNUM *pub_key" +.Fa "DH *dh" +.Fc +.Sh DESCRIPTION +.Fn DH_generate_key +performs the first step of a Diffie-Hellman key exchange by generating +private and public DH values. +By calling +.Fn DH_compute_key , +these are combined with the other party's public value to compute the +shared key. +.Pp +.Fn DH_generate_key +expects +.Fa dh +to contain the shared parameters +.Sy dh->p +and +.Sy dh->g . +It generates a random private DH value unless +.Sy dh->priv_key +is already set, and computes the corresponding public value +.Sy dh->pub_key , +which can then be published. +.Pp +.Fn DH_compute_key +computes the shared secret from the private DH value in +.Fa dh +and the other party's public value in +.Fa pub_key +and stores it in +.Fa key . +.Fa key +must point to +.Fn DH_size dh +bytes of memory. +.Sh RETURN VALUES +.Fn DH_generate_key +returns 1 on success, or 0 otherwise. +.Pp +.Fn DH_compute_key +returns the size of the shared secret on success, or -1 on error. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr DH_get0_key 3 , +.Xr DH_new 3 , +.Xr DH_size 3 , +.Xr ECDH_compute_key 3 +.Sh HISTORY +.Fn DH_generate_key +and +.Fn DH_compute_key +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/DH_generate_parameters.3 b/static/openbsd/man3/DH_generate_parameters.3 new file mode 100644 index 00000000..f47475e3 --- /dev/null +++ b/static/openbsd/man3/DH_generate_parameters.3 @@ -0,0 +1,242 @@ +.\" $OpenBSD: DH_generate_parameters.3,v 1.15 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" selective merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022 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. +.\" +.\" The original file was written by Ulf Moeller +.\" and Matt Caswell . +.\" Copyright (c) 2000, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DH_GENERATE_PARAMETERS 3 +.Os +.Sh NAME +.Nm DH_generate_parameters_ex , +.Nm DH_check , +.Nm DH_check_pub_key , +.Nm DH_generate_parameters +.Nd generate and check Diffie-Hellman parameters +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dh.h +.Ft int +.Fo DH_generate_parameters_ex +.Fa "DH *dh" +.Fa "int prime_len" +.Fa "int generator" +.Fa "BN_GENCB *cb" +.Fc +.Ft int +.Fo DH_check +.Fa "DH *dh" +.Fa "int *codes" +.Fc +.Ft int +.Fo DH_check_pub_key +.Fa "const DH *dh" +.Fa "const BIGNUM *pub_key" +.Fa "int *codes" +.Fc +.Pp +Deprecated: +.Pp +.Ft DH * +.Fo DH_generate_parameters +.Fa "int prime_len" +.Fa "int generator" +.Fa "void (*callback)(int, int, void *)" +.Fa "void *cb_arg" +.Fc +.Sh DESCRIPTION +.Fn DH_generate_parameters_ex +generates Diffie-Hellman parameters that can be shared among a group of +users, and stores them in the provided +.Vt DH +structure. +.Pp +.Fa prime_len +is the length in bits of the safe prime to be generated. +.Fa generator +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 +.Fa cb +is not +.Dv NULL , +it will be called as described in +.Xr BN_generate_prime 3 +while a random prime number is generated, and when a prime has been +found, +.Fn BN_GENCB_call cb 3 0 +is called; see +.Xr BN_GENCB_call 3 . +.Pp +.Fn DH_check +validates Diffie-Hellman parameters. +If no problems are found, +.Pf * Ar codes +is set to zero. +Otherwise, one or more of the following bits are set: +.Bl -tag -width Ds +.It Dv DH_CHECK_P_NOT_PRIME +The parameter +.Fa dh->p +is not prime. +.It Dv DH_CHECK_P_NOT_SAFE_PRIME +The parameter +.Fa dh->p +is not a safe prime. +.It Dv DH_UNABLE_TO_CHECK_GENERATOR +The generator +.Fa dh->g +cannot be checked for suitability: it is neither 2 nor 5. +.It Dv DH_NOT_SUITABLE_GENERATOR +The generator +.Fa dh->g +is not suitable. +.El +.Pp +.Fn DH_check_pub_key +checks whether +.Fa pub_key +is a valid public key when using the domain parameters contained in +.Fa dh . +If no problems are found, +.Pf * Ar codes +is set to zero. +Otherwise, one or more of the following bits are set: +.Bl -tag -width Ds +.It Dv DH_CHECK_PUBKEY_TOO_SMALL +.Fa pub_key +is less than or equal to 1. +.It Dv DH_CHECK_PUBKEY_TOO_LARGE +.Fa pub_key +is greater than or equal to +.Fa dh->p No \- 1 . +.It DH_CHECK_PUBKEY_INVALID +.Fa dh->q +is set but +.Fa pub_key +to the power of +.Fa dh->q +is not 1 modulo +.Fa dh->p . +.El +.Sh RETURN VALUES +.Fn DH_generate_parameters_ex , +.Fn DH_check , +and +.Fn DH_check_pub_key +return 1 if the check could be performed or 0 otherwise. +.Pp +.Fn DH_generate_parameters +(deprecated) returns a pointer to the +.Vt DH +structure, or +.Dv NULL +if the parameter generation fails. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr DH_get0_pqg 3 , +.Xr DH_new 3 +.Sh HISTORY +.Fn DH_check +and +.Fn DH_generate_parameters +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +The +.Fa cb_arg +argument to +.Fn DH_generate_parameters +was added in SSLeay 0.9.0. +.Pp +.Fn DH_check_pub_key +first appeared in OpenSSL 0.9.8a and has been available since +.Ox 4.0 . +.Pp +.Fn DH_generate_parameters_ex +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Sh CAVEATS +.Fn DH_generate_parameters_ex +and +.Fn DH_generate_parameters +may run for several hours before finding a suitable prime. +.Pp +The parameters generated by +.Fn DH_generate_parameters_ex +and +.Fn DH_generate_parameters +are not to be used in signature schemes. +.Sh BUGS +If +.Fa generator +is not 2 or 5, +.Fa dh->g Ns = Ns Fa generator +is not a usable generator. diff --git a/static/openbsd/man3/DH_get0_pqg.3 b/static/openbsd/man3/DH_get0_pqg.3 new file mode 100644 index 00000000..e30d628c --- /dev/null +++ b/static/openbsd/man3/DH_get0_pqg.3 @@ -0,0 +1,343 @@ +.\" $OpenBSD: DH_get0_pqg.3,v 1.10 2025/06/13 18:34:00 schwarze Exp $ +.\" selective merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2016, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt DH_GET0_PQG 3 +.Os +.Sh NAME +.Nm DH_get0_pqg , +.Nm DH_get0_p , +.Nm DH_get0_q , +.Nm DH_get0_g , +.Nm DH_set0_pqg , +.Nm DH_get0_key , +.Nm DH_get0_pub_key , +.Nm DH_get0_priv_key , +.Nm DH_set0_key , +.Nm DH_clear_flags , +.Nm DH_test_flags , +.Nm DH_set_flags , +.Nm DH_get0_engine , +.Nm DH_set_length +.Nd get data from and set data in a DH object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dh.h +.Ft void +.Fo DH_get0_pqg +.Fa "const DH *dh" +.Fa "const BIGNUM **p" +.Fa "const BIGNUM **q" +.Fa "const BIGNUM **g" +.Fc +.Ft const BIGNUM * +.Fo DH_get0_p +.Fa "const DH *dh" +.Fc +.Ft const BIGNUM * +.Fo DH_get0_q +.Fa "const DH *dh" +.Fc +.Ft const BIGNUM * +.Fo DH_get0_g +.Fa "const DH *dh" +.Fc +.Ft int +.Fo DH_set0_pqg +.Fa "DH *dh" +.Fa "BIGNUM *p" +.Fa "BIGNUM *q" +.Fa "BIGNUM *g" +.Fc +.Ft void +.Fo DH_get0_key +.Fa "const DH *dh" +.Fa "const BIGNUM **pub_key" +.Fa "const BIGNUM **priv_key" +.Fc +.Ft const BIGNUM * +.Fo DH_get0_pub_key +.Fa "const DH *dh" +.Fc +.Ft const BIGNUM * +.Fo DH_get0_priv_key +.Fa "const DH *dh" +.Fc +.Ft int +.Fo DH_set0_key +.Fa "DH *dh" +.Fa "BIGNUM *pub_key" +.Fa "BIGNUM *priv_key" +.Fc +.Ft void +.Fo DH_clear_flags +.Fa "DH *dh" +.Fa "int flags" +.Fc +.Ft int +.Fo DH_test_flags +.Fa "const DH *dh" +.Fa "int flags" +.Fc +.Ft void +.Fo DH_set_flags +.Fa "DH *dh" +.Fa "int flags" +.Fc +.Ft ENGINE * +.Fo DH_get0_engine +.Fa "DH *d" +.Fc +.Ft int +.Fo DH_set_length +.Fa "DH *dh" +.Fa "long length" +.Fc +.Sh DESCRIPTION +A +.Vt DH +object contains the parameters +.Fa p , +.Fa g , +and optionally +.Fa q . +It also contains a public key +.Fa pub_key +and an optional private key +.Fa priv_key . +.Pp +The +.Fa p , +.Fa q , +and +.Fa g +parameters can be obtained by calling +.Fn DH_get0_pqg . +If the parameters have not yet been set, then +.Pf * Fa p , +.Pf * Fa q , +and +.Pf * Fa g +are set to +.Dv NULL . +Otherwise, they are set to pointers to the internal representations +of the values that should not be freed by the application. +Any of the out parameters +.Fa p , +.Fa q , +and +.Fa g +can be +.Dv NULL , +in which case no value is returned for that parameter. +.Pp +The +.Fa p , +.Fa q , +and +.Fa g +values can be set by calling +.Fn DH_set0_pqg . +Calling this function transfers the memory management of the values to +.Fa dh , +and therefore they should not be freed by the caller. +The +.Fa q +argument may be +.Dv NULL . +.Pp +The +.Fn DH_get0_key +function stores pointers to the internal representations +of the public key in +.Pf * Fa pub_key +and to the private key in +.Pf * Fa priv_key . +Either may be +.Dv NULL +if it has not yet been set. +If the private key has been set, then the public key must be. +Any of the out parameters +.Fa pub_key +and +.Fa priv_key +can be +.Dv NULL , +in which case no value is returned for that parameter. +.Pp +The public and private key values can be set using +.Fn DH_set0_key . +Either parameter may be +.Dv NULL , +which means the corresponding +.Vt DH +field is left untouched. +This function transfers the memory management of the key values to +.Fa dh , +and therefore they should not be freed by the caller. +.Pp +Values retrieved with +.Fn DH_get0_pqg +and +.Fn DH_get0_key +are owned by the +.Vt DH +object and may therefore not be passed to +.Fn DH_set0_pqg +or +.Fn DH_set0_key . +If needed, duplicate the received values using +.Xr BN_dup 3 +and pass the duplicates. +.Pp +Any of the values +.Fa p , +.Fa q , +.Fa g , +.Fa pub_key , +and +.Fa priv_key +can also be retrieved separately by the corresponding functions +.Fn DH_get0_p , +.Fn DH_get0_q , +.Fn DH_get0_g , +.Fn DH_get0_pub_key , +and +.Fn DH_get0_priv_key , +respectively. +The pointers are owned by the +.Vt DH +object. +.Pp +.Fn DH_clear_flags +clears the specified +.Fa flags +in +.Fa dh . +.Fn DH_test_flags +tests the +.Fa flags +in +.Fa dh . +.Fn DH_set_flags +sets the +.Fa flags +in +.Fa dh ; +any flags already set remain set. +For all three functions, multiple flags can be passed in one call, +OR'ed together bitwise. +.Pp +.Fn DH_set_length +sets the optional length attribute of +.Fa dh , +indicating the length of the secret exponent (private key) in bits. +If the length attribute is non-zero, it is used, otherwise it is ignored. +.Sh RETURN VALUES ++.Fn DH_get0_p , ++.Fn DH_get0_q , ++.Fn DH_get0_g , ++.Fn DH_get0_pub_key , ++and ++.Fn DH_get0_priv_key , ++return a pointer owned by the ++.Vt DH ++object if the corresponding value has been set, ++otherwise they return ++.Dv NULL . +.Fn DH_set0_pqg , +.Fn DH_set0_key , +and +.Fn DH_set_length +return 1 on success or 0 on failure. +.Pp +.Fn DH_test_flags +return those of the given +.Fa flags +currently set in +.Fa dh +or 0 if none of the given +.Fa flags +are set. +.Pp +.Fn DH_get0_engine +always returns +.Dv NULL . +.Sh SEE ALSO +.Xr DH_generate_key 3 , +.Xr DH_generate_parameters 3 , +.Xr DH_new 3 , +.Xr DH_security_bits 3 , +.Xr DH_size 3 , +.Xr DHparams_print 3 +.Sh HISTORY +.Fn DH_get0_pqg , +.Fn DH_set0_pqg , +.Fn DH_get0_key , +.Fn DH_set0_key , +.Fn DH_clear_flags , +.Fn DH_test_flags , +.Fn DH_set_flags , +.Fn DH_get0_engine , +and +.Fn DH_set_length +first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 6.3 . +.Pp +.Fn DH_get0_p , +.Fn DH_get0_q , +.Fn DH_get0_g , +.Fn DH_get0_pub_key , +and +.Fn DH_get0_priv_key +first appeared in OpenSSL 1.1.1 +and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/DH_get_ex_new_index.3 b/static/openbsd/man3/DH_get_ex_new_index.3 new file mode 100644 index 00000000..e0d1f1b8 --- /dev/null +++ b/static/openbsd/man3/DH_get_ex_new_index.3 @@ -0,0 +1,100 @@ +.\" $OpenBSD: DH_get_ex_new_index.3,v 1.6 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DH_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm DH_get_ex_new_index , +.Nm DH_set_ex_data , +.Nm DH_get_ex_data +.Nd add application specific data to DH structures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dh.h +.Ft int +.Fo DH_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo DH_set_ex_data +.Fa "DH *d" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft char * +.Fo DH_get_ex_data +.Fa "DH *d" +.Fa "int idx" +.Fc +.Sh DESCRIPTION +These functions handle application specific data in +.Vt DH +structures. +Their usage is identical to that of +.Xr RSA_get_ex_new_index 3 , +.Xr RSA_set_ex_data 3 , +and +.Xr RSA_get_ex_data 3 . +.Sh SEE ALSO +.Xr DH_new 3 , +.Xr RSA_get_ex_new_index 3 +.Sh HISTORY +.Fn DH_get_ex_new_index , +.Fn DH_set_ex_data , +and +.Fn DH_get_ex_data +first appeared in OpenSSL 0.9.5 +and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/DH_new.3 b/static/openbsd/man3/DH_new.3 new file mode 100644 index 00000000..0e01a267 --- /dev/null +++ b/static/openbsd/man3/DH_new.3 @@ -0,0 +1,134 @@ +.\" $OpenBSD: DH_new.3,v 1.13 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DH_NEW 3 +.Os +.Sh NAME +.Nm DH_new , +.Nm DH_up_ref , +.Nm DH_free +.Nd allocate and free DH objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dh.h +.Ft DH* +.Fn DH_new void +.Ft int +.Fo DH_up_ref +.Fa "DH *dh" +.Fc +.Ft void +.Fo DH_free +.Fa "DH *dh" +.Fc +.Sh DESCRIPTION +The DH functions implement the Diffie-Hellman key agreement protocol. +.Pp +.Fn DH_new +allocates and initializes a +.Vt DH +structure, setting the reference count to 1. +It is equivalent to +.Xr DH_new_method 3 +with a +.Dv NULL +argument. +.Pp +.Fn DH_up_ref +increments the reference count by 1. +.Pp +.Fn DH_free +decrements the reference count by 1. +If it reaches 0, it frees the +.Vt DH +structure and its components. +The values are erased before the memory is returned to the system. +If +.Fa dh +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +If the allocation fails, +.Fn DH_new +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +Otherwise it returns a pointer to the newly allocated structure. +.Pp +.Fn DH_up_ref +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr BN_new 3 , +.Xr crypto 3 , +.Xr d2i_DHparams 3 , +.Xr DH_generate_key 3 , +.Xr DH_generate_parameters 3 , +.Xr DH_get0_pqg 3 , +.Xr DH_get_ex_new_index 3 , +.Xr DH_security_bits 3 , +.Xr DH_set_method 3 , +.Xr DH_size 3 , +.Xr DHparams_print 3 , +.Xr DSA_dup_DH 3 , +.Xr EVP_PKEY_CTX_set_dh_paramgen_prime_len 3 , +.Xr EVP_PKEY_set1_DH 3 +.Sh HISTORY +.Fn DH_new +and +.Fn DH_free +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn DH_up_ref +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/DH_set_method.3 b/static/openbsd/man3/DH_set_method.3 new file mode 100644 index 00000000..3491cf8f --- /dev/null +++ b/static/openbsd/man3/DH_set_method.3 @@ -0,0 +1,196 @@ +.\" $OpenBSD: DH_set_method.3,v 1.10 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2002, 2007 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DH_SET_METHOD 3 +.Os +.Sh NAME +.Nm DH_set_default_method , +.Nm DH_get_default_method , +.Nm DH_set_method , +.Nm DH_new_method , +.Nm DH_OpenSSL +.Nd select DH method +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dh.h +.Ft void +.Fo DH_set_default_method +.Fa "const DH_METHOD *meth" +.Fc +.Ft const DH_METHOD * +.Fo DH_get_default_method +.Fa void +.Fc +.Ft int +.Fo DH_set_method +.Fa "DH *dh" +.Fa "const DH_METHOD *meth" +.Fc +.Ft DH * +.Fo DH_new_method +.Fa "ENGINE *engine" +.Fc +.Ft const DH_METHOD * +.Fo DH_OpenSSL +.Fa void +.Fc +.Sh DESCRIPTION +A +.Vt DH_METHOD +object contains pointers to the functions +used for Diffie-Hellman operations. +By default, the internal implementation returned by +.Fn DH_OpenSSL +is used. +By selecting another method, alternative implementations +such as hardware accelerators may be used. +.Pp +.Fn DH_set_default_method +selects +.Fa meth +as the default method for all +.Vt DH +structures created later. +.Pp +.Fn DH_get_default_method +returns a pointer to the current default method. +.Pp +.Fn DH_set_method +selects +.Fa meth +to perform all operations using the key +.Fa dh . +This replaces the +.Vt DH_METHOD +used by the +.Fa dh +key. +It is possible to have +.Vt DH +keys that only work with certain +.Vt DH_METHOD +implementations, +and in such cases attempting to change the +.Vt DH_METHOD +for the key can have unexpected results. +.Pp +.Fn DH_new_method +allocates and initializes a +.Vt DH +structure. +The +.Fa engine +argument is ignored and +the default method controlled by +.Fn DH_set_default_method +is used. +.Pp +The +.Vt DH_METHOD +structure is defined as follows: +.Bd -literal +typedef struct dh_meth_st +{ + /* name of the implementation */ + const char *name; + + /* generate private and public DH values for key agreement */ + int (*generate_key)(DH *dh); + + /* compute shared secret */ + int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); + + /* compute r = a ^ p mod m (May be NULL for some implementations) */ + int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, + BN_MONT_CTX *m_ctx); + + /* called at DH_new */ + int (*init)(DH *dh); + + /* called at DH_free */ + int (*finish)(DH *dh); + + int flags; + + char *app_data; /* ?? */ + +} DH_METHOD; +.Ed +.Sh RETURN VALUES +.Fn DH_OpenSSL +and +.Fn DH_get_default_method +return pointers to the respective +.Vt DH_METHOD . +.Pp +.Fn DH_set_method +returns 1 on success or 0 on failure. +Currently, it cannot fail. +.Pp +.Fn DH_new_method +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 +if the allocation fails. +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr DH_new 3 +.Sh HISTORY +.Fn DH_set_default_method , +.Fn DH_get_default_method , +.Fn DH_set_method , +.Fn DH_new_method +and +.Fn DH_OpenSSL +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/DH_size.3 b/static/openbsd/man3/DH_size.3 new file mode 100644 index 00000000..09c019f3 --- /dev/null +++ b/static/openbsd/man3/DH_size.3 @@ -0,0 +1,98 @@ +.\" $OpenBSD: DH_size.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller +.\" and Kurt Roeckx . +.\" Copyright (c) 2000, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DH_SIZE 3 +.Os +.Sh NAME +.Nm DH_size , +.Nm DH_bits +.Nd get Diffie-Hellman prime size +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dh.h +.Ft int +.Fo DH_size +.Fa "const DH *dh" +.Fc +.Ft int +.Fo DH_bits +.Fa "const DH *dh" +.Fc +.Sh DESCRIPTION +.Fn DH_size +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 +.Xr DH_compute_key 3 . +.Pp +.Fn DH_bits +returns the number of significant bits in the key. +.Pp +.Fa dh +and +.Fa dh->p +must not be +.Dv NULL . +.Sh SEE ALSO +.Xr BN_num_bytes 3 , +.Xr DH_generate_key 3 , +.Xr DH_get0_key 3 , +.Xr DH_new 3 , +.Xr DH_security_bits 3 +.Sh HISTORY +.Fn DH_size +first appeared in SSLeay 0.5.1 and has been available since +.Ox 2.4 . +.Pp +.Fn DH_bits +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/DIST_POINT_new.3 b/static/openbsd/man3/DIST_POINT_new.3 new file mode 100644 index 00000000..e5aeb2a5 --- /dev/null +++ b/static/openbsd/man3/DIST_POINT_new.3 @@ -0,0 +1,155 @@ +.\" $OpenBSD: DIST_POINT_new.3,v 1.6 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt DIST_POINT_NEW 3 +.Os +.Sh NAME +.Nm DIST_POINT_new , +.Nm DIST_POINT_free , +.Nm CRL_DIST_POINTS_new , +.Nm CRL_DIST_POINTS_free , +.Nm DIST_POINT_NAME_new , +.Nm DIST_POINT_NAME_free , +.Nm ISSUING_DIST_POINT_new , +.Nm ISSUING_DIST_POINT_free +.Nd X.509 CRL distribution point extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft DIST_POINT * +.Fn DIST_POINT_new void +.Ft void +.Fn DIST_POINT_free "DIST_POINT *dp" +.Ft CRL_DIST_POINTS * +.Fn CRL_DIST_POINTS_new void +.Ft void +.Fn CRL_DIST_POINTS_free "CRL_DIST_POINTS *dps" +.Ft DIST_POINT_NAME * +.Fn DIST_POINT_NAME_new void +.Ft void +.Fn DIST_POINT_NAME_free "DIST_POINT_NAME *name" +.Ft ISSUING_DIST_POINT * +.Fn ISSUING_DIST_POINT_new void +.Ft void +.Fn ISSUING_DIST_POINT_free "ISSUING_DIST_POINT *dp" +.Sh DESCRIPTION +Using the CRL distribution point extension, a certificate can specify +where to obtain certificate revocation lists that might later revoke it. +.Pp +.Fn DIST_POINT_new +allocates and initializes an empty +.Vt DIST_POINT +object, representing an ASN.1 +.Vt DistributionPoint +structure defined in RFC 5280 section 4.2.1.13. +It can hold issuer names, distribution point names, and reason flags. +.Fn DIST_POINT_free +frees +.Fa dp . +.Pp +.Fn CRL_DIST_POINTS_new +allocates and initializes an empty +.Vt CRL_DIST_POINTS +object, which is a +.Vt STACK_OF(DIST_POINT) +and represents the ASN.1 +.Vt CRLDistributionPoints +structure defined in RFC 5280 section 4.2.1.13. +It can be used as an extension in +.Vt X509 +and in +.Vt X509_CRL +objects. +.Fn CRL_DIST_POINTS_free +frees +.Fa dps . +.Pp +.Fn DIST_POINT_NAME_new +allocates and initializes an empty +.Vt DIST_POINT_NAME +object, representing an ASN.1 +.Vt DistributionPointName +structure defined in RFC 5280 section 4.2.1.13. +It is used by the +.Vt DIST_POINT +and +.Vt ISSUING_DIST_POINT +objects and can hold multiple names, each representing a different +way to obtain the same CRL. +.Fn DIST_POINT_NAME_free +frees +.Fa name . +.Pp +.Fn ISSUING_DIST_POINT_new +allocates and initializes an empty +.Vt ISSUING_DIST_POINT +object, representing an ASN.1 +.Vt IssuingDistributionPoint +structure defined in RFC 5280 section 5.2.5. +Using this extension, a CRL can specify which distribution point +it was issued from and which kinds of certificates and revocation +reasons it covers. +.Fn ISSUING_DIST_POINT_free +frees +.Fa dp . +.Sh RETURN VALUES +.Fn DIST_POINT_new , +.Fn CRL_DIST_POINTS_new , +.Fn DIST_POINT_NAME_new , +and +.Fn ISSUING_DIST_POINT_new +return the new +.Vt DIST_POINT , +.Vt CRL_DIST_POINTS , +.Vt DIST_POINT_NAME , +or +.Vt ISSUING_DIST_POINT +object, respectively, or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_DIST_POINT 3 , +.Xr GENERAL_NAMES_new 3 , +.Xr X509_CRL_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_NAME_new 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile: +.Bl -dash -compact +.It +section 4.2.1.13: CRL Distribution Points +.It +section 5.2.5: Issuing Distribution Point +.El +.Sh HISTORY +.Fn DIST_POINT_new , +.Fn DIST_POINT_free , +.Fn CRL_DIST_POINTS_new , +.Fn CRL_DIST_POINTS_free , +.Fn DIST_POINT_NAME_new , +and +.Fn DIST_POINT_NAME_free +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . +.Pp +.Fn ISSUING_DIST_POINT_new +and +.Fn ISSUING_DIST_POINT_free +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/DSA_SIG_new.3 b/static/openbsd/man3/DSA_SIG_new.3 new file mode 100644 index 00000000..003f71f0 --- /dev/null +++ b/static/openbsd/man3/DSA_SIG_new.3 @@ -0,0 +1,142 @@ +.\" $OpenBSD: DSA_SIG_new.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller , +.\" Dr. Stephen Henson , and +.\" TJ Saunders . +.\" Copyright (c) 2000, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_SIG_NEW 3 +.Os +.Sh NAME +.Nm DSA_SIG_new , +.Nm DSA_SIG_free , +.Nm DSA_SIG_get0 , +.Nm DSA_SIG_set0 +.Nd manipulate DSA signature objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft DSA_SIG * +.Fn DSA_SIG_new void +.Ft void +.Fo DSA_SIG_free +.Fa "DSA_SIG *sig" +.Fc +.Ft void +.Fo DSA_SIG_get0 +.Fa "const DSA_SIG *sig" +.Fa "const BIGNUM **r" +.Fa "const BIGNUM **s" +.Fc +.Ft int +.Fo DSA_SIG_set0 +.Fa "DSA_SIG *sig" +.Fa "BIGNUM *r" +.Fa "BIGNUM *s" +.Fc +.Sh DESCRIPTION +.Fn DSA_SIG_new +allocates an empty +.Vt DSA_SIG +structure. +.Pp +.Fn DSA_SIG_free +frees the +.Vt DSA_SIG +structure and its components. +The values are erased before the memory is returned to the system. +If +.Fa sig +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn DSA_SIG_get0 +retrieves internal pointers to the +.Fa r +and +.Fa s +values contained in +.Fa sig . +.Pp +The +.Fa r +and +.Fa s +values can be set by calling +.Fn DSA_SIG_set0 . +Calling this function transfers the memory management of the values to +.Fa sig , +and therefore they should not be freed by the caller. +.Sh RETURN VALUES +If the allocation fails, +.Fn DSA_SIG_new +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +Otherwise it returns a pointer to the newly allocated structure. +.Pp +.Fn DSA_SIG_set0 +returns 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr DSA_do_sign 3 , +.Xr DSA_new 3 +.Sh HISTORY +.Fn DSA_SIG_new +and +.Fn DSA_SIG_free +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . +.Pp +.Fn DSA_SIG_get0 +and +.Fn DSA_SIG_set0 +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/DSA_do_sign.3 b/static/openbsd/man3/DSA_do_sign.3 new file mode 100644 index 00000000..f7de537b --- /dev/null +++ b/static/openbsd/man3/DSA_do_sign.3 @@ -0,0 +1,120 @@ +.\" $OpenBSD: DSA_do_sign.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_DO_SIGN 3 +.Os +.Sh NAME +.Nm DSA_do_sign , +.Nm DSA_do_verify +.Nd raw DSA signature operations +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft DSA_SIG * +.Fo DSA_do_sign +.Fa "const unsigned char *dgst" +.Fa "int dlen" +.Fa "DSA *dsa" +.Fc +.Ft int +.Fo DSA_do_verify +.Fa "const unsigned char *dgst" +.Fa "int dgst_len" +.Fa "DSA_SIG *sig" +.Fa "DSA *dsa" +.Fc +.Sh DESCRIPTION +.Fn DSA_do_sign +computes a digital signature on the +.Fa dlen +byte message digest +.Fa dgst +using the private key +.Fa dsa +and returns it in a newly allocated +.Vt DSA_SIG +structure. +.Pp +.Xr DSA_sign_setup 3 +may be used to precompute part of the signing operation in case +signature generation is time-critical. +.Pp +.Fn DSA_do_verify +verifies that the signature +.Fa sig +matches a given message digest +.Fa dgst +of size +.Fa dgst_len . +.Fa dsa +is the signer's public key. +.Sh RETURN VALUES +.Fn DSA_do_sign +returns the signature or +.Dv NULL +on error. +.Fn DSA_do_verify +returns 1 for a valid signature, 0 for an incorrect signature, +and -1 on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr DSA_get0_key 3 , +.Xr DSA_meth_set_sign 3 , +.Xr DSA_new 3 , +.Xr DSA_SIG_new 3 , +.Xr DSA_sign 3 +.Sh HISTORY +.Fn DSA_do_sign +and +.Fn DSA_do_verify +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/DSA_dup_DH.3 b/static/openbsd/man3/DSA_dup_DH.3 new file mode 100644 index 00000000..a3ec94f6 --- /dev/null +++ b/static/openbsd/man3/DSA_dup_DH.3 @@ -0,0 +1,89 @@ +.\" $OpenBSD: DSA_dup_DH.3,v 1.10 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2002 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_DUP_DH 3 +.Os +.Sh NAME +.Nm DSA_dup_DH +.Nd create a DH structure out of DSA structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft DH * +.Fo DSA_dup_DH +.Fa "const DSA *r" +.Fc +.Sh DESCRIPTION +.Fn DSA_dup_DH +duplicates +.Vt DSA +parameters/keys as +.Vt DH +parameters/keys. +.Sh RETURN VALUES +.Fn DSA_dup_DH +returns the new +.Vt DH +structure or +.Dv NULL +on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr DH_new 3 , +.Xr DSA_get0_pqg 3 , +.Xr DSA_new 3 +.Sh HISTORY +.Fn DSA_dup_DH +first appeared in OpenSSL 0.9.4 and has been available since +.Ox 2.6 . +.Sh CAVEATS +Be careful to avoid small subgroup attacks when using this. diff --git a/static/openbsd/man3/DSA_generate_key.3 b/static/openbsd/man3/DSA_generate_key.3 new file mode 100644 index 00000000..161e0680 --- /dev/null +++ b/static/openbsd/man3/DSA_generate_key.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: DSA_generate_key.3,v 1.12 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_GENERATE_KEY 3 +.Os +.Sh NAME +.Nm DSA_generate_key +.Nd generate DSA key pair +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft int +.Fo DSA_generate_key +.Fa "DSA *a" +.Fc +.Sh DESCRIPTION +.Fn DSA_generate_key +expects +.Fa a +to contain DSA parameters. +It generates a new key pair and stores it in +.Fa a->pub_key +and +.Fa a->priv_key . +.Sh RETURN VALUES +.Fn DSA_generate_key +returns 1 on success or 0 otherwise. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr DSA_generate_parameters_ex 3 , +.Xr DSA_get0_key 3 , +.Xr DSA_new 3 +.Sh HISTORY +.Fn DSA_generate_key +first appeared in SSLeay 0.6.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/DSA_generate_parameters_ex.3 b/static/openbsd/man3/DSA_generate_parameters_ex.3 new file mode 100644 index 00000000..fb610b81 --- /dev/null +++ b/static/openbsd/man3/DSA_generate_parameters_ex.3 @@ -0,0 +1,173 @@ +.\" $OpenBSD: DSA_generate_parameters_ex.3,v 1.2 2025/06/08 22:37:23 schwarze Exp $ +.\" OpenSSL 9b86974e Aug 7 22:14:47 2015 -0400 +.\" +.\" This file was written by Ulf Moeller , +.\" Bodo Moeller , and Matt Caswell . +.\" Copyright (c) 2000, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_GENERATE_PARAMETERS_EX 3 +.Os +.Sh NAME +.Nm DSA_generate_parameters_ex +.Nd generate DSA parameters +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft int +.Fo DSA_generate_parameters_ex +.Fa "DSA *dsa" +.Fa "int bits" +.Fa "const unsigned char *seed" +.Fa "int seed_len" +.Fa "int *counter_ret" +.Fa "unsigned long *h_ret" +.Fa "BN_GENCB *cb" +.Fc +.Sh DESCRIPTION +.Fn DSA_generate_parameters_ex +generates primes p and q and a generator g for use in the DSA and stores +the result in +.Fa dsa . +.Pp +.Fa bits +is the length of the prime to be generated; the DSS allows a maximum of +1024 bits. +.Pp +If +.Fa seed +is +.Dv NULL +or +.Fa seed_len +< 20, the primes will be generated at random. +Otherwise, the seed is used to generate them. +If the given seed does not yield a prime q, a new random seed is chosen +and placed at +.Fa seed . +.Pp +.Fn DSA_generate_parameters_ex +places the iteration count in +.Pf * Fa counter_ret +and a counter used for finding a generator in +.Pf * Fa h_ret , +unless these are +.Dv NULL . +.Pp +A callback function may be used to provide feedback about the progress +of the key generation. +If +.Fa cb +is not +.Dv NULL , +it will be called as shown below. +For information on the +.Vt BN_GENCB +structure, refer to +.Xr BN_GENCB_call 3 . +.Bl -bullet +.It +When a candidate for q is generated, +.Fn BN_GENCB_call cb 0 m++ +is called +.Pf ( Fa m +is 0 for the first candidate). +.It +When a candidate for q has passed a test by trial division, +.Fn BN_GENCB_call cb 1 -1 +is called. +While a candidate for q is tested by Miller-Rabin primality tests, +.Fn BN_GENCB_call cb 1 i +is called in the outer loop (once for each witness that confirms that +the candidate may be prime); +.Fa i +is the loop counter (starting at 0). +.It +When a prime q has been found, +.Fn BN_GENCB_call cb 2 0 +and +.Fn BN_GENCB_call cb 3 0 +are called. +.It +Before a candidate for p (other than the first) is generated and tested, +.Fn BN_GENCB_call cb 0 counter +is called. +.It +When a candidate for p has passed the test by trial division, +.Fn BN_GENCB_call cb 1 -1 +is called. +While it is tested by the Miller-Rabin primality test, +.Fn BN_GENCB_call cb 1 i +is called in the outer loop (once for each witness that confirms that +the candidate may be prime). +.Fa i +is the loop counter (starting at 0). +.It +When p has been found, +.Fn BN_GENCB_call cb 2 1 +is called. +.It +When the generator has been found, +.Fn BN_GENCB_call cb 3 1 +is called. +.El +.Sh RETURN VALUES +.Fn DSA_generate_parameters_ex +returns a 1 on success, or 0 otherwise. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_generate_prime 3 , +.Xr DSA_get0_pqg 3 , +.Xr DSA_new 3 +.Sh HISTORY +.Fn DSA_generate_parameters_ex +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Sh BUGS +Seed lengths > 20 are not supported. diff --git a/static/openbsd/man3/DSA_get0_pqg.3 b/static/openbsd/man3/DSA_get0_pqg.3 new file mode 100644 index 00000000..e609b625 --- /dev/null +++ b/static/openbsd/man3/DSA_get0_pqg.3 @@ -0,0 +1,321 @@ +.\" $OpenBSD: DSA_get0_pqg.3,v 1.13 2025/06/13 18:34:00 schwarze Exp $ +.\" full merge up to: OpenSSL e90fc053 Jul 15 09:39:45 2017 -0400 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt DSA_GET0_PQG 3 +.Os +.Sh NAME +.Nm DSA_get0_pqg , +.Nm DSA_get0_p , +.Nm DSA_get0_q , +.Nm DSA_get0_g , +.Nm DSA_set0_pqg , +.Nm DSA_get0_key , +.Nm DSA_get0_pub_key , +.Nm DSA_get0_priv_key , +.Nm DSA_set0_key , +.Nm DSA_clear_flags , +.Nm DSA_test_flags , +.Nm DSA_set_flags , +.Nm DSA_get0_engine +.Nd get data from and set data in a DSA object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft void +.Fo DSA_get0_pqg +.Fa "const DSA *d" +.Fa "const BIGNUM **p" +.Fa "const BIGNUM **q" +.Fa "const BIGNUM **g" +.Fc +.Ft const BIGNUM * +.Fo DSA_get0_p +.Fa "const DSA *d" +.Fc +.Ft const BIGNUM * +.Fo DSA_get0_q +.Fa "const DSA *d" +.Fc +.Ft const BIGNUM * +.Fo DSA_get0_g +.Fa "const DSA *d" +.Fc +.Ft int +.Fo DSA_set0_pqg +.Fa "DSA *d" +.Fa "BIGNUM *p" +.Fa "BIGNUM *q" +.Fa "BIGNUM *g" +.Fc +.Ft void +.Fo DSA_get0_key +.Fa "const DSA *d" +.Fa "const BIGNUM **pub_key" +.Fa "const BIGNUM **priv_key" +.Fc +.Ft const BIGNUM * +.Fo DSA_get0_pub_key +.Fa "const DSA *d" +.Fc +.Ft const BIGNUM * +.Fo DSA_get0_priv_key +.Fa "const DSA *d" +.Fc +.Ft int +.Fo DSA_set0_key +.Fa "DSA *d" +.Fa "BIGNUM *pub_key" +.Fa "BIGNUM *priv_key" +.Fc +.Ft void +.Fo DSA_clear_flags +.Fa "DSA *d" +.Fa "int flags" +.Fc +.Ft int +.Fo DSA_test_flags +.Fa "const DSA *d" +.Fa "int flags" +.Fc +.Ft void +.Fo DSA_set_flags +.Fa "DSA *d" +.Fa "int flags" +.Fc +.Ft ENGINE * +.Fo DSA_get0_engine +.Fa "DSA *d" +.Fc +.Sh DESCRIPTION +A +.Vt DSA +object contains the parameters +.Fa p , +.Fa q , +and +.Fa g . +It also contains a public key +.Fa pub_key +and an optional private key +.Fa priv_key . +.Pp +The +.Fa p , +.Fa q , +and +.Fa g +parameters can be obtained by calling +.Fn DSA_get0_pqg . +If the parameters have not yet been set, then +.Pf * Fa p , +.Pf * Fa q , +and +.Pf * Fa g +are set to +.Dv NULL . +Otherwise, they are set to pointers to the internal representations +of the values that should not be freed by the application. +.Pp +The +.Fa p , +.Fa q , +and +.Fa g +values can be set by calling +.Fn DSA_set0_pqg . +Calling this function transfers the memory management of the values to +.Fa d , +and therefore they should not be freed by the caller. +.Pp +The +.Fn DSA_get0_key +function stores pointers to the internal representations +of the public key in +.Pf * Fa pub_key +and to the private key in +.Pf * Fa priv_key . +Either may be +.Dv NULL +if it has not yet been set. +If the private key has been set, then the public key must be. +.Pp +The public and private key values can be set using +.Fn DSA_set0_key . +The public key must be +.Pf non- Dv NULL +the first time this function is called on a given +.Vt DSA +object. +The private key may be +.Dv NULL . +On subsequent calls, either may be +.Dv NULL , +which means the corresponding +.Vt DSA +field is left untouched. +.Fn DSA_set0_key +transfers the memory management of the key values to +.Fa d , +and therefore they should not be freed by the caller. +.Pp +Values retrieved with +.Fn DSA_get0_pqg +and +.Fn DSA_get0_key +are owned by the +.Vt DSA +object and may therefore not be passed to +.Fn DSA_set0_pqg +or +.Fn DSA_set0_key . +If needed, duplicate the received values using +.Xr BN_dup 3 +and pass the duplicates. +.Pp +Any of the values +.Fa p , +.Fa q , +.Fa g , +.Fa pub_key , +and +.Fa priv_key +can also be retrieved separately by the corresponding functions +.Fn DSA_get0_p , +.Fn DSA_get0_q , +.Fn DSA_get0_g , +.Fn DSA_get0_pub_key , +and +.Fn DSA_get0_priv_key , +respectively. +The pointers are owned by the +.Vt DSA +object. +.Pp +.Fn DSA_clear_flags +clears the specified +.Fa flags +in +.Fa d . +.Fn DSA_test_flags +tests the +.Fa flags +in +.Fa d . +.Fn DSA_set_flags +sets the +.Fa flags +in +.Fa d ; +any flags already set remain set. +For all three functions, multiple flags can be passed in one call, +OR'ed together bitwise. +.Sh RETURN VALUES +.Fn DSA_get0_p , +.Fn DSA_get0_q , +.Fn DSA_get0_g , +.Fn DSA_get0_pub_key , +and +.Fn DSA_get0_priv_key +return a pointer owned by the +.Vt DSA +object if the corresponding value has been set, +otherwise they return +.Dv NULL . +.Fn DSA_set0_pqg +and +.Fn DSA_set0_key +return 1 on success or 0 on failure. +.Pp +.Fn DSA_test_flags +returns those of the given +.Fa flags +currently set in +.Fa d +or 0 if none of the given +.Fa flags +are set. +.Pp +.Fn DSA_get0_engine +always returns +.Dv NULL . +.Sh SEE ALSO +.Xr DSA_do_sign 3 , +.Xr DSA_dup_DH 3 , +.Xr DSA_generate_key 3 , +.Xr DSA_generate_parameters_ex 3 , +.Xr DSA_new 3 , +.Xr DSA_print 3 , +.Xr DSA_security_bits 3 , +.Xr DSA_sign 3 , +.Xr DSA_size 3 +.Sh HISTORY +.Fn DSA_get0_pqg , +.Fn DSA_set0_pqg , +.Fn DSA_get0_key , +.Fn DSA_set0_key , +.Fn DSA_clear_flags , +.Fn DSA_test_flags , +.Fn DSA_set_flags , +and +.Fn DSA_get0_engine +first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 6.3 . +.Pp +.Fn DSA_get0_p , +.Fn DSA_get0_q , +.Fn DSA_get0_g , +.Fn DSA_get0_pub_key , +and +.Fn DSA_get0_priv_key +first appeared in OpenSSL 1.1.1 +and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/DSA_get_ex_new_index.3 b/static/openbsd/man3/DSA_get_ex_new_index.3 new file mode 100644 index 00000000..477c011c --- /dev/null +++ b/static/openbsd/man3/DSA_get_ex_new_index.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: DSA_get_ex_new_index.3,v 1.6 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2009 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm DSA_get_ex_new_index , +.Nm DSA_set_ex_data , +.Nm DSA_get_ex_data +.Nd add application specific data to DSA structures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft int +.Fo DSA_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo DSA_set_ex_data +.Fa "DSA *d" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft char * +.Fo DSA_get_ex_data +.Fa "DSA *d" +.Fa "int idx" +.Fc +.Sh DESCRIPTION +These functions handle application specific data in +.Vt DSA +structures. +Their usage is identical to that of +.Xr RSA_get_ex_new_index 3 , +.Xr RSA_set_ex_data 3 , +and +.Xr RSA_get_ex_data 3 . +.Sh SEE ALSO +.Xr DSA_new 3 , +.Xr RSA_get_ex_new_index 3 +.Sh HISTORY +.Fn DSA_get_ex_new_index , +.Fn DSA_set_ex_data , +and +.Fn DSA_get_ex_data +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/DSA_meth_new.3 b/static/openbsd/man3/DSA_meth_new.3 new file mode 100644 index 00000000..abd02334 --- /dev/null +++ b/static/openbsd/man3/DSA_meth_new.3 @@ -0,0 +1,231 @@ +.\" $OpenBSD: DSA_meth_new.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" selective merge up to: OpenSSL c4d3c19b Apr 3 13:57:12 2018 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2022 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. +.\" +.\" The original file was written by Matt Caswell . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_METH_NEW 3 +.Os +.Sh NAME +.Nm DSA_meth_new , +.Nm DSA_meth_free , +.Nm DSA_meth_dup , +.Nm DSA_meth_get0_name , +.Nm DSA_meth_set1_name , +.Nm DSA_meth_set_sign , +.Nm DSA_meth_set_finish +.Nd build up DSA methods +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft DSA_METHOD * +.Fo DSA_meth_new +.Fa "const char *name" +.Fa "int flags" +.Fc +.Ft void +.Fo DSA_meth_free +.Fa "DSA_METHOD *meth" +.Fc +.Ft DSA_METHOD * +.Fo DSA_meth_dup +.Fa "const DSA_METHOD *meth" +.Fc +.Ft const char * +.Fo DSA_meth_get0_name +.Fa "const DSA_METHOD *meth" +.Fc +.Ft int +.Fo DSA_meth_set1_name +.Fa "DSA_METHOD *meth" +.Fa "const char *name" +.Fc +.Ft int +.Fo DSA_meth_set_sign +.Fa "DSA_METHOD *meth" +.Fa "DSA_SIG *(*sign)(const unsigned char *, int, DSA *)" +.Fc +.Ft int +.Fo DSA_meth_set_finish +.Fa "DSA_METHOD *meth" +.Fa "int (*finish)(DSA *)" +.Fc +.Sh DESCRIPTION +The +.Vt DSA_METHOD +structure holds function pointers for custom DSA implementations. +.Pp +.Fn DSA_meth_new +creates a new +.Vt DSA_METHOD +structure. +A copy of the NUL-terminated +.Fa name +is stored in the new +.Vt DSA_METHOD +object. +Any new +.Vt DSA +object constructed from this +.Vt DSA_METHOD +will have the given +.Fa flags +set by default. +.Pp +.Fn DSA_meth_dup +creates a deep copy of +.Fa meth . +This might be useful for creating a new +.Vt DSA_METHOD +based on an existing one, but with some differences. +.Pp +.Fn DSA_meth_free +destroys +.Fa meth +and frees any memory associated with it. +.Pp +.Fn DSA_meth_get0_name +returns an internal pointer to the name of +.Fa meth . +.Fn DSA_meth_set1_name +stores a copy of the NUL-terminated +.Fa name +in +.Fa meth +after freeing the previously stored name. +Method names are ignored by the default DSA implementation but can be +used by alternative implementations and by the application program. +.Pp +.Fn DSA_meth_set_sign +sets the function used for creating a DSA signature. +This function will be called from +.Xr DSA_do_sign 3 +and indirectly from +.Xr DSA_sign 3 . +The parameters of +.Fa sign +have the same meaning as for +.Xr DSA_do_sign 3 . +.Pp +.Fn DSA_meth_set_finish +sets an optional function for destroying a +.Vt DSA +object. +Unless +.Fa finish +is +.Dv NULL , +it will be called from +.Xr DSA_free 3 . +It takes the same argument +and is intended to do DSA implementation specific cleanup. +The memory used by the +.Vt DSA +object itself should not be freed by the +.Fa finish +function. +.Sh RETURN VALUES +.Fn DSA_meth_new +and +.Fn DSA_meth_dup +return the newly allocated +.Vt DSA_METHOD +object or +.Dv NULL +on failure. +.Pp +.Fn DSA_meth_get0_name +returns an internal pointer which must not be freed by the caller. +.Pp +.Fn DSA_meth_set1_name +and all +.Fn DSA_meth_set_* +functions return 1 on success or 0 on failure. +In the current implementation, only +.Fn DSA_meth_set1_name +can actually fail. +.Sh SEE ALSO +.Xr DSA_do_sign 3 , +.Xr DSA_new 3 , +.Xr DSA_set_method 3 , +.Xr DSA_SIG_new 3 , +.Xr DSA_sign 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0. +.Pp +.Fn DSA_meth_new , +.Fn DSA_meth_free , +.Fn DSA_meth_dup , +.Fn DSA_meth_set_sign , +and +.Fn DSA_meth_set_finish +have been available since +.Ox 6.3 . +.Pp +.Fn DSA_meth_get0_name +and +.Fn DSA_meth_set1_name +have been available since +.Ox 7.2 . diff --git a/static/openbsd/man3/DSA_new.3 b/static/openbsd/man3/DSA_new.3 new file mode 100644 index 00000000..5340bec4 --- /dev/null +++ b/static/openbsd/man3/DSA_new.3 @@ -0,0 +1,142 @@ +.\" $OpenBSD: DSA_new.3,v 1.15 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2002 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_NEW 3 +.Os +.Sh NAME +.Nm DSA_new , +.Nm DSA_up_ref , +.Nm DSA_free +.Nd allocate and free DSA objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft DSA* +.Fn DSA_new void +.Ft int +.Fo DSA_up_ref +.Fa "DSA *dsa" +.Fc +.Ft void +.Fo DSA_free +.Fa "DSA *dsa" +.Fc +.Sh DESCRIPTION +The DSA functions implement the Digital Signature Algorithm. +.Pp +.Fn DSA_new +allocates and initializes a +.Vt DSA +structure, setting the reference count to 1. +It is equivalent to calling +.Xr DSA_new_method 3 +with a +.Dv NULL +argument. +.Pp +.Fn DSA_up_ref +increments the reference count by 1. +.Pp +.Fn DSA_free +decrements the reference count by 1. +If it reaches 0, it frees the +.Vt DSA +structure and its components. +The values are erased before the memory is returned to the system. +If +.Fa dsa +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +If the allocation fails, +.Fn DSA_new +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +Otherwise it returns a pointer to the newly allocated structure. +.Pp +.Fn DSA_up_ref +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr BN_new 3 , +.Xr crypto 3 , +.Xr d2i_DSAPublicKey 3 , +.Xr DH_new 3 , +.Xr DSA_do_sign 3 , +.Xr DSA_dup_DH 3 , +.Xr DSA_generate_key 3 , +.Xr DSA_generate_parameters_ex 3 , +.Xr DSA_get0_pqg 3 , +.Xr DSA_get_ex_new_index 3 , +.Xr DSA_meth_new 3 , +.Xr DSA_print 3 , +.Xr DSA_security_bits 3 , +.Xr DSA_set_method 3 , +.Xr DSA_SIG_new 3 , +.Xr DSA_sign 3 , +.Xr DSA_size 3 , +.Xr EVP_PKEY_set1_DSA 3 , +.Xr RSA_new 3 +.Sh STANDARDS +US Federal Information Processing Standard FIPS 186 (Digital Signature +Standard, DSS), ANSI X9.30 +.Sh HISTORY +.Fn DSA_new +and +.Fn DSA_free +first appeared in SSLeay 0.6.0 and have been available since +.Ox 2.4 . +.Pp +.Fn DSA_up_ref +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/DSA_set_method.3 b/static/openbsd/man3/DSA_set_method.3 new file mode 100644 index 00000000..f2a6eca5 --- /dev/null +++ b/static/openbsd/man3/DSA_set_method.3 @@ -0,0 +1,179 @@ +.\" $OpenBSD: DSA_set_method.3,v 1.13 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2002, 2007 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_SET_METHOD 3 +.Os +.Sh NAME +.Nm DSA_set_default_method , +.Nm DSA_get_default_method , +.Nm DSA_set_method , +.Nm DSA_new_method , +.Nm DSA_OpenSSL +.Nd select DSA method +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft void +.Fo DSA_set_default_method +.Fa "const DSA_METHOD *meth" +.Fc +.Ft const DSA_METHOD * +.Fn DSA_get_default_method void +.Ft int +.Fo DSA_set_method +.Fa "DSA *dsa" +.Fa "const DSA_METHOD *meth" +.Fc +.Ft DSA * +.Fo DSA_new_method +.Fa "ENGINE *engine" +.Fc +.Ft DSA_METHOD * +.Fn DSA_OpenSSL void +.Sh DESCRIPTION +A +.Vt DSA_METHOD +object contains pointers to the functions used for DSA operations. +By default, the internal implementation returned by +.Fn DSA_OpenSSL +is used. +By selecting another method, alternative implementations +such as hardware accelerators may be used. +.Pp +.Fn DSA_set_default_method +selects +.Fa meth +as the default method for all +.Vt DSA +structures created later. +.Pp +.Fn DSA_get_default_method +returns a pointer to the current default method. +.Pp +.Fn DSA_set_method +selects +.Fa meth +to perform all operations using the key +.Fa dsa . +This replaces the +.Vt DSA_METHOD +used by the DSA key. +It is possible to have DSA keys that only work with certain +.Vt DSA_METHOD +implementations, +and in such cases attempting to change the +.Vt DSA_METHOD +for the key can have unexpected results. +.Pp +.Fn DSA_new_method +allocates and initializes a +.Vt DSA +structure. +The +.Fa engine +argument is ignored and +the default method controlled by +.Fn DSA_set_default_method +is used. +.Pp +The +.Vt DSA_METHOD +structure is defined as follows: +.Bd -literal +struct { + /* name of the implementation */ + const char *name; + /* sign */ + DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, + DSA *dsa); + /* pre-compute k^-1 and r */ + int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, + BIGNUM **rp); + /* verify */ + int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len, + DSA_SIG *sig, DSA *dsa); + /* called at DSA_new */ + int (*init)(DSA *DSA); + /* called at DSA_free */ + int (*finish)(DSA *DSA); + int flags; +} DSA_METHOD; +.Ed +.Sh RETURN VALUES +.Fn DSA_OpenSSL +and +.Fn DSA_get_default_method +return pointers to the respective +.Vt DSA_METHOD . +.Pp +.Fn DSA_set_method +returns 1 on success or 0 on failure. +Currently, it cannot fail. +.Pp +.Fn DSA_new_method +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 +if the allocation fails. +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr DSA_meth_new 3 , +.Xr DSA_new 3 +.Sh HISTORY +.Fn DSA_set_default_method , +.Fn DSA_get_default_method , +.Fn DSA_set_method , +.Fn DSA_new_method , +and +.Fn DSA_OpenSSL +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/DSA_sign.3 b/static/openbsd/man3/DSA_sign.3 new file mode 100644 index 00000000..787dc903 --- /dev/null +++ b/static/openbsd/man3/DSA_sign.3 @@ -0,0 +1,174 @@ +.\" $OpenBSD: DSA_sign.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_SIGN 3 +.Os +.Sh NAME +.Nm DSA_sign , +.Nm DSA_sign_setup , +.Nm DSA_verify +.Nd DSA signatures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft int +.Fo DSA_sign +.Fa "int type" +.Fa "const unsigned char *dgst" +.Fa "int len" +.Fa "unsigned char *sigret" +.Fa "unsigned int *siglen" +.Fa "DSA *dsa" +.Fc +.Ft int +.Fo DSA_sign_setup +.Fa "DSA *dsa" +.Fa "BN_CTX *ctx" +.Fa "BIGNUM **kinvp" +.Fa "BIGNUM **rp" +.Fc +.Ft int +.Fo DSA_verify +.Fa "int type" +.Fa "const unsigned char *dgst" +.Fa "int len" +.Fa "unsigned char *sigbuf" +.Fa "int siglen" +.Fa "DSA *dsa" +.Fc +.Sh DESCRIPTION +.Fn DSA_sign +computes a digital signature on the +.Fa len +byte message digest +.Fa dgst +using the private key +.Fa dsa +and places its ASN.1 DER encoding at +.Fa sigret . +The length of the signature is placed in +.Pf * Fa siglen . +.Fa sigret +must point to +.Fn DSA_size dsa +bytes of memory. +.Pp +.Fn DSA_sign_setup +may be used to precompute part of the signing operation in case +signature generation is time-critical. +It expects +.Fa dsa +to contain DSA parameters. +It places the precomputed values in newly allocated +.Vt BIGNUM Ns s +at +.Pf * Fa kinvp +and +.Pf * Fa rp , +after freeing the old ones unless +.Fa kinvp +and +.Fa rp +are +.Dv NULL . +These values may be passed to +.Fn DSA_sign +in +.Fa dsa->kinv +and +.Sy dsa->r . +.Fa ctx +is a pre-allocated +.Vt BN_CTX +or +.Dv NULL . +.Pp +.Fn DSA_verify +verifies that the signature +.Fa sigbuf +of size +.Fa siglen +matches a given message digest +.Fa dgst +of size +.Fa len . +.Fa dsa +is the signer's public key. +.Pp +The +.Fa type +parameter is ignored. +.Sh RETURN VALUES +.Fn DSA_sign +and +.Fn DSA_sign_setup +return 1 on success or 0 on error. +.Fn DSA_verify +returns 1 for a valid signature, 0 for an incorrect signature, +and -1 on error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr DSA_do_sign 3 , +.Xr DSA_get0_key 3 , +.Xr DSA_new 3 +.Sh STANDARDS +US Federal Information Processing Standard FIPS 186 (Digital Signature +Standard, DSS), ANSI X9.30 +.Sh HISTORY +.Fn DSA_sign +and +.Fn DSA_verify +first appeared in SSLeay 0.6.0. +.Fn DSA_sign_setup +first appeared in SSLeay 0.8.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/DSA_size.3 b/static/openbsd/man3/DSA_size.3 new file mode 100644 index 00000000..09ce80e1 --- /dev/null +++ b/static/openbsd/man3/DSA_size.3 @@ -0,0 +1,123 @@ +.\" $OpenBSD: DSA_size.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022 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. +.\" +.\" The original file was written by Ulf Moeller +.\" and Dr. Stephen Henson . +.\" Copyright (c) 2000, 2002, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DSA_SIZE 3 +.Os +.Sh NAME +.Nm DSA_size , +.Nm DSA_bits +.Nd get DSA signature or key size +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft int +.Fo DSA_size +.Fa "const DSA *dsa" +.Fc +.Ft int +.Fo DSA_bits +.Fa "const DSA *dsa" +.Fc +.Sh DESCRIPTION +.Fn DSA_size +returns the maximum size of an ASN.1 encoded DSA signature for the key +.Fa dsa +in bytes. +It can be used to determine how much memory must be allocated for a DSA +signature. +.Pp +.Fa dsa->q +must not be +.Dv NULL . +.Pp +.Fn DSA_bits +returns the number of significant bits in the public domain parameter +.Fa p +contained in +.Fa dsa . +This is also the number of bits in the public key. +.Sh RETURN VALUES +.Fn DSA_size +returns the size of the signature in bytes. +.Pp +.Fn DSA_bits +returns the size of the public key in bits. +.Sh SEE ALSO +.Xr DSA_get0_pqg 3 , +.Xr DSA_new 3 , +.Xr DSA_security_bits 3 , +.Xr DSA_sign 3 +.Sh HISTORY +.Fn DSA_size +first appeared in SSLeay 0.6.0 and has been available since +.Ox 2.4 . +.Pp +.Fn DSA_bits +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/DTLSv1_listen.3 b/static/openbsd/man3/DTLSv1_listen.3 new file mode 100644 index 00000000..bdba1c59 --- /dev/null +++ b/static/openbsd/man3/DTLSv1_listen.3 @@ -0,0 +1,188 @@ +.\" $OpenBSD: DTLSv1_listen.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 7795475f Dec 18 13:18:31 2015 -0500 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DTLSV1_LISTEN 3 +.Os +.Sh NAME +.Nm DTLSv1_listen +.Nd listen for incoming DTLS connections +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo DTLSv1_listen +.Fa "SSL *ssl" +.Fa "struct sockaddr *peer" +.Fc +.Sh DESCRIPTION +.Fn DTLSv1_listen +listens for new incoming DTLS connections. +If a ClientHello is received that does not contain a cookie, then +.Fn DTLSv1_listen +responds with a HelloVerifyRequest. +If a ClientHello is received with a cookie that is verified, then +control is returned to user code to enable the handshake to be +completed (for example by using +.Xr SSL_accept 3 ) . +.Pp +.Fn DTLSv1_listen +is currently implemented as a macro. +.Pp +Datagram based protocols can be susceptible to Denial of Service +attacks. +A DTLS attacker could, for example, submit a series of handshake +initiation requests that cause the server to allocate state (and +possibly perform cryptographic operations) thus consuming server +resources. +The attacker could also (with UDP) quite simply forge the source IP +address in such an attack. +.Pp +As a counter measure to that DTLS includes 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 HelloVerifyRequest 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 +.Fn DTLSv1_listen +function. +The +.Fa ssl +parameter should be a newly allocated +.Vt SSL +object with its read and write BIOs set, in the same way as might +be done for a call to +.Xr SSL_accept 3 . +Typically 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 +.Fn DTLSv1_listen +will return with the +.Fa ssl +parameter updated into a state where the handshake can be continued by a +call to (for example) +.Xr SSL_accept 3 . +Additionally the +.Vt struct sockaddr +pointed to by +.Fa peer +will be filled in with details of the peer that sent the ClientHello. +It is the calling code's responsibility to ensure that the +.Fa peer +location is sufficiently large to accommodate the addressing scheme in use. +For example this might be done by allocating space for a +.Vt struct sockaddr_storage +and casting the pointer to it to a +.Vt struct sockaddr * +for the call to +.Fn DTLSv1_listen . +Typically user code is expected to "connect" the underlying socket +to the peer and continue the handshake in a connected state. +.Pp +Prior to calling +.Fn DTLSv1_listen +user code must ensure that cookie generation and verification callbacks +have been set up using +.Fn SSL_CTX_set_cookie_generate_cb +and +.Fn SSL_CTX_set_cookie_verify_cb +respectively. +.Pp +Since +.Fn DTLSv1_listen +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 +.Fn DTLSv1_listen +only supports ClientHellos that fit inside a single datagram. +.Sh RETURN VALUES +From OpenSSL 1.1.0 a return value of >= 1 indicates success. +In this instance the +.Fa peer +value will be filled in and the +.Fa ssl +object set up ready to continue the handshake. +.Pp +A return value of 0 indicates a non-fatal error. +This could (for example) be because of non-blocking 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 +.Fn DTLSv1_listen +in the event of a non-fatal error. +Any old errors on the error queue will be cleared in the subsequent +call. +.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 +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 +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_get_error 3 +.Sh HISTORY +.Fn DTLSv1_listen +first appeared in OpenSSL 0.9.8m and has been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/ECDH_compute_key.3 b/static/openbsd/man3/ECDH_compute_key.3 new file mode 100644 index 00000000..b0ae6ad3 --- /dev/null +++ b/static/openbsd/man3/ECDH_compute_key.3 @@ -0,0 +1,89 @@ +.\" $OpenBSD: ECDH_compute_key.3,v 1.5 2025/06/08 22:40:29 schwarze Exp $ +.\" Copyright (c) 2019 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 $Mdocdate: June 8 2025 $ +.Dt ECDH_COMPUTE_KEY 3 +.Os +.Sh NAME +.Nm ECDH_compute_key , +.Nm ECDH_size +.Nd Elliptic Curve Diffie-Hellman key exchange +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ec.h +.Ft int +.Fo ECDH_compute_key +.Fa "void *out" +.Fa "size_t outlen" +.Fa "const EC_POINT *public_key" +.Fa "EC_KEY *ecdh" +.Fa "void *(*KDF)(const void *in, size_t inlen, void *out, size_t *outlen)" +.Fc +.Ft int +.Fo ECDH_size +.Fa "const EC_KEY *ecdh" +.Fc +.Sh DESCRIPTION +.Fn ECDH_compute_key +performs Elliptic Curve Diffie-Hellman key agreement. +It combines the private key contained in +.Fa ecdh +with the other party's +.Fa public_key , +takes the +.Fa x +component of the affine coordinates, +and optionally applies the key derivation function +.Fa KDF . +It stores the resulting symmetric key in the buffer +.Fa out , +which is +.Fa outlen +bytes long. +If +.Fa KDF +is +.Dv NULL , +.Fa outlen +must be at least +.Fn ECDH_size ecdh . +.Pp +.Fn ECDH_size +returns the number of bytes needed to store an affine coordinate of a +point on the elliptic curve used by +.Fa ecdh , +which is one eighth of the degree of the finite field underlying +that elliptic curve, rounded up to the next integer number. +.Sh RETURN VALUES +.Fn ECDH_compute_key +returns the length of the computed key in bytes or -1 if an error occurs. +.Pp +.Fn ECDH_size +returns the number of bytes needed to store an affine coordinate. +.Sh SEE ALSO +.Xr DH_generate_key 3 , +.Xr DH_size 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_new 3 , +.Xr X25519 3 +.Sh HISTORY +.Fn ECDH_compute_key +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Pp +.Fn ECDH_size +first appeared in +.Ox 6.1 . diff --git a/static/openbsd/man3/ECDSA_SIG_new.3 b/static/openbsd/man3/ECDSA_SIG_new.3 new file mode 100644 index 00000000..4554af03 --- /dev/null +++ b/static/openbsd/man3/ECDSA_SIG_new.3 @@ -0,0 +1,453 @@ +.\" $OpenBSD: ECDSA_SIG_new.3,v 1.24 2025/06/13 18:34:00 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" selective merge up to: OpenSSL da4ea0cf Aug 5 16:13:24 2019 +0100 +.\" +.\" This file was written by Nils Larsch . +.\" Copyright (c) 2004, 2005, 2013, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt ECDSA_SIG_NEW 3 +.Os +.Sh NAME +.Nm ECDSA_SIG_new , +.Nm ECDSA_SIG_free , +.Nm ECDSA_SIG_get0 , +.Nm ECDSA_SIG_get0_r , +.Nm ECDSA_SIG_get0_s , +.Nm ECDSA_SIG_set0 , +.Nm i2d_ECDSA_SIG , +.Nm d2i_ECDSA_SIG , +.Nm ECDSA_size , +.Nm ECDSA_sign , +.Nm ECDSA_verify , +.Nm ECDSA_do_sign , +.Nm ECDSA_do_verify +.Nd Elliptic Curve Digital Signature Algorithm +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ec.h +.Ft ECDSA_SIG * +.Fo ECDSA_SIG_new +.Fa void +.Fc +.Ft void +.Fo ECDSA_SIG_free +.Fa "ECDSA_SIG *sig" +.Fc +.Ft void +.Fo ECDSA_SIG_get0 +.Fa "const ECDSA_SIG *sig" +.Fa "const BIGNUM **r" +.Fa "const BIGNUM **s" +.Fc +.Ft const BIGNUM * +.Fo ECDSA_SIG_get0_r +.Fa "const ECDSA_SIG *sig" +.Fc +.Ft const BIGNUM * +.Fo ECDSA_SIG_get0_s +.Fa "const ECDSA_SIG *sig" +.Fc +.Ft int +.Fo ECDSA_SIG_set0 +.Fa "ECDSA_SIG *sig" +.Fa "BIGNUM *r" +.Fa "BIGNUM *s" +.Fc +.Ft int +.Fo i2d_ECDSA_SIG +.Fa "const ECDSA_SIG *sig_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ECDSA_SIG * +.Fo d2i_ECDSA_SIG +.Fa "ECDSA_SIG **sig_out" +.Fa "const unsigned char **der_in" +.Fa "long len" +.Fc +.Ft int +.Fo ECDSA_size +.Fa "const EC_KEY *eckey" +.Fc +.Ft int +.Fo ECDSA_sign +.Fa "int type" +.Fa "const unsigned char *dgst" +.Fa "int dgstlen" +.Fa "unsigned char *sig" +.Fa "unsigned int *siglen" +.Fa "EC_KEY *eckey" +.Fc +.Ft int +.Fo ECDSA_verify +.Fa "int type" +.Fa "const unsigned char *dgst" +.Fa "int dgstlen" +.Fa "const unsigned char *sig" +.Fa "int siglen" +.Fa "EC_KEY *eckey" +.Fc +.Ft ECDSA_SIG * +.Fo ECDSA_do_sign +.Fa "const unsigned char *dgst" +.Fa "int dgst_len" +.Fa "EC_KEY *eckey" +.Fc +.Ft int +.Fo ECDSA_do_verify +.Fa "const unsigned char *dgst" +.Fa "int dgst_len" +.Fa "const ECDSA_SIG *sig" +.Fa "EC_KEY* eckey" +.Fc +.Sh DESCRIPTION +These functions provide a low level interface to ECDSA. +Most applications should use the higher level EVP interface such as +.Xr EVP_DigestSignInit 3 +or +.Xr EVP_DigestVerifyInit 3 +instead. +Creation of the required +.Vt EC_KEY +objects is described in +.Xr EC_KEY_new 3 . +.Pp +The +.Vt ECDSA_SIG +structure consists of two +.Vt BIGNUM Ns s +for the +.Fa r +and +.Fa s +value of an ECDSA signature (see X9.62 or FIPS 186-2). +.Bd -literal -offset indent +struct { + BIGNUM *r; + BIGNUM *s; +} ECDSA_SIG; +.Ed +.Pp +.Fn ECDSA_SIG_new +allocates a new +.Vt ECDSA_SIG +structure (note: this function also allocates the +.Vt BIGNUM Ns s ) +and initializes it. +.Pp +.Fn ECDSA_SIG_free +frees the +.Vt ECDSA_SIG +structure +.Fa sig . +.Pp +.Fn ECDSA_SIG_get0 +retrieves internal pointers the +.Fa r +and +.Fa s +values contained in +.Fa sig . +The values +.Fa r +and +.Fa s +can also be retrieved separately by the corresponding function +.Fn ECDSA_SIG_get0_r +and +.Fn ECDSA_SIG_get0_s , +respectively. +.Pp +.Fn ECDSA_SIG_set0 +sets the +.Fa r +and +.Fa s +values in +.Fa sig . +Calling this function transfers the memory management of the values to +.Fa sig . +Therefore, the values that have been passed in +should not be freed by the caller. +.Pp +.Fn i2d_ECDSA_SIG +creates the DER encoding of the ECDSA signature +.Fa sig_in +and writes the encoded signature to +.Pf * Fa der_out . +.Fn d2i_ECDSA_SIG +decodes the DER-encoded signature stored in the buffer +.Pf * Fa der_in +which is +.Fa len +bytes long into +.Pf * Fa sig_out . +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn ECDSA_size +returns the maximum length of a DER-encoded ECDSA signature created with +the private EC key +.Fa eckey . +.Pp +.Fn ECDSA_sign +computes a digital signature of the +.Fa dgstlen +bytes hash value +.Fa dgst +using the private EC key +.Fa eckey . +The DER-encoded signature is stored in +.Fa sig +and its length is returned in +.Fa siglen . +Note: +.Fa sig +must point to +.Fn ECDSA_size +bytes of memory. +The parameter +.Fa type +is ignored. +.Pp +.Fn ECDSA_verify +verifies that the signature in +.Fa sig +of size +.Fa siglen +is a valid ECDSA signature of the hash value +.Fa dgst +of size +.Fa dgstlen +using the public key +.Fa eckey . +The parameter +.Fa type +is ignored. +.Pp +.Fn ECDSA_do_sign +computes a digital signature of the +.Fa dgst_len +bytes hash value +.Fa dgst +using the private key +.Fa eckey . +The signature is returned in a newly allocated +.Vt ECDSA_SIG +structure (or +.Dv NULL +on error). +.Pp +.Fn ECDSA_do_verify +verifies that the signature +.Fa sig +is a valid ECDSA signature of the hash value +.Fa dgst +of size +.Fa dgst_len +using the public key +.Fa eckey . +.Sh RETURN VALUES +.Fn ECDSA_SIG_new +returns the new +.Vt ECDSA_SIG +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_ECDSA_SIG +returns the number of bytes successfully encoded +or a negative value if an error occurs. +.Pp +.Fn d2i_ECDSA_SIG +returns a pointer to the decoded +.Vt ECDSA_SIG +structure or +.Dv NULL +if an error occurs. +.Pp +.Fn ECDSA_size +returns the maximum length signature or 0 on error. +.Pp +.Fn ECDSA_SIG_get0_r +and +.Fn ECDSA_SIG_get0_s +return a pointer owned by the +.Vt ECDSA_SIG +object if it has been set or +.Dv NULL +otherwise. +.Pp +.Fn ECDSA_SIG_set0 +and +.Fn ECDSA_sign +return 1 if successful or 0 on error. +.Pp +.Fn ECDSA_do_sign +returns a pointer to an allocated +.Vt ECDSA_SIG +structure or +.Dv NULL +on error. +.Pp +.Fn ECDSA_verify +and +.Fn ECDSA_do_verify +return 1 for a valid signature, 0 for an invalid signature and -1 on +error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh EXAMPLES +Creating an ECDSA signature of given SHA-384 hash value using the named +curve secp384r1. +.Pp +First step: create an +.Vt EC_KEY +object. +This part is +.Em not +ECDSA specific. +.Bd -literal -offset indent +int ret; +ECDSA_SIG *sig; +EC_KEY *eckey; + +eckey = EC_KEY_new_by_curve_name(NID_secp384r1); +if (eckey == NULL) { + /* error */ +} +if (!EC_KEY_generate_key(eckey)) { + /* error */ +} +.Ed +.Pp +Second step: compute the ECDSA signature of a SHA-384 hash value using +.Fn ECDSA_do_sign +.Bd -literal -offset indent +sig = ECDSA_do_sign(digest, SHA384_DIGEST_LENGTH, eckey); +if (sig == NULL) { + /* error */ +} +.Ed +.Pp +or using +.Fn ECDSA_sign +.Bd -literal -offset indent +unsigned char *buffer, *pp; +int buf_len; + +buf_len = ECDSA_size(eckey); +buffer = malloc(buf_len); +pp = buffer; +if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) { + /* error */ +} +.Ed +.Pp +Third step: verify the created ECDSA signature using +.Fn ECDSA_do_verify +.Pp +.Dl ret = ECDSA_do_verify(digest, SHA384_DIGEST_LENGTH, sig, eckey); +.Pp +or using +.Fn ECDSA_verify +.Pp +.Dl ret = ECDSA_verify(0, digest, SHA384_DIGEST_LENGTH, buffer, buf_len, eckey); +.Pp +and finally evaluate the return value: +.Bd -literal -offset indent +if (ret == -1) { + /* error */ +} else if (ret == 0) { + /* incorrect signature */ +} else { + /* ret == 1 */ + /* signature ok */ +} +.Ed +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr DSA_new 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_KEY_METHOD_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_KEY_set_ex_data 3 , +.Xr EVP_DigestSignInit 3 , +.Xr EVP_DigestVerifyInit 3 , +.Xr RSA_new 3 +.Sh STANDARDS +ANSI X9.62, US Federal Information Processing Standard FIPS 186-5 +(Digital Signature Standard, DSS) +.Sh HISTORY +.Fn ECDSA_SIG_new , +.Fn ECDSA_SIG_free , +.Fn i2d_ECDSA_SIG , +.Fn d2i_ECDSA_SIG , +.Fn ECDSA_size , +.Fn ECDSA_sign , +.Fn ECDSA_verify , +.Fn ECDSA_do_sign , +and +.Fn ECDSA_do_verify +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn ECDSA_SIG_get0 +and +.Fn ECDSA_SIG_set0 +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +.Fn ECDSA_SIG_get0_r +and +.Fn ECDSA_SIG_get0_s +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.1 . +.Sh AUTHORS +.An Nils Larsch +for the OpenSSL project. diff --git a/static/openbsd/man3/EC_GROUP_check.3 b/static/openbsd/man3/EC_GROUP_check.3 new file mode 100644 index 00000000..146c3d25 --- /dev/null +++ b/static/openbsd/man3/EC_GROUP_check.3 @@ -0,0 +1,160 @@ +.\" $OpenBSD: EC_GROUP_check.3,v 1.6 2025/07/04 05:16:56 jsg Exp $ +.\" +.\" Copyright (c) 2025 Theo Buehler +.\" +.\" 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: July 4 2025 $ +.Dt EC_GROUP_CHECK 3 +.Os +.Sh NAME +.Nm EC_GROUP_check_discriminant , +.Nm EC_GROUP_check +.Nd partially check validity of +.Vt EC_GROUP +objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.In openssl/ec.h +.Pp +Deprecated: +.Pp +.Ft int +.Fo EC_GROUP_check_discriminant +.Fa "const EC_GROUP *group" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_check +.Fa "const EC_GROUP *group" +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +These functions are deprecated. +Only standardized curves built into the library should be used, see +.Xr EC_GROUP_new_by_curve_name 3 . +Builtin curves went through far more thorough checking than +the minimal, incomplete tests performed by these functions. +.Pp +These functions have an optional +.Fa ctx +argument which is used to avoid the cost of repeated allocation of +auxiliary +.Vt BIGNUM +objects. +.Pp +.Fn EC_GROUP_check_discriminant +can be called after +.Xr EC_GROUP_new_curve_GFp 3 +to verify that +.Fa group Ns 's +parameters have non-zero discriminant 4a^3 + 27b^2 modulo p. +Assuming that +.Fa p +is a prime number larger than three +this implies that the Weierstrass equation defines an elliptic curve. +.Pp +.Fn EC_GROUP_check +partially verifies that +.Fa group +represents an elliptic curve and that +.Fa generator +is a point on the curve whose order divides +.Fa order . +It checks with +.Fn EC_GROUP_check_discriminant +that the discriminant is non-zero +and then verifies that that +.Fa order +is non-zero and that the product +.Fa generator No * Fa order +is the point at infinity. +This implies that the +.Fa order +set on +.Fa group +is an integer multiple of the +.Fa generator Ns 's +order. +The verification that +.Fa p +is a prime +and that +.Fa order +is equal to the +.Fa generator Ns 's +order are skipped because they are too expensive. +.Sh RETURN VALUES +.Fn EC_GROUP_check_discriminant +returns 1 on success and 0 on failure. +Failure modes include that the discriminant is zero modulo +.Fa p +and memory allocation failure. +.Pp +.Fn EC_GROUP_check +returns 1 on success and 0 on failure. +.Sh ERRORS +Diagnostics for +.Fn EC_GROUP_check +that can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 +include: +.Bl -tag -width Ds +.It Dv EC_R_DISCRIMINANT_IS_ZERO Qq "discriminant is zero" +.Fn EC_GROUP_check_discriminant +failed because the discriminant is zero or for some other reason. +.It Dv EC_R_UNDEFINED_GENERATOR Qq "undefined generator" +no generator is set on +.Fa group , +for example because a call to +.Xr EC_GROUP_set_generator 3 +is missing. +.It Dv EC_R_POINT_IS_NOT_ON_CURVE Qq "point is not on curve" +a generator is set, but it is not a point on the curve represented by +.Fa group . +.It Dv EC_R_UNDEFINED_ORDER Qq "undefined order" +the +.Fa order +set on +.Fa group +is zero. +.It Dv EC_R_INVALID_GROUP_ORDER Qq "invalid group order" +.Fa generator No * Fa order +is not the point at infinity. +.El +.Sh SEE ALSO +.Xr BN_CTX_new 3 , +.Xr BN_is_zero 3 , +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr EC_GROUP_get_curve_name 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_GROUP_new_curve_GFp 3 , +.Xr EC_KEY_METHOD_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_get_affine_coordinates 3 , +.Xr EC_POINT_new 3 , +.Xr EC_POINT_point2oct 3 , +.Xr ECDH_compute_key 3 , +.Xr ECDSA_SIG_new 3 +.Sh HISTORY +.Fn EC_GROUP_check +and +.Fn EC_GROUP_check_discriminant +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/EC_GROUP_get_curve_name.3 b/static/openbsd/man3/EC_GROUP_get_curve_name.3 new file mode 100644 index 00000000..940aa3c1 --- /dev/null +++ b/static/openbsd/man3/EC_GROUP_get_curve_name.3 @@ -0,0 +1,266 @@ +.\" $OpenBSD: EC_GROUP_get_curve_name.3,v 1.4 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2025 Theo Buehler +.\" +.\" 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: June 13 2025 $ +.Dt EC_GROUP_GET_CURVE_NAME 3 +.Os +.Sh NAME +.Nm EC_GROUP_get_curve_name , +.Nm EC_GROUP_set_curve_name , +.Nm EC_GROUP_get_asn1_flag , +.Nm EC_GROUP_set_asn1_flag , +.Nm EC_GROUP_get0_seed , +.Nm EC_GROUP_get_seed_len , +.Nm EC_GROUP_set_seed , +.Nm EC_GROUP_get_point_conversion_form , +.Nm EC_GROUP_set_point_conversion_form , +.Nm EC_GROUP_get_basis_type +.Nd configure and inspect details of the ASN.1 encoding of +.Vt EC_GROUP +and related objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ec.h +.Ft int +.Fo EC_GROUP_get_curve_name +.Fa "const EC_GROUP *group" +.Fc +.Ft void +.Fo EC_GROUP_set_curve_name +.Fa "EC_GROUP *group" +.Fa "int nid" +.Fc +.Ft int +.Fo EC_GROUP_get_asn1_flag +.Fa "const EC_GROUP *group" +.Fc +.Ft void +.Fo EC_GROUP_set_asn1_flag +.Fa "EC_GROUP *group" +.Fa "int flag" +.Fc +.Ft unsigned char * +.Fo EC_GROUP_get0_seed +.Fa "const EC_GROUP *group" +.Fc +.Ft size_t +.Fo EC_GROUP_get_seed_len +.Fa "const EC_GROUP *group" +.Fc +.Ft size_t +.Fo EC_GROUP_set_seed +.Fa "EC_GROUP *group" +.Fa "const unsigned char *seed" +.Fa "size_t len" +.Fc +.Bd -literal +typedef enum { + POINT_CONVERSION_COMPRESSED = 2, + POINT_CONVERSION_UNCOMPRESSED = 4, + POINT_CONVERSION_HYBRID = 6 +} point_conversion_form_t; + +.Ed +.Ft point_conversion_form_t +.Fo EC_GROUP_get_point_conversion_form +.Fa "const EC_GROUP *group" +.Fc +.Ft void +.Fo EC_GROUP_set_point_conversion_form +.Fa "EC_GROUP *group" +.Fa "point_conversion_form_t form" +.Fc +.Pp +Deprecated: +.Pp +.Ft int +.Fo EC_GROUP_get_basis_type +.Fa "const EC_GROUP *group" +.Fc +.Sh DESCRIPTION +The functions in this manual affect or allow the inspection of +the details of the ASN.1 encoding produced by the +.Xr i2d_ECPKParameters 3 +family of functions. +Modern applications use named curves and uncompressed point encoding, +which are the default for +.Xr EC_GROUP_new_by_curve_name 3 . +.Pp +In this library, Elliptic curve parameters are either encoded as a +.Em named curve , +using an ASN.1 Object Identifier (OID) to refer to +standardized parameters that need to be built into the library, +or using +.Em explicit curve parameters +where the field, the curve equation, the base point's coordinates +and other data are encoded explicitly. +The +.Em implicitly CA +variant is not supported. +.Pp +.Fn EC_GROUP_get_curve_name +gets the Numerical Identifier (NID) representation of the +ASN.1 Object Identifier used for the named curve encoding of +.Fa group . +.Fn EC_GROUP_set_curve_name +sets it to +.Fa nid . +.Pp +.Fn EC_GROUP_get_asn1_flag +retrieves the value of the +.Fa asn1_flag +member of +.Fa group . +If the bit corresponding to +.Dv OPENSSL_EC_NAMED_CURVE +is set, named curve encoding is used for +.Fa group , +otherwise explicit encoding is used. +.Fn EC_GROUP_set_asn1_flag +sets the +.Fa asn1_flag +member of group to +.Fa flag , +which should be either +.Dv OPENSSL_EC_NAMED_CURVE +to use named curve encoding or +.Dv OPENSSL_EC_EXPLICIT_CURVE +to use explicit encoding. +.Pp +The ASN.1 encoding of explicit curve parameters includes +an optional seed value for parameters generated verifiably at random. +If a seed value is set on +.Fa group , +.Fn EC_GROUP_get0_seed +returns a pointer to the internal byte string whose length is returned by +.Fn EC_GROUP_get_seed_len . +.Pp +.Fn EC_GROUP_set_seed +first clears any seed and length already stored in +.Fa group . +If +.Fa seed +is not +.Dv NULL +and +.Fa len +is not zero, it stores a copy of them in +.Fa group . +The +.Fa seed +should be a random byte string of +.Fa len +at least 20 bytes. +The seed can be unset by passing +.Dv NULL +as a +.Fa seed +and a +.Fa len +of zero. +The library does not perform any computation or validation with this seed, +it only includes it in its ASN.1 encoded parameters, +whether it contains a sensible value or not. +.Pp +Points on an elliptic curve, such as the generator or a public key, +can be encoded in compressed form, uncompressed form, +or in a hybrid form encompassing both, see +.Xr EC_POINT_point2oct 3 . +.Fn EC_GROUP_get_point_conversion_form +retrieves the encoding used for points on +.Fa group +and +.Fn EC_GROUP_set_point_conversion_form +sets it to +.Fa form . +.Pp +The deprecated +.Fn EC_GROUP_get_basis_type +only makes sense for curves over binary fields. +It is provided for compatibility only. +.Sh RETURN VALUES +.Fn EC_GROUP_get_curve_name +returns the NID to be used for named curve encoding of +.Fa group +or +.Dv NID_undef +if no NID is set. +.Pp +.Fn EC_GROUP_get_asn1_flag +returns the value most recently set by +.Fn EC_GROUP_set_asn1_flag +on +.Fa group . +.Pp +.Fn EC_GROUP_get0_seed +returns an internal pointer to the +.Fa seed +on +.Fa group +or +.Dv NULL +if none is set. +.Pp +.Fn EC_GROUP_get_seed_len +returns the byte length of the seed set on +.Fa group +or zero if none is set. +.Pp +.Fn EC_GROUP_set_seed +returns 0 on memory allocation failure. +It returns +.Fa len +on success unless +.Fa seed +is +.Dv NULL +or +.Fa len +is zero, in which case it returns 1. +.Pp +.Fn EC_GROUP_get_point_conversion_form +returns the point conversion form last set by +.Fn EC_GROUP_set_point_conversion_form +on +.Fa group . +.Pp +.Fn EC_GROUP_get_basis_type +always returns +.Dv NID_undef . +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr EC_GROUP_check 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_GROUP_new_curve_GFp 3 , +.Xr EC_KEY_METHOD_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_get_affine_coordinates 3 , +.Xr EC_POINT_new 3 , +.Xr EC_POINT_point2oct 3 , +.Xr ECDH_compute_key 3 , +.Xr ECDSA_SIG_new 3 , +.Xr OBJ_obj2nid 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Sh BUGS +Most of the setters cannot report errors and none of them perform proper +input validation and accept most of the values passed in. +This can result in invalid or nonsensical ASN.1 encoding produced by +.Xr i2d_ECPKParameters 3 +and related functions. diff --git a/static/openbsd/man3/EC_GROUP_new_by_curve_name.3 b/static/openbsd/man3/EC_GROUP_new_by_curve_name.3 new file mode 100644 index 00000000..e0536587 --- /dev/null +++ b/static/openbsd/man3/EC_GROUP_new_by_curve_name.3 @@ -0,0 +1,311 @@ +.\" $OpenBSD: EC_GROUP_new_by_curve_name.3,v 1.4 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2024, 2025 Theo Buehler +.\" +.\" 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: June 13 2025 $ +.Dt EC_GROUP_NEW_BY_CURVE_NAME 3 +.Os +.Sh NAME +.Nm EC_GROUP_new_by_curve_name , +.Nm EC_GROUP_free , +.Nm EC_GROUP_dup , +.Nm EC_GROUP_cmp , +.Nm EC_get_builtin_curves , +.Nm EC_curve_nid2nist , +.Nm EC_curve_nist2nid +.Nd instantiate named curves built into libcrypto +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.In openssl/ec.h +.In openssl/objects.h +.Ft EC_GROUP * +.Fo EC_GROUP_new_by_curve_name +.Fa "int nid" +.Fc +.Ft void +.Fo EC_GROUP_free +.Fa "EC_GROUP *group" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_dup +.Fa "const EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_cmp +.Fa "const EC_GROUP *group1" +.Fa "const EC_GROUP *group2" +.Fa "BN_CTX *ctx" +.Fc +.Bd -literal +typedef struct { + int nid; + const char *comment; +} EC_builtin_curve; + +.Ed +.Ft size_t +.Fo EC_get_builtin_curves +.Fa "EC_builtin_curve *curves" +.Fa "size_t ncurves" +.Fc +.Ft int +.Fo EC_curve_nist2nid +.Fa "const char *name" +.Fc +.Ft const char * +.Fo EC_curve_nid2nist +.Fa "int nid" +.Fc +.Sh DESCRIPTION +Most elliptic curves used in cryptographic protocols have a +standardized representation as a +.Em named curve , +where an ASN.1 Object Identifier (OID) is used instead of +detailed domain parameters. +This OID is represented internally by a Numerical Identifier (NID), +and the parameters themselves must be built into the library. +In the EC library the +.Em curve name +refers to this NID. +.Pp +.Fn EC_GROUP_new_by_curve_name +returns a new +.Vt EC_GROUP +object representing the named curve corresponding to +.Fa nid , +using the parameters built into the library. +It is equivalent to passing the appropriate parameters to +.Xr EC_GROUP_new_curve_GFp 3 , +.Xr EC_GROUP_set_curve_name 3 , +.Xr EC_GROUP_set_generator 3 +and +.Xr EC_GROUP_set_seed 3 . +.Pp +.Fn EC_GROUP_free +frees +.Fa group +and all the memory associated with it. +If +.Fa group +is +.Dv NULL , +no action occurs. +.Pp +.Fn EC_GROUP_dup +creates a deep copy of +.Fa group . +.Pp +.Fn EC_GROUP_cmp +is intended to determine whether +.Fa group1 +and +.Fa group2 +represent the same elliptic curve, +making use of the optional +.Fa ctx . +If the curve name is set on both curves, they are compared as integers, +then the prime field, +the coefficients of the Weierstrass equation, +the generators, their order and their cofactors are compared +using +.Xr BN_cmp 3 +or +.Xr EC_POINT_cmp 3 , +respectively. +.Pp +.Fn EC_get_builtin_curves +returns the number of builtin curves. +If +.Fa curves +is +.Dv NULL +or +.Fa ncurves +is zero, it performs no other action. +Otherwise, after reducing +.Fa ncurves +to the number of builtin curves if necessary, +it copies the +.Fa nid +and a pointer to the +.Fa comment +of the first +.Fa ncurves +built-in curves to the array of +.Vt EC_builtin_curve +objects pointed to by +.Fa curves +and leaves the remainder of the array uninitialized. +.Pp +Some curves can be identified by their NIST name +in addition to the numerical identifier (NID). +.Fn EC_curve_nist2nid +and +.Fn EC_curve_nid2nist +translate between the two. +The builtin NIST curves over a prime field are: +.Pp +.Bl -column "NIST name" NID_X9_62_prime256v1 "deprecated in SP800-186" -compact +.It No NIST Fa name Ta Em ASN.1 NID Ta Em notes +.It Qq P-224 Ta Dv NID_secp224r1 Ta +.It Qq P-256 Ta Dv NID_X9_62_prime256v1 Ta also known as secp256r1 +.It Qq P-384 Ta Dv NID_secp384r1 Ta +.It Qq P-521 Ta Dv NID_secp521r1 Ta +.El +.Pp +.Fn EC_curve_nist2nid +and +.Fn EC_curve_nid2nist +also accept the binary curves defined in FIPS\& 186-4 +and deprecated in SP800-186, +as well as +.Qq P-192 +and +.Dv NID_X9_62_prime192v1 , +although all these no longer correspond to builtin curves in LibreSSL. +.Sh RETURN VALUES +.Fn EC_GROUP_new_by_curve_name +returns a newly allocated group or +.Dv NULL +if there is no built-in group with NID +.Fa nid , +or if memory allocation fails. +.Pp +.Fn EC_GROUP_dup +returns a newly allocated group or +.Dv NULL +if memory allocation fails. +.Pp +.Fn EC_GROUP_cmp +returns 1 if the groups are distinct, 0 if the groups are +considered identical and \-1 on memory allocation error. +.Pp +.Fn EC_get_builtin_curves +returns the number of builtin curves. +.Pp +.Fn EC_curve_nid2nist +returns a string constant containing the NIST name if +.Fa nid +identifies a NIST curve or +.Dv NULL +otherwise. +.Pp +.Fn EC_curve_nist2nid +returns the NID corresponding to the NIST curve +.Fa name , +or +.Dv NID_undef . +.Sh EXAMPLES +Print the list of builtin curves, their NIDs, their NIST name and +a comment describing each curve: +.Bd -literal +#include +#include +#include +#include + +#include + +int +main(void) +{ + EC_builtin_curve *curves; + size_t ncurves, i; + + if (pledge("stdio", NULL) == \-1) + err(1, "pledge"); + + ncurves = EC_get_builtin_curves(NULL, 0); + if ((curves = calloc(ncurves, sizeof(*curves))) == NULL) + err(1, NULL); + (void)EC_get_builtin_curves(curves, ncurves); + + printf("curve\etnid\etNIST\etcomment\en"); + for (i = 0; i < ncurves; i++) { + const char *nist_name = EC_curve_nid2nist(curves[i].nid); + + printf("%2zu\et%d\et%s\et%s\en", i, curves[i].nid, + nist_name != NULL ? nist_name : "", curves[i].comment); + } + + free(curves); + + return 0; +} +.Ed +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr EC_GROUP_check 3 , +.Xr EC_GROUP_get_curve_name 3 , +.Xr EC_GROUP_new_curve_GFp 3 , +.Xr EC_KEY_METHOD_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_get_affine_coordinates 3 , +.Xr EC_POINT_new 3 , +.Xr EC_POINT_point2oct 3 , +.Xr ECDH_compute_key 3 , +.Xr ECDSA_SIG_new 3 , +.Xr OBJ_nid2obj 3 +.Sh STANDARDS +.Rs +.%T SEC 1: Elliptic Curve Cryptography, Version 2.0 +.%U https://www.secg.org/sec1-v2.pdf +.%D May 21, 2009 +.Re +.Pp +.Rs +.%T SEC 2: Recommended Elliptic Curve Domain Parameters, Version 2.0 +.%U https://www.secg.org/sec2-v2.pdf +.%D Jan 27, 2010 +.Re +.Sh HISTORY +.Fn EC_GROUP_free +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Pp +.Fn EC_GROUP_new_by_curve_name , +.Fn EC_GROUP_cmp , +.Fn EC_GROUP_dup , +and +.Fn EC_get_builtin_curves +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn EC_curve_nid2nist +and +.Fn EC_curve_nist2nid +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 5.8 . +.Sh BUGS +.Fn EC_GROUP_cmp +compares the coefficients of the Weierstrass equation as +integers, not as elements of the prime field. +It also treats the generator as mandatory while it is generally +optional in the EC library. +Aspects of the ASN.1 encoding controlled by the functions in +.Xr EC_GROUP_get_asn1_flag 3 , +in particular seed, ASN.1 flag, and point conversion form, +are ignored in the comparison. +Group objects may therefore compare as equal and produce +completely different ASN.1 encodings via +.Xr i2d_ECPKParameters 3 +and related functions. +In fact, either of these encodings might be valid or not, +accepted or rejected by +.Xr d2i_ECPKParameters 3 , +or the encoding might fail on one or both of the group objects. diff --git a/static/openbsd/man3/EC_GROUP_new_curve_GFp.3 b/static/openbsd/man3/EC_GROUP_new_curve_GFp.3 new file mode 100644 index 00000000..bf586bcb --- /dev/null +++ b/static/openbsd/man3/EC_GROUP_new_curve_GFp.3 @@ -0,0 +1,463 @@ +.\" $OpenBSD: EC_GROUP_new_curve_GFp.3,v 1.6 2025/08/31 11:32:03 tb Exp $ +.\" +.\" Copyright (c) 2025 Theo Buehler +.\" +.\" 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: August 31 2025 $ +.Dt EC_GROUP_NEW_CURVE_GFP 3 +.Os +.Sh NAME +.Nm EC_GROUP_new_curve_GFp , +.Nm EC_GROUP_set_curve , +.Nm EC_GROUP_get_curve , +.Nm EC_GROUP_set_generator , +.Nm EC_GROUP_get0_generator , +.Nm EC_GROUP_get_degree , +.Nm EC_GROUP_get_order , +.Nm EC_GROUP_order_bits , +.Nm EC_GROUP_get_cofactor , +.Nm EC_GROUP_clear_free , +.Nm EC_GROUP_set_curve_GFp , +.Nm EC_GROUP_get_curve_GFp +.Nd define elliptic curves and retrieve information from them +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.In openssl/ec.h +.Ft EC_GROUP * +.Fo EC_GROUP_new_curve_GFp +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_set_curve +.Fa "EC_GROUP *group" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_curve +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *p" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_set_generator +.Fa "EC_GROUP *group" +.Fa "const EC_POINT *generator" +.Fa "const BIGNUM *order" +.Fa "const BIGNUM *cofactor" +.Fc +.Ft const EC_POINT * +.Fo EC_GROUP_get0_generator +.Fa "const EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_get_degree +.Fa "const EC_GROUP *" +.Fc +.Ft int +.Fo EC_GROUP_get_order +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *order" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_order_bits +.Fa "const EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_get_cofactor +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *cofactor" +.Fa "BN_CTX *ctx" +.Fc +.Pp +Deprecated: +.Pp +.Ft void +.Fo EC_GROUP_clear_free +.Fa "EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_set_curve_GFp +.Fa "EC_GROUP *group" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_curve_GFp +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *p" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +With the exception of the getters +the functions in this manual should not be used. +Use +.Xr EC_GROUP_new_by_curve_name 3 +instead. +.Pp +The EC library uses +.Vt EC_GROUP +objects to represent +elliptic curves in Weierstrass form. +These curves are defined over the prime field of order +.Fa p +via the Weierstrass equation +.Pp +.Dl y^2 = x^3 + ax + b +.Pp +where +.Fa a +and +.Fa b +are such that the discriminant 4a^3 - 27b^2 is non-zero. +They consist of +.Em affine points , +which are pairs of field elements (x, y) satisfying +the Weierstrass equation, and an extra +.Em point at infinity . +.Pp +The points on an elliptic curve form a group. +Cryptographic applications usually depend on the choice of a +.Fa generator +whose multiples form a cyclic subgroup of a certain +.Fa order . +By Lagrange's theorem, the number of points on the elliptic curve is +the product of +.Fa order +and another integer called the +.Fa cofactor . +Hasse's theorem is the inequality +.Pp +.Dl | Ns Fa order No * Fa cofactor No - (p + 1)| <= 2 sqrt(p) +.Pp +which implies an upper bound on +.Fa order +in terms of +.Fa p +and allows the computation of +.Fa cofactor +provided that +.Fa order +is large enough. +.Pp +.Fn EC_GROUP_new_curve_GFp +instantiates a new +.Vt EC_GROUP +object over the prime field of size +.Fa p +with Weierstrass equation given by the coefficients +.Fa a +and +.Fa b . +The optional +.Fa ctx +is used to transform the other arguments into internal representation. +It is the caller's responsibility to ensure that +.Fa p +is a prime number greater than three and that +the discriminant is non-zero. +This can be done with +.Xr EC_GROUP_check_discriminant 3 +or as part of +.Xr EC_GROUP_check 3 +after +.Fn EC_GROUP_set_generator . +.Pp +.Fn EC_GROUP_set_curve +sets the curve parameters of +.Fa group +to +.Fa p , +.Fa a , +.Fa b +using the optional +.Fa ctx +and the comments in +.Fn EC_GROUP_new_curve_GFp +apply. +Existing +.Fa generator , +.Fa order , +or +.Fa cofactor +on +.Fa group +are left unmodified and become most likely invalid. +They must therefore be set to legitimate values using +.Fn EC_GROUP_set_generator . +.Pp +.Fn EC_GROUP_get_curve +copies the curve parameters of +.Fa group +into the caller-owned +.Fa p , +.Fa a , +and +.Fa b , +possibly making use of the +.Fa ctx +for conversion from internal representations. +Except for +.Fa group , +all arguments are optional. +.Pp +.Fn EC_GROUP_set_generator +performs sanity checks based on Hasse's theorem +and copies +.Fa generator , +.Fa order +and the optional +.Fa cofactor +into +.Fa group , +replacing all existing entries. +It is the caller's responsibility to ensure that +.Fa generator +is a point on the curve and that +.Fa order +is its order, +which can partially be accomplished with a subsequent call to +.Xr EC_GROUP_check 3 . +If +.Fa cofactor +is +.Dv NULL , +it can be computed on curves of cryptographic interest, +in which case +.Fa cofactor +is set to the computed value, otherwise it is set to zero. +.Pp +.Fn EC_GROUP_get0_generator +returns an internal pointer to the +.Fa group Ns 's +.Fa generator , +which may be +.Dv NULL +if no generator was set. +.Pp +.Fn EC_GROUP_get_degree +returns the bit length of the prime +.Fa p +set on +.Fa group . +.Pp +.Fn EC_GROUP_get_order +copies the value of the +.Fa group Ns 's +.Fa order +into the caller-owned +.Fa order , +returning failure if the +.Fa group Ns 's +.Fa order +is zero. +The +.Fa ctx +argument is ignored. +.Pp +.Fn EC_GROUP_order_bits +returns the number of bits in the +.Fa group Ns 's +.Fa order , +which is the result of calling +.Xr BN_num_bits 3 +on +.Fa order . +Unlike +.Fn EC_GROUP_get_order , +it does not fail if +.Fa order +is zero. +.Pp +.Fn EC_GROUP_get_cofactor +copies the value of the +.Fa group Ns 's +.Fa cofactor +into the caller-owned +.Fa cofactor , +returning failure if the +.Fa group Ns 's +.Fa cofactor +is zero. +The +.Fa ctx +argument is ignored. +.Pp +The deprecated +.Fn EC_GROUP_clear_free +uses +.Xr explicit_bzero 3 +and +.Xr freezero 3 +to clear and free all data associated with +.Fa group . +If +.Fa group +is +.Dv NULL , +no action occurs. +Since there is no secret data in +.Fa group , +this API is useless. +In LibreSSL, +.Xr EC_GROUP_free 3 +and +.Fn EC_GROUP_clear_free +behave identically. +.Pp +.Fn EC_GROUP_set_curve_GFp +and +.Fn EC_GROUP_get_curve_GFp +are deprecated aliases for +.Fn EC_GROUP_set_curve +and +.Fn EC_GROUP_get_curve , +respectively. +.Sh RETURN VALUES +.Fn EC_GROUP_new_curve_GFp +returns a newly allocated group or +.Dv NULL +if memory allocation fails, +or if some minimal sanity checks on +.Fa p , +.Fa a , +and +.Fa b +fail. +.Pp +.Fn EC_GROUP_set_curve +and +.Fn EC_GROUP_set_curve_GFp +return 1 on success and 0 on failure. +Failure conditions include that +.Fa p +is smaller than or equal to three, or even, or +memory allocation failure. +.Pp +.Fn EC_GROUP_get_curve +and +.Fn EC_GROUP_get_curve_GFp +return 1 on success and 0 on memory allocation failure. +.Pp +.Fn EC_GROUP_set_generator +returns 1 on success and 0 on memory allocation failure, or if +.Fa order +or +.Fa cofactor +are larger than Hasse's theorem allows. +.Pp +.Fn EC_GROUP_get0_generator +returns an internal pointer to the +.Fa generator +or +.Dv NULL +if none was set on +.Fa group . +.Pp +.Fn EC_GROUP_get_order +returns 1 on success or 0 on memory allocation failure or if the +.Fa order +is zero. +.Pp +.Fn EC_GROUP_get_cofactor +returns 1 on success or 0 on memory allocation failure or if the +.Fa cofactor +is zero. +.Pp +.Fn EC_GROUP_get_degree , +and +.Fn EC_GROUP_order_bits +return the number of bits in the +.Fa group Ns 's +.Fa p , +and +.Fa order , +respectively. +.Sh SEE ALSO +.Xr BN_new 3 , +.Xr BN_num_bits 3 , +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr EC_GROUP_check 3 , +.Xr EC_GROUP_get_curve_name 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_KEY_METHOD_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_get_affine_coordinates 3 , +.Xr EC_POINT_new 3 , +.Xr EC_POINT_point2oct 3 , +.Xr ECDH_compute_key 3 , +.Xr ECDSA_SIG_new 3 +.Sh STANDARDS +.Rs +.%T SEC 1: Elliptic Curve Cryptography, Version 2.0 +.%U https://www.secg.org/sec1-v2.pdf +.%D May 21, 2009 +.Re +.Pp +.Rs +.%T SEC 2: Recommended Elliptic Curve Domain Parameters, Version 2.0 +.%U https://www.secg.org/sec2-v2.pdf +.%D Jan 27, 2010 +.Re +.Sh HISTORY +.Fn EC_GROUP_new_curve_GFp , +.Fn EC_GROUP_clear_free , +.Fn EC_GROUP_set_curve_GFp , +.Fn EC_GROUP_get_curve_GFp , +.Fn EC_GROUP_set_generator , +.Fn EC_GROUP_get0_generator , +.Fn EC_GROUP_get_order , +and +.Fn EC_GROUP_get_cofactor +first appeared in OpenSSL 0.9.7 and +have been available since +.Ox 3.2 . +.Pp +.Fn EC_GROUP_get_degree +first appeared in OpenSSL 0.9.8 and +has been available since +.Ox 4.5 . +.Pp +.Fn EC_GROUP_set_curve , +.Fn EC_GROUP_get_curve , +and +.Fn EC_GROUP_order_bits +first appeared in OpenSSL 1.1.1 and +have been available since +.Ox 7.0 +.Sh BUGS +Too many. +The API is unergonomic and the design is very poor even by +OpenSSL's standards. +Naming is inconsistent, especially in regard to the _GFp suffix +and the _get_ infix. +Function signatures are inconsistent. +In particular, functions that should have a +.Vt BN_CTX +argument don't have one and functions that don't need it have one. diff --git a/static/openbsd/man3/EC_KEY_METHOD_new.3 b/static/openbsd/man3/EC_KEY_METHOD_new.3 new file mode 100644 index 00000000..a0ab6bac --- /dev/null +++ b/static/openbsd/man3/EC_KEY_METHOD_new.3 @@ -0,0 +1,330 @@ +.\" $OpenBSD: EC_KEY_METHOD_new.3,v 1.6 2025/06/08 22:40:29 schwarze Exp $ +.\" Copyright (c) 2019 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 $Mdocdate: June 8 2025 $ +.Dt EC_KEY_METHOD_NEW 3 +.Os +.Sh NAME +.Nm EC_KEY_METHOD_new , +.Nm EC_KEY_METHOD_free , +.Nm EC_KEY_METHOD_set_init , +.Nm EC_KEY_METHOD_get_init , +.Nm EC_KEY_METHOD_set_sign , +.Nm EC_KEY_METHOD_get_sign , +.Nm EC_KEY_METHOD_set_verify , +.Nm EC_KEY_METHOD_get_verify , +.Nm EC_KEY_METHOD_set_keygen , +.Nm EC_KEY_METHOD_get_keygen , +.Nm EC_KEY_METHOD_set_compute_key , +.Nm EC_KEY_METHOD_get_compute_key , +.Nm EC_KEY_OpenSSL , +.Nm EC_KEY_set_default_method , +.Nm EC_KEY_get_default_method , +.Nm EC_KEY_new_method , +.Nm EC_KEY_set_method , +.Nm EC_KEY_get_method +.Nd custom EC_KEY implementations +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ec.h +.Ft EC_KEY_METHOD * +.Fo EC_KEY_METHOD_new +.Fa "const EC_KEY_METHOD *meth" +.Fc +.Ft void +.Fo EC_KEY_METHOD_free +.Fa "EC_KEY_METHOD *meth" +.Fc +.Ft void +.Fo EC_KEY_METHOD_set_init +.Fa "EC_KEY_METHOD *meth" +.Fa "int (*init)(EC_KEY *key)" +.Fa "void (*finish)(EC_KEY *key)" +.Fa "int (*copy)(EC_KEY *dest, const EC_KEY *src)" +.Fa "int (*set_group)(EC_KEY *key, const EC_GROUP *grp)" +.Fa "int (*set_private)(EC_KEY *key, const BIGNUM *priv_key)" +.Fa "int (*set_public)(EC_KEY *key, const EC_POINT *pub_key)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_get_init +.Fa "const EC_KEY_METHOD *meth" +.Fa "int (**pinit)(EC_KEY *key)" +.Fa "void (**pfinish)(EC_KEY *key)" +.Fa "int (**pcopy)(EC_KEY *dest, const EC_KEY *src)" +.Fa "int (**pset_group)(EC_KEY *key, const EC_GROUP *grp)" +.Fa "int (**pset_private)(EC_KEY *key, const BIGNUM *priv_key)" +.Fa "int (**pset_public)(EC_KEY *key, const EC_POINT *pub_key)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_set_sign +.Fa "EC_KEY_METHOD *meth" +.Fa "int (*sign)(int type, const unsigned char *dgst, int dgstlen,\ + unsigned char *sig, unsigned int *siglen,\ + const BIGNUM *kinv, const BIGNUM *r, EC_KEY *eckey)" +.Fa "int (*sign_setup)(EC_KEY *eckey, BN_CTX *ctx,\ + BIGNUM **kinv, BIGNUM **rp)" +.Fa "ECDSA_SIG *(*sign_sig)(const unsigned char *dgst, int dgstlen,\ + const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_get_sign +.Fa "const EC_KEY_METHOD *meth" +.Fa "int (**psign)(int type, const unsigned char *dgst, int dgstlen,\ + unsigned char *sig, unsigned int *siglen,\ + const BIGNUM *kinv, const BIGNUM *r, EC_KEY *eckey)" +.Fa "int (**psign_setup)(EC_KEY *eckey, BN_CTX *ctx,\ + BIGNUM **kinv, BIGNUM **rp)" +.Fa "ECDSA_SIG *(**psign_sig)(const unsigned char *dgst, int dgstlen,\ + const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_set_verify +.Fa "EC_KEY_METHOD *meth" +.Fa "int (*verify)(int type, const unsigned char *dgst, int dgst_len,\ + const unsigned char *sigbuf, int sig_len, EC_KEY *eckey)" +.Fa "int (*verify_sig)(const unsigned char *dgst, int dgst_len,\ + const ECDSA_SIG *sig, EC_KEY *eckey)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_get_verify +.Fa "const EC_KEY_METHOD *meth" +.Fa "int (**pverify)(int type, const unsigned char *dgst, int dgst_len,\ + const unsigned char *sigbuf, int sig_len, EC_KEY *eckey)" +.Fa "int (**pverify_sig)(const unsigned char *dgst, int dgst_len,\ + const ECDSA_SIG *sig, EC_KEY *eckey)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_set_keygen +.Fa "EC_KEY_METHOD *meth" +.Fa "int (*keygen)(EC_KEY *key)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_get_keygen +.Fa "const EC_KEY_METHOD *meth" +.Fa "int (**pkeygen)(EC_KEY *key)" +.Fc +.Ft void +.Fo EC_KEY_METHOD_set_compute_key +.Fa "EC_KEY_METHOD *meth" +.Fa "int (*ckey)(void *out, size_t outlen,\ + const EC_POINT *pub_key, EC_KEY *ecdh,\ + void *(*KDF) (const void *in, size_t inlen, void *out, size_t *outlen))" +.Fc +.Ft void +.Fo EC_KEY_METHOD_get_compute_key +.Fa "const EC_KEY_METHOD *meth" +.Fa "int (**pck)(void *out, size_t outlen,\ + const EC_POINT *pub_key, EC_KEY *ecdh,\ + void *(*KDF) (const void *in, size_t inlen, void *out, size_t *outlen))" +.Fc +.Ft const EC_KEY_METHOD * +.Fn EC_KEY_OpenSSL void +.Ft void +.Fo EC_KEY_set_default_method +.Fa "const EC_KEY_METHOD *meth" +.Fc +.Ft const EC_KEY_METHOD * +.Fn EC_KEY_get_default_method void +.Ft EC_KEY * +.Fo EC_KEY_new_method +.Fa "ENGINE *engine" +.Fc +.Ft int +.Fo EC_KEY_set_method +.Fa "EC_KEY *key" +.Fa "const EC_KEY_METHOD *meth" +.Fc +.Ft const EC_KEY_METHOD * +.Fo EC_KEY_get_method +.Fa "const EC_KEY *key" +.Fc +.Sh DESCRIPTION +An +.Vt EC_KEY_METHOD +object holds function pointers used for +.Vt EC_KEY +operations. +.Pp +.Fn EC_KEY_METHOD_new +creates a shallow copy of +.Fa meth , +or an empty +.Vt EC_KEY_METHOD +object if +.Fa meth +is +.Dv NULL . +.Pp +.Fn EC_KEY_METHOD_free +frees +.Fa meth . +If +.Fa meth +is +.Dv NULL +or the return value of +.Fn EC_KEY_OpenSSL , +no action occurs. +.Pp +.Fn EC_KEY_METHOD_set_init +and +.Fn EC_KEY_METHOD_get_init +set and retrieve optional callback functions called at the following places: +.Pp +.Bl -tag -width set_private -compact +.It Fa init +at the end of +.Fn EC_KEY_new_method +and +.Fn EC_KEY_set_method +.It Fa finish +at the beginning of +.Xr EC_KEY_free 3 , +.Xr EC_KEY_copy 3 , +and +.Fn EC_KEY_set_method +.It Fa copy +at the end of +.Xr EC_KEY_copy 3 +.It Fa set_group +at the end of +.Xr EC_KEY_set_group 3 +and +.Xr EC_KEY_new_by_curve_name 3 +.It Fa set_private +at the beginning of +.Xr EC_KEY_set_private_key 3 +.It Fa set_public +at the beginning of +.Xr EC_KEY_set_public_key 3 +.El +.Pp +If any of these callbacks returns 0, the calling function fails. +By default, all these callbacks are +.Dv NULL . +Arguments of +.Fn EC_KEY_METHOD_get_init +can be set to +.Dv NULL +to selectively retrieve callback function pointers. +.Pp +.Fn EC_KEY_METHOD_set_sign +and +.Fn EC_KEY_METHOD_get_sign +set and retrieve the functions implementing +.Xr ECDSA_sign 3 +and +.Xr ECDSA_do_sign 3 . +.Pp +.Fn EC_KEY_METHOD_set_verify +and +.Fn EC_KEY_METHOD_get_verify +set and retrieve the functions implementing +.Xr ECDSA_verify 3 +and +.Xr ECDSA_do_verify 3 . +.Pp +.Fn EC_KEY_METHOD_set_keygen +and +.Fn EC_KEY_METHOD_get_keygen +set and retrieve the function implementing +.Xr EC_KEY_generate_key 3 . +.Pp +.Fn EC_KEY_METHOD_set_compute_key +and +.Fn EC_KEY_METHOD_get_compute_key +set and retrieve the function implementing +.Xr ECDH_compute_key 3 . +.Pp +.Fn EC_KEY_set_default_method +chooses the +.Fa meth +to be used for the creation of new +.Vt EC_KEY +objects by future invocations of +.Fn EC_KEY_new_method , +or reverts to the default implementation if +.Fa meth +is +.Dv NULL . +.Pp +.Fn EC_KEY_new_method +creates and initializes a new +.Vt EC_KEY +object using the +.Vt EC_KEY_METHOD +set with +.Fn EC_KEY_set_default_method . +The +.Fa ENGINE *engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +.Fn EC_KEY_set_method +dissociates the +.Fa key +from the +.Vt ENGINE +it is using, if any, and causes it to use +.Fa meth +in the future. +.Sh RETURN VALUES +.Fn EC_KEY_METHOD_new +returns the newly allocated +.Vt EC_KEY_METHOD +object or +.Dv NULL +if an error occurs. +.Pp +.Fn EC_KEY_OpenSSL +returns a static object representing the default EC_KEY implementation. +.Pp +.Fn EC_KEY_get_default_method +returns the +.Vt EC_KEY_METHOD +that +.Fn EC_KEY_new_method +will use for the creation of new +.Vt EC_KEY +objects in the future. +.Pp +.Fn EC_KEY_new_method +returns the newly allocated +.Vt EC_KEY +object or NULL if an error occurs. +.Pp +.Fn EC_KEY_set_method +returns 1 for success or 0 for failure. +.Pp +.Fn EC_KEY_get_method +returns the EC_KEY implementation used by the given +.Fa key . +.Sh SEE ALSO +.Xr crypto 3 , +.Xr EC_GROUP_check 3 , +.Xr EC_GROUP_get_curve_name 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_GROUP_new_curve_GFp 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_get_affine_coordinates 3 , +.Xr EC_POINT_new 3 , +.Xr EC_POINT_point2oct 3 , +.Xr ECDSA_sign 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 6.5 . diff --git a/static/openbsd/man3/EC_KEY_new.3 b/static/openbsd/man3/EC_KEY_new.3 new file mode 100644 index 00000000..41ebbbe8 --- /dev/null +++ b/static/openbsd/man3/EC_KEY_new.3 @@ -0,0 +1,536 @@ +.\" $OpenBSD: EC_KEY_new.3,v 1.23 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 3aef36ff Jan 5 13:06:03 2016 -0500 +.\" partial merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2013, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EC_KEY_NEW 3 +.Os +.Sh NAME +.Nm EC_KEY_new , +.Nm EC_KEY_get_flags , +.Nm EC_KEY_set_flags , +.Nm EC_KEY_clear_flags , +.Nm EC_KEY_new_by_curve_name , +.Nm EC_KEY_free , +.Nm EC_KEY_copy , +.Nm EC_KEY_dup , +.Nm EC_KEY_up_ref , +.Nm EC_KEY_get0_group , +.Nm EC_KEY_set_group , +.Nm EC_KEY_get0_private_key , +.Nm EC_KEY_set_private_key , +.Nm EC_KEY_get0_public_key , +.Nm EC_KEY_set_public_key , +.Nm EC_KEY_get_enc_flags , +.Nm EC_KEY_set_enc_flags , +.Nm EC_KEY_get_conv_form , +.Nm EC_KEY_set_conv_form , +.Nm EC_KEY_set_asn1_flag , +.Nm EC_KEY_precompute_mult , +.Nm EC_KEY_generate_key , +.Nm EC_KEY_check_key , +.Nm EC_KEY_set_public_key_affine_coordinates , +.Nm EC_KEY_print , +.Nm EC_KEY_print_fp +.Nd create, destroy and manipulate EC_KEY objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ec.h +.In openssl/bn.h +.Ft EC_KEY * +.Fn EC_KEY_new void +.Ft int +.Fo EC_KEY_get_flags +.Fa "const EC_KEY *key" +.Fc +.Ft void +.Fo EC_KEY_set_flags +.Fa "EC_KEY *key" +.Fa "int flags" +.Fc +.Ft void +.Fo EC_KEY_clear_flags +.Fa "EC_KEY *key" +.Fa "int flags" +.Fc +.Ft EC_KEY * +.Fo EC_KEY_new_by_curve_name +.Fa "int nid" +.Fc +.Ft void +.Fo EC_KEY_free +.Fa "EC_KEY *key" +.Fc +.Ft EC_KEY * +.Fo EC_KEY_copy +.Fa "EC_KEY *dst" +.Fa "const EC_KEY *src" +.Fc +.Ft EC_KEY * +.Fo EC_KEY_dup +.Fa "const EC_KEY *src" +.Fc +.Ft int +.Fo EC_KEY_up_ref +.Fa "EC_KEY *key" +.Fc +.Ft const EC_GROUP * +.Fo EC_KEY_get0_group +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_group +.Fa "EC_KEY *key" +.Fa "const EC_GROUP *group" +.Fc +.Ft const BIGNUM * +.Fo EC_KEY_get0_private_key +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_private_key +.Fa "EC_KEY *key" +.Fa "const BIGNUM *prv" +.Fc +.Ft const EC_POINT * +.Fo EC_KEY_get0_public_key +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_public_key +.Fa "EC_KEY *key" +.Fa "const EC_POINT *pub" +.Fc +.Ft unsigned int +.Fo EC_KEY_get_enc_flags +.Fa "const EC_KEY *key" +.Fc +.Ft void +.Fo EC_KEY_set_enc_flags +.Fa "EC_KEY *key" +.Fa "unsigned int flags" +.Fc +.Ft point_conversion_form_t +.Fo EC_KEY_get_conv_form +.Fa "const EC_KEY *key" +.Fc +.Ft void +.Fo EC_KEY_set_conv_form +.Fa "EC_KEY *key" +.Fa "point_conversion_form_t cform" +.Fc +.Ft void +.Fo EC_KEY_set_asn1_flag +.Fa "EC_KEY *key" +.Fa "int asn1_flag" +.Fc +.Ft int +.Fo EC_KEY_precompute_mult +.Fa "EC_KEY *key" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_KEY_generate_key +.Fa "EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_check_key +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_public_key_affine_coordinates +.Fa "EC_KEY *key" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fc +.Ft int +.Fo EC_KEY_print +.Fa "BIO *bp" +.Fa "const EC_KEY *key" +.Fa "int off" +.Fc +.Ft int +.Fo EC_KEY_print_fp +.Fa "FILE *fp" +.Fa "const EC_KEY *key" +.Fa "int off" +.Fc +.Sh DESCRIPTION +An +.Vt EC_KEY +represents a public key and (optionally) an associated private key. +The public key is a point on a curve represented by an +.Vt EC_POINT , +see +.Xr EC_POINT_new 3 . +The private key is simply a +.Vt BIGNUM , +see +.Xr BN_new 3 . +.Pp +A new +.Vt EC_KEY +(with no associated curve) can be constructed by calling +.Fn EC_KEY_new . +The reference count for the newly created +.Vt EC_KEY +is initially set to 1. +A curve can be associated with the +.Vt EC_KEY +by calling +.Fn EC_KEY_set_group . +.Pp +Alternatively a new +.Vt EC_KEY +can be constructed by calling +.Fn EC_KEY_new_by_curve_name +and supplying the +.Fa nid +of the associated curve. +Refer to +.Xr EC_GROUP_new_by_curve_name 3 +for a description of curve names. +This function simply wraps calls to +.Fn EC_KEY_new +and +.Fn EC_GROUP_new_by_curve_name . +.Pp +Calling +.Fn EC_KEY_free +decrements the reference count for the +.Vt EC_KEY +object and, if it has dropped to zero, then frees the memory associated +with it. +If +.Fa key +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn EC_KEY_copy +copies the contents of the +.Vt EC_KEY +in +.Fa src +into +.Fa dst . +.Pp +.Fn EC_KEY_dup +creates a new +.Vt EC_KEY +object and copies +.Fa src +into it. +.Pp +.Fn EC_KEY_up_ref +increments the reference count associated with the +.Vt EC_KEY +object. +.Pp +.Fn EC_KEY_generate_key +generates a new public and private key for the supplied +.Fa key +object. +.Fa key +must have an +.Vt EC_GROUP +object associated with it before calling this function. +The private key is a random integer (0 < priv_key < order, where order +is the order of the +.Vt EC_GROUP +object). +The public key is an +.Vt EC_POINT +on the curve calculated by multiplying the generator for the curve +by the private key. +.Pp +.Fn EC_KEY_check_key +performs various sanity checks on the +.Vt EC_KEY +object to confirm that it is valid. +.Pp +.Fn EC_KEY_set_public_key_affine_coordinates +sets the public key for +.Fa key +based on its affine coordinates, i.e. it constructs an +.Vt EC_POINT +object based on the supplied +.Fa x +and +.Fa y +values and sets the public key to be this +.Vt EC_POINT . +It also performs certain sanity checks on the key to confirm that +it is valid. +.Pp +The functions +.Fn EC_KEY_get0_group , +.Fn EC_KEY_set_group , +.Fn EC_KEY_get0_private_key , +.Fn EC_KEY_set_private_key , +.Fn EC_KEY_get0_public_key , +and +.Fn EC_KEY_set_public_key +get and set the +.Vt EC_GROUP +object, the private key and the +.Vt EC_POINT +public key for the +.Fa key , +respectively. +The setters copy the group and key objects without sanity checks +and it is the caller's responsibility to ensure that +the resulting key is valid, for example using +.Fn EC_KEY_check_key . +.Pp +The functions +.Fn EC_KEY_get_enc_flags +and +.Fn EC_KEY_set_enc_flags +get and set the value of the encoding flags for the +.Fa key . +There are two encoding flags currently defined: +.Dv EC_PKEY_NO_PARAMETERS +and +.Dv EC_PKEY_NO_PUBKEY . +These flags define the behaviour of how the +.Fa key +is converted into ASN.1 in a call to +.Fn i2d_ECPrivateKey . +If +.Dv EC_PKEY_NO_PARAMETERS +is set then the public parameters for the curve +are not encoded along with the private key. +If +.Dv EC_PKEY_NO_PUBKEY +is set then the public key is not encoded along with the private +key. +.Pp +The format of the external representation of the public key written by +.Xr i2d_ECPrivateKey 3 , +such as whether it is stored in a compressed form or not, +is described by the point_conversion_form. +See +.Xr EC_POINT_point2oct 3 +for a description of point_conversion_form. +.Pp +When reading a private key encoded without an associated public key, +for example if +.Dv EC_PKEY_NO_PUBKEY +was used, +.Xr d2i_ECPrivateKey 3 +generates the missing public key automatically. +Private keys encoded without parameters, for example if +.Dv EC_PKEY_NO_PARAMETERS +was used, cannot be loaded using +.Xr d2i_ECPrivateKey 3 . +.Pp +The functions +.Fn EC_KEY_get_conv_form +and +.Fn EC_KEY_set_conv_form +get and set the point_conversion_form for the +.Fa key . +For a description of point_conversion_form refer to +.Xr EC_POINT_point2oct 3 . +.Pp +.Fn EC_KEY_set_flags +sets the flags in the +.Fa flags +parameter on the +.Vt EC_KEY +object. +Any flags that are already set are left set. +The currently defined standard flags are +.Dv EC_FLAG_NON_FIPS_ALLOW +and +.Dv EC_FLAG_FIPS_CHECKED . +In addition there is the ECDH-specific flag +.Dv EC_FLAG_COFACTOR_ECDH . +.Fn EC_KEY_get_flags +returns the current flags that are set for this +.Vt EC_KEY . +.Fn EC_KEY_clear_flags +clears the flags indicated by the +.Fa flags +parameter. +All other flags are left in their existing state. +.Pp +.Fn EC_KEY_set_asn1_flag +sets the asn1_flag on the underlying +.Vt EC_GROUP +object (if set). +Refer to +.Xr EC_GROUP_get_curve_name 3 +for further information on the asn1_flag. +.Pp +.Fn EC_KEY_precompute_mult +stores multiples of the underlying +.Vt EC_GROUP +generator for faster point multiplication. +See also +.Xr EC_POINT_add 3 . +.Pp +.Fn EC_KEY_print +and +.Fn EC_KEY_print_fp +print out the content of +.Fa key +to the +.Vt BIO +.Fa bp +or to the +.Vt FILE +pointer +.Fa fp , +respectively. +Each line is indented by +.Fa indent +spaces. +.Sh RETURN VALUES +.Fn EC_KEY_new , +.Fn EC_KEY_new_by_curve_name , +and +.Fn EC_KEY_dup +return a pointer to the newly created +.Vt EC_KEY object +or +.Dv NULL +on error. +.Pp +.Fn EC_KEY_get_flags +returns the flags associated with the +.Vt EC_KEY object . +.Pp +.Fn EC_KEY_copy +returns a pointer to the destination key or +.Dv NULL +on error. +In the latter case, part of the content may already have been copied. +.Pp +.Fn EC_KEY_up_ref , +.Fn EC_KEY_set_group , +.Fn EC_KEY_set_private_key , +.Fn EC_KEY_set_public_key , +.Fn EC_KEY_precompute_mult , +.Fn EC_KEY_generate_key , +.Fn EC_KEY_check_key , +.Fn EC_KEY_set_public_key_affine_coordinates , +.Fn EC_KEY_print , +and +.Fn EC_KEY_print_fp +return 1 on success or 0 on error. +.Pp +.Fn EC_KEY_get0_group +returns the +.Vt EC_GROUP +associated with the +.Vt EC_KEY . +.Pp +.Fn EC_KEY_get0_private_key +and +.Fn EC_KEY_get0_public_key +return the private or public keys, respectively, associated with the +.Vt EC_KEY . +.Pp +.Fn EC_KEY_get_enc_flags +returns the value of the current encoding flags for the +.Vt EC_KEY . +.Pp +.Fn EC_KEY_get_conv_form +returns the point_conversion_form for the +.Vt EC_KEY . +.Sh SEE ALSO +.Xr d2i_ECPKParameters 3 , +.Xr EC_GROUP_check 3 , +.Xr EC_GROUP_get_curve_name 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_GROUP_new_curve_GFp 3 , +.Xr EC_KEY_METHOD_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_get_affine_coordinates 3 , +.Xr EC_POINT_point2oct 3 , +.Xr ECDH_compute_key 3 , +.Xr ECDSA_SIG_new 3 , +.Xr EVP_PKEY_set1_EC_KEY 3 +.Sh HISTORY +.Fn EC_KEY_new , +.Fn EC_KEY_new_by_curve_name , +.Fn EC_KEY_free , +.Fn EC_KEY_copy , +.Fn EC_KEY_dup , +.Fn EC_KEY_up_ref , +.Fn EC_KEY_get0_group , +.Fn EC_KEY_set_group , +.Fn EC_KEY_get0_private_key , +.Fn EC_KEY_set_private_key , +.Fn EC_KEY_get0_public_key , +.Fn EC_KEY_set_public_key , +.Fn EC_KEY_get_enc_flags , +.Fn EC_KEY_set_enc_flags , +.Fn EC_KEY_get_conv_form , +.Fn EC_KEY_set_conv_form , +.Fn EC_KEY_set_asn1_flag , +.Fn EC_KEY_precompute_mult , +.Fn EC_KEY_generate_key , +.Fn EC_KEY_check_key , +.Fn EC_KEY_print , +and +.Fn EC_KEY_print_fp +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn EC_KEY_get_flags , +.Fn EC_KEY_set_flags , +.Fn EC_KEY_clear_flags , +and +.Fn EC_KEY_set_public_key_affine_coordinates +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/EC_POINT_add.3 b/static/openbsd/man3/EC_POINT_add.3 new file mode 100644 index 00000000..28f3143a --- /dev/null +++ b/static/openbsd/man3/EC_POINT_add.3 @@ -0,0 +1,223 @@ +.\" $OpenBSD: EC_POINT_add.3,v 1.17 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EC_POINT_ADD 3 +.Os +.Sh NAME +.Nm EC_POINT_add , +.Nm EC_POINT_dbl , +.Nm EC_POINT_invert , +.Nm EC_POINT_is_at_infinity , +.Nm EC_POINT_is_on_curve , +.Nm EC_POINT_cmp , +.Nm EC_POINT_make_affine , +.Nm EC_POINT_mul +.Nd perform mathematical operations and tests on EC_POINT objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ec.h +.In openssl/bn.h +.Ft int +.Fo EC_POINT_add +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const EC_POINT *a" +.Fa "const EC_POINT *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_dbl +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const EC_POINT *a" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_invert +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *a" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_is_at_infinity +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fc +.Ft int +.Fo EC_POINT_is_on_curve +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *point" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_cmp +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *a" +.Fa "const EC_POINT *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_make_affine +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_mul +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const BIGNUM *n" +.Fa "const EC_POINT *q" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +These functions operate on +.Vt EC_POINT +objects created by +.Xr EC_POINT_new 3 . +.Pp +.Fn EC_POINT_add +adds the two points +.Fa a +and +.Fa b +and places the result in +.Fa r . +Similarly +.Fn EC_POINT_dbl +doubles the point +.Fa a +and places the result in +.Fa r . +In both cases it is valid for +.Fa r +to be one of +.Fa a +or +.Fa b . +.Pp +.Fn EC_POINT_invert +calculates the inverse of the supplied point +.Fa a . +The result is placed back in +.Fa a . +.Pp +The function +.Fn EC_POINT_is_at_infinity +tests whether the supplied point is at infinity or not. +.Pp +.Fn EC_POINT_is_on_curve +tests whether the supplied point is on the curve or not. +.Pp +.Fn EC_POINT_cmp +compares the two supplied points and tests whether or not they are +equal. +.Pp +.Fn EC_POINT_mul +calculates the value +.Pp +.D1 generator * n + q * m +.Pp +and stores the result in +.Fa r . +The value +.Fa n +may be +.Dv NULL , +in which case the result is just +.Pp +.Dl q * m. +.Pp +See +.Xr EC_GROUP_new_curve_GFp 3 +for information about the generator. +.Sh RETURN VALUES +The following functions return 1 on success or 0 on error: +.Fn EC_POINT_add , +.Fn EC_POINT_dbl , +.Fn EC_POINT_invert , +.Fn EC_POINT_make_affine , +and +.Fn EC_POINT_mul +.Pp +.Fn EC_POINT_is_at_infinity +returns 1 if the point is at infinity or 0 otherwise. +.Pp +.Fn EC_POINT_is_on_curve +returns 1 if the point is on the curve, 0 if not, or -1 on error. +.Pp +.Fn EC_POINT_cmp +returns 1 if the points are not equal, 0 if they are, or -1 on error. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr EC_GROUP_check 3 , +.Xr EC_GROUP_get_curve_name 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_GROUP_new_curve_GFp 3 , +.Xr EC_KEY_METHOD_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_get_affine_coordinates 3 , +.Xr EC_POINT_new 3 , +.Xr EC_POINT_point2oct 3 +.Sh HISTORY +.Fn EC_POINT_add , +.Fn EC_POINT_dbl , +.Fn EC_POINT_invert , +.Fn EC_POINT_is_at_infinity , +.Fn EC_POINT_is_on_curve , +.Fn EC_POINT_cmp , +.Fn EC_POINT_make_affine , +and +.Fn EC_POINT_mul +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/EC_POINT_get_affine_coordinates.3 b/static/openbsd/man3/EC_POINT_get_affine_coordinates.3 new file mode 100644 index 00000000..76ef5163 --- /dev/null +++ b/static/openbsd/man3/EC_POINT_get_affine_coordinates.3 @@ -0,0 +1,216 @@ +.\" $OpenBSD: EC_POINT_get_affine_coordinates.3,v 1.2 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2025 Theo Buehler +.\" +.\" 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: June 8 2025 $ +.Dt EC_POINT_GET_AFFINE_COORDINATES 3 +.Os +.Sh NAME +.Nm EC_POINT_get_affine_coordinates , +.Nm EC_POINT_set_affine_coordinates , +.Nm EC_POINT_set_compressed_coordinates , +.Nm EC_POINT_set_to_infinity , +.Nm EC_POINT_get_affine_coordinates_GFp , +.Nm EC_POINT_set_affine_coordinates_GFp , +.Nm EC_POINT_set_compressed_coordinates_GFp +.Nd get and set coordinates of elliptic curve points +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.In openssl/ec.h +.Pp +.Ft int +.Fo EC_POINT_get_affine_coordinates +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *point" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_affine_coordinates +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fa "const BIGNUM *x" +.Fa "const BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_compressed_coordinates +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fa "const BIGNUM *x" +.Fa "int y_bit" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_to_infinity +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fc +.Pp +Deprecated: +.Pp +.Ft int +.Fo EC_POINT_get_affine_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *point" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_affine_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fa "const BIGNUM *x" +.Fa "const BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_compressed_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fa "const BIGNUM *x" +.Fa "int y_bit" +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn EC_POINT_get_affine_coordinates +assumes that +.Fa point +is a point on +.Fa group , +calculates its affine coordinates from its internal representation +using the optional +.Fa ctx , +and copies them into the optional user-provided +.Fa x +and +.Fa y . +.Pp +.Fn EC_POINT_set_affine_coordinates +assumes that +.Fa x +and +.Fa y +are the affine coordinates of a point on +.Fa group , +converts them into internal representation and sets them on +.Fa point +using the optional +.Fa ctx . +The user-provided +.Fa point +should be the result of +.Fn EC_POINT_new 3 +with an argument of +.Fa group . +It then verifies using +.Xr EC_POINT_is_on_curve 3 +that +.Fa x +and +.Fa y +are indeed the affine coordinates of a point on +.Fa group . +.Pp +.Fn EC_POINT_set_compressed_coordinates +assumes that +.Fa x +is the x-coordinate and +.Fa y_bit +is the parity bit of a point on +.Fa group +and sets +.Fa point +to the corresponding point on +.Fa group . +It does this by solving the quadratic equation y^2 = x^3 + ax + b using +.Xr BN_mod_sqrt 3 +and the optional +.Fa ctx , +chooses the solution +.Fa y +with parity matching +.Fa y_bit , +and passes +.Fa x +and +.Fa y +to +.Fn EC_POINT_set_affine_coordinates . +The user-provided +.Fa point +should be the result of +.Fn EC_POINT_new +with argument +.Fa group . +.Pp +.Fn EC_POINT_set_to_infinity +sets +.Fa point +to the internal representation of the point at infinity on +.Fa group . +.Pp +.Fn EC_POINT_get_affine_coordinates_GFp +is a deprecated alias for +.Fn EC_POINT_get_affine_coordinates . +Similarly for +.Fn EC_POINT_set_affine_coordinates_GFp +and +.Fn EC_POINT_set_compressed_coordinates_GFp . +.Sh RETURN VALUES +All these functions return 1 on success and 0 on error. +Error conditions include memory allocation failure, +that +.Fa point +is incompatible with +.Fa group , +and, for the coordinate setters, that the provided coordinates +do not represent a point on +.Fa group . +.Sh SEE ALSO +.Xr BN_CTX_new 3 , +.Xr BN_is_zero 3 , +.Xr BN_mod_sqrt 3 , +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr EC_GROUP_check 3 , +.Xr EC_GROUP_get_curve_name 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_GROUP_new_curve_GFp 3 , +.Xr EC_KEY_METHOD_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_new 3 , +.Xr EC_POINT_point2oct 3 , +.Xr ECDH_compute_key 3 , +.Xr ECDSA_SIG_new 3 +.Sh HISTORY +.Fn EC_POINT_get_affine_coordinates_GFp , +.Fn EC_POINT_set_affine_coordinates_GFp , +.Fn EC_POINT_set_compressed_coordinates_GFp , +and +.Fn EC_POINT_set_to_infinity +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EC_POINT_get_affine_coordinates , +.Fn EC_POINT_set_affine_coordinates , +and +.Fn EC_POINT_set_compressed_coordinates +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.0 . diff --git a/static/openbsd/man3/EC_POINT_new.3 b/static/openbsd/man3/EC_POINT_new.3 new file mode 100644 index 00000000..0a797f8b --- /dev/null +++ b/static/openbsd/man3/EC_POINT_new.3 @@ -0,0 +1,208 @@ +.\" $OpenBSD: EC_POINT_new.3,v 1.21 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2025 Theo Buehler +.\" +.\" 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: June 13 2025 $ +.Dt EC_POINT_NEW 3 +.Os +.Sh NAME +.Nm EC_POINT_new , +.Nm EC_POINT_free , +.Nm EC_POINT_clear_free , +.Nm EC_POINT_copy , +.Nm EC_POINT_dup +.Nd allocate, free and copy elliptic curve points +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ec.h +.Pp +.Ft EC_POINT * +.Fo EC_POINT_new +.Fa "const EC_GROUP *group" +.Fc +.Ft void +.Fo EC_POINT_free +.Fa "EC_POINT *point" +.Fc +.Ft void +.Fo EC_POINT_clear_free +.Fa "EC_POINT *point" +.Fc +.Ft int +.Fo EC_POINT_copy +.Fa "EC_POINT *dst" +.Fa "const EC_POINT *src" +.Fc +.Ft EC_POINT * +.Fo EC_POINT_dup +.Fa "const EC_POINT *point" +.Fa "const EC_GROUP *group" +.Fc +.Sh DESCRIPTION +An +.Vt EC_POINT +object holds a point on the elliptic curve represented by an +.Vt EC_GROUP . +The details of the internal representation depend on the group +and should never be an application's concern since the EC library +has API to set a point's coordinates, +.Xr EC_POINT_set_affine_coordinates 3 . +.Pp +.Fn EC_POINT_new +allocates and initializes an +.Vt EC_POINT +object to be used with the +.Fa group . +Before explicitly setting its coordinates, the returned +.Vt EC_POINT +is invalid. +.Pp +.Fn EC_POINT_free +frees +.Fa point +and all memory associated with it. +If +.Fa point +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn EC_POINT_clear_free +is intended to destroy sensitive data held in +.Fa point +in addition to freeing all memory associated with it. +Since elliptic curve points usually hold public data, this +is rarely needed. +In LibreSSL, +.Fn EC_POINT_free +and +.Fn EC_POINT_clear_free +behave identically. +.Pp +.Fn EC_POINT_copy +copies the internal representation of +.Fa src +into +.Fa dst . +If +.Fa src +and +.Fa dst +are identical, no action occurs. +Both +.Fa src +and +.Fa dst +should be the result of +.Fn EC_POINT_new +with the same +.Fa group +argument, although +.Fn EC_POINT_copy +cannot check that. +.Pp +.Fn EC_POINT_dup +creates a deep copy of +.Fa point +by combining +.Fn EC_POINT_new +with +.Fn EC_GROUP_copy . +.Sh RETURN VALUES +.Fn EC_POINT_new +returns a newly allocated +.Vt EC_POINT +or +.Dv NULL +on memory allocation failure. +.Pp +.Fn EC_POINT_copy +returns 1 on success or 0 on error. +Error conditions include memory allocation failure and that +.Fa dst +is incompatible with the group on which +.Fa src +is defined. +.Pp +.Fn EC_POINT_dup +returns a newly allocated +.Vt EC_POINT +or +.Dv NULL +on failure. +Error conditions include memory allocation failure or that +.Fa group +is incompatible with +.Fa src . +.Sh SEE ALSO +.Xr BN_CTX_new 3 , +.Xr BN_is_zero 3 , +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr EC_GROUP_check 3 , +.Xr EC_GROUP_get_curve_name 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_GROUP_new_curve_GFp 3 , +.Xr EC_KEY_METHOD_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_get_affine_coordinates 3 , +.Xr EC_POINT_point2oct 3 , +.Xr ECDH_compute_key 3 , +.Xr ECDSA_SIG_new 3 +.Sh HISTORY +.Fn EC_POINT_new , +.Fn EC_POINT_free , +.Fn EC_POINT_clear_free , +and +.Fn EC_POINT_copy +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EC_POINT_dup +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Sh BUGS +A fundamental flaw in the OpenSSL API toolkit is that +.Fn *_new +functions usually create invalid objects that are tricky to +turn into valid objects. +One specific flaw in the EC library internals is that +.Vt EC_POINT +objects do not hold a reference to the group they live on +despite the fact that +.Fn EC_POINT_new +has a +.Fa group +argument. +This is difficult to fix because +.Vt EC_GROUP +objects are not reference counted and +because of const qualifiers in the API. +This is the root cause for various contortions in the EC library +and API and +there are security implications because not +only does the library not know whether an +.Fa EC_POINT +object represents a valid point, +even if it did know that it would still not know on what curve. +.Pp +The signature of +.Fn EC_GROUP_dup +is bizarre and the order of +.Fa point +and +.Fa group +is inconsistent with the rest of the EC API. diff --git a/static/openbsd/man3/EC_POINT_point2oct.3 b/static/openbsd/man3/EC_POINT_point2oct.3 new file mode 100644 index 00000000..ac89c9b1 --- /dev/null +++ b/static/openbsd/man3/EC_POINT_point2oct.3 @@ -0,0 +1,434 @@ +.\" $OpenBSD: EC_POINT_point2oct.3,v 1.6 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2025 Theo Buehler +.\" +.\" 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: June 13 2025 $ +.Dt EC_POINT_POINT2OCT 3 +.Os +.Sh NAME +.Nm EC_POINT_point2oct , +.Nm EC_POINT_oct2point , +.Nm EC_POINT_point2bn , +.Nm EC_POINT_bn2point , +.Nm EC_POINT_point2hex , +.Nm EC_POINT_hex2point +.Nd encode and decode elliptic curve points +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/bn.h +.In openssl/ec.h +.Bd -literal +typedef enum { + POINT_CONVERSION_COMPRESSED = 2, + POINT_CONVERSION_UNCOMPRESSED = 4, + POINT_CONVERSION_HYBRID = 6 +} point_conversion_form_t; + +.Ed +.Ft size_t +.Fo EC_POINT_point2oct +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *point" +.Fa "point_conversion_form_t form" +.Fa "unsigned char *buf" +.Fa "size_t len" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_oct2point +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fa "const unsigned char *buf" +.Fa "size_t len" +.Fa "BN_CTX *ctx" +.Fc +.Ft BIGNUM * +.Fo EC_POINT_point2bn +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *point" +.Fa "point_conversion_form_t form" +.Fa "BIGNUM *bn" +.Fa "BN_CTX *ctx" +.Fc +.Ft EC_POINT * +.Fo EC_POINT_bn2point +.Fa "const EC_GROUP *group" +.Fa "const BIGNUM *bn" +.Fa "EC_POINT *point" +.Fa "BN_CTX *ctx" +.Fc +.Ft char * +.Fo EC_POINT_point2hex +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *point" +.Fa "point_conversion_form_t form" +.Fa "BN_CTX *ctx" +.Fc +.Ft EC_POINT * +.Fo EC_POINT_hex2point +.Fa "const EC_GROUP *group" +.Fa "const char *hex" +.Fa "EC_POINT *point" +.Fa "BN_CTX *ctx" +.Fc +.Sh DESCRIPTION +The +.Fa ctx +argument of all functions in this manual is optional. +.Pp +An +.Vt EC_POINT +object represents a point on the elliptic curve given by an +.Vt EC_GROUP +object. +It is either the point at infinity or it has a representation +(x, y) in standard affine coordinates, +in which case it satisfies the curve's Weierstrass equation +.Pp +.Dl y^2 = x^3 + ax + b +.Pp +in the prime field of size p. +Thus, y is a square root of x^3 + ax + b. +Since p > 3 is odd, p - y is another square root +with different parity, unless y is zero. +Point compression uses that x and the parity of y are enough +to compute y using +.Xr BN_mod_sqrt 3 . +.Pp +Field elements are represented as non-negative integers < p +in big-endian 2-complement form, zero-padded on the left to the byte +length l of p. +If X and Y are the representations of x and y, respectively, and P is +the parity bit of y, the three encodings of the point (x, y) are +the byte strings: +.Bl -column "EncodingX" "CompressedX" "UncompressedX" "Hybrid" -offset indent -compact +.It Ta Em Compressed Ta Em Uncompressed Ta Em Hybrid +.It Encoding Ta 2+P || X Ta 4 || X || Y Ta 6+P || X || Y +.It Length Ta 1 + l Ta 1 + 2l Ta 1 + 2l +.El +where the first octet is the point conversion form +combined with the parity bit in the compressed and hybrid encodings. +The point at infinity is encoded as a single zero byte. +.Pp +.Fn EC_POINT_point2oct +converts +.Fa point +into the octet string encoding of type +.Fa form . +It assumes without checking that +.Fa point +is a point on the elliptic curve represented by +.Fa group +and operates in two modes depending on the +.Fa buf +argument. +If +.Fa buf +is +.Dv NULL , +.Fn EC_POINT_point2oct +returns the length of +.Fa point Ns 's +encoding of type +.Fa form +and ignores the +.Fa len +and +.Fa ctx +arguments. +If +.Fa buf +is not +.Dv NULL +and its length +.Fa len +is sufficiently big, +.Fn EC_POINT_point2oct +writes the +.Fa point Ns 's +encoding of type +.Fa form +to +.Fa buf +and returns the number of bytes written. +Unless +.Fa point +is the point at infinity, the coordinates to be encoded are calculated using +.Xr EC_POINT_get_affine_coordinates 3 . +.Pp +.Fn EC_POINT_oct2point +decodes the octet string representation of a point on +.Fa group +in +.Fa buf +of size +.Fa len +and, if it represents a point on +.Fa group , +sets it on the caller-provided +.Fa point +using +.Xr EC_POINT_set_to_infinity 3 +.Xr EC_POINT_set_compressed_coordinates 3 , +or +.Xr EC_POINT_set_affine_coordinates 3 . +For hybrid encoding the consistency of +the parity bit in the leading octet is verified. +.Pp +.Fn EC_POINT_point2bn +returns a +.Vt BIGNUM +containing the encoding of type +.Fa form +of the +.Fa point +on +.Fa group . +If +.Fa bn +is +.Dv NULL , +this +.Vt BIGNUM +is newly allocated, otherwise the result is copied into +.Fa bn +and returned. +.Fn EC_POINT_point2bn +is equivalent to +.Fn EC_POINT_point2oct +followed by +.Xr BN_bin2bn 3 . +.Pp +.Fn EC_POINT_bn2point +assumes that +.Fa bn +contains the encoding of a point on +.Fa group . +If +.Fa point +is +.Dv NULL , +the result is placed in a newly allocated +.Vt EC_POINT , +otherwise the result is placed in +.Fa point +which is then returned. +.Fn EC_POINT_bn2point +is equivalent to +.Xr BN_bn2bin 3 +followed by +.Fn EC_POINT_oct2point . +.Pp +.Fn EC_POINT_point2hex +returns a printable string containing the hexadecimal encoding of +the point encoding of type +.Fa form +of the +.Fa point +on +.Fa group . +The string must be freed by the caller using +.Xr free 3 . +.Fn EC_POINT_point2hex +is equivalent to +.Fn EC_POINT_point2bn +followed by +.Xr BN_bn2hex 3 . +.Pp +.Fn EC_POINT_hex2point +interprets +.Fa hex +as a hexadecimal encoding of the point encoding of a point on +.Fa group . +If +.Fa point +is +.Dv NULL , +the result is returned in a newly allocated +.Vt EC_POINT , +otherwise the result is copied into +.Fa point , +which is then returned. +.Fn EC_POINT_hex2point +is equivalent to +.Xr BN_hex2bn 3 +followed by +.Fn EC_POINT_bn2point . +.Sh RETURN VALUES +If +.Fa buf +is +.Dv NULL , +.Fn EC_POINT_point2oct +returns the length needed to encode the +.Fa point +on +.Fa group , +or 0 on error. +If +.Fa buf +is not +.Dv NULL , +.Fn EC_POINT_point2oct +returns the number of bytes written to +.Fa buf +or 0 on error. +Error conditions include that +.Fa form +is invalid, +.Fa len +is too small, and memory allocation failure. +.Pp +.Fn EC_POINT_oct2point +returns 1 on success and 0 on error. +Error conditions include invalid encoding, +.Fa buf +does not represent a point on +.Fa group , +or memory allocation failure. +.Pp +.Fn EC_POINT_point2bn +returns a +.Vt BIGNUM +containing the encoding of +.Fa point +or +.Dv NULL +on error. +The returned +.Vt BIGNUM +is either +.Fa bn +or a newly allocated one which must be freed by the caller. +Error conditions include those of +.Fn EC_POINT_point2oct , +.Xr BN_bn2bin 3 , +or memory allocation failure. +.Pp +.Fn EC_POINT_bn2point +returns an +.Vt EC_POINT +corresponding to the encoding in +.Fa bn +or +.Dv NULL +on error. +The returned +.Vt EC_POINT +is either +.Fa point +or a newly allocated one which must be freed by the caller. +Error conditions include those of +.Xr BN_bn2bin 3 , +.Fn EC_POINT_oct2point , +or memory allocation failure. +.Pp +.Fn EC_POINT_point2hex +returns a newly allocated string or +.Dv NULL +on error. +Error conditions include those of +.Fn EC_POINT_point2bn +or +.Xr BN_bn2hex 3 . +.Pp +.Fn EC_POINT_hex2point +returns an +.Vt EC_POINT +containing the decoded point on +.Fa group +or +.Dv NULL +on error. +The returned +.Vt EC_POINT +is either +.Fa point +or a newly allocated one which must be freed by the caller. +Error conditions are those of +.Xr BN_hex2bn 3 , +or +.Fn EC_POINT_bn2point . +.Sh SEE ALSO +.Xr BN_mod_sqrt 3 , +.Xr BN_new 3 , +.Xr BN_num_bits 3 , +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr EC_GROUP_check 3 , +.Xr EC_GROUP_get_curve_name 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_GROUP_new_curve_GFp 3 , +.Xr EC_KEY_METHOD_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_get_affine_coordinates 3 , +.Xr EC_POINT_new 3 , +.Xr ECDH_compute_key 3 , +.Xr ECDSA_SIG_new 3 +.Sh STANDARDS +.Rs +.%T SEC 1: Elliptic Curve Cryptography, Version 2.0 +.%U https://www.secg.org/sec1-v2.pdf +.%D May 21, 2009 +.Re +.Sh HISTORY +.Fn EC_POINT_point2oct +and +.Fn EC_POINT_oct2point +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EC_POINT_point2bn , +.Fn EC_POINT_bn2point , +.Fn EC_POINT_point2hex , +and +.Fn EC_POINT_hex2point +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Sh BUGS +The +.Vt point_conversion_form_t +is not properly exposed in the API. +There is no representation for the point at infinity nor is there +an API interface for the parity bit, +forcing applications to invent their own and do bit twiddling in buffers. +.Pp +The poorly chosen signatures of the functions in this manual result +in an unergonomic API, particularly so for +.Fn EC_POINT_point2oct +and +.Fn EC_POINT_oct2point . +Due to fundamental misdesign in the EC library, +points are not directly linked to the curve they live on. +Adding checks that +.Fa point +lives on +.Fa group +is too expensive and intrusive, so it is and will continue to be easy +to make the EC_POINT_point2* API output nonsense. +.Pp +.Fn EC_POINT_point2bn +and +.Fn EC_POINT_bn2point +make no sense. +They abuse +.Vt BIGNUM +as a vector type, which is in poor taste. +.Pp +.Fn EC_POINT_point2hex +and +.Fn EC_POINT_hex2point +use a non-standard encoding format. diff --git a/static/openbsd/man3/ENGINE_new.3 b/static/openbsd/man3/ENGINE_new.3 new file mode 100644 index 00000000..f70adecc --- /dev/null +++ b/static/openbsd/man3/ENGINE_new.3 @@ -0,0 +1,175 @@ +.\" $OpenBSD: ENGINE_new.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" Copyright (c) 2018 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 $Mdocdate: June 8 2025 $ +.Dt ENGINE_NEW 3 +.Os +.Sh NAME +.Nm ENGINE_new , +.Nm ENGINE_free , +.Nm ENGINE_init , +.Nm ENGINE_finish , +.Nm ENGINE_ctrl_cmd , +.Nm ENGINE_ctrl_cmd_string , +.Nm ENGINE_by_id , +.Nm ENGINE_get_id , +.Nm ENGINE_get_name , +.Nm ENGINE_set_default , +.Nm ENGINE_get_default_RSA , +.Nm ENGINE_set_default_RSA , +.Nm ENGINE_load_private_key , +.Nm ENGINE_load_public_key , +.Nm ENGINE_load_builtin_engines , +.Nm ENGINE_load_dynamic , +.Nm ENGINE_load_openssl , +.Nm ENGINE_register_all_complete , +.Nm ENGINE_cleanup +.Nd ENGINE stub functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/engine.h +.Ft ENGINE * +.Fn ENGINE_new void +.Ft int +.Fo ENGINE_free +.Fa "ENGINE *engine" +.Fc +.Ft int +.Fn ENGINE_init "ENGINE *engine" +.Ft int +.Fn ENGINE_finish "ENGINE *engine" +.Ft int +.Fo ENGINE_ctrl_cmd +.Fa "ENGINE *engine" +.Fa "const char *cmd_name" +.Fa "long i" +.Fa "void *p" +.Fa "void (*f)(void)" +.Fa "int cmd_optional" +.Fc +.Ft int +.Fo ENGINE_ctrl_cmd_string +.Fa "ENGINE *engine" +.Fa "const char *cmd_name" +.Fa "const char *arg" +.Fa "int cmd_optional" +.Fc +.Ft ENGINE * +.Fn ENGINE_by_id "const char *id" +.Ft const char * +.Fn ENGINE_get_id "const ENGINE *engine" +.Ft const char * +.Fn ENGINE_get_name "const ENGINE *engine" +.Ft int +.Fn ENGINE_set_default "ENGINE *engine" "unsigned int flags" +.Ft ENGINE * +.Fn ENGINE_get_default_RSA "ENGINE *engine" +.Ft int +.Fn ENGINE_set_default_RSA "ENGINE *engine" +.Ft EVP_PKEY * +.Fo ENGINE_load_private_key +.Fa "ENGINE *engine" +.Fa "const char *key_id" +.Fa "UI_METHOD *ui_method" +.Fa "void *callback_data" +.Fc +.Ft EVP_PKEY * +.Fo ENGINE_load_public_key +.Fa "ENGINE *engine" +.Fa "const char *key_id" +.Fa "UI_METHOD *ui_method" +.Fa "void *callback_data" +.Fc +.Ft void +.Fn ENGINE_load_builtin_engines "void" +.Ft void +.Fn ENGINE_load_dynamic "void" +.Ft void +.Fn ENGINE_load_openssl "void" +.Ft int +.Fn ENGINE_register_all_complete "void" +.Ft void +.Fn ENGINE_cleanup "void" +.Sh DESCRIPTION +.Vt ENGINE +objects used to provide alternative implementations of +cryptographic algorithms, for example using specialized hardware. +LibreSSL no longer supports this feature. +.Pp +All functions in this manual ignore all their arguments and +do nothing except return failure if possible. +They are provided only to avoid patching software that expects +.Vt ENGINE +support to be available. +.Sh RETURN VALUES +.Fn ENGINE_new , +.Fn ENGINE_by_id , +.Fn ENGINE_get_default_RSA , +.Fn ENGINE_load_private_key , +and +.Fn ENGINE_load_public_key +always return +.Dv NULL . +.Pp +.Fn ENGINE_free , +.Fn ENGINE_init , +.Fn ENGINE_finish , +.Fn ENGINE_ctrl_cmd , +.Fn ENGINE_ctrl_cmd_string , +.Fn ENGINE_set_default , +.Fn ENGINE_set_default_RSA , +and +.Fn ENGINE_register_all_complete +always return 0. +.Pp +.Fn ENGINE_get_id +and +.Fn ENGINE_get_name +always return the constant empty string. +.Sh SEE ALSO +.Xr crypto 3 +.Sh HISTORY +.Fn ENGINE_new , +.Fn ENGINE_free , +.Fn ENGINE_init , +.Fn ENGINE_finish , +.Fn ENGINE_by_id , +.Fn ENGINE_get_id , +.Fn ENGINE_get_name , +.Fn ENGINE_set_default , +.Fn ENGINE_get_default_RSA , +.Fn ENGINE_set_default_RSA , +.Fn ENGINE_load_private_key , +and +.Fn ENGINE_load_public_key +first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 2.9 . +.Pp +.Fn ENGINE_ctrl_cmd , +.Fn ENGINE_ctrl_cmd_string , +.Fn ENGINE_load_builtin_engines , +.Fn ENGINE_load_openssl , +.Fn ENGINE_register_all_complete , +and +.Fn ENGINE_cleanup +first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.4 . +.Pp +All these functions were turned into stubs in +.Ox 7.4 . diff --git a/static/openbsd/man3/ERR_GET_LIB.3 b/static/openbsd/man3/ERR_GET_LIB.3 new file mode 100644 index 00000000..754f7faf --- /dev/null +++ b/static/openbsd/man3/ERR_GET_LIB.3 @@ -0,0 +1,127 @@ +.\" $OpenBSD: ERR_GET_LIB.3,v 1.8 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL doc/man3/ERR_GET_LIB.pod 3dfda1a6 Dec 12 11:14:40 2016 -0500 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR_GET_LIB 3 +.Os +.Sh NAME +.Nm ERR_GET_LIB , +.Nm ERR_GET_FUNC , +.Nm ERR_GET_REASON , +.Nm ERR_FATAL_ERROR +.Nd get library, function and reason codes for OpenSSL errors +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft int +.Fo ERR_GET_LIB +.Fa "unsigned long e" +.Fc +.Ft int +.Fo ERR_GET_FUNC +.Fa "unsigned long e" +.Fc +.Ft int +.Fo ERR_GET_REASON +.Fa "unsigned long e" +.Fc +.Ft int +.Fo ERR_FATAL_ERROR +.Fa "unsigned long e" +.Fc +.Sh DESCRIPTION +The error code returned by +.Xr ERR_get_error 3 +consists of a library number, function code, and reason code. +.Fn ERR_GET_LIB , +.Fn ERR_GET_FUNC , +and +.Fn ERR_GET_REASON +can be used to extract these. +.Pp +The library number and function code describe where the error occurred, +whereas the reason code is the information about what went wrong. +.Pp +Each sub-library of OpenSSL has a unique library number; function and +reason codes are unique within each sub-library. +Note that different libraries may use the same value to signal different +functions and reasons. +.Pp +.Dv ERR_R_* +reason codes such as +.Dv ERR_R_MALLOC_FAILURE +are globally unique. +However, when checking for sub-library specific reason codes, be sure to +also compare the library number. +.Pp +.Fn ERR_FATAL_ERROR +indicates whether a given error code is a fatal error. +.Pp +These functions are implemented as macros. +.Sh RETURN VALUES +.Fn ERR_GET_LIB , +.Fn ERR_GET_FUNC , +and +.Fn ERR_GET_REASON +return the library number, function code, and reason code, respectively. +.Pp +.Fn ERR_FATAL_ERROR +returns non-zero if the error is fatal or 0 otherwise. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn ERR_GET_LIB , +.Fn ERR_GET_FUNC , +.Fn ERR_GET_REASON , +and +.Fn ERR_FATAL_ERROR +first appeared in SSLeay 0.4.4 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/ERR_asprintf_error_data.3 b/static/openbsd/man3/ERR_asprintf_error_data.3 new file mode 100644 index 00000000..edd8655d --- /dev/null +++ b/static/openbsd/man3/ERR_asprintf_error_data.3 @@ -0,0 +1,56 @@ +.\" $OpenBSD: ERR_asprintf_error_data.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2017 Bob Beck +.\" +.\" 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: June 8 2025 $ +.Dt ERR_ASPRINTF_ERROR_DATA 3 +.Os +.Sh NAME +.Nm ERR_asprintf_error_data +.Nd record a LibreSSL error using a formatted string +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft void +.Fo ERR_asprintf_error_data +.Fa "char * format" +.Fa ... +.Fc +.Sh DESCRIPTION +.Nm +builds a string using +.Xr asprintf 3 +called with the provided +.Ar format +and arguments. +The resulting string is then associated with the error code that was most +recently added. +If +.Xr asprintf 3 +fails, the string "malloc failed" is associated instead. +.Pp +.Nm +is intended to be used instead of the OpenSSL functions +.Fn ERR_add_error_data +and +.Fn ERR_add_error_vdata . +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_put_error 3 , +.Xr printf 3 +.Sh HISTORY +.Nm +appeared in +.Ox 5.6 +and is available in all versions of LibreSSL. diff --git a/static/openbsd/man3/ERR_clear_error.3 b/static/openbsd/man3/ERR_clear_error.3 new file mode 100644 index 00000000..d39ac119 --- /dev/null +++ b/static/openbsd/man3/ERR_clear_error.3 @@ -0,0 +1,71 @@ +.\" $OpenBSD: ERR_clear_error.3,v 1.6 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR_CLEAR_ERROR 3 +.Os +.Sh NAME +.Nm ERR_clear_error +.Nd clear the OpenSSL error queue +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft void +.Fn ERR_clear_error void +.Sh DESCRIPTION +.Fn ERR_clear_error +empties the current thread's error queue. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn ERR_clear_error +first appeared in SSLeay 0.4.4 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/ERR_error_string.3 b/static/openbsd/man3/ERR_error_string.3 new file mode 100644 index 00000000..a1df20fe --- /dev/null +++ b/static/openbsd/man3/ERR_error_string.3 @@ -0,0 +1,177 @@ +.\" $OpenBSD: ERR_error_string.3,v 1.8 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2004 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR_ERROR_STRING 3 +.Os +.Sh NAME +.Nm ERR_error_string , +.Nm ERR_error_string_n , +.Nm ERR_lib_error_string , +.Nm ERR_func_error_string , +.Nm ERR_reason_error_string +.Nd obtain human-readable OpenSSL error messages +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft char * +.Fo ERR_error_string +.Fa "unsigned long e" +.Fa "char *buf" +.Fc +.Ft void +.Fo ERR_error_string_n +.Fa "unsigned long e" +.Fa "char *buf" +.Fa "size_t len" +.Fc +.Ft const char * +.Fo ERR_lib_error_string +.Fa "unsigned long e" +.Fc +.Ft const char * +.Fo ERR_func_error_string +.Fa "unsigned long e" +.Fc +.Ft const char * +.Fo ERR_reason_error_string +.Fa "unsigned long e" +.Fc +.Sh DESCRIPTION +.Fn ERR_error_string +generates a human-readable string representing the error code +.Fa e +and places it in +.Fa buf . +.Fa buf +must be at least 256 bytes long. +If +.Fa buf +is +.Dv NULL , +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 +.Fn ERR_error_string_n +instead. +.Pp +.Fn ERR_error_string_n +is a variant of +.Fn ERR_error_string +that writes at most +.Fa len +characters (including the terminating NUL) and truncates the string +if necessary. +For +.Fn ERR_error_string_n , +.Fa buf +may not be +.Dv NULL . +.Pp +The string will have the following format: +.Pp +.Dl error:[error code]:[library name]:[function name]:[reason string] +.Pp +The error code is an 8-digit hexadecimal number. +The library name, the function name, and the reason string are ASCII +text. +.Pp +.Fn ERR_lib_error_string , +.Fn ERR_func_error_string , +and +.Fn ERR_reason_error_string +return the library name, the function name, and the reason string, +respectively. +.Pp +The OpenSSL error strings should be loaded by calling +.Xr ERR_load_crypto_strings 3 +or, for SSL applications, +.Xr SSL_load_error_strings 3 +first. +If there is no text string registered for the given error code, the +error string will contain the numeric code. +.Pp +.Xr ERR_print_errors 3 +can be used to print all error codes currently in the queue. +.Sh RETURN VALUES +.Fn ERR_error_string +returns a pointer to a static buffer containing the string if +.Fa buf +is +.Dv NULL , +or +.Fa buf +otherwise. +.Pp +.Fn ERR_lib_error_string , +.Fn ERR_func_error_string , +and +.Fn ERR_reason_error_string +return the strings, or +.Dv NULL +if none is registered for the error code. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_get_error 3 , +.Xr ERR_load_crypto_strings 3 , +.Xr ERR_print_errors 3 , +.Xr SSL_load_error_strings 3 +.Sh HISTORY +.Fn ERR_error_string , +.Fn ERR_lib_error_string , +.Fn ERR_func_error_string , +and +.Fn ERR_reason_error_string +first appeared in SSLeay 0.4.4 and have been available since +.Ox 2.4 . +.Pp +.Fn ERR_error_string_n +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . diff --git a/static/openbsd/man3/ERR_get_error.3 b/static/openbsd/man3/ERR_get_error.3 new file mode 100644 index 00000000..c592c345 --- /dev/null +++ b/static/openbsd/man3/ERR_get_error.3 @@ -0,0 +1,192 @@ +.\" $OpenBSD: ERR_get_error.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2002, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR_GET_ERROR 3 +.Os +.Sh NAME +.Nm ERR_get_error , +.Nm ERR_peek_error , +.Nm ERR_peek_last_error , +.Nm ERR_get_error_line , +.Nm ERR_peek_error_line , +.Nm ERR_peek_last_error_line , +.Nm ERR_get_error_line_data , +.Nm ERR_peek_error_line_data , +.Nm ERR_peek_last_error_line_data +.Nd obtain OpenSSL error code and data +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft unsigned long +.Fn ERR_get_error void +.Ft unsigned long +.Fn ERR_peek_error void +.Ft unsigned long +.Fn ERR_peek_last_error void +.Ft unsigned long +.Fo ERR_get_error_line +.Fa "const char **file" +.Fa "int *line" +.Fc +.Ft unsigned long +.Fo ERR_peek_error_line +.Fa "const char **file" +.Fa "int *line" +.Fc +.Ft unsigned long +.Fo ERR_peek_last_error_line +.Fa "const char **file" +.Fa "int *line" +.Fc +.Ft unsigned long +.Fo ERR_get_error_line_data +.Fa "const char **file" +.Fa "int *line" +.Fa "const char **data" +.Fa "int *flags" +.Fc +.Ft unsigned long +.Fo ERR_peek_error_line_data +.Fa "const char **file" +.Fa "int *line" +.Fa "const char **data" +.Fa "int *flags" +.Fc +.Ft unsigned long +.Fo ERR_peek_last_error_line_data +.Fa "const char **file" +.Fa "int *line" +.Fa "const char **data" +.Fa "int *flags" +.Fc +.Sh DESCRIPTION +.Fn ERR_get_error +returns the earliest error code from the thread's error queue and +removes the entry. +This function can be called repeatedly until there are no more error +codes to return. +.Pp +.Fn ERR_peek_error +returns the earliest error code from the thread's error queue without +modifying it. +.Pp +.Fn ERR_peek_last_error +returns the latest error code from the thread's error queue without +modifying it. +.Pp +See +.Xr ERR_GET_LIB 3 +for obtaining information about the location and reason for the error, and +.Xr ERR_error_string 3 +for human-readable error messages. +.Pp +.Fn ERR_get_error_line , +.Fn ERR_peek_error_line , +and +.Fn ERR_peek_last_error_line +are the same as the above, but they additionally store the file name and +line number where the error occurred in +.Pf * Fa file +and +.Pf * Fa line , +unless these are +.Dv NULL . +.Pp +.Fn ERR_get_error_line_data , +.Fn ERR_peek_error_line_data , +and +.Fn ERR_peek_last_error_line_data +store additional data and flags associated with the error code in +.Pf * Fa data +and +.Pf * Fa flags , +unless these are +.Dv NULL . +.Pf * Fa data +contains a string if +.Pf * Fa flags Ns & Ns Dv ERR_TXT_STRING +is true. +.Pp +An application +.Sy MUST NOT +free the +.Pf * Fa data +pointer (or any other pointers returned by these functions) with +.Xr free 3 +as freeing is handled automatically by the error library. +.Sh RETURN VALUES +The error code, or 0 if there is no error in the queue. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_error_string 3 , +.Xr ERR_GET_LIB 3 +.Sh HISTORY +.Fn ERR_get_error +and +.Fn ERR_peek_error +first appeared in SSLeay 0.4.4. +.Fn ERR_get_error_line +and +.Fn ERR_peek_error_line +first appeared in SSLeay 0.6.0. +.Fn ERR_get_error_line_data +and +.Fn ERR_peek_error_line_data +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn ERR_peek_last_error , +.Fn ERR_peek_last_error_line , +and +.Fn ERR_peek_last_error_line_data +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/ERR_load_crypto_strings.3 b/static/openbsd/man3/ERR_load_crypto_strings.3 new file mode 100644 index 00000000..13da93e2 --- /dev/null +++ b/static/openbsd/man3/ERR_load_crypto_strings.3 @@ -0,0 +1,153 @@ +.\" $OpenBSD: ERR_load_crypto_strings.3,v 1.14 2025/06/08 22:58:09 schwarze Exp $ +.\" full merge up to: OpenSSL f672aee4 Feb 9 11:52:40 2016 -0500 +.\" selective merge up to: OpenSSL b3696a55 Sep 2 09:35:50 2017 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 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. +.\" +.\" The original file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR_LOAD_CRYPTO_STRINGS 3 +.Os +.Sh NAME +.Nm ERR_load_crypto_strings , +.Nm ERR_free_strings , +.Nm SSL_load_error_strings +.Nd load and free OpenSSL error strings +.\" The following functions are intentionally undocumented +.\" because they are merely subroutines of ERR_load_crypto_strings(3) +.\" and should not have been made a part of the API: +.\" ERR_load_ASN1_strings() +.\" ERR_load_BIO_strings() +.\" ERR_load_BN_strings() +.\" ERR_load_BUF_strings() +.\" ERR_load_CMS_strings() +.\" ERR_load_CONF_strings() +.\" ERR_load_CRYPTO_strings() +.\" ERR_load_DH_strings() +.\" ERR_load_DSA_strings() +.\" ERR_load_EC_strings() +.\" ERR_load_ERR_strings() +.\" ERR_load_EVP_strings() +.\" ERR_load_OBJ_strings() +.\" ERR_load_OCSP_strings() +.\" ERR_load_PEM_strings() +.\" ERR_load_PKCS12_strings() +.\" ERR_load_PKCS7_strings() +.\" ERR_load_RAND_strings() +.\" ERR_load_RSA_strings() +.\" ERR_load_TS_strings() +.\" ERR_load_UI_strings() +.\" ERR_load_X509_strings() +.\" ERR_load_X509V3_strings() +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft void +.Fn ERR_load_crypto_strings void +.Ft void +.Fn ERR_free_strings void +.Pp +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_load_error_strings void +.Sh DESCRIPTION +These functions are deprecated. +It is never useful for any application program to call any of them explicitly. +The library automatically calls them internally whenever needed. +.Pp +.Fn ERR_load_crypto_strings +registers the error strings for all +.Xr crypto 3 +functions. +.Fn SSL_load_error_strings +does the same, but also registers the +.Xr ssl 3 +error strings. +.Pp +If the error strings were already loaded before, no action occurs. +.Pp +.Fn ERR_free_strings +frees all previously loaded error strings. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_error_string 3 , +.Xr OPENSSL_config 3 +.Sh HISTORY +.Fn ERR_load_crypto_strings +and +.Fn SSL_load_error_strings +first appeared in SSLeay 0.4.4. +.Fn ERR_free_strings +first appeared in SSLeay 0.5.1. +These functions been available since +.Ox 2.4 . +.Sh BUGS +Even though the error strings are already compiled into the object +code of the library as static strings, these functions store them +again using dynamically allocated memory on the heap. +That may fail if insufficient memory is available, +but these functions do not report such errors. +Instead, they fail silently, possibly having registered none or only +a part of the strings requested. diff --git a/static/openbsd/man3/ERR_load_strings.3 b/static/openbsd/man3/ERR_load_strings.3 new file mode 100644 index 00000000..96977424 --- /dev/null +++ b/static/openbsd/man3/ERR_load_strings.3 @@ -0,0 +1,117 @@ +.\" $OpenBSD: ERR_load_strings.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL 05ea606a May 20 20:52:46 2016 -0400 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR_LOAD_STRINGS 3 +.Os +.Sh NAME +.Nm ERR_load_strings , +.Nm ERR_PACK , +.Nm ERR_get_next_error_library +.Nd load arbitrary OpenSSL error strings +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft void +.Fo ERR_load_strings +.Fa "int lib" +.Fa "ERR_STRING_DATA str[]" +.Fc +.Ft unsigned long +.Fo ERR_PACK +.Fa "int lib" +.Fa "int func" +.Fa "int reason" +.Fc +.Ft int +.Fn ERR_get_next_error_library void +.Sh DESCRIPTION +.Fn ERR_load_strings +registers error strings for library number +.Fa lib . +.Pp +.Fa str +is an array of error string data: +.Bd -literal -offset indent +typedef struct ERR_string_data_st { + unsigned long error; + char *string; +} ERR_STRING_DATA; +.Ed +.Pp +The error code is generated from the library number and a function and +reason code: +.Pp +.Dl error = ERR_PACK(lib, func, reason) +.Pp +.Fn ERR_PACK +is a macro. +.Pp +The last entry in the array is +.Brq 0 , Dv NULL . +.Pp +.Fn ERR_get_next_error_library +can be used to assign library numbers to user libraries at runtime. +.Sh RETURN VALUES +.Fn ERR_PACK +returns the error code. +.Fn ERR_get_next_error_library +returns a new library number. +.Sh SEE ALSO +.Xr ERR 3 +.Sh HISTORY +.Fn ERR_load_strings +and +.Fn ERR_PACK +first appeared in SSLeay 0.4.4. +.Fn ERR_get_next_error_library +first appeared in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/ERR_print_errors.3 b/static/openbsd/man3/ERR_print_errors.3 new file mode 100644 index 00000000..4d6f8d37 --- /dev/null +++ b/static/openbsd/man3/ERR_print_errors.3 @@ -0,0 +1,123 @@ +.\" $OpenBSD: ERR_print_errors.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller , +.\" with additions by Rich Salz . +.\" Copyright (c) 2000, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR_PRINT_ERRORS 3 +.Os +.Sh NAME +.Nm ERR_print_errors , +.Nm ERR_print_errors_fp , +.Nm ERR_print_errors_cb +.Nd print OpenSSL error messages +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft void +.Fo ERR_print_errors +.Fa "BIO *bp" +.Fc +.Ft void +.Fo ERR_print_errors_fp +.Fa "FILE *fp" +.Fc +.Ft void +.Fo ERR_print_errors_cb +.Fa "int (*cb)(const char *str, size_t len, void *u)" +.Fa "void *u" +.Fc +.Sh DESCRIPTION +.Fn ERR_print_errors +is a convenience function that prints the error strings for all errors +that OpenSSL has recorded to +.Fa bp , +thus emptying the error queue. +.Pp +.Fn ERR_print_errors_fp +is the same, except that the output goes to a +.Vt FILE . +.Pp +.Fn ERR_print_errors_cb +is the same, except that the callback function, +.Fa cb , +is called for each error line with the string, length, and userdata +.Fa u +as the callback parameters. +.Pp +The error strings have the following format: +.Bd -literal +[pid]:error:[error code]:[library name]:[function name]:[reason string]: +[file name]:[line]:[optional text message] +.Ed +.Pp +The error code is an 8-digit hexadecimal number. +The library name, the function name, and the reason string are ASCII +text, as is the optional text message 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 SEE ALSO +.Xr ERR 3 , +.Xr ERR_error_string 3 , +.Xr ERR_get_error 3 , +.Xr ERR_load_crypto_strings 3 , +.Xr SSL_load_error_strings 3 +.Sh HISTORY +.Fn ERR_print_errors +first appeared in SSLeay 0.4.5. +.Fn ERR_print_errors_fp +first appeared in SSLeay 0.6.0. +Both functions have been available since +.Ox 2.4 . +.Pp +.Fn ERR_print_errors_cb +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/ERR_put_error.3 b/static/openbsd/man3/ERR_put_error.3 new file mode 100644 index 00000000..1af0e378 --- /dev/null +++ b/static/openbsd/man3/ERR_put_error.3 @@ -0,0 +1,126 @@ +.\" $OpenBSD: ERR_put_error.3,v 1.12 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR_PUT_ERROR 3 +.Os +.Sh NAME +.Nm ERR_put_error +.Nd record an OpenSSL error +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft void +.Fo ERR_put_error +.Fa "int lib" +.Fa "int func" +.Fa "int reason" +.Fa "const char *file" +.Fa "int line" +.Fc +.Sh DESCRIPTION +.Fn ERR_put_error +adds an error code to the thread's error queue. +It signals that the error of reason code +.Fa reason +occurred in function +.Fa func +of library +.Fa lib , +in line number +.Fa line +of +.Fa file . +This function is usually called by a macro. +.Pp +.Xr ERR_load_strings 3 +can be used to register error strings so that the application can +generate human-readable error messages for the error code. +.Pp +Each sub-library has a specific macro +.Fn XXXerr f r +that is used to report errors. +Its first argument is a function code +.Dv XXX_F_* ; +the second argument is a reason code +.Dv XXX_R_* . +Function codes are derived from the function names +whereas reason codes consist of textual error descriptions. +For example, the function +.Fn ssl23_read +reports a "handshake failure" as follows: +.Pp +.Dl SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); +.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 "SSL23_READ" +in the above example. +.Pp +The trailing section of a reason code (after the "_R_") is translated +into lower case and underscores changed to spaces. +.Pp +Although a library will normally report errors using its own specific +.Fn XXXerr +macro, another library's macro can be used. +This is normally only done when a library wants to include ASN.1 code +which must use the +.Fn ASN1err +macro. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_asprintf_error_data 3 , +.Xr ERR_load_strings 3 +.Sh HISTORY +.Fn ERR_put_error +first appeared in SSLeay 0.4.4 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/ERR_remove_state.3 b/static/openbsd/man3/ERR_remove_state.3 new file mode 100644 index 00000000..c05810d7 --- /dev/null +++ b/static/openbsd/man3/ERR_remove_state.3 @@ -0,0 +1,109 @@ +.\" $OpenBSD: ERR_remove_state.3,v 1.8 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 +.\" +.\" This file was written by Ulf Moeller and +.\" Matt Caswell . +.\" Copyright (c) 2000, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR_REMOVE_STATE 3 +.Os +.Sh NAME +.Nm ERR_remove_thread_state , +.Nm ERR_remove_state +.Nd free a thread's OpenSSL error queue +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft void +.Fo ERR_remove_thread_state +.Fa "const CRYPTO_THREADID *tid" +.Fc +.Pp +Deprecated: +.Pp +.Ft void +.Fo ERR_remove_state +.Fa "unsigned long pid" +.Fc +.Sh DESCRIPTION +.Fn ERR_remove_thread_state +frees the error queue associated with thread +.Fa tid . +If +.Fa tid +is +.Dv NULL , +the current thread will have its error queue removed. +.Pp +Since error queue data structures are allocated automatically for new +threads, they must be freed when threads are terminated in order to +avoid memory leaks. +.Pp +.Fn ERR_remove_state +is deprecated and has been replaced by +.Fn ERR_remove_thread_state . +Since threads in OpenSSL are no longer identified by unsigned long +values, any argument to this function is ignored. +Calling +.Fn ERR_remove_state +is equivalent to +.Fn ERR_remove_thread_state NULL . +.Sh SEE ALSO +.Xr ERR 3 +.Sh HISTORY +.Fn ERR_remove_state +first appeared in SSLeay 0.6.1 and has been available since +.Ox 2.4 . +.Pp +It was deprecated in OpenSSL 1.0.0 and +.Ox 4.9 +when +.Fn ERR_remove_thread_state +was introduced and thread IDs were introduced to identify threads +instead of +.Vt unsigned long . diff --git a/static/openbsd/man3/ERR_set_mark.3 b/static/openbsd/man3/ERR_set_mark.3 new file mode 100644 index 00000000..88b1be88 --- /dev/null +++ b/static/openbsd/man3/ERR_set_mark.3 @@ -0,0 +1,87 @@ +.\" $OpenBSD: ERR_set_mark.3,v 1.5 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Richard Levitte . +.\" Copyright (c) 2003 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR_SET_MARK 3 +.Os +.Sh NAME +.Nm ERR_set_mark , +.Nm ERR_pop_to_mark +.Nd set marks and pop OpenSSL errors until mark +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Ft int +.Fn ERR_set_mark void +.Ft int +.Fn ERR_pop_to_mark void +.Sh DESCRIPTION +.Fn ERR_set_mark +sets a mark on the current topmost error record if there is one. +.Pp +.Fn ERR_pop_to_mark +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. +.Sh RETURN VALUES +.Fn ERR_set_mark +returns 0 if the error stack is empty, otherwise 1. +.Pp +.Fn ERR_pop_to_mark +returns 0 if there was no mark in the error stack, which implies that +the stack became empty, otherwise 1. +.Sh SEE ALSO +.Xr ERR 3 +.Sh HISTORY +.Fn ERR_set_mark +and +.Fn ERR_pop_to_mark +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/ESS_SIGNING_CERT_new.3 b/static/openbsd/man3/ESS_SIGNING_CERT_new.3 new file mode 100644 index 00000000..7014d008 --- /dev/null +++ b/static/openbsd/man3/ESS_SIGNING_CERT_new.3 @@ -0,0 +1,118 @@ +.\" $OpenBSD: ESS_SIGNING_CERT_new.3,v 1.6 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt ESS_SIGNING_CERT_NEW 3 +.Os +.Sh NAME +.Nm ESS_SIGNING_CERT_new , +.Nm ESS_SIGNING_CERT_free , +.Nm ESS_CERT_ID_new , +.Nm ESS_CERT_ID_free , +.Nm ESS_ISSUER_SERIAL_new , +.Nm ESS_ISSUER_SERIAL_free +.Nd signing certificates for S/MIME +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ts.h +.Ft ESS_SIGNING_CERT * +.Fn ESS_SIGNING_CERT_new void +.Ft void +.Fn ESS_SIGNING_CERT_free "ESS_SIGNING_CERT *signing_cert" +.Ft ESS_CERT_ID * +.Fn ESS_CERT_ID_new void +.Ft void +.Fn ESS_CERT_ID_free "ESS_CERT_ID *cert_id" +.Ft ESS_ISSUER_SERIAL * +.Fn ESS_ISSUER_SERIAL_new void +.Ft void +.Fn ESS_ISSUER_SERIAL_free "ESS_ISSUER_SERIAL *issuer_serial" +.Sh DESCRIPTION +The signing certificate may be included in the signedAttributes +field of a +.Vt SignerInfo +structure to mitigate simple substitution and re-issue attacks. +.Pp +.Fn ESS_SIGNING_CERT_new +allocates and initializes an empty +.Vt ESS_SIGNING_CERT +object, representing an ASN.1 +.Vt SigningCertificate +structure defined in RFC 2634 section 5.4. +It can hold the certificate used for signing the data, +additional authorization certificates that can be used during +validation, and policies applying to the certificate. +.Fn ESS_SIGNING_CERT_free +frees +.Fa signing_cert . +.Pp +.Fn ESS_CERT_ID_new +allocates and initializes an empty +.Vt ESS_CERT_ID +object, representing an ASN.1 +.Vt ESSCertID +structure defined in RFC 2634 section 5.4.1. +Such objects can be used inside +.Vt ESS_SIGNING_CERT +objects, and each one can hold a SHA1 hash of one certificate. +.Fn ESS_CERT_ID_free +frees +.Fa cert_id . +.Pp +.Fn ESS_ISSUER_SERIAL_new +allocates and initializes an empty +.Vt ESS_ISSUER_SERIAL +object, representing an ASN.1 +.Vt IssuerSerial +structure defined in RFC 2634 section 5.4.1. +It can hold an issuer name and a serial number and can be included in an +.Vt ESS_CERT_ID +object, which is useful for additional authorization certificates, +but redundant for the signing certificate itself. +.Fn ESS_ISSUER_SERIAL_free +frees +.Fa issuer_serial . +.Sh RETURN VALUES +.Fn ESS_SIGNING_CERT_new , +.Fn ESS_CERT_ID_new , +and +.Fn ESS_ISSUER_SERIAL_new +return the new +.Vt ESS_SIGNING_CERT , +.Vt ESS_CERT_ID , +or +.Vt ESS_ISSUER_SERIAL +object, respectively, or +.Dv NULL +if an error occurred. +.Sh SEE ALSO +.Xr d2i_ESS_SIGNING_CERT 3 +.Sh STANDARDS +RFC 2634: Enhanced Security Services for S/MIME, +section 5: Signing Certificate Attribute +.Pp +Note that RFC 2634 has been updated by RFC 5035: +Enhanced Security Services (ESS) Update: +Adding CertID Algorithm Agility. +But the current implementation only supports the +Signing Certificate Attribute Definition Version 1 +according to RFC 2634, not the +Signing Certificate Attribute Definition Version 2 +according to RFC 5035. +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.0 +and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_AEAD_CTX_init.3 b/static/openbsd/man3/EVP_AEAD_CTX_init.3 new file mode 100644 index 00000000..41a829c6 --- /dev/null +++ b/static/openbsd/man3/EVP_AEAD_CTX_init.3 @@ -0,0 +1,412 @@ +.\" $OpenBSD: EVP_AEAD_CTX_init.3,v 1.17 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2014, Google Inc. +.\" Parts of the text were written by Adam Langley and David Benjamin. +.\" Copyright (c) 2015 Reyk Floeter +.\" Copyright (c) 2023 Ingo Schwarze +.\" +.\" 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 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: June 8 2025 $ +.Dt EVP_AEAD_CTX_INIT 3 +.Os +.Sh NAME +.Nm EVP_AEAD_CTX_new , +.Nm EVP_AEAD_CTX_free , +.Nm EVP_AEAD_CTX_init , +.Nm EVP_AEAD_CTX_cleanup , +.Nm EVP_AEAD_CTX_open , +.Nm EVP_AEAD_CTX_seal , +.Nm EVP_AEAD_key_length , +.Nm EVP_AEAD_max_overhead , +.Nm EVP_AEAD_max_tag_len , +.Nm EVP_AEAD_nonce_length , +.Nm EVP_aead_aes_128_gcm , +.Nm EVP_aead_aes_256_gcm , +.Nm EVP_aead_chacha20_poly1305 , +.Nm EVP_aead_xchacha20_poly1305 +.Nd authenticated encryption with additional data +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft EVP_AEAD_CTX * +.Fn EVP_AEAD_CTX_new void +.Ft void +.Fo EVP_AEAD_CTX_free +.Fa "EVP_AEAD_CTX *ctx" +.Fc +.Ft int +.Fo EVP_AEAD_CTX_init +.Fa "EVP_AEAD_CTX *ctx" +.Fa "const EVP_AEAD *aead" +.Fa "const unsigned char *key" +.Fa "size_t key_len" +.Fa "size_t tag_len" +.Fa "ENGINE *engine" +.Fc +.Ft void +.Fo EVP_AEAD_CTX_cleanup +.Fa "EVP_AEAD_CTX *ctx" +.Fc +.Ft int +.Fo EVP_AEAD_CTX_open +.Fa "const EVP_AEAD_CTX *ctx" +.Fa "unsigned char *out" +.Fa "size_t *out_len" +.Fa "size_t max_out_len" +.Fa "const unsigned char *nonce" +.Fa "size_t nonce_len" +.Fa "const unsigned char *in" +.Fa "size_t in_len" +.Fa "const unsigned char *ad" +.Fa "size_t ad_len" +.Fc +.Ft int +.Fo EVP_AEAD_CTX_seal +.Fa "const EVP_AEAD_CTX *ctx" +.Fa "unsigned char *out" +.Fa "size_t *out_len" +.Fa "size_t max_out_len" +.Fa "const unsigned char *nonce" +.Fa "size_t nonce_len" +.Fa "const unsigned char *in" +.Fa "size_t in_len" +.Fa "const unsigned char *ad" +.Fa "size_t ad_len" +.Fc +.Ft size_t +.Fo EVP_AEAD_key_length +.Fa "const EVP_AEAD *aead" +.Fc +.Ft size_t +.Fo EVP_AEAD_max_overhead +.Fa "const EVP_AEAD *aead" +.Fc +.Ft size_t +.Fo EVP_AEAD_max_tag_len +.Fa "const EVP_AEAD *aead" +.Fc +.Ft size_t +.Fo EVP_AEAD_nonce_length +.Fa "const EVP_AEAD *aead" +.Fc +.Ft const EVP_AEAD * +.Fo EVP_aead_aes_128_gcm +.Fa void +.Fc +.Ft const EVP_AEAD * +.Fo EVP_aead_aes_256_gcm +.Fa void +.Fc +.Ft const EVP_AEAD * +.Fo EVP_aead_chacha20_poly1305 +.Fa void +.Fc +.Ft const EVP_AEAD * +.Fo EVP_aead_xchacha20_poly1305 +.Fa void +.Fc +.Sh DESCRIPTION +AEAD (Authenticated Encryption with Additional Data) couples +confidentiality and integrity in a single primitive. +AEAD algorithms take a key and can then seal and open individual +messages. +Each message has a unique, per-message nonce and, optionally, additional +data which is authenticated but not included in the output. +.Pp +.Fn EVP_AEAD_CTX_new +allocates a new context for use with +.Fn EVP_AEAD_CTX_init . +It can be cleaned up for reuse with +.Fn EVP_AEAD_CTX_cleanup +and must be freed with +.Fn EVP_AEAD_CTX_free . +.Pp +.Fn EVP_AEAD_CTX_free +cleans up +.Fa ctx +and frees the space allocated to it. +.Pp +.Fn EVP_AEAD_CTX_init +initializes the context +.Fa ctx +for the given AEAD algorithm +.Fa aead . +The +.Fa engine +argument must be +.Dv NULL +for the default implementation; +other values are not supported. +Authentication tags may be truncated by passing a tag length. +A +.Fa tag_len +argument of +.Dv EVP_AEAD_DEFAULT_TAG_LENGTH , +which has the value 0, causes the default tag length to be used. +.Pp +.Fn EVP_AEAD_CTX_cleanup +frees any data allocated for the context +.Fa ctx . +After +.Fn EVP_AEAD_CTX_cleanup , +.Fa ctx +is in the same state as after +.Fn EVP_AEAD_CTX_new . +.Pp +.Fn EVP_AEAD_CTX_open +authenticates the input +.Fa in +and optional additional data +.Fa ad , +decrypting the input and writing it as output +.Fa out . +This function may be called (with the same +.Vt EVP_AEAD_CTX ) +concurrently with itself or with +.Fn EVP_AEAD_CTX_seal . +At most the number of input bytes are written as output. +In order to ensure success, +.Fa max_out_len +should be at least the same as the input length +.Fa in_len . +On successful return +.Fa out_len +is set to the actual number of bytes written. +The length of the +.Fa nonce +specified with +.Fa nonce_len +must be equal to the result of EVP_AEAD_nonce_length for this AEAD. +.Fn EVP_AEAD_CTX_open +never results in partial output. +If +.Fa max_out_len +is insufficient, zero will be returned and +.Fa out_len +will be set to zero. +If the input and output are aliased then +.Fa out +must be <= +.Fa in . +.Pp +.Fn EVP_AEAD_CTX_seal +encrypts and authenticates the input and authenticates any additional +data provided in +.Fa ad , +the encrypted input and authentication tag being written as output +.Fa out . +This function may be called (with the same +.Vt EVP_AEAD_CTX ) +concurrently with itself or with +.Fn EVP_AEAD_CTX_open . +At most +.Fa max_out_len +bytes are written as output and, in order to ensure success, this value +should be the +.Fa in_len +plus the result of +.Fn EVP_AEAD_max_overhead . +On successful return, +.Fa out_len +is set to the actual number of bytes written. +The length of the +.Fa nonce +specified with +.Fa nonce_len +must be equal to the result of +.Fn EVP_AEAD_nonce_length +for this AEAD. +.Fn EVP_AEAD_CTX_seal +never results in a partial output. +If +.Fa max_out_len +is insufficient, zero will be returned and +.Fa out_len +will be set to zero. +If the input and output are aliased then +.Fa out +must be <= +.Fa in . +.Pp +.Fn EVP_AEAD_key_length , +.Fn EVP_AEAD_max_overhead , +.Fn EVP_AEAD_max_tag_len , +and +.Fn EVP_AEAD_nonce_length +provide information about the AEAD algorithm +.Fa aead . +.Pp +.Fn EVP_AEAD_max_tag_len +returns the maximum tag length that can be used with the given +.Fa aead . +This is the largest value that can be passed as the +.Fa tag_len +argument to +.Fn EVP_AEAD_CTX_init . +No built-in +.Vt EVP_AEAD +object has a maximum tag length larger than the constant +.Dv EVP_AEAD_MAX_TAG_LENGTH . +.Pp +All cipher algorithms have a fixed key length unless otherwise stated. +The following ciphers are available: +.Bl -tag -width Ds -offset indent +.It Fn EVP_aead_aes_128_gcm +AES-128 in Galois Counter Mode, using a +.Fa key_len +of 16 bytes and a +.Fa nonce_len +of 12 bytes. +.It Fn EVP_aead_aes_256_gcm +AES-256 in Galois Counter Mode, using a +.Fa key_len +of 32 bytes and a +.Fa nonce_len +of 12 bytes. +.It Fn EVP_aead_chacha20_poly1305 +ChaCha20 with a Poly1305 authenticator, using a +.Fa key_len +of 32 bytes and a +.Fa nonce_len +of 12 bytes. +The constant +.Dv EVP_CHACHAPOLY_TLS_TAG_LEN +specifies the length of the authentication tag in bytes and has a value of 16. +.It Fn EVP_aead_xchacha20_poly1305 +XChaCha20 with a Poly1305 authenticator, using a +.Fa key_len +of 32 bytes and a +.Fa nonce_len +of 24 bytes. +.El +.Pp +Unless compatibility with other implementations +like OpenSSL or BoringSSL is required, using the +.Sy EVP_AEAD +interface to AEAD ciphers is recommended +in preference to the functions documented in the +.Xr EVP_EncryptInit 3 , +.Xr EVP_aes_256_gcm 3 , +and +.Xr EVP_chacha20_poly1305 3 +manual pages. +The code then becomes transparent to the AEAD cipher used +and much more flexible. +It is also safer to use as it prevents common mistakes with the EVP APIs. +.Sh RETURN VALUES +.Fn EVP_AEAD_CTX_new +returns the new +.Vt EVP_AEAD_CTX +object on success; +otherwise +.Dv NULL +is returned and +.Va errno +is set to +.Er ENOMEM . +.Pp +.Fn EVP_AEAD_CTX_init , +.Fn EVP_AEAD_CTX_open , +and +.Fn EVP_AEAD_CTX_seal +return 1 for success or zero for failure. +.Pp +.Fn EVP_AEAD_key_length +returns the length of the key used for this AEAD. +.Pp +.Fn EVP_AEAD_max_overhead +returns the maximum number of additional bytes added by the act of +sealing data with the AEAD. +.Pp +.Fn EVP_AEAD_max_tag_len +returns the maximum tag length when using this AEAD. +.Pp +.Fn EVP_AEAD_nonce_length +returns the length of the per-message nonce. +.Sh EXAMPLES +Encrypt a string using ChaCha20-Poly1305: +.Bd -literal -offset indent +const EVP_AEAD *aead = EVP_aead_chacha20_poly1305(); +static const unsigned char nonce[32] = {0}; +size_t buf_len, nonce_len; +EVP_AEAD_CTX *ctx; + +ctx = EVP_AEAD_CTX_new(); +EVP_AEAD_CTX_init(ctx, aead, key32, EVP_AEAD_key_length(aead), + EVP_AEAD_DEFAULT_TAG_LENGTH, NULL); +nonce_len = EVP_AEAD_nonce_length(aead); + +EVP_AEAD_CTX_seal(ctx, out, &out_len, BUFSIZE, nonce, + nonce_len, in, in_len, NULL, 0); + +EVP_AEAD_CTX_free(ctx); +.Ed +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 +.Sh STANDARDS +.Rs +.%A A. Langley +.%A W. Chang +.%A N. Mavrogiannopoulos +.%A J. Strombergson +.%A S. Josefsson +.%D June 2016 +.%R RFC 7905 +.%T ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS) +.Re +.Pp +.Rs +.%A S. Arciszewski +.%D October 2018 +.%R draft-arciszewski-xchacha-02 +.%T XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305 +.Re +.Sh HISTORY +AEAD is based on the implementation by +.An Adam Langley +.\" OpenSSL commit 9a8646510b Sep 9 12:13:24 2013 -0400 +for Chromium/BoringSSL and first appeared in +.Ox 5.6 . +.Pp +.Fn EVP_AEAD_CTX_new +and +.Fn EVP_AEAD_CTX_free +first appeared in +.Ox 7.1 . +.Sh CAVEATS +The original publications and code by +.An Adam Langley +used a modified AEAD construction that is incompatible with the common +style used by AEAD in TLS and incompatible with RFC 7905: +.Pp +.Rs +.%A A. Langley +.%A W. Chang +.%D November 2013 +.%R draft-agl-tls-chacha20poly1305-04 +.%T ChaCha20 and Poly1305 based Cipher Suites for TLS +.Re +.Pp +.Rs +.%A Y. Nir +.%A A. Langley +.%D June 2018 +.%R RFC 8439 +.%T ChaCha20 and Poly1305 for IETF Protocols +.Re +.Pp +In particular, the original version used a +.Fa nonce_len +of 8 bytes. diff --git a/static/openbsd/man3/EVP_BytesToKey.3 b/static/openbsd/man3/EVP_BytesToKey.3 new file mode 100644 index 00000000..06033574 --- /dev/null +++ b/static/openbsd/man3/EVP_BytesToKey.3 @@ -0,0 +1,146 @@ +.\" $OpenBSD: EVP_BytesToKey.3,v 1.10 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2001, 2011, 2013, 2014, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_BYTESTOKEY 3 +.Os +.Sh NAME +.Nm EVP_BytesToKey +.Nd password based encryption routine +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_BytesToKey +.Fa "const EVP_CIPHER *type" +.Fa "const EVP_MD *md" +.Fa "const unsigned char *salt" +.Fa "const unsigned char *data" +.Fa "int datal" +.Fa "int count" +.Fa "unsigned char *key" +.Fa "unsigned char *iv" +.Fc +.Sh DESCRIPTION +.Fn EVP_BytesToKey +derives a key and IV from various parameters. +.Fa type +is the cipher to derive the key and IV for. +.Fa md +is the message digest to use. +The +.Fa salt +parameter is used as a salt in the derivation: +it should point to a buffer containing +.Dv PKCS5_SALT_LEN No = 8 +bytes or +.Dv NULL +if no salt is used. +.Fa data +is a buffer containing +.Fa datal +bytes which is used to derive the keying data. +.Fa count +is the iteration count to use. +The derived key and IV will be written to +.Fa key +and +.Fa iv , +respectively. +.Pp +A typical application of this function is to derive keying material for +an encryption algorithm from a password in the +.Fa data +parameter. +.Pp +Increasing the +.Fa count +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 MD5 +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 more standard algorithms such as PBKDF2 as +defined in PKCS#5v2.1 for key derivation. +.Sh 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 recursively as: +.Pp +.Dl D_i = HASH^count(D_(i-1) || data || salt) +.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 +If +.Fa data +is +.Dv NULL , +.Fn EVP_BytesToKey +returns the number of bytes needed to store the derived key. +Otherwise, +.Fn EVP_BytesToKey +returns the size of the derived key in bytes or 0 on error. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 , +.Xr PKCS5_PBKDF2_HMAC 3 +.Sh HISTORY +.Fn EVP_BytesToKey +first appeared in SSLeay 0.5.1 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/EVP_CIPHER_CTX_ctrl.3 b/static/openbsd/man3/EVP_CIPHER_CTX_ctrl.3 new file mode 100644 index 00000000..8aaf2cc3 --- /dev/null +++ b/static/openbsd/man3/EVP_CIPHER_CTX_ctrl.3 @@ -0,0 +1,262 @@ +.\" $OpenBSD: EVP_CIPHER_CTX_ctrl.3,v 1.5 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2023 Ingo Schwarze +.\" Copyright (c) 2018 Damien 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2001, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_CIPHER_CTX_CTRL 3 +.Os +.Sh NAME +.Nm EVP_CIPHER_CTX_ctrl , +.Nm EVP_CIPHER_CTX_set_padding , +.Nm EVP_CIPHER_CTX_set_key_length , +.Nm EVP_CIPHER_CTX_key_length , +.Nm EVP_CIPHER_key_length , +.Nm EVP_CIPHER_CTX_iv_length , +.Nm EVP_CIPHER_iv_length , +.Nm EVP_CIPHER_CTX_set_iv , +.Nm EVP_CIPHER_CTX_get_iv +.Nd configure EVP cipher contexts +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_CIPHER_CTX_ctrl +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "int type" +.Fa "int arg" +.Fa "void *ptr" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_set_padding +.Fa "EVP_CIPHER_CTX *x" +.Fa "int padding" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_set_key_length +.Fa "EVP_CIPHER_CTX *x" +.Fa "int keylen" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_key_length +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Ft int +.Fo EVP_CIPHER_key_length +.Fa "const EVP_CIPHER *e" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_iv_length +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Ft int +.Fo EVP_CIPHER_iv_length +.Fa "const EVP_CIPHER *e" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_set_iv +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const unsigned char *iv" +.Fa "size_t len" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_get_iv +.Fa "const EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *iv" +.Fa "size_t len" +.Fc +.Sh DESCRIPTION +.Fn EVP_CIPHER_CTX_ctrl +allows various cipher specific parameters to be determined and set. +Currently only the RC2 effective key length can be set; see +.Xr EVP_rc2_cbc 3 +for details. +.Pp +.Fn 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 +.Xr EVP_EncryptInit_ex 3 , +.Xr EVP_DecryptInit_ex 3 , +or +.Xr EVP_CipherInit_ex 3 . +By default encryption operations are padded using standard block padding +and the padding is checked and removed when decrypting. +If the +.Fa padding +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. +.Pp +.Fn EVP_CIPHER_CTX_set_key_length +sets the key length of the cipher ctx. +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. +.Pp +.Fn EVP_CIPHER_CTX_key_length +and +.Fn EVP_CIPHER_key_length +return the key length of a cipher when passed an +.Vt EVP_CIPHER_CTX +or +.Vt EVP_CIPHER +structure. +The constant +.Dv EVP_MAX_KEY_LENGTH +is the maximum key length for all ciphers. +Note: although +.Fn EVP_CIPHER_key_length +is fixed for a given cipher, the value of +.Fn EVP_CIPHER_CTX_key_length +may be different for variable key length ciphers. +.Pp +.Fn EVP_CIPHER_CTX_iv_length +and +.Fn EVP_CIPHER_iv_length +return the IV length of a cipher when passed an +.Vt EVP_CIPHER_CTX +or +.Vt EVP_CIPHER . +They will return zero if the cipher does not use an IV. +.Fn EVP_CIPHER_CTX_iv_length +can fail and return \-1. +The constant +.Dv EVP_MAX_IV_LENGTH +is the maximum IV length for all ciphers. +.Pp +.Fn EVP_CIPHER_CTX_set_iv +and +.Fn EVP_CIPHER_CTX_get_iv +set and retrieve the IV for an +.Vt EVP_CIPHER_CTX , +respectively. +In both cases, the specified IV length must exactly equal the expected +IV length for the context as returned by +.Fn EVP_CIPHER_CTX_iv_length . +.Sh RETURN VALUES +.Fn EVP_CIPHER_CTX_ctrl +returns 1 for success or 0 for failure. +Some implementations may return negative values for some errors. +.Pp +.Fn EVP_CIPHER_CTX_set_padding +always returns 1. +.Pp +.Fn EVP_CIPHER_CTX_set_key_length , +.Fn EVP_CIPHER_CTX_set_iv , +and +.Fn EVP_CIPHER_CTX_get_iv +return 1 for success or 0 for failure. +.Pp +.Fn EVP_CIPHER_CTX_key_length +and +.Fn EVP_CIPHER_key_length +return the key length. +.Pp +.Fn EVP_CIPHER_CTX_iv_length +and +.Fn EVP_CIPHER_iv_length +return the IV length or zero if the cipher does not use an IV. +.Fn EVP_CIPHER_CTX_iv_length +can fail and return \-1. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_CIPHER_nid 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn EVP_CIPHER_CTX_key_length , +.Fn EVP_CIPHER_key_length , +.Fn EVP_CIPHER_CTX_iv_length , +and +.Fn EVP_CIPHER_iv_length +first appeared in SSLeay 0.6.5 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_CIPHER_CTX_ctrl +and +.Fn EVP_CIPHER_CTX_set_key_length +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Pp +.Fn EVP_CIPHER_CTX_set_padding +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Pp +.Fn EVP_CIPHER_CTX_set_iv +and +.Fn EVP_CIPHER_CTX_get_iv +first appeared in LibreSSL 2.8.1 and have been available since +.Ox 6.4 . +.Sh BUGS +.Dv EVP_MAX_KEY_LENGTH +and +.Dv EVP_MAX_IV_LENGTH +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 +.Dv EVP_MAX_KEY_LENGTH +bytes. diff --git a/static/openbsd/man3/EVP_CIPHER_CTX_get_cipher_data.3 b/static/openbsd/man3/EVP_CIPHER_CTX_get_cipher_data.3 new file mode 100644 index 00000000..a549ea25 --- /dev/null +++ b/static/openbsd/man3/EVP_CIPHER_CTX_get_cipher_data.3 @@ -0,0 +1,147 @@ +.\" $OpenBSD: EVP_CIPHER_CTX_get_cipher_data.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Matt Caswell . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_CIPHER_CTX_GET_CIPHER_DATA 3 +.Os +.Sh NAME +.Nm EVP_CIPHER_CTX_get_cipher_data , +.Nm EVP_CIPHER_CTX_set_cipher_data , +.Nm EVP_CIPHER_CTX_buf_noconst +.Nd inspect and modify EVP_CIPHER_CTX objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft void * +.Fo EVP_CIPHER_CTX_get_cipher_data +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Ft void * +.Fo EVP_CIPHER_CTX_set_cipher_data +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "void *cipher_data" +.Fc +.Ft unsigned char * +.Fo EVP_CIPHER_CTX_buf_noconst +.Fa "EVP_CIPHER_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn EVP_CIPHER_CTX_get_cipher_data +returns a pointer to the cipher data of +.Fa ctx . +The format and content of this data is specific to the algorithm +and 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 +.Fn EVP_CIPHER_CTX_set_cipher_data +allows an application or engine to replace the existing cipher data +with new data, transferring ownership of +.Fa cipher_data +to the +.Fa ctx +object. +A pointer to any existing cipher data is returned from this function. +If the old data is no longer required, +it should be freed through a call to +.Xr free 3 . +.Pp +.Fn EVP_CIPHER_CTX_buf_noconst +provides engines and custom cipher implementations +with access to the internal buffer that +.Xr EVP_EncryptUpdate 3 +copies input data into before encrypting it. +This function can for example be used +inside callback functions installed with +.Xr EVP_CIPHER_meth_set_do_cipher 3 . +.Sh RETURN VALUES +.Fn EVP_CIPHER_CTX_get_cipher_data +returns an internal pointer owned by +.Fa ctx . +.Pp +.Fn EVP_CIPHER_CTX_set_cipher_data +returns a pointer to the old cipher data of +.Fa ctx +and transfers ownership to the caller. +.Pp +.Fn EVP_CIPHER_CTX_buf_noconst +returns a pointer to an internal buffer owned by +.Fa ctx . +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_CIPHER_meth_new 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn EVP_CIPHER_CTX_get_cipher_data , +.Fn EVP_CIPHER_CTX_set_cipher_data , +and +.Fn EVP_CIPHER_CTX_buf_noconst +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/EVP_CIPHER_CTX_init.3 b/static/openbsd/man3/EVP_CIPHER_CTX_init.3 new file mode 100644 index 00000000..7b1d81ba --- /dev/null +++ b/static/openbsd/man3/EVP_CIPHER_CTX_init.3 @@ -0,0 +1,210 @@ +.\" $OpenBSD: EVP_CIPHER_CTX_init.3,v 1.5 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2019, 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Richard Levitte . +.\" Copyright (c) 2000-2001, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_CIPHER_CTX_INIT 3 +.Os +.Sh NAME +.Nm EVP_CIPHER_CTX_init , +.Nm EVP_CIPHER_CTX_cleanup , +.Nm EVP_Cipher +.Nd obsolete EVP cipher functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_CIPHER_CTX_init +.Fa "EVP_CIPHER_CTX *ctx" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_cleanup +.Fa "EVP_CIPHER_CTX *ctx" +.Fc +.Ft int +.Fo EVP_Cipher +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "const unsigned char *in" +.Fa "unsigned int in_len" +.Fc +.Sh DESCRIPTION +.Fn EVP_CIPHER_CTX_init +is a deprecated function that could be used to clear a cipher context +on the stack before +.Vt EVP_CIPHER_CTX +was made opaque. +Calling it on a cipher context just returned from +.Xr EVP_CIPHER_CTX_new 3 +has no effect. +Calling it on a cipher context that was already used may leak memory +with older versions of the library. +Instead, use +.Xr EVP_CIPHER_CTX_reset 3 +or +.Xr EVP_CIPHER_CTX_free 3 . +.Pp +.Fn EVP_CIPHER_CTX_cleanup +is a deprecated alias for +.Xr EVP_CIPHER_CTX_reset 3 . +It clears all information from +.Fa ctx +and frees all allocated memory associated with it, except the +.Fa ctx +object itself. +.Pp +.Fn EVP_Cipher +exposes implementation details of the functions +.Xr EVP_CipherUpdate 3 +and +.Xr EVP_CipherFinal 3 +that should never have become part of the public API. +.Pp +If the flag +.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER +is set for the cipher used by +.Fa ctx , +behaviour depends on +.Fa in . +If that argument is +.Dv NULL +and +.Fa in_len +is 0, behaviour is similar to +.Xr EVP_CipherFinal 3 ; +if +.Fa in_len +is not 0, behaviour is undefined. +If +.Fa in +is not +.Dv NULL , +behaviour is similar to +.Xr EVP_CipherUpdate 3 . +In both cases, the exceptions to the similarity are that arguments +and return values differ. +.Pp +If the flag +.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER +is not set for the cipher used by +.Fa ctx , +it encrypts or decrypts aligned blocks of data +whose lengths match the cipher block size. +It requires that the previous encryption or decryption operation +using the same +.Fa ctx , +if there was any, ended exactly on a block boundary and that +.Fa in_len +is an integer multiple of the cipher block size. +If either of these conditions is violated, +.Fn EVP_Cipher +silently produces incorrect results. +For that reason, using the function +.Xr EVP_CipherUpdate 3 +instead is strongly recommended. +The latter can safely handle partial blocks, and even if +.Fa in_len +actually is a multiple of the cipher block size for all calls, +the overhead incurred by using +.Xr EVP_CipherUpdate 3 +is minimal. +.Sh RETURN VALUES +.Fn EVP_CIPHER_CTX_init +always returns 1. +.Pp +.Fn EVP_CIPHER_CTX_cleanup +returns 1 for success or 0 for failure. +.Pp +With +.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER , +.Fn EVP_Cipher +returns the number of bytes written to +.Fa out +for success or \-1 for failure. +Without +.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER , +it returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn EVP_Cipher +first appeared in SSLeay 0.6.5. +.Fn EVP_CIPHER_CTX_cleanup +first appeared in SSLeay 0.8.0. +.Fn EVP_CIPHER_CTX_init +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Sh CAVEATS +Checking the return value of +.Fn EVP_Cipher +requires unusual caution: zero signals success if +.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER +is set or failure otherwise. diff --git a/static/openbsd/man3/EVP_CIPHER_CTX_set_flags.3 b/static/openbsd/man3/EVP_CIPHER_CTX_set_flags.3 new file mode 100644 index 00000000..0d86050a --- /dev/null +++ b/static/openbsd/man3/EVP_CIPHER_CTX_set_flags.3 @@ -0,0 +1,234 @@ +.\" $OpenBSD: EVP_CIPHER_CTX_set_flags.3,v 1.3 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Patrick Steuer . +.\" Copyright (c) 2000, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_CIPHER_CTX_SET_FLAGS 3 +.Os +.Sh NAME +.Nm EVP_CIPHER_CTX_set_flags , +.Nm EVP_CIPHER_CTX_clear_flags , +.Nm EVP_CIPHER_CTX_test_flags , +.Nm EVP_CIPHER_CTX_rand_key , +.Nm EVP_CIPHER_param_to_asn1 , +.Nm EVP_CIPHER_asn1_to_param , +.\" .Nm EVP_CIPHER_set_asn1_iv and +.\" .Nm EVP_CIPHER_get_asn1_iv are intentionally undocumented +.\" because they are unused according to codesearch.debian.net +.\" and should probably not be public: they seem hardly useful +.\" even for implementing custom EVP_CIPHER algorithms. +.Nm EVP_CIPHER_CTX_get_app_data , +.Nm EVP_CIPHER_CTX_set_app_data +.Nd unusual EVP cipher context configuration +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft void +.Fo EVP_CIPHER_CTX_set_flags +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "int flags" +.Fc +.Ft void +.Fo EVP_CIPHER_CTX_clear_flags +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "int flags" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_test_flags +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "int flags" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_rand_key +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *key" +.Fc +.Ft int +.Fo EVP_CIPHER_param_to_asn1 +.Fa "EVP_CIPHER_CTX *c" +.Fa "ASN1_TYPE *type" +.Fc +.Ft int +.Fo EVP_CIPHER_asn1_to_param +.Fa "EVP_CIPHER_CTX *c" +.Fa "ASN1_TYPE *type" +.Fc +.Ft void * +.Fo EVP_CIPHER_CTX_get_app_data +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Ft void +.Fo EVP_CIPHER_CTX_set_app_data +.Fa "const EVP_CIPHER_CTX *ctx" +.Fa "void *data" +.Fc +.Sh DESCRIPTION +.Fn EVP_CIPHER_CTX_set_flags +enables the given +.Fa flags +in +.Fa ctx . +.Fn EVP_CIPHER_CTX_clear_flags +disables the given +.Fa flags +in +.Fa ctx . +.Fn EVP_CIPHER_CTX_test_flags +checks whether any of the given +.Fa flags +are currently set in +.Fa ctx , +returning the subset of the +.Fa flags +that are set, or 0 if none of them are set. +Currently, the only supported cipher context flag is +.Dv EVP_CIPHER_CTX_FLAG_WRAP_ALLOW ; +see +.Xr EVP_aes_128_wrap 3 +for details. +.Pp +.Fn EVP_CIPHER_CTX_rand_key +generates a random key of the appropriate length based on the cipher +context. +The +.Vt EVP_CIPHER +can provide its own random key generation routine to support keys +of a specific form. +The +.Fa key +argument must point to a buffer at least as big as the value returned by +.Xr EVP_CIPHER_CTX_key_length 3 . +.Pp +.Fn EVP_CIPHER_param_to_asn1 +sets the ASN.1 +.Vt 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 +.Xr EVP_EncryptUpdate 3 +or +.Xr EVP_DecryptUpdate 3 +calls, for example). +This function may fail if the cipher does not have any ASN.1 support. +.Pp +.Fn EVP_CIPHER_asn1_to_param +sets the cipher parameters based on an ASN.1 +.Vt AlgorithmIdentifier +parameter. +The precise effect depends on the cipher. +In the case of RC2, 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 +.Xr EVP_CipherInit 3 +will be called with the IV and key set to +.Dv NULL , +.Fn EVP_CIPHER_asn1_to_param +will be called and finally +.Xr EVP_CipherInit 3 +again with all parameters except the key set to +.Dv NULL . +It is possible for this function to fail if the cipher does not +have any ASN.1 support or the parameters cannot be set (for example +the RC2 effective key length is not supported). +.Sh RETURN VALUES +.Fn EVP_CIPHER_CTX_rand_key +return 1 for success or 0 for failure. +.Pp +.Fn EVP_CIPHER_param_to_asn1 +and +.Fn EVP_CIPHER_asn1_to_param +return greater than zero for success and zero or a negative number +for failure. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_CIPHER_CTX_ctrl 3 , +.Xr EVP_CIPHER_CTX_get_cipher_data 3 , +.Xr EVP_CIPHER_nid 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn EVP_CIPHER_CTX_set_app_data +and +.Fn EVP_CIPHER_CTX_get_app_data +first appeared in SSLeay 0.8.0. +.Fn EVP_CIPHER_param_to_asn1 +and +.Fn EVP_CIPHER_asn1_to_param +first appeared in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_CIPHER_CTX_rand_key +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Sh BUGS +The ASN.1 code is incomplete (and sometimes inaccurate). +It has only been tested for certain common S/MIME ciphers +(RC2, DES, triple DES) in CBC mode. diff --git a/static/openbsd/man3/EVP_CIPHER_do_all.3 b/static/openbsd/man3/EVP_CIPHER_do_all.3 new file mode 100644 index 00000000..342cf372 --- /dev/null +++ b/static/openbsd/man3/EVP_CIPHER_do_all.3 @@ -0,0 +1,212 @@ +.\" $OpenBSD: EVP_CIPHER_do_all.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2023,2024 Theo Buehler +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt EVP_CIPHER_DO_ALL 3 +.Os +.Sh NAME +.Nm EVP_CIPHER_do_all , +.Nm EVP_CIPHER_do_all_sorted , +.Nm EVP_MD_do_all , +.Nm EVP_MD_do_all_sorted , +.Nm OBJ_NAME_do_all , +.Nm OBJ_NAME_do_all_sorted +.Nd iterate over lookup tables for ciphers and digests +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft void +.Fo EVP_CIPHER_do_all +.Fa "void (*fn)(const EVP_CIPHER *cipher, const char *from,\ + const char *to, void *arg)" +.Fa "void *arg" +.Fc +.Ft void +.Fo EVP_CIPHER_do_all_sorted +.Fa "void (*fn)(const EVP_CIPHER *cipher, const char *from,\ + const char *to, void *arg)" +.Fa "void *arg" +.Fc +.Ft void +.Fo EVP_MD_do_all +.Fa "void (*fn)(const EVP_MD *md, const char *from,\ + const char *to, void *arg)" +.Fa "void *arg" +.Fc +.Ft void +.Fo EVP_MD_do_all_sorted +.Fa "void (*fn)(const EVP_MD *md, const char *from,\ + const char *to, void *arg)" +.Fa "void *arg" +.Fc +.Bd -literal +typedef struct { + int type; + int alias; + const char *name; + const char *data; +} OBJ_NAME; +.Ed +.Pp +.Ft void +.Fo OBJ_NAME_do_all +.Fa "int type" +.Fa "void (*fn)(const OBJ_NAME *obj_name, void *arg)" +.Fa "void *arg" +.Fc +.Ft void +.Fo OBJ_NAME_do_all_sorted +.Fa "int type" +.Fa "void (*fn)(const OBJ_NAME *obj_name, void *arg)" +.Fa "void *arg" +.Fc +.Sh DESCRIPTION +.Fn EVP_CIPHER_do_all +calls +.Fa fn +on every entry of the global table of cipher names and aliases. +For a cipher name entry, +.Fa fn +is called with a non-NULL +.Fa cipher , +its non-NULL cipher name +.Fa from , +a NULL +.Fa to , +and the +.Fa arg +pointer. +For an alias entry, +.Fa fn +is called with a NULL +.Fa cipher , +its alias +.Fa from , +the cipher name that alias points +.Fa to , +and the +.Fa arg +pointer. +.Pp +.Fn EVP_CIPHER_do_all_sorted +is similar, except that it processes the cipher names and aliases +in lexicographic order of their +.Fa from +names as determined by +.Xr strcmp 3 . +.Pp +.Fn EVP_MD_do_all +calls +.Fa fn +on every entry of the global table of digest names and aliases. +For a digest name entry, +.Fa fn +is called with a non-NULL +.Fa md , +its non-NULL digest name +.Fa from , +a NULL +.Fa to , +and the +.Fa arg +pointer. +For an alias entry, +.Fa fn +is called with a NULL +.Fa md , +its alias +.Fa from , +the digest name that alias points +.Fa to , +and the +.Fa arg +pointer. +.Pp +.Fn EVP_MD_do_all_sorted +is similar, except that it processes the digest names and aliases +in lexicographic order of their +.Fa from +names as determined by +.Xr strcmp 3 . +.Pp +.Vt OBJ_NAME +is an abstraction of the types underlying the lookup tables +for ciphers and their aliases, and digests and their aliases, respectively. +For a cipher, +.Fa type +is +.Dv OBJ_NAME_TYPE_CIPHER_METH , +.Fa alias +is 0, +.Fa name +is its lookup name and +.Fa data +is the +.Vt EVP_CIPHER +object it represents, cast to +.Vt const char * . +For a cipher alias, +.Fa type +is +.Dv OBJ_NAME_TYPE_CIPHER_METH , +.Fa alias +is +.Dv OBJ_NAME_ALIAS , +.Fa name +is its lookup name and +.Fa data +is the name it aliases. +Digests representing an +.Vt EVP_MD +object and their aliases are represented similarly, except that their type is +.Dv OBJ_NAME_TYPE_MD_METH . +.Pp +.Fn OBJ_NAME_do_all +calls +.Fa fn +on every +.Fa obj_name +in the table that has the given +.Fa type +(either +.Dv OBJ_NAME_TYPE_CIPHER_METH +or +.Dv OBJ_NAME_TYPE_MD_METH ) , +also passing the +.Fa arg +pointer. +.Fn OBJ_NAME_do_all_sorted +is similar except that it processes the +.Fa obj_name +in lexicographic order of their names as determined by +.Xr strcmp 3 . +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_get_cipherbyname 3 , +.Xr EVP_get_digestbyname 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Sh CAVEATS +.Fn EVP_CIPHER_do_all_sorted , +.Fn EVP_MD_do_all_sorted , +and +.Fn OBJ_NAME_do_all_sorted +cannot report errors. +In some implementations they need to allocate internally and +if memory allocation fails they do nothing at all, +without telling the caller about the problem. diff --git a/static/openbsd/man3/EVP_CIPHER_meth_new.3 b/static/openbsd/man3/EVP_CIPHER_meth_new.3 new file mode 100644 index 00000000..f831b20c --- /dev/null +++ b/static/openbsd/man3/EVP_CIPHER_meth_new.3 @@ -0,0 +1,389 @@ +.\" $OpenBSD: EVP_CIPHER_meth_new.3,v 1.7 2025/06/08 22:40:29 schwarze Exp $ +.\" selective merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Richard Levitte +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_CIPHER_METH_NEW 3 +.Os +.Sh NAME +.Nm EVP_CIPHER_meth_new , +.Nm EVP_CIPHER_meth_dup , +.Nm EVP_CIPHER_meth_free , +.Nm EVP_CIPHER_meth_set_iv_length , +.Nm EVP_CIPHER_meth_set_flags , +.Nm EVP_CIPHER_meth_set_impl_ctx_size , +.Nm EVP_CIPHER_meth_set_init , +.Nm EVP_CIPHER_meth_set_do_cipher , +.Nm EVP_CIPHER_meth_set_cleanup , +.Nm EVP_CIPHER_meth_set_set_asn1_params , +.Nm EVP_CIPHER_meth_set_get_asn1_params , +.Nm EVP_CIPHER_meth_set_ctrl +.Nd Routines to build up EVP_CIPHER methods +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft EVP_CIPHER * +.Fo EVP_CIPHER_meth_new +.Fa "int cipher_type" +.Fa "int block_size" +.Fa "int key_len" +.Fc +.Ft EVP_CIPHER * +.Fo EVP_CIPHER_meth_dup +.Fa "const EVP_CIPHER *cipher" +.Fc +.Ft void +.Fo EVP_CIPHER_meth_free +.Fa "EVP_CIPHER *cipher" +.Fc +.Ft int +.Fo EVP_CIPHER_meth_set_iv_length +.Fa "EVP_CIPHER *cipher" +.Fa "int iv_len" +.Fc +.Ft int +.Fo EVP_CIPHER_meth_set_flags +.Fa "EVP_CIPHER *cipher" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo EVP_CIPHER_meth_set_impl_ctx_size +.Fa "EVP_CIPHER *cipher" +.Fa "int ctx_size" +.Fc +.Ft int +.Fo EVP_CIPHER_meth_set_init +.Fa "EVP_CIPHER *cipher" +.Fa "int (*init)(EVP_CIPHER_CTX *ctx, const unsigned char *key,\ + const unsigned char *iv, int enc)" +.Fc +.Ft int +.Fo EVP_CIPHER_meth_set_do_cipher +.Fa "EVP_CIPHER *cipher" +.Fa "int (*do_cipher)(EVP_CIPHER_CTX *ctx, unsigned char *out,\ + const unsigned char *in, size_t inl)" +.Fc +.Ft int +.Fo EVP_CIPHER_meth_set_cleanup +.Fa "EVP_CIPHER *cipher" +.Fa "int (*cleanup)(EVP_CIPHER_CTX *)" +.Fc +.Ft int +.Fo EVP_CIPHER_meth_set_set_asn1_params +.Fa "EVP_CIPHER *cipher" +.Fa "int (*set_asn1_parameters)(EVP_CIPHER_CTX *, ASN1_TYPE *)" +.Fc +.Ft int +.Fo EVP_CIPHER_meth_set_get_asn1_params +.Fa "EVP_CIPHER *cipher" +.Fa "int (*get_asn1_parameters)(EVP_CIPHER_CTX *, ASN1_TYPE *)" +.Fc +.Ft int +.Fo EVP_CIPHER_meth_set_ctrl +.Fa "EVP_CIPHER *cipher" +.Fa "int (*ctrl)(EVP_CIPHER_CTX *, int type, int arg, void *ptr)" +.Fc +.Sh DESCRIPTION +The +.Vt EVP_CIPHER +type is a structure holding function pointers for +a symmetric cipher implementation. +.Pp +.Fn EVP_CIPHER_meth_new +allocates a new +.Vt EVP_CIPHER +structure. +The cipher's NID (see +.Xr EVP_CIPHER_nid 3 ) +is set to +.Fa cipher_type , +the block size and key length are set to +.Fa block_size +and +.Fa key_len , +respectively. +.Pp +.Fn EVP_CIPHER_meth_dup +creates a copy of +.Fa cipher . +.Pp +.Fn EVP_CIPHER_meth_free +frees an +.Vt EVP_CIPHER +structure. +.Pp +.Fn EVP_CIPHER_meth_set_iv_length +sets the length of the initialization vector. +This is only needed when the implemented cipher mode requires it. +.Pp +.Fn EVP_CIPHER_meth_set_flags +overwrites the flags to describe optional behaviours in +.Fa cipher +with +.Fa flags . +At most one of the following cipher modes can be set: +.Dv EVP_CIPH_STREAM_CIPHER , +.Dv EVP_CIPH_ECB_MODE , +.Dv EVP_CIPH_CBC_MODE , +.Dv EVP_CIPH_CFB_MODE , +.Dv EVP_CIPH_OFB_MODE , +.Dv EVP_CIPH_CTR_MODE , +.Dv EVP_CIPH_GCM_MODE , +.Dv EVP_CIPH_CCM_MODE , +.Dv EVP_CIPH_XTS_MODE , +and +.Dv EVP_CIPH_WRAP_MODE . +.Pp +Zero or more of the following flags can be OR'ed into the +.Fa flags +argument: +.Bl -tag -width Ds +.It Dv EVP_CIPH_VARIABLE_LENGTH +This cipher has a variable key length, and the function +.Xr EVP_CIPHER_CTX_set_key_length 3 +can be used with it. +.It Dv EVP_CIPH_CUSTOM_IV +Instruct +.Xr EVP_CipherInit_ex 3 +and similar initialization functions to leave storing and initialising +the IV entirely to the implementation. +If this flag is set, +the implementation is typically expected to do that in its +.Fa init +function. +.It Dv EVP_CIPH_ALWAYS_CALL_INIT +Instruct +.Xr EVP_CipherInit_ex 3 +and similar initialization functions to call the implementation's +.Fa init +function even if the +.Fa key +argument is +.Dv NULL . +.It Dv EVP_CIPH_CTRL_INIT +Instruct +.Xr EVP_CipherInit_ex 3 +and similar initialization functions to call the implementation's +.Fa ctrl +function with a command +.Fa type +of +.Dv EVP_CTRL_INIT +early during the setup. +.It Dv EVP_CIPH_NO_PADDING +Instruct +.Xr EVP_CipherFinal_ex 3 +and similar finalization functions to not use standard block padding +but instead report an error if the total amount of data +to be encrypted or decrypted is not a multiple of the block size. +.It Dv EVP_CIPH_RAND_KEY +Instruct +.Xr EVP_CIPHER_CTX_rand_key 3 +to not generate a random key using +.Xr arc4random_buf 3 +but instead leave that to the implementation by calling the +.Fa ctrl +function with a command +.Fa type +of +.Dv EVP_CTRL_RAND_KEY +and the pointer to the key memory storage in +.Fa ptr . +.It Dv EVP_CIPH_CUSTOM_COPY +Instruct +.Xr EVP_CIPHER_CTX_copy 3 +to call the implementation's +.Fa ctrl +function with a command +.Fa type +of +.Dv EVP_CTRL_COPY +and the destination +.Fa "EVP_CIPHER_CTX *out" +in the +.Fa ptr +argument immediately before returning successfully. +The intended use is for further things to deal with after the +implementation specific data block has been copied. +The implementation-specific data block is reached with +.Xr EVP_CIPHER_CTX_get_cipher_data 3 . +.It Dv EVP_CIPH_FLAG_DEFAULT_ASN1 +Instruct +.Xr EVP_CIPHER_param_to_asn1 3 +to use +.Xr ASN1_TYPE_set_octetstring 3 +if no +.Fa set_asn1_parameters +function is installed, and instruct +.Xr EVP_CIPHER_asn1_to_param 3 +to use +.Xr ASN1_TYPE_get_octetstring 3 +if no +.Fa get_asn1_parameters +function is installed. +.It Dv 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. +.It Dv EVP_CIPH_FLAG_CUSTOM_CIPHER +Instruct +.Xr EVP_CipherUpdate 3 , +.Xr EVP_CipherFinal_ex 3 , +and similar encryption, decryption, and finalization functions +that the implementation's +.Fa do_cipher +function takes care of everything, +including padding, buffering and finalization. +.It Dv EVP_CIPH_FLAG_AEAD_CIPHER +This indicates that this is an AEAD cipher implementation. +.El +.Pp +.Fn EVP_CIPHER_meth_set_impl_ctx_size +sets the size of the EVP_CIPHER's implementation context so that it can +be automatically allocated. +.Pp +.Fn EVP_CIPHER_meth_set_init +sets the +.Fa init +function for +.Fa cipher . +The cipher init function is called by +.Xr EVP_CipherInit 3 , +.Xr EVP_CipherInit_ex 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_EncryptInit_ex 3 , +.Xr EVP_DecryptInit 3 , +and +.Xr EVP_DecryptInit_ex 3 . +.Pp +.Fn EVP_CIPHER_meth_set_do_cipher +sets the cipher function for +.Fa cipher . +The cipher function is called by +.Xr EVP_CipherUpdate 3 , +.Xr EVP_EncryptUpdate 3 , +.Xr EVP_DecryptUpdate 3 , +.Xr EVP_CipherFinal 3 , +.Xr EVP_EncryptFinal 3 , +.Xr EVP_EncryptFinal_ex 3 , +.Xr EVP_DecryptFinal 3 +and +.Xr EVP_DecryptFinal_ex 3 . +.Pp +.Fn EVP_CIPHER_meth_set_cleanup +sets the function for +.Fa cipher +to do extra cleanup before the method's private data structure is +cleaned out and freed. +Note that the cleanup function is passed a +.Sy EVP_CIPHER_CTX * , +the private data structure is then available with +.Xr EVP_CIPHER_CTX_get_cipher_data 3 . +This cleanup function is called by +.Xr EVP_CIPHER_CTX_reset 3 +and +.Xr EVP_CIPHER_CTX_free 3 . +.Pp +.Fn EVP_CIPHER_meth_set_set_asn1_params +sets the function for +.Fa cipher +to set the AlgorithmIdentifier "parameter" based on the passed cipher. +This function is called by +.Xr EVP_CIPHER_param_to_asn1 3 . +.Fn EVP_CIPHER_meth_set_get_asn1_params +sets the function for +.Fa cipher +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 +.Xr EVP_CIPHER_param_to_asn1 3 +and +.Xr EVP_CIPHER_asn1_to_param 3 +respectively if defined. +.Pp +.Fn EVP_CIPHER_meth_set_ctrl +sets the control function for +.Fa cipher . +.Sh RETURN VALUES +.Fn EVP_CIPHER_meth_new +and +.Fn EVP_CIPHER_meth_dup +return a pointer to a newly created +.Vt EVP_CIPHER , +or NULL on failure. +.Pp +All +.Fn EVP_CIPHER_meth_set_* +functions return 1. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.3 . diff --git a/static/openbsd/man3/EVP_CIPHER_nid.3 b/static/openbsd/man3/EVP_CIPHER_nid.3 new file mode 100644 index 00000000..6152c389 --- /dev/null +++ b/static/openbsd/man3/EVP_CIPHER_nid.3 @@ -0,0 +1,307 @@ +.\" $OpenBSD: EVP_CIPHER_nid.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL man3/EVP_EncryptInit.pod +.\" 0874d7f2 Oct 11 13:13:47 2022 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_CIPHER_NID 3 +.Os +.Sh NAME +.Nm EVP_CIPHER_nid , +.Nm EVP_CIPHER_CTX_nid , +.Nm EVP_CIPHER_name , +.Nm EVP_CIPHER_type , +.Nm EVP_CIPHER_CTX_type , +.Nm EVP_CIPHER_block_size , +.Nm EVP_CIPHER_CTX_block_size , +.Nm EVP_CIPHER_flags , +.Nm EVP_CIPHER_CTX_flags , +.Nm EVP_CIPHER_mode , +.Nm EVP_CIPHER_CTX_mode +.Nd inspect EVP_CIPHER objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_CIPHER_nid +.Fa "const EVP_CIPHER *cipher" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_nid +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Ft const char * +.Fo EVP_CIPHER_name +.Fa "const EVP_CIPHER *cipher" +.Fc +.Ft int +.Fo EVP_CIPHER_type +.Fa "const EVP_CIPHER *ctx" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_type +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Ft int +.Fo EVP_CIPHER_block_size +.Fa "const EVP_CIPHER *cipher" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_block_size +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Ft unsigned long +.Fo EVP_CIPHER_flags +.Fa "const EVP_CIPHER *cipher" +.Fc +.Ft unsigned long +.Fo EVP_CIPHER_CTX_flags +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Ft unsigned long +.Fo EVP_CIPHER_mode +.Fa "const EVP_CIPHER *cipher" +.Fc +.Ft unsigned long +.Fo EVP_CIPHER_CTX_mode +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn EVP_CIPHER_nid +returns the numerical identifier (NID) of the +.Fa cipher . +The NID is an internal value which may or may not have a corresponding +ASN.1 OBJECT IDENTIFIER; see +.Xr OBJ_nid2obj 3 +for details. +.Pp +.Fn EVP_CIPHER_CTX_nid +returns the NID of the cipher that +.Fa ctx +is configured to use. +.Pp +.Fn EVP_CIPHER_name +converts the NID of the +.Fa cipher +to its short name with +.Xr OBJ_nid2sn 3 . +.Pp +.Fn EVP_CIPHER_type +returns the NID associated with the ASN.1 OBJECT IDENTIFIER of the +.Fa cipher , +ignoring the cipher parameters. +For example, +.Xr EVP_aes_256_cfb1 3 , +.Xr EVP_aes_256_cfb8 3 , +and +.Xr EVP_aes_256_cfb128 3 +all return the same NID, +.Dv NID_aes_256_cfb128 . +.Pp +.Fn EVP_CIPHER_CTX_type +returns the NID associated with the ASN.1 OBJECT IDENTIFIER of the cipher that +.Fa ctx +is configured to use. +.Pp +.Fn EVP_CIPHER_block_size +returns the block size of the +.Fa cipher +in bytes. +.Fn EVP_CIPHER_CTX_block_size +returns the block size of the cipher that +.Fa ctx +is configured to use. +Block sizes are guaranteed to be less than or equal to the constant +.Dv EVP_MAX_BLOCK_LENGTH . +Currently, +.Xr EVP_CipherInit_ex 3 +and the other functions documented in the same manual page +only support block sizes of 1, 8, and 16 bytes. +.Pp +.Fn EVP_CIPHER_flags +returns the cipher flags used by the +.Fa cipher . +The meaning of the flags is described in the +.Xr EVP_CIPHER_meth_set_flags 3 +manual page. +.Pp +.Fn EVP_CIPHER_CTX_flags +returns the cipher flags of the cipher that +.Fa ctx +is configured to use. +Be careful to not confuse these with the unrelated cipher context flags +that can be inspected with +.Xr EVP_CIPHER_CTX_test_flags 3 . +.Pp +.Fn EVP_CIPHER_mode +returns the +.Fa cipher +mode, which is the logical AND of the constant +.Dv EVP_CIPH_MODE +and the return value of +.Fn EVP_CIPHER_flags . +.Pp +.Fn EVP_CIPHER_CTX_mode +returns the cipher mode of the cipher that +.Fa ctx +is configured to use. +.Pp +.Fn EVP_CIPHER_name , +.Fn EVP_CIPHER_CTX_type , +.Fn EVP_CIPHER_mode , +and +.Fn EVP_CIPHER_CTX_mode +are implemented as macros. +.Sh RETURN VALUES +.Fn EVP_CIPHER_nid +and +.Fn EVP_CIPHER_CTX_nid +return an NID. +.Pp +.Fn EVP_CIPHER_name +returns a pointer to a string that is owned by an internal library object or +.Dv NULL +if the NID is neither built into the library nor added to the global +object table by one of the functions documented in the manual page +.Xr OBJ_create 3 , +of if the object does not contain a short name. +.Pp +.Fn EVP_CIPHER_type +and +.Fn EVP_CIPHER_CTX_type +return the NID of the cipher's OBJECT IDENTIFIER or +.Dv NID_undef +if it is not associated with an OBJECT IDENTIFIER. +.Pp +.Fn EVP_CIPHER_block_size +and +.Fn EVP_CIPHER_CTX_block_size +return the block size in bytes. +.Pp +.Fn EVP_CIPHER_flags +and +.Fn EVP_CIPHER_CTX_flags +return one or more +.Dv EVP_CIPH_* +flag bits OR'ed together. +.Pp +.Fn EVP_CIPHER_mode +and +.Fn EVP_CIPHER_CTX_mode +return one of the constants +.Dv EVP_CIPH_ECB_MODE , +.Dv EVP_CIPH_CBC_MODE , +.Dv EVP_CIPH_CFB_MODE , +.Dv EVP_CIPH_OFB_MODE , +.Dv EVP_CIPH_CTR_MODE , +.Dv EVP_CIPH_GCM_MODE , +.Dv EVP_CIPH_CCM_MODE , +.Dv EVP_CIPH_XTS_MODE , +or +.Dv EVP_CIPH_WRAP_MODE +to indicate a block cipher or +.Dv EVP_CIPH_STREAM_CIPHER +to indicate a stream cipher. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_CIPHER_CTX_ctrl 3 , +.Xr EVP_EncryptInit 3 , +.Xr OBJ_nid2obj 3 +.Sh HISTORY +.Fn EVP_CIPHER_type , +.Fn EVP_CIPHER_CTX_type , +.Fn EVP_CIPHER_block_size , +and +.Fn EVP_CIPHER_CTX_block_size +first appeared in SSLeay 0.6.5. +.Fn EVP_CIPHER_nid +and +.Fn EVP_CIPHER_CTX_nid +first appeared in SSLeay 0.8.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_CIPHER_flags , +.Fn EVP_CIPHER_CTX_flags , +.Fn EVP_CIPHER_mode , +and +.Fn EVP_CIPHER_CTX_mode +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Pp +.Fn EVP_CIPHER_name +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Sh CAVEATS +The behaviour of the functions taking an +.Vt EVP_CIPHER_CTX +argument is undefined if they are called on a +.Fa ctx +that has no cipher configured yet, for example one freshly returned from +.Xr EVP_CIPHER_CTX_new 3 . +In that case, the program may for example be terminated by a +.Dv NULL +pointer access. diff --git a/static/openbsd/man3/EVP_DigestInit.3 b/static/openbsd/man3/EVP_DigestInit.3 new file mode 100644 index 00000000..1457d65e --- /dev/null +++ b/static/openbsd/man3/EVP_DigestInit.3 @@ -0,0 +1,608 @@ +.\" $OpenBSD: EVP_DigestInit.3,v 1.39 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000 +.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019, 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson , +.\" Richard Levitte , +.\" Paul Yang , and +.\" Antoine Salon . +.\" Copyright (c) 2000-2004, 2009, 2012-2016, 2018, 2019 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_DIGESTINIT 3 +.Os +.Sh NAME +.Nm EVP_MD_CTX_new , +.Nm EVP_MD_CTX_reset , +.Nm EVP_MD_CTX_free , +.Nm EVP_MD_CTX_init , +.Nm EVP_MD_CTX_create , +.Nm EVP_MD_CTX_cleanup , +.Nm EVP_MD_CTX_destroy , +.Nm EVP_DigestInit_ex , +.Nm EVP_DigestUpdate , +.Nm EVP_DigestFinal_ex , +.Nm EVP_Digest , +.Nm EVP_MD_CTX_copy_ex , +.Nm EVP_DigestInit , +.Nm EVP_DigestFinal , +.Nm EVP_MD_CTX_copy , +.Nm EVP_MD_CTX_md , +.Nm EVP_md_null , +.Nm EVP_sha224 , +.Nm EVP_sha256 , +.Nm EVP_sha384 , +.Nm EVP_sha512 , +.Nm EVP_sha512_224 , +.Nm EVP_sha512_256 , +.Nm EVP_ripemd160 , +.Nm EVP_get_digestbyname , +.Nm EVP_get_digestbynid , +.Nm EVP_get_digestbyobj +.Nd EVP digest routines +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft EVP_MD_CTX * +.Fn EVP_MD_CTX_new void +.Ft int +.Fo EVP_MD_CTX_reset +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft void +.Fo EVP_MD_CTX_free +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft int +.Fo EVP_MD_CTX_init +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft EVP_MD_CTX * +.Fn EVP_MD_CTX_create void +.Ft int +.Fo EVP_MD_CTX_cleanup +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft void +.Fo EVP_MD_CTX_destroy +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft int +.Fo EVP_DigestInit_ex +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fa "ENGINE *engine" +.Fc +.Ft int +.Fo EVP_DigestUpdate +.Fa "EVP_MD_CTX *ctx" +.Fa "const void *d" +.Fa "size_t cnt" +.Fc +.Ft int +.Fo EVP_DigestFinal_ex +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *md" +.Fa "unsigned int *s" +.Fc +.Ft int +.Fo EVP_Digest +.Fa "const void *d" +.Fa "size_t cnt" +.Fa "unsigned char *md" +.Fa "unsigned int *s" +.Fa "const EVP_MD *type" +.Fa "ENGINE *engine" +.Fc +.Ft int +.Fo EVP_MD_CTX_copy_ex +.Fa "EVP_MD_CTX *out" +.Fa "const EVP_MD_CTX *in" +.Fc +.Ft int +.Fo EVP_DigestInit +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fc +.Ft int +.Fo EVP_DigestFinal +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *md" +.Fa "unsigned int *s" +.Fc +.Ft int +.Fo EVP_MD_CTX_copy +.Fa "EVP_MD_CTX *out" +.Fa "EVP_MD_CTX *in" +.Fc +.Ft const EVP_MD * +.Fo EVP_MD_CTX_md +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft const EVP_MD * +.Fn EVP_md_null void +.Ft const EVP_MD * +.Fn EVP_sha224 void +.Ft const EVP_MD * +.Fn EVP_sha256 void +.Ft const EVP_MD * +.Fn EVP_sha384 void +.Ft const EVP_MD * +.Fn EVP_sha512 void +.Ft const EVP_MD * +.Fn EVP_sha512_224 void +.Ft const EVP_MD * +.Fn EVP_sha512_256 void +.Ft const EVP_MD * +.Fn EVP_ripemd160 void +.Ft const EVP_MD * +.Fo EVP_get_digestbyname +.Fa "const char *name" +.Fc +.Ft const EVP_MD * +.Fo EVP_get_digestbynid +.Fa "int type" +.Fc +.Ft const EVP_MD * +.Fo EVP_get_digestbyobj +.Fa "const ASN1_OBJECT *o" +.Fc +.Sh DESCRIPTION +The EVP digest routines are a high-level interface to message digests +and should be used instead of the cipher-specific functions. +.Pp +.Fn EVP_MD_CTX_new +allocates a new, empty digest context. +.Pp +.Fn EVP_MD_CTX_reset +cleans up +.Fa ctx +and resets it to the state it had after +.Fn EVP_MD_CTX_new , +such that it can be reused. +.Pp +.Fn EVP_MD_CTX_free +cleans up +.Fa ctx +and frees the space allocated to it. +.Pp +.Fn EVP_MD_CTX_init +is a deprecated function to clear a digest context on the stack +before use. +Do not use it on a digest context returned from +.Fn EVP_MD_CTX_new +or one that was already used. +.Pp +.Fn EVP_MD_CTX_create , +.Fn EVP_MD_CTX_cleanup , +and +.Fn EVP_MD_CTX_destroy +are deprecated aliases for +.Fn EVP_MD_CTX_new , +.Fn EVP_MD_CTX_reset , +and +.Fn EVP_MD_CTX_free , +respectively. +.Pp +.Fn EVP_DigestInit_ex +sets up the digest context +.Fa ctx +to use a digest +.Fa type . +The +.Fa type +will typically be supplied by a function such as +.Fn EVP_sha512 . +The +.Fa ENGINE *engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +.Fn EVP_DigestUpdate +hashes +.Fa cnt +bytes of data at +.Fa d +into the digest context +.Fa ctx . +This function can be called several times on the same +.Fa ctx +to hash additional data. +.Pp +.Fn EVP_DigestFinal_ex +retrieves the digest value from +.Fa ctx +and places it in +.Fa md . +If the +.Fa s +parameter is not +.Dv NULL , +then the number of bytes of data written (i.e. the length of the +digest) will be written to the integer at +.Fa s ; +at most +.Dv EVP_MAX_MD_SIZE +bytes will be written. +After calling +.Fn EVP_DigestFinal_ex , +no additional calls to +.Fn EVP_DigestUpdate +can be made, but +.Fn EVP_DigestInit_ex +can be called to initialize a new digest operation. +.Pp +.Fn EVP_Digest +is a simple wrapper function to hash +.Fa cnt +bytes of data at +.Fa d +using the digest +.Fa type +in a one-shot operation and place the digest value into +.Fa md , +and, unless +.Fa s +is +.Dv NULL , +the length of the digest in bytes into +.Pf * Fa s . +This wrapper uses a temporary digest context and passes its arguments to +.Fn EVP_DigestInit_ex , +.Fn EVP_DigestUpdate , +and +.Fn EVP_DigestFinal_ex +internally. +The +.Fa ENGINE *engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +.Fn EVP_MD_CTX_copy_ex +can be used to copy the message digest state from +.Fa in +to +.Fa out . +This is useful if large amounts of data are to be hashed which only +differ in the last few bytes. +.Pp +.Fn EVP_DigestInit +is a deprecated function behaving like +.Fn EVP_DigestInit_ex +except that it requires +.Fn EVP_MD_CTX_reset +before it can be used on a context that was already used. +.Pp +.Fn EVP_DigestFinal +is a deprecated function behaving like +.Fn EVP_DigestFinal_ex +except that the digest context +.Fa ctx +is automatically cleaned up after use by calling +.Fn EVP_MD_CTX_reset +internally. +.Pp +.Fn EVP_MD_CTX_copy +is a deprecated function behaving like +.Fn EVP_MD_CTX_copy_ex +except that it requires +.Fn EVP_MD_CTX_reset +before a context that was already used can be passed as +.Fa out . +.Pp +.Fn EVP_sha224 , +.Fn EVP_sha256 , +.Fn EVP_sha384 , +.Fn EVP_sha512 , +and +.Fn EVP_ripemd160 +return +.Vt EVP_MD +structures for the SHA-224, SHA-256, SHA-384, SHA-512 and +RIPEMD-160 digest algorithms respectively. +.Pp +.Fn EVP_sha512_224 +and +.Fn EVP_sha512_256 +return an +.Vt EVP_MD +structure that provides the truncated SHA-512 variants +SHA-512/224 and SHA-512/256, +respectively. +.Pp +.Fn EVP_md_null +is a "null" message digest that does nothing: +i.e. the hash it returns is of zero length. +.Pp +.Fn EVP_get_digestbyname , +.Fn EVP_get_digestbynid , +and +.Fn EVP_get_digestbyobj +return an +.Vt EVP_MD +structure when passed a digest name, a digest NID, or an ASN1_OBJECT +structure respectively. +.Pp +.Fn EVP_get_digestbynid +and +.Fn EVP_get_digestbyobj +are implemented as macros. +.Pp +The EVP 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 +The +.Fa ENGINE *engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +The functions +.Fn EVP_DigestInit , +.Fn EVP_DigestFinal , +and +.Fn EVP_MD_CTX_copy +are obsolete but are retained to maintain compatibility with existing +code. +New applications should use +.Fn EVP_DigestInit_ex , +.Fn EVP_DigestFinal_ex , +and +.Fn EVP_MD_CTX_copy_ex +because they can efficiently reuse a digest context instead of +initializing and cleaning it up on each call. +.Pp +If digest contexts are not cleaned up after use, memory leaks will occur. +.Sh RETURN VALUES +.Fn EVP_MD_CTX_new +and +.Fn EVP_MD_CTX_create +return the new +.Vt EVP_MD_CTX +object or +.Dv NULL +for failure. +.Pp +.Fn EVP_MD_CTX_reset , +.Fn EVP_MD_CTX_init , +and +.Fn EVP_MD_CTX_cleanup +always return 1. +.Pp +.Fn EVP_DigestInit_ex , +.Fn EVP_DigestUpdate , +.Fn EVP_DigestFinal_ex , +.Fn EVP_Digest , +.Fn EVP_MD_CTX_copy_ex , +.Fn EVP_DigestInit , +.Fn EVP_DigestFinal , +and +.Fn EVP_MD_CTX_copy +return 1 for success or 0 for failure. +.Pp +.Fn EVP_MD_CTX_md +returns the +.Vt EVP_MD +object used by +.Fa ctx , +or +.Dv NULL +if +.Fa ctx +is +.Dv NULL +or does not have any message digest algorithm assigned yet. +.Pp +.Fn EVP_md_null , +.Fn EVP_sha224 , +.Fn EVP_sha256 , +.Fn EVP_sha384 , +.Fn EVP_sha512 , +.Fn EVP_sha512_224 , +.Fn EVP_sha512_256 , +and +.Fn EVP_ripemd160 +return pointers to constant static objects owned by the library. +.Pp +.Fn EVP_get_digestbyname , +.Fn EVP_get_digestbynid , +and +.Fn EVP_get_digestbyobj +return either an +.Vt EVP_MD +structure or +.Dv NULL +if an error occurs. +.Sh EXAMPLES +This example digests the data "Test Message\en" and "Hello World\en", +using the digest name passed on the command line. +.Bd -literal -offset indent +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + EVP_MD_CTX *mdctx; + const EVP_MD *md; + const char mess1[] = "Test Message\en"; + const char mess2[] = "Hello World\en"; + unsigned char md_value[EVP_MAX_MD_SIZE]; + unsigned int md_len, i; + + if (argc <= 1) { + 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(); + EVP_DigestInit_ex(mdctx, md, NULL); + EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); + EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); + EVP_DigestFinal_ex(mdctx, md_value, &md_len); + EVP_MD_CTX_free(mdctx); + + printf("Digest is: "); + for(i = 0; i < md_len; i++) + printf("%02x", md_value[i]); + printf("\en"); + + return 0; +} +.Ed +.Sh SEE ALSO +.Xr BIO_f_md 3 , +.Xr CMAC_Init 3 , +.Xr evp 3 , +.Xr EVP_BytesToKey 3 , +.Xr EVP_DigestSignInit 3 , +.Xr EVP_DigestVerifyInit 3 , +.Xr EVP_MD_CTX_ctrl 3 , +.Xr EVP_MD_nid 3 , +.Xr EVP_PKEY_CTX_set_signature_md 3 , +.Xr EVP_sha1 3 , +.Xr EVP_sha3_224 3 , +.Xr EVP_SignInit 3 , +.Xr EVP_sm3 3 , +.Xr EVP_VerifyInit 3 , +.Xr HMAC 3 , +.Xr OCSP_basic_sign 3 , +.Xr OCSP_request_sign 3 , +.Xr PKCS5_PBKDF2_HMAC 3 , +.Xr PKCS7_sign_add_signer 3 , +.Xr X509_ALGOR_set0 3 , +.Xr X509_digest 3 , +.Xr X509_sign 3 +.Sh HISTORY +.Fn EVP_DigestInit , +.Fn EVP_DigestUpdate , +and +.Fn EVP_DigestFinal +first appeared in SSLeay 0.5.1. +.Fn EVP_md_null +and +.Fn EVP_get_digestbyname +first appeared in SSLeay 0.8.0. +.Fn EVP_get_digestbynid +and +.Fn EVP_get_digestbyobj +first appeared in SSLeay 0.8.1. +.Fn EVP_ripemd160 +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_MD_CTX_copy +first appeared in OpenSSL 0.9.2b and has been available since +.Ox 2.6 . +.Pp +.Fn EVP_MD_CTX_md +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn EVP_MD_CTX_init , +.Fn EVP_MD_CTX_create , +.Fn EVP_MD_CTX_cleanup , +.Fn EVP_MD_CTX_destroy , +.Fn EVP_DigestInit_ex , +.Fn EVP_DigestFinal_ex , +.Fn EVP_Digest , +and +.Fn EVP_MD_CTX_copy_ex +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EVP_sha224 , +.Fn EVP_sha256 , +.Fn EVP_sha384 , +and +.Fn EVP_sha512 +first appeared in OpenSSL 0.9.7h and 0.9.8a +and have been available since +.Ox 4.0 . +.Pp +.Fn EVP_MD_CTX_new , +.Fn EVP_MD_CTX_reset , +and +.Fn EVP_MD_CTX_free +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +.Pp +.Fn EVP_sha512_224 +and +.Fn EVP_sha512_256 +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.4 . diff --git a/static/openbsd/man3/EVP_DigestSignInit.3 b/static/openbsd/man3/EVP_DigestSignInit.3 new file mode 100644 index 00000000..46b8acbd --- /dev/null +++ b/static/openbsd/man3/EVP_DigestSignInit.3 @@ -0,0 +1,244 @@ +.\" $OpenBSD: EVP_DigestSignInit.3,v 1.16 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 28428130 Apr 17 15:18:40 2018 +0200 +.\" selective merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2015, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_DIGESTSIGNINIT 3 +.Os +.Sh NAME +.Nm EVP_DigestSignInit , +.Nm EVP_DigestSignUpdate , +.Nm EVP_DigestSignFinal , +.Nm EVP_DigestSign +.Nd EVP signing functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_DigestSignInit +.Fa "EVP_MD_CTX *ctx" +.Fa "EVP_PKEY_CTX **pctx" +.Fa "const EVP_MD *type" +.Fa "ENGINE *engine" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_DigestSignUpdate +.Fa "EVP_MD_CTX *ctx" +.Fa "const void *d" +.Fa "size_t cnt" +.Fc +.Ft int +.Fo EVP_DigestSignFinal +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *sig" +.Fa "size_t *siglen" +.Fc +.Ft int +.Fo EVP_DigestSign +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *sigret" +.Fa "size_t *siglen" +.Fa "const unsigned char *tbs" +.Fa "size_t tbslen" +.Fc +.Sh DESCRIPTION +The EVP signature routines are a high-level interface to digital +signatures. +.Pp +.Fn EVP_DigestSignInit +sets up the signing context +.Fa ctx +to use the digest +.Fa type +and the private key +.Fa pkey . +Before calling this function, obtain +.Fa ctx +from +.Xr EVP_MD_CTX_new 3 +or call +.Xr EVP_MD_CTX_reset 3 +on it. +The +.Fa engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +If +.Fa pctx +is not +.Dv NULL , +any pointer passed in as +.Pf * Fa pctx +is ignored and overwritten by an internal pointer to the +.Vt EVP_PKEY_CTX +used by the signing operation: +this can be used to set alternative signing options. +The returned +.Vt EVP_PKEY_CTX +must not be freed by the application. +It is freed automatically when the +.Vt EVP_MD_CTX +is freed. +.Pp +.Fn EVP_DigestSignUpdate +hashes +.Fa cnt +bytes of data at +.Fa d +into the signature context +.Fa ctx . +This function can be called several times on the same +.Fa ctx +to include additional data. +This function is currently implemented using a macro. +.Pp +.Fn EVP_DigestSignFinal +signs the data in +.Fa ctx +and places the signature in +.Fa sig . +If +.Fa sig +is +.Dv NULL , +then the maximum size of the output buffer is written to +.Pf * Fa siglen . +If +.Fa sig +is not +.Dv NULL , +then before the call +.Fa siglen +should contain the length of the +.Fa sig +buffer. +If the call is successful, the signature is written to +.Fa sig +and the amount of data written to +.Fa siglen . +.Pp +.Fn EVP_DigestSign +signs +.Fa tbslen +bytes of data at +.Fa tbs +and places the signature in +.Fa sigret +and its length in +.Fa siglen +in a similar way to +.Fn EVP_DigestSignFinal . +.Fn EVP_DigestSign +is a one shot operation which signs a single block of data +with one function call. +For algorithms that support streaming it is equivalent to calling +.Fn EVP_DigestSignUpdate +and +.Fn EVP_DigestSignFinal . +.\" For algorithms which do not support streaming +.\" (e.g. PureEdDSA) +.\" it is the only way to sign data. +.Pp +The EVP 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 +.Fn EVP_DigestSignFinal +internally finalizes a copy of the digest context. +This means that +.Fn EVP_DigestSignUpdate +and +.Fn EVP_DigestSignFinal +can be called later to digest and sign additional data. +.Pp +Since only a copy of the digest context is ever finalized, the context +must be cleaned up after use by calling +.Xr EVP_MD_CTX_free 3 , +or a memory leak will occur. +.Pp +The use of +.Xr EVP_PKEY_size 3 +with these functions is discouraged because some signature operations +may have a signature length which depends on the parameters set. +As a result, +.Xr EVP_PKEY_size 3 +would have to return a value which indicates the maximum possible +signature for any set of parameters. +.Sh RETURN VALUES +.Fn EVP_DigestSignInit , +.Fn EVP_DigestSignUpdate , +.Fn EVP_DigestSignFinal , +and +.Fn EVP_DigestSign +return 1 for success and 0 for failure. +.Pp +The error codes can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_DigestVerifyInit 3 +.Sh HISTORY +.Fn EVP_DigestSignInit , +.Fn EVP_DigestSignUpdate , +and +.Fn EVP_DigestSignFinal +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +.Fn EVP_DigestSign +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 7.0 . diff --git a/static/openbsd/man3/EVP_DigestVerifyInit.3 b/static/openbsd/man3/EVP_DigestVerifyInit.3 new file mode 100644 index 00000000..3d40f8e9 --- /dev/null +++ b/static/openbsd/man3/EVP_DigestVerifyInit.3 @@ -0,0 +1,224 @@ +.\" $OpenBSD: EVP_DigestVerifyInit.3,v 1.18 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to OpenSSL f097e875 Aug 23 11:37:22 2018 +0100 +.\" selective merge up to 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2014, 2015, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_DIGESTVERIFYINIT 3 +.Os +.Sh NAME +.Nm EVP_DigestVerifyInit , +.Nm EVP_DigestVerifyUpdate , +.Nm EVP_DigestVerifyFinal , +.Nm EVP_DigestVerify +.Nd EVP signature verification functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_DigestVerifyInit +.Fa "EVP_MD_CTX *ctx" +.Fa "EVP_PKEY_CTX **pctx" +.Fa "const EVP_MD *type" +.Fa "ENGINE *engine" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_DigestVerifyUpdate +.Fa "EVP_MD_CTX *ctx" +.Fa "const void *d" +.Fa "size_t cnt" +.Fc +.Ft int +.Fo EVP_DigestVerifyFinal +.Fa "EVP_MD_CTX *ctx" +.Fa "const unsigned char *sig" +.Fa "size_t siglen" +.Fc +.Ft int +.Fo EVP_DigestVerify +.Fa "EVP_MD_CTX *ctx" +.Fa "const unsigned char *sig" +.Fa "size_t siglen" +.Fa "const unsigned char *tbs" +.Fa "size_t *tbslen" +.Fc +.Sh DESCRIPTION +The EVP signature routines are a high-level interface to digital +signatures. +.Pp +.Fn EVP_DigestVerifyInit +sets up the verification context +.Fa ctx +to use the digest +.Fa type +and the public key +.Fa pkey . +Before calling this function, obtain +.Fa ctx +from +.Xr EVP_MD_CTX_new 3 +or call +.Xr EVP_MD_CTX_reset 3 +on it. +The +.Fa engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +If +.Fa pctx +is not +.Dv NULL , +any pointer passed in as +.Pf * Fa pctx +is ignored and overwritten by an internal pointer to the +.Vt EVP_PKEY_CTX +used by the verification operation: +this can be used to set alternative signing options. +The returned +.Vt EVP_PKEY_CTX +must not be freed by the application. +It is freed automatically when the +.Vt EVP_MD_CTX +is freed. +.Pp +.Fn EVP_DigestVerifyUpdate +hashes +.Fa cnt +bytes of data at +.Fa d +into the verification context +.Fa ctx . +This function can be called several times on the same +.Fa ctx +to include additional data. +This function is currently implemented using a macro. +.Pp +.Fn EVP_DigestVerifyFinal +verifies the data in +.Fa ctx +against the signature in +.Fa sig +of length +.Fa siglen . +.Pp +.Fn EVP_DigestVerify +verifies +.Fa tbslen +bytes at +.Fa tbs +against the signature in +.Fa sig +of length +.Fa siglen . +.Fn EVP_DigestVerify +is a one shot operation which verifies a single block of data +in one function call. +For algorithms that support streaming it is equivalent to calling +.Fn EVP_DigestVerifyUpdate +and +.Fn EVP_DigestVerifyFinal . +.\" For algorithms which do not support streaming +.\" (e.g. PureEdDSA) +.\" it is the only way to verify data. +.Pp +The EVP 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 +.Fn EVP_DigestVerifyFinal +internally finalizes a copy of the digest context. +This means that +.Xr EVP_VerifyUpdate 3 +and +.Xr EVP_VerifyFinal 3 +can be called later to digest and verify additional data. +.Pp +Since only a copy of the digest context is ever finalized, the context +must be cleaned up after use by calling +.Xr EVP_MD_CTX_free 3 +or a memory leak will occur. +.Sh RETURN VALUES +.Fn EVP_DigestVerifyInit +and +.Fn EVP_DigestVerifyUpdate +return 1 for success and 0 for failure. +.Pp +.Fn EVP_DigestVerifyFinal +and +.Fn EVP_DigestVerify +return 1 for success; any other value indicates failure. +A return value of 0 indicates that the signature did not verify +successfully (that is, the signature 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 +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_DigestSignInit 3 +.Sh HISTORY +.Fn EVP_DigestVerifyInit , +.Fn EVP_DigestVerifyUpdate , +and +.Fn EVP_DigestVerifyFinal +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +.Fn EVP_DigestVerify +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 7.0 . diff --git a/static/openbsd/man3/EVP_EncodeInit.3 b/static/openbsd/man3/EVP_EncodeInit.3 new file mode 100644 index 00000000..82f5687c --- /dev/null +++ b/static/openbsd/man3/EVP_EncodeInit.3 @@ -0,0 +1,335 @@ +.\" $OpenBSD: EVP_EncodeInit.3,v 1.8 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL f430ba31 Jun 19 19:39:01 2016 +0200 +.\" selective merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_ENCODEINIT 3 +.Os +.Sh NAME +.Nm EVP_ENCODE_CTX_new , +.Nm EVP_ENCODE_CTX_free , +.Nm EVP_EncodeInit , +.Nm EVP_EncodeUpdate , +.Nm EVP_EncodeFinal , +.Nm EVP_EncodeBlock , +.Nm EVP_DecodeInit , +.Nm EVP_DecodeUpdate , +.Nm EVP_DecodeFinal , +.Nm EVP_DecodeBlock +.Nd EVP base64 encode/decode routines +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft EVP_ENCODE_CTX * +.Fn EVP_ENCODE_CTX_new void +.Ft void +.Fo EVP_ENCODE_CTX_free +.Fa "EVP_ENCODE_CTX *ctx" +.Fc +.Ft void +.Fo EVP_EncodeInit +.Fa "EVP_ENCODE_CTX *ctx" +.Fc +.Ft int +.Fo EVP_EncodeUpdate +.Fa "EVP_ENCODE_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fa "const unsigned char *in" +.Fa "int inl" +.Fc +.Ft void +.Fo EVP_EncodeFinal +.Fa "EVP_ENCODE_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fc +.Ft int +.Fo EVP_EncodeBlock +.Fa "unsigned char *t" +.Fa "const unsigned char *f" +.Fa "int n" +.Fc +.Ft void +.Fo EVP_DecodeInit +.Fa "EVP_ENCODE_CTX *ctx" +.Fc +.Ft int +.Fo EVP_DecodeUpdate +.Fa "EVP_ENCODE_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fa "const unsigned char *in" +.Fa "int inl" +.Fc +.Ft int +.Fo EVP_DecodeFinal +.Fa "EVP_ENCODE_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fc +.Ft int +.Fo EVP_DecodeBlock +.Fa "unsigned char *t" +.Fa "const unsigned char *f" +.Fa "int n" +.Fc +.Sh 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. +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 +.Fn EVP_ENCODE_CTX_new +allocates, initializes and returns a context to be used for the encode +and decode functions. +.Pp +.Fn EVP_ENCODE_CTX_free +frees +.Fa ctx . +.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 +.Fn EVP_EncodeInit +initialises +.Fa ctx +for the start of a new encoding operation. +.Pp +.Fn EVP_EncodeUpdate +encodes +.Fa inl +bytes of data found in the buffer pointed to by +.Fa in . +The output is stored in the buffer +.Fa out +and the number of bytes output is stored in +.Pf * Fa outl . +It is the caller's responsibility to ensure that the buffer at +.Fa out +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 +.Fa ctx +object and will be processed by a subsequent call to +.Fn EVP_EncodeUpdate +or +.Fn EVP_EncodeFinal . +To calculate the required size of the output buffer, add together the +value of +.Fa inl +with the amount of unprocessed data held in +.Fa ctx +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. +.Fn EVP_EncodeUpdate +may be called repeatedly to process large amounts of input data. +In the event of an error , +.Fn EVP_EncodeUpdate +will set +.Pf * Fa outl +to 0 and return 0. +On success 1 will be returned. +.Pp +.Fn EVP_EncodeFinal +must be called at the end of an encoding operation. +It will process any partial block of data remaining in the +.Fa ctx +object. +The output data will be stored in +.Fa out +and the length of the data written will be stored in +.Pf * Fa outl . +It is the caller's responsibility to ensure that +.Fa out +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 +.Fn EVP_EncodeBlock +encodes a full block of input data in +.Fa f +and of length +.Fa n +and stores it in +.Fa t . +For every 3 bytes of input provided, 4 bytes of output data will be +produced. +If +.Sy n +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 are 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 +.Em without +the NUL terminator is returned from the function. +.Pp +.Fn EVP_DecodeInit +initialises +.Fa ctx +for the start of a new decoding operation. +.Pp +.Fn EVP_DecodeUpdate +decodes +.Fa inl +characters of data found in the buffer pointed to by +.Fa in . +The output is stored in the buffer +.Fa out +and the number of bytes output is stored in +.Pf * Fa outl . +It is the caller's responsibility to ensure that the buffer at +.Fa out +is sufficiently large to accommodate the output data. +This function will attempt to decode as much data as possible in 4-byte +chunks. +Any whitespace, newline or carriage return characters are ignored. +Any partial chunk of unprocessed data (1, 2 or 3 bytes) that remains at +the end will be held in the +.Fa ctx +object and processed by a subsequent call to +.Fn EVP_DecodeUpdate . +If any illegal base64 characters are encountered or if the base64 +padding character "=" is encountered in the middle of the data, +then the function 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 input data +characters processed included the base64 padding character "=" and +therefore no more non-padding character data is expected to be +processed. +For every 4 valid base64 bytes processed \(em ignoring whitespace, +carriage returns and line feeds \(em 3 bytes of binary output data +will be produced, or less at the end of the data where the padding +character "=" has been used. +.Pp +.Fn EVP_DecodeFinal +must be called at the end of a decoding operation. +If there is any unprocessed data still in +.Fa ctx , +then the input data must not have been a multiple of 4 and therefore an +error has occurred. +The function will return -1 in this case. +Otherwise the function returns 1 on success. +.Pp +.Fn EVP_DecodeBlock +will decode the block of +.Fa n +characters of base64 data contained in +.Fa f +and store the result in +.Fa t . +Any leading whitespace will be trimmed as will any trailing whitespace, +newlines, carriage returns or EOF characters. +After such trimming the length of the data in +.Fa f +must be divisible by 4. +For every 4 input bytes, exactly 3 output bytes will be produced. +The output will be padded with 0 bits if necessary to ensure that the +output is always 3 bytes for every 4 input bytes. +This function will return the length of the data decoded or -1 on error. +.Sh RETURN VALUES +.Fn EVP_ENCODE_CTX_new +returns a pointer to the newly allocated +.Vt EVP_ENCODE_CTX +object or +.Dv NULL +on error. +.Pp +.Fn EVP_EncodeUpdate +returns 0 on error or 1 on success. +.Pp +.Fn EVP_EncodeBlock +returns the number of bytes encoded excluding the NUL terminator. +.Pp +.Fn EVP_DecodeUpdate +returns -1 on error and 0 or 1 on success. +If 0 is returned, then no more non-padding base64 characters are +expected. +.Pp +.Fn EVP_DecodeFinal +returns -1 on error or 1 on success. +.Pp +.Fn EVP_DecodeBlock +returns the length of the data decoded or -1 on error. +.Sh SEE ALSO +.Xr BIO_f_base64 3 , +.Xr evp 3 +.Sh HISTORY +The +.Fn EVP_Encode* +and +.Fn EVP_Decode* +functions first appeared in SSLeay 0.5.1 +and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_ENCODE_CTX_new +and +.Fn EVP_ENCODE_CTX_free +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.5 . diff --git a/static/openbsd/man3/EVP_EncryptInit.3 b/static/openbsd/man3/EVP_EncryptInit.3 new file mode 100644 index 00000000..382c0e2b --- /dev/null +++ b/static/openbsd/man3/EVP_EncryptInit.3 @@ -0,0 +1,814 @@ +.\" $OpenBSD: EVP_EncryptInit.3,v 1.57 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800 +.\" EVP_bf_cbc.pod EVP_cast5_cbc.pod EVP_idea_cbc.pod EVP_rc2_cbc.pod +.\" 7c6d372a Nov 20 13:20:01 2018 +0000 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019, 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Richard Levitte . +.\" Copyright (c) 2000-2002, 2005, 2012-2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_ENCRYPTINIT 3 +.Os +.Sh NAME +.Nm EVP_CIPHER_CTX_new , +.Nm EVP_CIPHER_CTX_reset , +.Nm EVP_CIPHER_CTX_free , +.Nm EVP_CIPHER_CTX_copy , +.Nm EVP_EncryptInit_ex , +.Nm EVP_EncryptUpdate , +.Nm EVP_EncryptFinal_ex , +.Nm EVP_DecryptInit_ex , +.Nm EVP_DecryptUpdate , +.Nm EVP_DecryptFinal_ex , +.Nm EVP_CipherInit_ex , +.Nm EVP_CipherUpdate , +.Nm EVP_CipherFinal_ex , +.Nm EVP_EncryptInit , +.Nm EVP_EncryptFinal , +.Nm EVP_DecryptInit , +.Nm EVP_DecryptFinal , +.Nm EVP_CipherInit , +.Nm EVP_CipherFinal , +.Nm EVP_CIPHER_CTX_encrypting , +.Nm EVP_get_cipherbyname , +.Nm EVP_get_cipherbynid , +.Nm EVP_get_cipherbyobj , +.Nm EVP_CIPHER_CTX_cipher , +.Nm EVP_enc_null , +.Nm EVP_idea_cbc , +.Nm EVP_idea_ecb , +.Nm EVP_idea_cfb64 , +.Nm EVP_idea_cfb , +.Nm EVP_idea_ofb , +.Nm EVP_bf_cbc , +.Nm EVP_bf_ecb , +.Nm EVP_bf_cfb64 , +.Nm EVP_bf_cfb , +.Nm EVP_bf_ofb , +.Nm EVP_cast5_cbc , +.Nm EVP_cast5_ecb , +.Nm EVP_cast5_cfb64 , +.Nm EVP_cast5_cfb , +.Nm EVP_cast5_ofb +.Nd EVP cipher routines +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft EVP_CIPHER_CTX * +.Fn EVP_CIPHER_CTX_new void +.Ft int +.Fo EVP_CIPHER_CTX_reset +.Fa "EVP_CIPHER_CTX *ctx" +.Fc +.Ft void +.Fo EVP_CIPHER_CTX_free +.Fa "EVP_CIPHER_CTX *ctx" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_copy +.Fa "EVP_CIPHER_CTX *out" +.Fa "const EVP_CIPHER_CTX *in" +.Fc +.Ft int +.Fo EVP_EncryptInit_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "ENGINE *engine" +.Fa "const unsigned char *key" +.Fa "const unsigned char *iv" +.Fc +.Ft int +.Fo EVP_EncryptUpdate +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *out_len" +.Fa "const unsigned char *in" +.Fa "int in_len" +.Fc +.Ft int +.Fo EVP_EncryptFinal_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *out_len" +.Fc +.Ft int +.Fo EVP_DecryptInit_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "ENGINE *engine" +.Fa "const unsigned char *key" +.Fa "const unsigned char *iv" +.Fc +.Ft int +.Fo EVP_DecryptUpdate +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *out_len" +.Fa "const unsigned char *in" +.Fa "int in_len" +.Fc +.Ft int +.Fo EVP_DecryptFinal_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *out_len" +.Fc +.Ft int +.Fo EVP_CipherInit_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "ENGINE *engine" +.Fa "const unsigned char *key" +.Fa "const unsigned char *iv" +.Fa "int enc" +.Fc +.Ft int +.Fo EVP_CipherUpdate +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *out_len" +.Fa "const unsigned char *in" +.Fa "int in_len" +.Fc +.Ft int +.Fo EVP_CipherFinal_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *out_len" +.Fc +.Ft int +.Fo EVP_EncryptInit +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "const unsigned char *key" +.Fa "const unsigned char *iv" +.Fc +.Ft int +.Fo EVP_EncryptFinal +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *out_len" +.Fc +.Ft int +.Fo EVP_DecryptInit +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "const unsigned char *key" +.Fa "const unsigned char *iv" +.Fc +.Ft int +.Fo EVP_DecryptFinal +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *out_len" +.Fc +.Ft int +.Fo EVP_CipherInit +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "const unsigned char *key" +.Fa "const unsigned char *iv" +.Fa "int enc" +.Fc +.Ft int +.Fo EVP_CipherFinal +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *out_len" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_encrypting +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Ft const EVP_CIPHER * +.Fo EVP_get_cipherbyname +.Fa "const char *name" +.Fc +.Ft const EVP_CIPHER * +.Fo EVP_get_cipherbynid +.Fa "int nid" +.Fc +.Ft const EVP_CIPHER * +.Fo EVP_get_cipherbyobj +.Fa "const ASN1_OBJECT *a" +.Fc +.Ft const EVP_CIPHER * +.Fo EVP_CIPHER_CTX_cipher +.Fa "const EVP_CIPHER_CTX *ctx" +.Fc +.Sh DESCRIPTION +The EVP cipher routines are a high level interface to certain symmetric +ciphers. +.Pp +.Fn EVP_CIPHER_CTX_new +creates a new, empty cipher context. +.Pp +.Fn EVP_CIPHER_CTX_reset +clears all information from +.Fa ctx +and frees all allocated memory associated with it, except the +.Fa ctx +object itself, such that it can be reused for another series of calls to +.Fn EVP_CipherInit , +.Fn EVP_CipherUpdate , +and +.Fn EVP_CipherFinal . +.Pp +.Fn EVP_CIPHER_CTX_free +clears all information from +.Fa ctx +and frees all allocated memory associated with it, including +.Fa ctx +itself. +This function should be called after all operations using a cipher +are complete, so sensitive information does not remain in memory. +If +.Fa ctx +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn EVP_CIPHER_CTX_copy +calls +.Fn EVP_CIPHER_CTX_reset +on +.Fa out +and copies all the data from +.Fa in +to +.Fa out , +except that the +.Vt EVP_CIPHER +object used by +.Fa in +and any application specific data set with +.Xr EVP_CIPHER_CTX_set_app_data 3 +are not copied and +.Fa out +will point to the same two objects. +The algorithm- and implementation-specific cipher data described in +.Xr EVP_CIPHER_CTX_get_cipher_data 3 +is copied with +.Xr malloc 3 +and +.Xr memcpy 3 , +i.e. assuming that it does not contain pointers to any sub-objects. +If the bit +.Dv EVP_CIPH_CUSTOM_COPY +has been set with +.Xr EVP_CIPHER_meth_set_flags 3 , +.Xr EVP_CIPHER_CTX_ctrl 3 +is called at the end with arguments +.Fa in , +.Dv EVP_CTRL_COPY , +.No 0 , +and +.Fa out +such that the cipher implementation can perform further algorithm- +and implementation-specific initializations after the algorithm- +and implementation-specific cipher data has been copied. +Among the cipher algorithms built into the library, +.Dv EVP_CIPH_CUSTOM_COPY +and +.Dv EVP_CTRL_COPY +are used by some of the ciphers documented in the +.Xr EVP_aes_256_gcm 3 +manual page. +.Pp +.Fn EVP_EncryptInit +and +.Fn EVP_EncryptInit_ex +set up the cipher context +.Fa ctx +for encryption with cipher +.Fa type . +.Fa type +is normally supplied by a function such as +.Xr EVP_aes_256_cbc 3 . +.Fa key +is the symmetric key to use and +.Fa iv +is the IV to use (if necessary). +The actual number of bytes used for the +key and IV depends on the cipher. +The +.Fa ENGINE *engine +argument is always ignored and passing +.Dv NULL +is recommended. +It is possible to set all parameters to +.Dv NULL +except +.Fa type +in an initial call and supply the remaining parameters in subsequent +calls, all of which have +.Fa type +set to +.Dv NULL . +This is done when the default cipher parameters are not appropriate. +.Pp +.Fn EVP_EncryptUpdate +encrypts +.Fa in_len +bytes from the buffer +.Fa in +and writes the encrypted version to +.Fa out . +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: as a result the amount of data written may be anything +from zero bytes to +.Pq Fa in_len No + cipher_block_size - 1 +so +.Fa out +should contain sufficient room. +The actual number of bytes written is placed in +.Pf * Fa out_len . +.Pp +If padding is enabled (the default) then +.Fn EVP_EncryptFinal +and +.Fn EVP_EncryptFinal_ex , +which behave identically, +encrypt the "final" data, that is any data that remains in a partial +block. +It uses NOTES (aka PKCS padding). +The encrypted final data is written to +.Fa out +which should have sufficient space for one cipher block. +The number of bytes written is placed in +.Pf * Fa out_len . +After this function is called, the encryption operation is finished and +no further calls to +.Fn EVP_EncryptUpdate +should be made. +.Pp +If padding is disabled then +.Fn EVP_EncryptFinal +and +.Fn EVP_EncryptFinal_ex +do not encrypt any more data and 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. +.Pp +.Fn EVP_DecryptInit , +.Fn EVP_DecryptInit_ex , +.Fn EVP_DecryptUpdate , +.Fn EVP_DecryptFinal , +and +.Fn EVP_DecryptFinal_ex +are the corresponding decryption operations. +.Fn EVP_DecryptFinal +and +.Fn EVP_DecryptFinal_ex +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 except that if padding is enabled the decrypted data buffer +.Fa out +passed to +.Fn EVP_DecryptUpdate +should have sufficient room for +.Pq Fa in_len No + cipher_block_size +bytes unless the cipher block size is 1 in which case +.Fa in_len +bytes is sufficient. +.Pp +.Fn EVP_CipherInit , +.Fn EVP_CipherInit_ex , +.Fn EVP_CipherUpdate , +.Fn EVP_CipherFinal , +and +.Fn EVP_CipherFinal_ex +are functions that can be used for decryption or encryption. +The operation performed depends on the value of the +.Fa enc +parameter. +It should be set to 1 for encryption, 0 for decryption and -1 to leave +the value unchanged (the actual value of +.Fa enc +being supplied in a previous call). +.Pp +.Fn EVP_get_cipherbyname , +.Fn EVP_get_cipherbynid , +and +.Fn EVP_get_cipherbyobj +return an +.Vt EVP_CIPHER +structure when passed a cipher name, a NID or an +.Vt ASN1_OBJECT +structure. +.Pp +.Fn EVP_CIPHER_CTX_cipher +returns the +.Vt EVP_CIPHER +structure when passed an +.Vt EVP_CIPHER_CTX +structure. +.Pp +Where possible the EVP 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. +.Pp +PKCS padding works by adding n padding bytes of value n 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 n 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 +.Fn EVP_get_cipherbynid +and +.Fn EVP_get_cipherbyobj +are implemented as macros. +.Sh RETURN VALUES +.Fn EVP_CIPHER_CTX_new +returns a pointer to a newly created +.Vt EVP_CIPHER_CTX +for success or +.Dv NULL +for failure. +.Pp +.Fn EVP_CIPHER_CTX_reset , +.Fn EVP_CIPHER_CTX_copy , +.Fn EVP_EncryptInit_ex , +.Fn EVP_EncryptUpdate , +.Fn EVP_EncryptFinal_ex , +.Fn EVP_DecryptInit_ex , +.Fn EVP_DecryptUpdate , +.Fn EVP_DecryptFinal_ex , +.Fn EVP_CipherInit_ex , +.Fn EVP_CipherUpdate , +.Fn EVP_CipherFinal_ex , +.Fn EVP_EncryptInit , +.Fn EVP_EncryptFinal , +.Fn EVP_DecryptInit , +.Fn EVP_DecryptFinal , +.Fn EVP_CipherInit , +and +.Fn EVP_CipherFinal +return 1 for success or 0 for failure. +.Pp +.Fn EVP_CIPHER_CTX_encrypting +returns 1 if +.Fa ctx +is initialized for encryption or 0 otherwise, in which case +it may be uninitialized or initialized for decryption. +.Pp +.Fn EVP_get_cipherbyname , +.Fn EVP_get_cipherbynid , +and +.Fn EVP_get_cipherbyobj +return an +.Vt EVP_CIPHER +structure or +.Dv NULL +on error. +.Pp +.Fn EVP_CIPHER_CTX_cipher +returns an +.Vt EVP_CIPHER +structure. +.Sh CIPHER LISTING +.Bl -tag -width Ds +.It Fn EVP_enc_null +Null cipher: does nothing. +.It Xo +.Fn EVP_idea_cbc , +.Fn EVP_idea_ecb , +.Fn EVP_idea_cfb64 , +.Fn EVP_idea_ofb +.Xc +IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. +IDEA is a block cipher operating on 64 bit blocks using a 128 bit +.Fa key . +.Fn EVP_idea_cfb +is an alias for +.Fn EVP_idea_cfb64 , +implemented as a macro. +.It Xo +.Fn EVP_bf_cbc , +.Fn EVP_bf_ecb , +.Fn EVP_bf_cfb64 , +.Fn EVP_bf_ofb +.Xc +Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes +respectively. +Blowfish is a block cipher operating on 64 bit blocks using a variable +.Fa key +length. +The default key length is 128 bits. +.Fn EVP_bf_cfb +is an alias for +.Fn EVP_bf_cfb64 , +implemented as a macro. +.It Xo +.Fn EVP_cast5_cbc , +.Fn EVP_cast5_ecb , +.Fn EVP_cast5_cfb64 , +.Fn EVP_cast5_ofb +.Xc +CAST-128 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. +CAST-128 is a block cipher operating on 64 bit blocks using a variable +.Fa key +length. +The default and maximum key length is 128 bits. +.Fn EVP_cast5_cfb +is an alias for +.Fn EVP_cast5_cfb64 , +implemented as a macro. +.El +.Pp +Some algorithms are documented in separate manual pages: +.Pp +.Bl -column "EVP_camellia_128_cbc(3)" "block size" -compact +.It manual page Ta block size Ta Fa key No size Pq in bits +.It Xr EVP_aes_128_cbc 3 Ta 128 Ta 128, 192, 256 +.It Xr EVP_aes_128_ccm 3 Ta 128 Ta 128, 192, 256 +.It Xr EVP_aes_128_gcm 3 Ta 128 Ta 128, 192, 256 +.It Xr EVP_camellia_128_cbc 3 Ta 128 Ta 128, 192, 256 +.It Xr EVP_chacha20 3 Ta stream Ta 256 +.It Xr EVP_des_cbc 3 Ta 64 Ta 64 +.It Xr EVP_rc2_cbc 3 Ta 64 Ta variable, default 128 +.It Xr EVP_rc4 3 Ta stream Ta variable, default 128 +.It Xr EVP_sm4_cbc 3 Ta 128 Ta 128 +.El +.Sh EXAMPLES +Encrypt a string using blowfish: +.Bd -literal -offset 3n +int +do_crypt(char *out_filename) +{ + unsigned char out_buf[1024]; + int out_len, tmp_len; + /* + * Bogus key and IV: we'd 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}; + const char in_text[] = "Some Crypto Text"; + EVP_CIPHER_CTX *ctx; + FILE *out_fileptr; + + ctx = EVP_CIPHER_CTX_new(); + EVP_EncryptInit_ex(ctx, EVP_bf_cbc(), NULL, key, iv); + + if (!EVP_EncryptUpdate(ctx, out_buf, &out_len, in_text, + strlen(in_text))) { + /* 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, out_buf + out_len, &tmp_len)) { + /* Error */ + EVP_CIPHER_CTX_free(ctx); + return 0; + } + out_len += tmp_len; + 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't be NUL terminated and may contain embedded + * NULs. + */ + out_fileptr = fopen(out_filename, "wb"); + if (out_fileptr == NULL) { + /* Error */ + return 0; + } + fwrite(out_buf, 1, out_len, out_fileptr); + fclose(out_fileptr); + return 1; +} +.Ed +.Pp +The ciphertext from the above example can be decrypted using the +.Xr openssl 1 +utility with the command line: +.Bd -literal -offset indent +openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F \e + -iv 0102030405060708 -d +.Ed +.Pp +General encryption, decryption function example using FILE I/O and AES128 +with a 128-bit key: +.Bd -literal +int +do_crypt(FILE *in_fileptr, FILE *out_fileptr, int do_encrypt) +{ + /* Allow enough space in output buffer for additional block */ + unsigned char in_buf[1024], out_buf[1024 + EVP_MAX_BLOCK_LENGTH]; + int in_len, out_len; + EVP_CIPHER_CTX *ctx; + + /* + * Bogus key and IV: we'd normally set these from + * another source. + */ + unsigned char key[] = "0123456789abcdeF"; + unsigned char iv[] = "1234567887654321"; + + ctx = EVP_CIPHER_CTX_new(); + EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, + do_encrypt); + EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); + + for (;;) { + in_len = fread(in_buf, 1, 1024, in_fileptr); + if (in_len <= 0) + break; + if (!EVP_CipherUpdate(ctx, out_buf, &out_len, in_buf, + in_len)) { + /* Error */ + EVP_CIPHER_CTX_free(ctx); + return 0; + } + fwrite(out_buf, 1, out_len, out_fileptr); + } + if (!EVP_CipherFinal_ex(ctx, out_buf, &out_len)) { + /* Error */ + EVP_CIPHER_CTX_free(ctx); + return 0; + } + fwrite(out_buf, 1, out_len, out_fileptr); + + EVP_CIPHER_CTX_free(ctx); + return 1; +} +.Ed +.Sh SEE ALSO +.Xr BIO_f_cipher 3 , +.Xr evp 3 , +.Xr EVP_AEAD_CTX_init 3 , +.Xr EVP_aes_128_cbc 3 , +.Xr EVP_aes_128_ccm 3 , +.Xr EVP_aes_128_gcm 3 , +.Xr EVP_camellia_128_cbc 3 , +.Xr EVP_chacha20 3 , +.Xr EVP_CIPHER_CTX_ctrl 3 , +.Xr EVP_CIPHER_CTX_get_cipher_data 3 , +.Xr EVP_CIPHER_CTX_init 3 , +.Xr EVP_CIPHER_CTX_set_flags 3 , +.Xr EVP_CIPHER_nid 3 , +.Xr EVP_des_cbc 3 , +.Xr EVP_OpenInit 3 , +.Xr EVP_rc2_cbc 3 , +.Xr EVP_rc4 3 , +.Xr EVP_SealInit 3 , +.Xr EVP_sm4_cbc 3 +.Sh HISTORY +.Fn EVP_EncryptInit , +.Fn EVP_EncryptUpdate , +.Fn EVP_EncryptFinal , +.Fn EVP_DecryptInit , +.Fn EVP_DecryptUpdate , +.Fn EVP_DecryptFinal , +.Fn EVP_CipherInit , +.Fn EVP_CipherUpdate , +.Fn EVP_CipherFinal , +.Fn EVP_get_cipherbyname , +.Fn EVP_idea_cbc , +.Fn EVP_idea_ecb , +.Fn EVP_idea_cfb , +and +.Fn EVP_idea_ofb +first appeared in SSLeay 0.5.1. +.Fn EVP_bf_cbc , +.Fn EVP_bf_ecb , +.Fn EVP_bf_cfb , +and +.Fn EVP_bf_ofb +first appeared in SSLeay 0.6.6. +.Fn EVP_get_cipherbyobj , +.Fn EVP_CIPHER_CTX_cipher , +and +.Fn EVP_enc_null +first appeared in SSLeay 0.8.0. +.Fn EVP_get_cipherbynid +first appeared in SSLeay 0.8.1. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_EncryptInit_ex , +.Fn EVP_EncryptFinal_ex , +.Fn EVP_DecryptInit_ex , +.Fn EVP_DecryptFinal_ex , +.Fn EVP_CipherInit_ex , +and +.Fn EVP_CipherFinal_ex +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EVP_bf_cfb64 , +.Fn EVP_cast5_cfb64 , +and +.Fn EVP_idea_cfb64 +first appeared in OpenSSL 0.9.7e and have been available since +.Ox 3.8 . +.Pp +.Fn EVP_CIPHER_CTX_new +and +.Fn EVP_CIPHER_CTX_free +first appeared in OpenSSL 0.9.8b and have been available since +.Ox 4.5 . +.Pp +.Fn EVP_CIPHER_CTX_copy +first appeared in OpenSSL 1.0.0 +and has been available since +.Ox 4.9 . +.Pp +.Fn EVP_CIPHER_CTX_reset +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . +.Pp +.Fn EVP_CIPHER_CTX_encrypting +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.4 . +.Sh BUGS +.Fn EVP_CIPHER_CTX_copy +may already have cleared the data in +.Fa out +and copied some new data into it even if it fails and returns 0. diff --git a/static/openbsd/man3/EVP_MD_CTX_ctrl.3 b/static/openbsd/man3/EVP_MD_CTX_ctrl.3 new file mode 100644 index 00000000..a16bba9b --- /dev/null +++ b/static/openbsd/man3/EVP_MD_CTX_ctrl.3 @@ -0,0 +1,282 @@ +.\" $OpenBSD: EVP_MD_CTX_ctrl.3,v 1.5 2025/06/11 13:48:54 schwarze Exp $ +.\" full merge up to: OpenSSL man3/EVP_DigestInit.pod +.\" 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Richard Levitte , +.\" Todd Short , Paul Yang , +.\" and Antoine Salon . +.\" Copyright (c) 2015, 2016, 2018, 2019 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 11 2025 $ +.Dt EVP_MD_CTX_CTRL 3 +.Os +.Sh NAME +.Nm EVP_MD_CTX_ctrl , +.Nm EVP_MD_CTX_set_flags , +.Nm EVP_MD_CTX_clear_flags , +.Nm EVP_MD_CTX_test_flags , +.Nm EVP_MD_CTX_pkey_ctx , +.Nm EVP_MD_CTX_set_pkey_ctx , +.Nm EVP_MD_CTX_md_data +.Nd configure EVP message digest contexts +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_MD_CTX_ctrl +.Fa "EVP_MD_CTX *ctx" +.Fa "int command" +.Fa "int p1" +.Fa "void* p2" +.Fc +.Ft void +.Fo EVP_MD_CTX_set_flags +.Fa "EVP_MD_CTX *ctx" +.Fa "int flags" +.Fc +.Ft void +.Fo EVP_MD_CTX_clear_flags +.Fa "EVP_MD_CTX *ctx" +.Fa "int flags" +.Fc +.Ft int +.Fo EVP_MD_CTX_test_flags +.Fa "const EVP_MD_CTX *ctx" +.Fa "int flags" +.Fc +.Ft EVP_PKEY_CTX * +.Fo EVP_MD_CTX_pkey_ctx +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft void +.Fo EVP_MD_CTX_set_pkey_ctx +.Fa "EVP_MD_CTX *ctx" +.Fa "EVP_PKEY_CTX *pctx" +.Fc +.Ft void * +.Fo EVP_MD_CTX_md_data +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn EVP_MD_CTX_ctrl +performs the digest-specific control +.Fa command +with the command-specific arguments +.Fa p1 +and +.Fa p2 +on +.Fa ctx , +which needs to already be set up with +.Xr EVP_DigestInit_ex 3 +before calling this function. +Other restrictions may apply depending on the control +.Fa command +and digest implementation. +.Pp +If the +.Fa command +is +.Dv EVP_MD_CTRL_MICALG , +.Fa p1 +is ignored and +.Fa p2 +is an output argument of the type +.Fa "char **p2" . +A string specifying the digest Message Integrity Check algorithm +is allocated and a pointer to this string is returned in +.Pf * Fa p2 . +It is the responsibility of the caller to +.Xr free 3 +.Pf * Fa p2 +when it is no longer needed. +This +.Fa command +is used by +.Xr SMIME_write_CMS 3 +and +.Xr SMIME_write_PKCS7 3 +when creating S/MIME multipart/signed messages as specified in RFC 3851. +.Pp +.Fn EVP_MD_CTX_set_flags +sets and +.Fn EVP_MD_CTX_clear_flags +clears all the flag bits in +.Fa ctx +that are set in the +.Fa flags +argument. +.Fn EVP_MD_CTX_test_flags +tests which of the flag bits that are set in the +.Fa flags +argument are also set in +.Fa ctx . +Possible flag bits are: +.Bl -tag -width Ds -offset 2n +.It Dv EVP_MD_CTX_FLAG_NO_INIT +Instruct +.Xr EVP_DigestInit_ex 3 +and functions calling it not to initialise the internal data +that is specific to the digest method and its implementation. +.It Dv EVP_MD_CTX_FLAG_ONESHOT +Instruct the digest to optimize for one update only, if possible. +For digest algorithms built into the library, this flag usually +has no effect. +.El +.Pp +.Fn EVP_MD_CTX_pkey_ctx +returns the +.Vt EVP_PKEY_CTX +assigned to +.Fa ctx . +The returned pointer should not be freed by the caller. +.Pp +.Fn EVP_MD_CTX_set_pkey_ctx +assigns +.Fa pctx +to +.Fa ctx . +This is normally used to provide a customized +.Vt EVP_PKEY_CTX +to +.Xr EVP_DigestSignInit 3 +or +.Xr EVP_DigestVerifyInit 3 . +The caller retains ownership of the +.Fa pctx +passed to this function and is responsible for freeing it +when it is no longer needed. +.Pp +If the +.Fa ctx +already contains a +.Vt EVP_PKEY_CTX +when this function is called, that old +.Vt EVP_PKEY_CTX +is freed if it was created internally, but if it was also installed with +.Fn EVP_MD_CTX_set_pkey_ctx , +the pointer to the old +.Vt EVP_PKEY_CTX +is merely replaced by the new pointer and ownership of the old +.Vt EVP_PKEY_CTX +remains with the previous caller. +.Pp +Passing a +.Dv NULL +pointer for the +.Fa pctx +argument is also allowed. +In that case, any +.Vt EVP_PKEY_CTX +already assigned to +.Fa ctx +is dissociated from it as described above, but no new +.Vt EVP_PKEY_CTX +is assigned. +.Pp +.Fn EVP_MD_CTX_md_data +returns the digest method private data of +.Fa ctx . +The space is allocated with a size determined at compile time. +The size is not exposed by an API. +.Sh RETURN VALUES +.Fn EVP_MD_CTX_ctrl +returns 1 for success or 0 for failure. +.Pp +.Fn EVP_MD_CTX_test_flags +returns the bitwise OR of the +.Fa flags +argument and the flags set in +.Fa ctx . +.Pp +.Fn EVP_MD_CTX_pkey_ctx +and +.Fn EVP_MD_CTX_md_data +return pointers to storage owned by +.Fa ctx . +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_MD_nid 3 +.Sh HISTORY +.Fn EVP_MD_CTX_set_flags , +.Fn EVP_MD_CTX_clear_flags , +and +.Fn EVP_MD_CTX_test_flags , +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EVP_MD_CTX_ctrl +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 5.7 . +.Pp +.Fn EVP_MD_CTX_pkey_ctx +and +.Fn EVP_MD_CTX_md_data +first appeared in OpenSSL 1.1.0 and +.Fn EVP_MD_CTX_set_pkey_ctx +in OpenSSL 1.1.1. +These functions have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/EVP_MD_nid.3 b/static/openbsd/man3/EVP_MD_nid.3 new file mode 100644 index 00000000..384c0431 --- /dev/null +++ b/static/openbsd/man3/EVP_MD_nid.3 @@ -0,0 +1,316 @@ +.\" $OpenBSD: EVP_MD_nid.3,v 1.5 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL man3/EVP_DigestInit.pod +.\" 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Antoine Salon . +.\" Copyright (c) 2000, 2012, 2019 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_MD_NID 3 +.Os +.Sh NAME +.Nm EVP_MD_nid , +.Nm EVP_MD_type , +.Nm EVP_MD_CTX_type , +.Nm EVP_MD_name , +.Nm EVP_MD_size , +.Nm EVP_MD_CTX_size , +.Nm EVP_MD_block_size , +.Nm EVP_MD_CTX_block_size , +.Nm EVP_MD_flags , +.Nm EVP_MD_pkey_type +.Nd inspect EVP_MD objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_MD_nid +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_type +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_CTX_type +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft const char * +.Fo EVP_MD_name +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_size +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_CTX_size +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft int +.Fo EVP_MD_block_size +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_CTX_block_size +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft unsigned long +.Fo EVP_MD_flags +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_pkey_type +.Fa "const EVP_MD *md" +.Fc +.Sh DESCRIPTION +.Fn EVP_MD_nid +and +.Fn EVP_MD_type +are identical and return the numerical identifier (NID) of +.Fa md . +The NID is an internal value which may or may not have +a corresponding ASN.1 OBJECT IDENTIFIER; see +.Xr OBJ_nid2obj 3 +for details. +For example , +.Fn EVP_MD_type EVP_sha512() +returns +.Dv NID_sha512 . +.Fn EVP_MD_CTX_type +returns the NID of the message digest algorithm that +.Fa ctx +is configured to use. +These functions are normally used when setting ASN.1 OIDs. +.Pp +.Fn EVP_MD_name +converts the NID of +.Fa md +to its short name with +.Xr OBJ_nid2sn 3 . +.Pp +.Fn EVP_MD_size +returns the size in bytes of the message digests (hashes) produced by +.Fa md . +.Fn EVP_MD_CTX_size +return the size of the hashes produced by the message digest algorithm that +.Fa ctx +is configured to use. +.Pp +.Fn EVP_MD_block_size +returns the block size in bytes of +.Fa md . +.Fn EVP_MD_CTX_block_size +returns the block size of the message digest algorithm that +.Fa ctx +is configured to use. +.Pp +.Fn EVP_MD_flags +returns the message digest flags used by +.Fa md . +Be careful to not confuse these flags with the unrelated +message digest context flags that can be inspected with +.Xr EVP_MD_CTX_test_flags 3 . +The available flags are: +.Bl -tag -width Ds +.It Dv EVP_MD_FLAG_DIGALGID_NULL +The parameters in a +.Vt DigestAlgorithmIdentifier +are encoded using an explicit ASN.1 +.Dv NULL +rather than omitting them. +This is the default, which means that it takes effect for +.Vt EVP_MD +objects that do not have +.Dv EVP_MD_FLAG_DIGALGID_ABSENT +set. +.It Dv EVP_MD_FLAG_DIGALGID_ABSENT +The parameters in a +.Vt DigestAlgorithmIdentifier +are omitted from the ASN.1 encoding. +This is used by the +.Vt EVP_MD +objects documented in the manual page +.Xr EVP_sha3_224 3 +and by the objects returned from +.Xr EVP_sha512 3 , +.Xr EVP_sha512_256 3 , +.Xr EVP_sha512_224 3 , +.Xr EVP_sha384 3 , +.Xr EVP_sha256 3 , +.Xr EVP_sha224 3 , +.Xr EVP_sha1 3 , +and +.Xr EVP_sm3 3 . +.It Dv EVP_MD_FLAG_DIGALGID_CUSTOM +This flag is reserved for user-defined +.Vt EVP_MD +objects supporting custom +.Vt DigestAlgorithmIdentifier +handling via +.Xr EVP_MD_CTX_ctrl 3 , +but actually, it is ignored by both LibreSSL and OpenSSL +and such user-defined behaviour is not supported by the libraries. +.It Dv EVP_MD_FLAG_FIPS +Mark the digest method as suitable for FIPS mode. +This flag is ignored by both LibreSSL and OpenSSL. +.It Dv EVP_MD_FLAG_ONESHOT +Intended to indicate that the digest method can only handle one block +of input, but actually, this flag is ignored by both LibreSSL and OpenSSL. +.El +.Pp +.Fn EVP_MD_pkey_type +returns the NID of the public key signing algorithm associated with this +digest. +For example, +.Xr EVP_sha512 3 +is associated with RSA, so this returns +.Dv NID_sha512WithRSAEncryption . +Since digests and signature algorithms are no longer linked, this +function is only retained for compatibility reasons. +.Pp +.Fn EVP_MD_nid , +.Fn EVP_MD_CTX_type , +.Fn EVP_MD_name , +.Fn EVP_MD_CTX_size , +and +.Fn EVP_MD_CTX_block_size +are implemented as macros. +.Sh RETURN VALUES +.Fn EVP_MD_nid , +.Fn EVP_MD_type , +.Fn EVP_MD_CTX_type , +and +.Fn EVP_MD_pkey_type +return the NID of the corresponding OBJECT IDENTIFIER or +.Dv NID_undef +if none exists. +.Pp +.Fn EVP_MD_name +returns a pointer to a string +that is owned by an internal library object or +.Dv NULL +if the NID is neither built into the library nor added to the global +object table by one of the functions documented in the manual page +.Xr OBJ_create 3 , +or if the object does not contain a short name. +.Pp +.Fn EVP_MD_size , +.Fn EVP_MD_CTX_size , +.Fn EVP_MD_block_size , +and +.Fn EVP_MD_CTX_block_size +return the digest or block size in bytes. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_MD_CTX_ctrl 3 , +.Xr OBJ_nid2obj 3 +.Sh STANDARDS +RFC 5754: Using SHA2 Algorithms with Cryptographic Message Syntax +.Bl -dash -compact -offset indent +.It +section 2: Message Digest Algorithms +.El +.Sh HISTORY +.Fn EVP_MD_size +first appeared in SSLeay 0.6.6, +.Fn EVP_MD_CTX_size +and +.Fn EVP_MD_CTX_type +in SSLeay 0.8.0, +.Fn EVP_MD_type +and +.Fn EVP_MD_pkey_type +in SSLeay 0.8.1, and +.Fn EVP_MD_block_size +and +.Fn EVP_MD_CTX_block_size +in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_MD_nid +and +.Fn EVP_MD_name +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EVP_MD_flags +first appeared in OpenSSL 1.0.0 +and has been available since +.Ox 4.9 . +.Sh CAVEATS +The behaviour of the functions taking an +.Vt EVP_MD_CTX +argument is undefined if they are called on a +.Fa ctx +that has no message digest configured yet, +for example one freshly returned from +.Xr EVP_MD_CTX_new 3 . +In that case, the program may for example be terminated by a +.Dv NULL +pointer access. diff --git a/static/openbsd/man3/EVP_OpenInit.3 b/static/openbsd/man3/EVP_OpenInit.3 new file mode 100644 index 00000000..c731a0e2 --- /dev/null +++ b/static/openbsd/man3/EVP_OpenInit.3 @@ -0,0 +1,156 @@ +.\" $OpenBSD: EVP_OpenInit.3,v 1.11 2026/01/30 14:26:04 tb Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: January 30 2026 $ +.Dt EVP_OPENINIT 3 +.Os +.Sh NAME +.Nm EVP_OpenInit , +.Nm EVP_OpenUpdate , +.Nm EVP_OpenFinal +.Nd EVP envelope decryption +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_OpenInit +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "EVP_CIPHER *type" +.Fa "unsigned char *ek" +.Fa "int ekl" +.Fa "unsigned char *iv" +.Fa "EVP_PKEY *priv" +.Fc +.Ft int +.Fo EVP_OpenUpdate +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fa "unsigned char *in" +.Fa "int inl" +.Fc +.Ft int +.Fo EVP_OpenFinal +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fc +.Sh 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 +.Fn EVP_OpenInit +initializes a cipher context +.Fa ctx +for decryption with cipher +.Fa type . +It decrypts the encrypted symmetric key of length +.Fa ekl +bytes passed in the +.Fa ek +parameter using the private key +.Fa priv . +The IV is supplied in the +.Fa iv +parameter. +.Pp +.Fn EVP_OpenUpdate +and +.Fn EVP_OpenFinal +have exactly the same properties as the +.Xr EVP_DecryptUpdate 3 +and +.Xr EVP_DecryptFinal 3 +routines. +.Pp +It is possible to call +.Fn EVP_OpenInit +twice in the same way as +.Xr EVP_DecryptInit 3 . +The first call should have +.Fa priv +set to +.Dv NULL +and (after setting any cipher parameters) it should be +called again with +.Fa type +set to +.Dv NULL . +.Pp +If the cipher passed in the +.Fa type +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. +.Pp +.Fn EVP_OpenUpdate +is implemented as a macro. +.Sh RETURN VALUES +.Fn EVP_OpenInit +and +.Fn EVP_OpenUpdate +return 1 for success or 0 for failure. +.Pp +.Fn EVP_OpenFinal +returns 0 if the decrypt failed or 1 for success. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_SealInit 3 +.Sh HISTORY +.Fn EVP_OpenInit , +.Fn EVP_OpenUpdate , +and +.Fn EVP_OpenFinal +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/EVP_PKCS82PKEY.3 b/static/openbsd/man3/EVP_PKCS82PKEY.3 new file mode 100644 index 00000000..a8b7d868 --- /dev/null +++ b/static/openbsd/man3/EVP_PKCS82PKEY.3 @@ -0,0 +1,61 @@ +.\" $OpenBSD: EVP_PKCS82PKEY.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt EVP_PKCS82PKEY 3 +.Os +.Sh NAME +.Nm EVP_PKCS82PKEY , +.Nm EVP_PKEY2PKCS8 +.Nd convert between EVP_PKEY and PKCS#8 PrivateKeyInfo +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft EVP_PKEY * +.Fn EVP_PKCS82PKEY "const PKCS8_PRIV_KEY_INFO *keyinfo" +.Ft PKCS8_PRIV_KEY_INFO * +.Fn EVP_PKEY2PKCS8 "EVP_PKEY *pkey" +.Sh DESCRIPTION +.Fn EVP_PKCS82PKEY +extracts the private key from a PKCS#8 +.Vt PrivateKeyInfo +structure. +.Pp +.Fn EVP_PKEY2PKCS8 +creates a PKCS#8 +.Vt PrivateKeyInfo +structure representing the private key contained in +.Fa pkey . +.Pp +Supported algorithms include DH, DSA, EC, and RSA. +.Sh RETURN VALUES +These functions return a newly allocated object or +.Dv NULL +if the algorithm indicated in +.Fa keyinfo +or +.Fa pkey +is unsupported or if memory allocation, decoding, or encoding fails. +.Sh SEE ALSO +.Xr EVP_PKEY_base_id 3 , +.Xr EVP_PKEY_new 3 , +.Xr PKCS8_pkey_set0 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 , +.Xr X509_ALGOR_get0 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.3 +and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/EVP_PKEY_CTX_ctrl.3 b/static/openbsd/man3/EVP_PKEY_CTX_ctrl.3 new file mode 100644 index 00000000..db65f132 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_CTX_ctrl.3 @@ -0,0 +1,583 @@ +.\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.30 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" Parts were split out into RSA_pkey_ctx_ctrl(3). +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019, 2023, 2024 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Antoine Salon . +.\" Copyright (c) 2006, 2009, 2013, 2014, 2015, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_CTX_CTRL 3 +.Os +.Sh NAME +.Nm EVP_PKEY_CTX_ctrl , +.Nm EVP_PKEY_CTX_ctrl_str , +.Nm EVP_PKEY_CTX_set_signature_md , +.Nm EVP_PKEY_CTX_get_signature_md , +.Nm EVP_PKEY_CTX_set_dsa_paramgen_bits , +.Nm EVP_PKEY_CTX_set_dh_paramgen_prime_len , +.Nm EVP_PKEY_CTX_set_dh_paramgen_generator , +.Nm EVP_PKEY_CTX_set_ec_paramgen_curve_nid , +.Nm EVP_PKEY_CTX_set_ec_param_enc , +.Nm EVP_PKEY_CTX_set_ecdh_cofactor_mode , +.Nm EVP_PKEY_CTX_get_ecdh_cofactor_mode , +.Nm EVP_PKEY_CTX_set_ecdh_kdf_type , +.Nm EVP_PKEY_CTX_get_ecdh_kdf_type , +.Nm EVP_PKEY_CTX_set_ecdh_kdf_md , +.Nm EVP_PKEY_CTX_get_ecdh_kdf_md , +.Nm EVP_PKEY_CTX_set_ecdh_kdf_outlen , +.Nm EVP_PKEY_CTX_get_ecdh_kdf_outlen , +.Nm EVP_PKEY_CTX_set0_ecdh_kdf_ukm , +.Nm EVP_PKEY_CTX_get0_ecdh_kdf_ukm , +.Nm EVP_PKEY_CTX_set1_id , +.Nm EVP_PKEY_CTX_get1_id , +.Nm EVP_PKEY_CTX_get1_id_len +.Nd algorithm specific control operations +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_CTX_ctrl +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int keytype" +.Fa "int optype" +.Fa "int cmd" +.Fa "int p1" +.Fa "void *p2" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_ctrl_str +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const char *type" +.Fa "const char *value" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_signature_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_signature_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD **pmd" +.Fc +.In openssl/dsa.h +.Ft int +.Fo EVP_PKEY_CTX_set_dsa_paramgen_bits +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int nbits" +.Fc +.In openssl/dh.h +.Ft int +.Fo EVP_PKEY_CTX_set_dh_paramgen_prime_len +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int len" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_dh_paramgen_generator +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int gen" +.Fc +.In openssl/ec.h +.Ft int +.Fo EVP_PKEY_CTX_set_ec_paramgen_curve_nid +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int nid" +.Fc +.Fa int +.Fo EVP_PKEY_CTX_set_ec_param_enc +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int param_enc" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_ecdh_cofactor_mode +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int cofactor_mode" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_ecdh_cofactor_mode +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_ecdh_kdf_type +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int kdf" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_ecdh_kdf_type +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_ecdh_kdf_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_ecdh_kdf_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD **pmd" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_ecdh_kdf_outlen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int len" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_ecdh_kdf_outlen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int *plen" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set0_ecdh_kdf_ukm +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *ukm" +.Fa "int len" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get0_ecdh_kdf_ukm +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char **pukm" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set1_id +.Fa "EVP_PKEY_CTX *ctx" +.Fa "void *id" +.Fa "size_t id_len" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get1_id +.Fa "EVP_PKEY_CTX *ctx" +.Fa "void *id" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get1_id_len +.Fa "EVP_PKEY_CTX *ctx" +.Fa "size_t *pid_len" +.Fc +.Sh DESCRIPTION +The function +.Fn EVP_PKEY_CTX_ctrl +sends a control operation to the context +.Fa ctx . +The key type used must match +.Fa keytype +if it is not -1. +The parameter +.Fa optype +is a mask indicating which operations the control can be applied to. +The control command is indicated in +.Fa cmd +and any additional arguments in +.Fa p1 +and +.Fa p2 . +.Pp +Applications will not normally call +.Fn EVP_PKEY_CTX_ctrl +directly but will instead call one of the algorithm specific macros +described below and in +.Xr RSA_pkey_ctx_ctrl 3 . +.Pp +The function +.Fn EVP_PKEY_CTX_ctrl_str +allows an application to send an algorithm specific control operation to +a context +.Fa ctx +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 +.Xr openssl 1 +utility command line pages for the option +.Fl pkeyopt +which is supported by the +.Cm pkeyutl , +.Cm genpkey , +and +.Cm req +commands. +.Pp +All the remaining "functions" are implemented as macros. +.Pp +The +.Fn EVP_PKEY_CTX_set_signature_md +and +.Fn EVP_PKEY_CTX_get_signature_md +macros set and get the message digest type used in a signature. +They can be used with the RSA, DSA, and ECDSA algorithms. +If the key is of the type +.Dv EVP_PKEY_RSA_PSS +and has usage restrictions, an error occurs if an attempt is made +to set the digest to anything other than the restricted value. +.Pp +These two macros expand to +.Fn EVP_PKEY_CTX_ctrl +with an +.Fa optype +of +.Dv EVP_PKEY_OP_TYPE_SIG +and the following command arguments: +.Pp +.Bl -column -compact EVP_PKEY_CTRL_GET_MD EVP_PKEY_CTX_get_signature_md() +.It Fa cmd No constant Ta corresponding macro +.It Dv EVP_PKEY_CTRL_MD Ta Fn EVP_PKEY_CTX_set_signature_md +.It Dv EVP_PKEY_CTRL_GET_MD Ta Fn EVP_PKEY_CTX_get_signature_md +.El +.Ss DSA parameters +The macro +.Fn EVP_PKEY_CTX_set_dsa_paramgen_bits +sets the number of bits used for DSA parameter generation to +.Fa nbits . +If not specified, 1024 is used. +.Ss DH parameters +The macro +.Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len +sets the length of the DH prime parameter +.Fa len +for DH parameter generation. +It only accepts lengths greater than or equal to 256. +If this macro is not called, then 1024 is used. +.Pp +The +.Fn EVP_PKEY_CTX_set_dh_paramgen_generator +macro sets DH generator to +.Fa gen +for DH parameter generation. +If not specified, 2 is used. +.Ss EC parameters +The +.Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid +macro sets the EC curve for EC parameter generation to +.Fa nid . +For EC parameter generation, this macro must be called or an error occurs +because there is no default curve. +.Pp +The +.Fn EVP_PKEY_CTX_set_ec_param_enc +macro sets the EC parameter encoding to +.Fa param_enc +when generating EC parameters or an EC key. +The encoding can be set to 0 for explicit parameters or to +.Dv OPENSSL_EC_NAMED_CURVE +to use named curve form. +.Ss ECDH parameters +The +.Fn EVP_PKEY_CTX_set_ecdh_cofactor_mode +macro sets the cofactor mode to +.Fa cofactor_mode +for ECDH key derivation. +Possible values are 1 to enable cofactor key derivation, 0 to disable +it, or -1 to clear the stored cofactor mode and fall back to the +private key cofactor mode. +.Pp +The +.Fn EVP_PKEY_CTX_get_ecdh_cofactor_mode +macro returns the cofactor mode for +.Fa ctx +used for ECDH key derivation. +Possible return values are 1 when cofactor key derivation is enabled +or 0 otherwise. +.Ss ECDH key derivation function parameters +The +.Fn EVP_PKEY_CTX_set_ecdh_kdf_type +macro sets the key derivation function type to +.Fa kdf +for ECDH key derivation. +Possible values are +.Dv EVP_PKEY_ECDH_KDF_NONE +or +.Dv EVP_PKEY_ECDH_KDF_X9_63 +which uses the key derivation specified in X9.63. +When using key derivation, the +.Fa kdf_md +and +.Fa kdf_outlen +parameters must also be specified. +.Pp +The +.Fn EVP_PKEY_CTX_get_ecdh_kdf_type +macro returns the key derivation function type for +.Fa ctx +used for ECDH key derivation. +Possible return values are +.Dv EVP_PKEY_ECDH_KDF_NONE +or +.Dv EVP_PKEY_ECDH_KDF_X9_63 . +.Pp +The +.Fn EVP_PKEY_CTX_set_ecdh_kdf_md +macro sets the key derivation function message digest to +.Fa md +for ECDH key derivation. +Note that X9.63 specifies that this digest should be SHA-1, +but OpenSSL tolerates other digests. +.Pp +The +.Fn EVP_PKEY_CTX_get_ecdh_kdf_md +macro gets the key derivation function message digest for +.Fa ctx +used for ECDH key derivation. +.Pp +The +.Fn EVP_PKEY_CTX_set_ecdh_kdf_outlen +macro sets the key derivation function output length to +.Fa len +for ECDH key derivation. +.Pp +The +.Fn EVP_PKEY_CTX_get_ecdh_kdf_outlen +macro gets the key derivation function output length for +.Fa ctx +used for ECDH key derivation. +.Pp +The +.Fn EVP_PKEY_CTX_set0_ecdh_kdf_ukm +macro sets the user key material to +.Fa ukm +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 +.Fa ukm . +.Pp +The +.Fn EVP_PKEY_CTX_get0_ecdh_kdf_ukm +macro gets the user key material for +.Fa ctx . +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 CMAC parameters +Application programs normally implement CMAC as described in +.Xr EVP_PKEY_new_CMAC_key 3 +and do not need the control commands documented here. +.Pp +Alternatively, the call to +.Xr EVP_PKEY_new_CMAC_key 3 +can be replaced as follows, +leaving the rest of the example code given there unchanged: +.Pp +.Bl -enum -width 2n -compact +.It +Create an empty +.Vt EVP_PKEY_CTX +object by passing the +.Dv EVP_PKEY_CMAC +constant to +.Xr EVP_PKEY_CTX_new_id 3 . +.It +Initialize it with +.Xr EVP_PKEY_keygen_init 3 . +.It +Select the block cipher by calling +.Fn EVP_PKEY_CTX_ctrl +with an +.Fa optype +of +.Dv EVP_PKEY_OP_KEYGEN , +a +.Fa cmd +of +.Dv EVP_PKEY_CTRL_CIPHER , +and +.Fa p2 +pointing to an +.Vt EVP_CIPHER +object, which can be obtained from the functions in the CIPHER LISTING in +.Xr EVP_EncryptInit 3 . +The +.Fa p1 +argument is ignored; passing 0 is recommended. +.It +Call +.Fn EVP_PKEY_CTX_ctrl +again with an +.Fa optype +of +.Dv EVP_PKEY_OP_KEYGEN , +a +.Fa cmd +of +.Dv EVP_PKEY_CTRL_SET_MAC_KEY , +.Fa p2 +pointing to the symmetric key, and +.Fa p1 +specifying the length of the symmetric key in bytes. +.It +Extract the desired +.Vt EVP_PKEY +object using +.Xr EVP_PKEY_keygen 3 , +making sure the +.Fa ppkey +argument points to a storage location containing a +.Dv NULL +pointer. +.It +Proceed with +.Xr EVP_MD_CTX_new 3 , +.Xr EVP_DigestSignInit 3 , +and +.Xr EVP_DigestSign 3 +as usual. +.El +.Ss HMAC parameters +Application programs normally implement HMAC as described in +.Xr EVP_PKEY_new_raw_private_key 3 . +While it is possible to instead use +.Dv EVP_PKEY_CTRL_SET_MAC_KEY +directly, similar to the above description for CMAC, +that is strongly discouraged. +It's essentially what the deprecated function +.Xr EVP_PKEY_new_mac_key 3 +does internally, and compared to the direct approach with +.Xr EVP_PKEY_new_raw_private_key 3 , +it requires a lot of cumbersome and unnecessary work. +.Ss Other parameters +The +.Fn EVP_PKEY_CTX_set1_id , +.Fn EVP_PKEY_CTX_get1_id , +and +.Fn EVP_PKEY_CTX_get1_id_len +macros manipulate a special identifier field used for some specific +signature algorithms such as SM2. +The +.Fn EVP_PKEY_set1_id +macro sets the ID to a copy of +.Fa id +with the length +.Fa id_len . +The caller can safely free the original memory pointed to by +.Fa id . +The +.Fn EVP_PKEY_CTX_get1_id_len +macro returns the length of the ID set via a previous call to +.Fn EVP_PKEY_set1_id . +That length is typically used to allocate memory for a subsequent call to +.Fn EVP_PKEY_CTX_get1_id , +which copies the previously set ID into +.Pf * Fa id . +The caller is responsible for allocating sufficient memory for +.Fa id +before calling +.Fn EVP_PKEY_CTX_get1_id . +.Sh RETURN VALUES +.Fn EVP_PKEY_CTX_ctrl +and its macros 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 +.Xr DH_new 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_get_default_digest_nid 3 , +.Xr EVP_PKEY_keygen 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 , +.Xr RSA_pkey_ctx_ctrl 3 +.Sh HISTORY +The functions +.Fn EVP_PKEY_CTX_ctrl , +.Fn EVP_PKEY_CTX_ctrl_str , +.Fn EVP_PKEY_CTX_set_signature_md , +.Fn EVP_PKEY_CTX_set_dsa_paramgen_bits , +.Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len , +.Fn EVP_PKEY_CTX_set_dh_paramgen_generator , +and +.Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +The functions +.Fn EVP_PKEY_CTX_get_signature_md , +.Fn EVP_PKEY_CTX_set_ec_param_enc , +.Fn EVP_PKEY_CTX_set_ecdh_cofactor_mode , +.Fn EVP_PKEY_CTX_get_ecdh_cofactor_mode , +.Fn EVP_PKEY_CTX_set_ecdh_kdf_type , +.Fn EVP_PKEY_CTX_get_ecdh_kdf_type , +.Fn EVP_PKEY_CTX_set_ecdh_kdf_md , +.Fn EVP_PKEY_CTX_get_ecdh_kdf_md , +.Fn EVP_PKEY_CTX_set_ecdh_kdf_outlen , +.Fn EVP_PKEY_CTX_get_ecdh_kdf_outlen , +.Fn EVP_PKEY_CTX_set0_ecdh_kdf_ukm , +and +.Fn EVP_PKEY_CTX_get0_ecdh_kdf_ukm +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 6.6 . +.Pp +The functions +.Fn EVP_PKEY_CTX_set1_id , +.Fn EVP_PKEY_CTX_get1_id , +and +.Fn EVP_PKEY_CTX_get1_id_len +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 6.6 . diff --git a/static/openbsd/man3/EVP_PKEY_CTX_get_operation.3 b/static/openbsd/man3/EVP_PKEY_CTX_get_operation.3 new file mode 100644 index 00000000..ce234337 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_CTX_get_operation.3 @@ -0,0 +1,138 @@ +.\" $OpenBSD: EVP_PKEY_CTX_get_operation.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2023 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 $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_CTX_GET_OPERATION 3 +.Os +.Sh NAME +.Nm EVP_PKEY_CTX_get_operation , +.Nm EVP_PKEY_CTX_get0_pkey +.Nd inspect EVP_PKEY_CTX objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_CTX_get_operation +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft EVP_PKEY * +.Fo EVP_PKEY_CTX_get0_pkey +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn EVP_PKEY_CTX_get_operation +finds out which initialization function has been called on +.Fa ctx , +if any: +.Bl -column EVP_PKEY_OP_VERIFYRECO EVP_PKEY_verify_recover_init +.It return value Ta initialized with Ta e.g. for +.It Dv EVP_PKEY_OP_DECRYPT Ta Xr EVP_PKEY_decrypt_init 3 Ta RSA, SM2 +.It Dv EVP_PKEY_OP_DERIVE Ta Xr EVP_PKEY_derive_init 3 Ta HKDF +.It Dv EVP_PKEY_OP_ENCRYPT Ta Xr EVP_PKEY_encrypt_init 3 Ta RSA, SM2 +.It Dv EVP_PKEY_OP_KEYGEN Ta Xr EVP_PKEY_keygen_init 3 Ta almost all +.It Dv EVP_PKEY_OP_PARAMGEN Ta Xr EVP_PKEY_paramgen_init 3 Ta DH, DSA, EC +.It Dv EVP_PKEY_OP_SIGN Ta Xr EVP_PKEY_sign_init 3 Ta DSA,EC,RSA,SM2 +.It Dv EVP_PKEY_OP_SIGN Ta Xr EVP_DigestSignInit 3 Ta ED25519 +.It Dv EVP_PKEY_OP_SIGNCTX Ta Xr EVP_DigestSignInit 3 Ta CMAC, HMAC +.It Dv EVP_PKEY_OP_UNDEFINED Ta not initialized Ta NONE +.It Dv EVP_PKEY_OP_VERIFY Ta Xr EVP_PKEY_verify_init 3 Ta DSA,EC,RSA,SM2 +.It Dv EVP_PKEY_OP_VERIFY Ta Xr EVP_DigestVerifyInit 3 Ta ED25519 +.It Dv EVP_PKEY_OP_VERIFYCTX Ta Xr EVP_DigestVerifyInit 3 Ta no built-in +.It Dv EVP_PKEY_OP_VERIFYRECOVER Ta Xr EVP_PKEY_verify_recover_init 3 Ta RSA +.El +.Pp +The rightmost column of the above table shows examples of algorithms +the return values can occur for. +For example, if +.Xr EVP_PKEY_base_id 3 +returns +.Dv EVP_PKEY_HKDF , +then calling +.Fn EVP_PKEY_CTX_get_operation +on a +.Vt EVP_PKEY_CTX +using that key may return +.Dv EVP_PKEY_OP_DERIVE . +.Pp +If the return value is +.Dv EVP_PKEY_OP_SIGNCTX +or +.Dv EVP_PKEY_OP_VERIFYCTX , +the +.Fa ctx +supports +.Xr EVP_DigestSignUpdate 3 +or +.Xr EVP_DigestVerifyUpdate 3 , +respectively. +If the return value is +.Dv EVP_PKEY_OP_SIGN +or +.Dv EVP_PKEY_OP_VERIFY , +if does not, and only one-shot signing or verification is supported. +.Pp +The return value +.Dv EVP_PKEY_OP_UNDEFINED +can for example occur if the +.Fa ctx +was freshly returned from +.Xr EVP_PKEY_CTX_new 3 +or +.Xr EVP_PKEY_CTX_new_id 3 +and not yet initialized. +.Pp +The following masks are defined as the logical OR of two or more of the above +.Dv EVP_PKEY_OP_* +bits: +.Pp +.Bl -tag -width EVP_PKEY_OP_TYPE_NOGEN -compact +.It Dv EVP_PKEY_OP_TYPE_CRYPT +DECRYPT | ENCRYPT +.It Dv EVP_PKEY_OP_TYPE_GEN +KEYGEN | PARAMGEN +.It Dv EVP_PKEY_OP_TYPE_NOGEN +CRYPT | DERIVE | SIG +.It Dv EVP_PKEY_OP_TYPE_SIG +SIGN | SIGNCTX | VERIFY | VERIFYCTX | VERIFYRECOVER +.El +.Sh RETURN VALUES +.Fn EVP_PKEY_CTX_get_operation +returns one of the single-bit +.Dv EVP_PKEY_OP_* +constants or +.Dv EVP_PKEY_OP_UNDEFINED +if +.Fa ctx +is not initialized. +.Pp +.Fn EVP_PKEY_CTX_get0_pkey +returns an internal pointer to the +.Vt EVP_PKEY +object used by +.Fa ctx , +without incrementing its reference count. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_PKEY_base_id 3 , +.Xr EVP_PKEY_CTX_ctrl 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_new 3 +.Sh HISTORY +.Fn EVP_PKEY_CTX_get_operation +and +.Fn EVP_PKEY_CTX_get0_pkey +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_PKEY_CTX_new.3 b/static/openbsd/man3/EVP_PKEY_CTX_new.3 new file mode 100644 index 00000000..d0f514d5 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_CTX_new.3 @@ -0,0 +1,184 @@ +.\" $OpenBSD: EVP_PKEY_CTX_new.3,v 1.17 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019, 2020 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_CTX_NEW 3 +.Os +.Sh NAME +.Nm EVP_PKEY_CTX_new , +.Nm EVP_PKEY_CTX_new_id , +.Nm EVP_PKEY_CTX_dup , +.Nm EVP_PKEY_CTX_free +.Nd public key algorithm context functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft EVP_PKEY_CTX * +.Fo EVP_PKEY_CTX_new +.Fa "EVP_PKEY *pkey" +.Fa "ENGINE *engine" +.Fc +.Ft EVP_PKEY_CTX * +.Fo EVP_PKEY_CTX_new_id +.Fa "int id" +.Fa "ENGINE *engine" +.Fc +.Ft EVP_PKEY_CTX * +.Fo EVP_PKEY_CTX_dup +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft void +.Fo EVP_PKEY_CTX_free +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_CTX_new +function allocates a public key algorithm context using the algorithm +specified in +.Fa pkey . +The +.Fa ENGINE *engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +The +.Fn EVP_PKEY_CTX_new_id +function allocates a public key algorithm context using the algorithm +specified by +.Fa id . +The +.Fa ENGINE *engine +argument is always ignored and passing +.Dv NULL +is recommended. +It is normally used when no +.Vt EVP_PKEY +structure is associated with the operations, for example during +parameter generation of key generation for some algorithms. +The +.Fa id +argument can be any of the constants that +.Xr EVP_PKEY_base_id 3 +and +.Xr EVP_PKEY_id 3 +may return. +.Pp +.Fn EVP_PKEY_CTX_dup +duplicates the context +.Fa ctx . +.Pp +.Fn EVP_PKEY_CTX_free +frees up the context +.Fa ctx . +If +.Fa ctx +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn EVP_PKEY_CTX_new , +.Fn EVP_PKEY_CTX_new_id , +and +.Fn EVP_PKEY_CTX_dup +return either the newly allocated +.Vt EVP_PKEY_CTX +structure or +.Dv NULL +if an error occurred. +.Sh SEE ALSO +.Xr EVP_DigestSignInit 3 , +.Xr EVP_DigestVerifyInit 3 , +.Xr EVP_PKEY_base_id 3 , +.Xr EVP_PKEY_CTX_ctrl 3 , +.Xr EVP_PKEY_CTX_get_operation 3 , +.Xr EVP_PKEY_CTX_hkdf_mode 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_keygen 3 , +.Xr EVP_PKEY_new 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 , +.Xr RSA_pkey_ctx_ctrl 3 , +.Xr X25519 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.0 +and have been available since +.Ox 4.9 . +.Sh CAVEATS +The +.Vt EVP_PKEY_CTX +structure is an opaque public key algorithm context used by the OpenSSL +high level public key API. +Contexts +.Sy MUST NOT +be shared between threads. +It is not permissible to use the same context simultaneously in two +threads. diff --git a/static/openbsd/man3/EVP_PKEY_CTX_set_hkdf_md.3 b/static/openbsd/man3/EVP_PKEY_CTX_set_hkdf_md.3 new file mode 100644 index 00000000..a6374409 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_CTX_set_hkdf_md.3 @@ -0,0 +1,259 @@ +.\" $OpenBSD: EVP_PKEY_CTX_set_hkdf_md.3,v 1.5 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 1cb7eff4 Sep 10 13:56:40 2019 +0100 +.\" +.\" This file was written by Alessandro Ghedini , +.\" Matt Caswell , and Viktor Dukhovni . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_CTX_SET_HKDF_MD 3 +.Os +.Sh NAME +.Nm EVP_PKEY_CTX_set_hkdf_md , +.Nm EVP_PKEY_CTX_set1_hkdf_salt , +.Nm EVP_PKEY_CTX_set1_hkdf_key , +.Nm EVP_PKEY_CTX_add1_hkdf_info , +.Nm EVP_PKEY_CTX_hkdf_mode +.Nd HMAC-based Extract-and-Expand key derivation algorithm +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.In openssl/kdf.h +.Ft int +.Fo EVP_PKEY_CTX_hkdf_mode +.Fa "EVP_PKEY_CTX *pctx" +.Fa "int mode" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_hkdf_md +.Fa "EVP_PKEY_CTX *pctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set1_hkdf_salt +.Fa "EVP_PKEY_CTX *pctx" +.Fa "unsigned char *salt" +.Fa "int saltlen" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set1_hkdf_key +.Fa "EVP_PKEY_CTX *pctx" +.Fa "unsigned char *key" +.Fa "int keylen" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_add1_hkdf_info +.Fa "EVP_PKEY_CTX *pctx" +.Fa "unsigned char *info" +.Fa "int infolen" +.Fc +.Sh DESCRIPTION +The +.Dv 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 +.Fn EVP_PKEY_CTX_hkdf_mode +sets the mode for the HKDF operation. +There are three modes that are currently defined: +.Bl -tag -width Ds +.It Dv EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND +This is the default mode. +Calling +.Xr EVP_PKEY_derive 3 +on an +.Vt 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. +.Pp +In this mode the digest, key, salt and info values must be set before a +key is derived or an error occurs. +.It Dv EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY +In this mode calling +.Xr EVP_PKEY_derive 3 +will just perform the extract operation. +The value returned will be the intermediate fixed-length pseudorandom +key K. +.Pp +The digest, key and salt values must be set before a key is derived or +an error occurs. +.It Dv EVP_PKEY_HKDEF_MODE_EXPAND_ONLY +In this mode calling +.Xr EVP_PKEY_derive 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. +.Pp +The digest, key and info values must be set before a key is derived or +an error occurs. +.El +.Pp +.Fn EVP_PKEY_CTX_set_hkdf_md +sets the message digest associated with the HKDF. +.Pp +.Fn EVP_PKEY_CTX_set1_hkdf_salt +sets the salt to +.Fa saltlen +bytes of the buffer +.Fa salt . +Any existing value is replaced. +.Pp +.Fn EVP_PKEY_CTX_set1_hkdf_key +sets the key to +.Fa keylen +bytes of the buffer +.Fa key . +Any existing value is replaced. +.Pp +.Fn EVP_PKEY_CTX_add1_hkdf_info +sets the info value to +.Fa infolen +bytes of the buffer +.Fa info . +If a value is already set, it is appended to the existing value. +.Sh STRING CTRLS +HKDF also supports string based control operations via +.Xr EVP_PKEY_CTX_ctrl_str 3 . +The +.Fa type +parameter "md" uses the supplied +.Fa value +as the name of the digest algorithm to use. +The +.Fa type +parameter "mode" accepts "EXTRACT_AND_EXPAND", "EXTRACT_ONLY" +and "EXPAND_ONLY" as +.Fa value +to determine the mode to use. +The +.Fa type +parameters "salt", "key" and "info" use the supplied +.Fa value +parameter as a +seed, key, or info. +The names "hexsalt", "hexkey" and "hexinfo" are similar except they take +a hex string which is converted to binary. +.Sh NOTES +All these functions are implemented as macros. +.Pp +A context for HKDF can be obtained by calling: +.Bd -literal + EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL); +.Ed +.Pp +The total length of the info buffer cannot exceed 1024 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 +.Xr EVP_PKEY_derive 3 +function. +Since the HKDF output length is variable, passing a +.Dv NULL +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 +.Xr EVP_PKEY_derive 3 +along with (a pointer initialized to) the desired length. +Passing a +.Dv NULL +buffer to obtain the length is allowed when using +.Dv EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY . +.Sh 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 +This example derives 10 bytes using SHA-256 with the secret key +"secret", salt value "salt" and info value "label": +.Bd -literal +EVP_PKEY_CTX *pctx; +unsigned char out[10]; +size_t outlen = sizeof(out); + +if ((pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL)) == NULL) + /* Error */ + +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 */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_ctrl_str 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_derive 3 +.Sh STANDARDS +RFC 5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF) +.Sh HISTORY +.Fn EVP_PKEY_CTX_set_hkdf_md , +.Fn EVP_PKEY_CTX_set1_hkdf_salt , +.Fn EVP_PKEY_CTX_set1_hkdf_key , +and +.Fn EVP_PKEY_CTX_add1_hkdf_info +first appeared in OpenSSL 1.1.0 and +.Fn EVP_PKEY_CTX_hkdf_mode +in OpenSSL 1.1.1. +These functions have been available since +.Ox 7.2 . diff --git a/static/openbsd/man3/EVP_PKEY_CTX_set_tls1_prf_md.3 b/static/openbsd/man3/EVP_PKEY_CTX_set_tls1_prf_md.3 new file mode 100644 index 00000000..57a85a78 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_CTX_set_tls1_prf_md.3 @@ -0,0 +1,172 @@ +.\" $OpenBSD: EVP_PKEY_CTX_set_tls1_prf_md.3,v 1.4 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 1cb7eff4 Sep 10 13:56:40 2019 +0100 +.\" +.\" This file was written by Dr Stephen Henson , +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_CTX_SET_TLS1_PRF_MD 3 +.Os +.Sh NAME +.Nm EVP_PKEY_CTX_set_tls1_prf_md , +.Nm EVP_PKEY_CTX_set1_tls1_prf_secret , +.Nm EVP_PKEY_CTX_add1_tls1_prf_seed +.Nd TLS PRF key derivation algorithm +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.In openssl/kdf.h +.Ft int +.Fo EVP_PKEY_CTX_set_tls1_prf_md +.Fa "EVP_PKEY_CTX *pctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set1_tls1_prf_secret +.Fa "EVP_PKEY_CTX *pctx" +.Fa "unsigned char *sec" +.Fa "int seclen" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_add1_tls1_prf_seed +.Fa "EVP_PKEY_CTX *pctx" +.Fa "unsigned char *seed" +.Fa "int seedlen" +.Fc +.Sh DESCRIPTION +The +.Dv EVP_PKEY_TLS1_PRF +algorithm implements the PRF key derivation function for TLS. +It has no associated private key and only implements key derivation using +.Xr EVP_PKEY_derive 3 . +.Pp +.Fn EVP_PKEY_set_tls1_prf_md +sets the message digest associated with the TLS PRF. +.Xr EVP_md5_sha1 3 +is treated as a special case which uses the PRF algorithm using both +MD5 and SHA-1 as used in TLS 1.0 and 1.1. +.Pp +.Fn EVP_PKEY_CTX_set_tls1_prf_secret +sets the secret value of the TLS PRF to +.Fa seclen +bytes of the buffer +.Fa sec . +Any existing secret value is replaced and any seed is reset. +.Pp +.Fn EVP_PKEY_CTX_add1_tls1_prf_seed +sets the seed to +.Fa seedlen +bytes of +.Fa seed . +If a seed is already set it is appended to the existing value. +.Sh STRING CTRLS +The TLS PRF also supports string based control operations using +.Xr EVP_PKEY_CTX_ctrl_str 3 . +The +.Fa type +parameter "md" uses the supplied +.Fa value +as the name of the digest algorithm to use. +The +.Fa type +parameters "secret" and "seed" use the supplied +.Fa value +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 +All these functions are implemented as macros. +.Pp +A context for the TLS PRF can be obtained by calling: +.Bd -literal + EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL); +.Ed +.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 +.Xr EVP_PKEY_derive 3 +function. +Since the output length is variable, setting the buffer to +.Dv NULL +is not meaningful for the TLS PRF. +.Sh 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 +This example derives 10 bytes using SHA-256 with the secret key "secret" +and seed value "seed": +.Bd -literal + 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 */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_ctrl_str 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_derive 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.6 . diff --git a/static/openbsd/man3/EVP_PKEY_asn1_get_count.3 b/static/openbsd/man3/EVP_PKEY_asn1_get_count.3 new file mode 100644 index 00000000..098a5565 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_asn1_get_count.3 @@ -0,0 +1,243 @@ +.\" $OpenBSD: EVP_PKEY_asn1_get_count.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 72a7a702 Feb 26 14:05:09 2019 +0000 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2020, 2023 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. +.\" +.\" The original file was written by Richard Levitte . +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_ASN1_GET_COUNT 3 +.Os +.Sh NAME +.Nm EVP_PKEY_asn1_get_count , +.Nm EVP_PKEY_asn1_get0 , +.Nm EVP_PKEY_get0_asn1 , +.Nm EVP_PKEY_asn1_find , +.Nm EVP_PKEY_asn1_find_str , +.Nm EVP_PKEY_asn1_get0_info +.Nd enumerate public key ASN.1 methods +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fn EVP_PKEY_asn1_get_count void +.Ft const EVP_PKEY_ASN1_METHOD * +.Fo EVP_PKEY_asn1_get0 +.Fa "int idx" +.Fc +.Ft const EVP_PKEY_ASN1_METHOD * +.Fo EVP_PKEY_get0_asn1 +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft const EVP_PKEY_ASN1_METHOD * +.Fo EVP_PKEY_asn1_find +.Fa "ENGINE **engine" +.Fa "int type" +.Fc +.Ft const EVP_PKEY_ASN1_METHOD * +.Fo EVP_PKEY_asn1_find_str +.Fa "ENGINE **engine" +.Fa "const char *str" +.Fa "int len" +.Fc +.Ft int +.Fo EVP_PKEY_asn1_get0_info +.Fa "int *ppkey_id" +.Fa "int *pkey_base_id" +.Fa "int *ppkey_flags" +.Fa "const char **pinfo" +.Fa "const char **ppem_str" +.Fa "const EVP_PKEY_ASN1_METHOD *ameth" +.Fc +.Sh DESCRIPTION +.Fn EVP_PKEY_asn1_get_count +returns the number of public key ASN.1 methods available. +.Pp +.Fn EVP_PKEY_asn1_get0 +returns the public key ASN.1 method +.Fa idx . +The value of +.Fa idx +must be in the range from zero to +.Fn EVP_PKEY_asn1_get_count +\- 1. +.Pp +.Fn EVP_PKEY_asn1_find +looks up the method with NID +.Fa type , +which can be any of the values that +.Xr EVP_PKEY_base_id 3 +and +.Xr EVP_PKEY_id 3 +may return. +If +.Fa engine +is not +.Dv NULL , +.Pf * Fa engine +is set to +.Dv NULL . +.Pp +.Fn EVP_PKEY_asn1_find_str +looks up the method with the PEM type string given by the first +.Fa len +bytes of +.Fa str . +If +.Fa len +is \-1, the +.Xr strlen 3 +of +.Fa str +is used instead. +The PEM type strings supported by default are listed in the +.Xr EVP_PKEY_base_id 3 +manual page. +Just like +.Fn EVP_PKEY_asn1_find , +if +.Fa engine +is not +.Dv NULL , +.Pf * Fa engine +is set to +.Dv NULL . +.Pp +.Fn EVP_PKEY_asn1_get0_info +retrieves the public key ID as returned by +.Xr EVP_PKEY_id 3 , +the base public key ID as returned by +.Xr EVP_PKEY_base_id 3 +.Pq both NIDs , +any flags, and internal pointers owned by +.Fa ameth +pointing to its method description string and its PEM type string. +.Pp +The following flags bits can occur, OR'ed together in +.Pf * Fa ppkey_flags : +.Bl -tag -width Ds +.It Dv ASN1_PKEY_ALIAS +This +.Fa ameth +object serves as an alias for another +.Vt EVP_PKEY_ASN1_METHOD +object and will never be returned from +.Fn EVP_PKEY_asn1_find +or +.Fn EVP_PKEY_asn1_find_str . +.It Dv ASN1_PKEY_DYNAMIC +This flag is unused. +It could formerly be used to mark an +.Fa ameth +object as dynamically allocated. +.It Dv ASN1_PKEY_SIGPARAM_NULL +If the signing +.Fa ctx +uses an +.Vt EVP_PKEY +private key associated with this +.Fa ameth , +instruct +.Xr ASN1_item_sign_ctx 3 +to use a parameter type of +.Dv V_ASN1_NULL +instead of the default +.Dv V_ASN1_UNDEF +when encoding the ASN.1 +.Vt AlgorithmIdentifier +objects with +.Xr X509_ALGOR_set0 3 . +In particular, this is used for +.Dv EVP_PKEY_RSA . +.El +.Sh RETURN VALUES +.Fn EVP_PKEY_asn1_get_count +returns the number of available public key methods. +.Pp +.Fn EVP_PKEY_asn1_get0 +returns a public key method or +.Dv NULL +if +.Fa idx +is out of range. +.Pp +.Fn EVP_PKEY_get0_asn1 +returns the public key method used by +.Fa pkey . +.Pp +.Fn EVP_PKEY_asn1_find +and +.Fn EVP_PKEY_asn1_find_str +return a matching public key method or +.Dv NULL +if no match is found. +.Pp +.Fn EVP_PKEY_asn1_get0_info +returns 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr EVP_PKEY_base_id 3 , +.Xr EVP_PKEY_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.0 +and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_PKEY_cmp.3 b/static/openbsd/man3/EVP_PKEY_cmp.3 new file mode 100644 index 00000000..bcd0152d --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_cmp.3 @@ -0,0 +1,180 @@ +.\" $OpenBSD: EVP_PKEY_cmp.3,v 1.16 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 05ea606a May 20 20:52:46 2016 -0400 +.\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2013, 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_CMP 3 +.Os +.Sh NAME +.Nm EVP_PKEY_missing_parameters , +.Nm EVP_PKEY_copy_parameters , +.Nm EVP_PKEY_cmp_parameters , +.Nm EVP_PKEY_cmp +.\" .Nm EVP_PKEY_save_parameters is intentionally undocumented +.\" because nothing uses it according to codesearch.debian.net +.\" and it only affects X509_PUBKEY_set(3) for DSA, +.\" resulting in incomplete output without the public key parameters. +.Nd public key parameter and comparison functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_missing_parameters +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_copy_parameters +.Fa "EVP_PKEY *destination" +.Fa "const EVP_PKEY *source" +.Fc +.Ft int +.Fo EVP_PKEY_cmp_parameters +.Fa "const EVP_PKEY *a" +.Fa "const EVP_PKEY *b" +.Fc +.Ft int +.Fo EVP_PKEY_cmp +.Fa "const EVP_PKEY *a" +.Fa "const EVP_PKEY *b" +.Fc +.Sh DESCRIPTION +.Fn EVP_PKEY_missing_parameters +checks whether any public key parameters are missing from +.Fa pkey . +.Pp +.Fn EVP_PKEY_copy_parameters +copies all public key parameters from the +.Fa source +to the +.Fa destination . +If the algorithm does not use parameters, no action occurs. +.Pp +.Fn EVP_PKEY_cmp_parameters +compares the public key parameters of +.Fa a +and +.Fa b . +This is only supported for algorithms that use parameters. +.Pp +.Fn EVP_PKEY_cmp +compares the public key components of +.Fa a +and +.Fa b . +If the algorithm uses public key parameters, +it also compares the parameters. +.Pp +The main purpose of the functions +.Fn EVP_PKEY_missing_parameters +and +.Fn EVP_PKEY_copy_parameters +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 +Since OpenSSL private keys contain public key components too, the +function +.Fn EVP_PKEY_cmp +can also be used to determine if a private key matches a public key. +.Sh RETURN VALUES +.Fn EVP_PKEY_missing_parameters +returns 1 if the public key parameters of +.Fa pkey +are missing or incomplete or 0 if they are present and complete +or if the algorithm doesn't use parameters. +.Pp +.Fn EVP_PKEY_copy_parameters +returns 1 for success or 0 for failure. +In particular, it fails if the key types mismatch or if the public +key parameters in the +.Fa source +are missing or incomplete. +.Pp +.Fn EVP_PKEY_cmp_parameters +and +.Fn EVP_PKEY_cmp +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 +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_keygen 3 , +.Xr EVP_PKEY_new 3 , +.Xr X509_get_pubkey_parameters 3 +.Sh HISTORY +.Fn EVP_PKEY_missing_parameters +and +.Fn EVP_PKEY_copy_parameters +first appeared in SSLeay 0.8.0. +.Fn EVP_PKEY_cmp_parameters +first appeared in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_PKEY_cmp +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/EVP_PKEY_decrypt.3 b/static/openbsd/man3/EVP_PKEY_decrypt.3 new file mode 100644 index 00000000..abac0e6a --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_decrypt.3 @@ -0,0 +1,176 @@ +.\" $OpenBSD: EVP_PKEY_decrypt.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2013, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_DECRYPT 3 +.Os +.Sh NAME +.Nm EVP_PKEY_decrypt_init , +.Nm EVP_PKEY_decrypt +.Nd decrypt using a public key algorithm +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_decrypt_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_decrypt +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *out" +.Fa "size_t *outlen" +.Fa "const unsigned char *in" +.Fa "size_t inlen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_decrypt_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for a decryption operation. +.Pp +The +.Fn EVP_PKEY_decrypt +function performs a public key decryption operation using +.Fa ctx . +The data to be decrypted is specified using the +.Fa in +and +.Fa inlen +parameters. +If +.Fa out +is +.Dv NULL +then the maximum size of the output buffer is written to the +.Fa outlen +parameter. +If +.Fa out +is not +.Dv NULL +then before the call the +.Fa outlen +parameter should contain the length of the +.Fa out +buffer. +If the call is successful, the decrypted data is written to +.Fa out +and the amount of data written to +.Fa outlen . +.Pp +After the call to +.Fn EVP_PKEY_decrypt_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The function +.Fn EVP_PKEY_decrypt +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_decrypt_init +and +.Fn EVP_PKEY_decrypt +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 +Decrypt data using OAEP (for RSA keys): +.Bd -literal -offset indent +#include +#include + +EVP_PKEY_CTX *ctx; +unsigned char *out, *in; +size_t outlen, inlen; +EVP_PKEY *key; + +/* + * Assumes that key, in, and inlen are already set up + * and that key is an RSA private key. + */ +ctx = EVP_PKEY_CTX_new(key, NULL); +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 = 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 */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +.Fn EVP_PKEY_decrypt_init +and +.Fn EVP_PKEY_decrypt +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_PKEY_derive.3 b/static/openbsd/man3/EVP_PKEY_derive.3 new file mode 100644 index 00000000..d02ef0e9 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_derive.3 @@ -0,0 +1,255 @@ +.\" $OpenBSD: EVP_PKEY_derive.3,v 1.13 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2013, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_DERIVE 3 +.Os +.Sh NAME +.Nm EVP_PKEY_derive_init , +.Nm EVP_PKEY_derive_set_peer , +.Nm EVP_PKEY_CTX_get0_peerkey , +.Nm EVP_PKEY_derive +.Nd derive public key algorithm shared secret +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_derive_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_derive_set_peer +.Fa "EVP_PKEY_CTX *ctx" +.Fa "EVP_PKEY *peerkey" +.Fc +.Ft EVP_PKEY * +.Fo EVP_PKEY_CTX_get0_peerkey +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_derive +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *key" +.Fa "size_t *keylen" +.Fc +.Sh DESCRIPTION +.Fn EVP_PKEY_derive_init +initializes the public key algorithm context +.Fa ctx +for shared secret derivation using the +.Vt EVP_PKEY +object already stored in +.Fa ctx . +The library provides built-in support for keys with an +.Xr EVP_PKEY_base_id 3 +of +.Dv EVP_PKEY_DH , +.Dv EVP_PKEY_EC , +.Dv EVP_PKEY_HKDF , +and +.Dv EVP_PKEY_X25519 . +.Pp +After the call to +.Fn EVP_PKEY_derive_init , +algorithm specific control operations can optionally be performed +to set any appropriate parameters for the operation. +.Pp +.Fn EVP_PKEY_derive_set_peer +configures the +.Fa ctx , +which already needs to be initialized with +.Fn EVP_PKEY_derive_init , +.Xr EVP_PKEY_encrypt_init 3 , +or +.Xr EVP_PKEY_decrypt_init 3 , +to use the +.Fa peerkey , +which is normally a public key. +In case of success, the reference count of the +.Fa peerkey +is incremented by one. +Consequently, the caller needs to call +.Xr EVP_PKEY_free 3 +on the +.Fa peerkey +when the caller no longer needs it, even if it is still in use by +.Fa ctx . +.Pp +.Fn EVP_PKEY_derive +derives a shared secret using +.Fa ctx . +If +.Fa key +is +.Dv NULL , +then the maximum size of the output buffer is written to the +.Fa keylen +parameter. +If +.Fa key +is not +.Dv NULL +then before the call the +.Fa keylen +parameter should contain the length of the +.Fa key +buffer. +If the call is successful, the shared secret is written to +.Fa key +and the amount of data written to +.Fa keylen . +.Pp +The function +.Fn EVP_PKEY_derive +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_derive_init , +.Fn EVP_PKEY_derive_set_peer , +and +.Fn EVP_PKEY_derive +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 +For +.Fn EVP_PKEY_derive_set_peer , +a return value of \-1 can for example occur if +.Fa ctx +is not properly initialized, does not contain an +.Vt EVP_PKEY +that can be retrieved with +.Xr EVP_PKEY_CTX_get0_pkey 3 , +the +.Xr EVP_PKEY_id 3 +of both keys mismatch, or +.Xr EVP_PKEY_cmp_parameters 3 +reports mismatching key parameters. +.Pp +.Fn EVP_PKEY_derive +fails with a return value of \-1 for example if +.Fa ctx +has not been successfully initialized with +.Fn EVP_PKEY_derive_init . +.Pp +.Fn EVP_PKEY_CTX_get0_peerkey +returns an internal pointer to the +.Fa peerkey +used by +.Fa ctx +without incrementing its reference count. +.Sh EXAMPLES +Derive shared secret (for example DH or EC keys): +.Bd -literal -offset indent +#include +#include + +EVP_PKEY_CTX *ctx; +unsigned char *skey; +size_t skeylen; +EVP_PKEY *pkey, *peerkey; + +/* Assumes that pkey and peerkey have already been set up. */ +ctx = EVP_PKEY_CTX_new(pkey, NULL); +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 = malloc(skeylen); + +if (!skey) + /* malloc failure */ + +if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) + /* Error */ + +/* Shared secret is skey bytes written to buffer skey */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 , +.Xr X25519 3 +.Sh HISTORY +.Fn EVP_PKEY_derive_init , +.Fn EVP_PKEY_derive_set_peer , +.Fn EVP_PKEY_CTX_get0_peerkey , +and +.Fn EVP_PKEY_derive +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_PKEY_encrypt.3 b/static/openbsd/man3/EVP_PKEY_encrypt.3 new file mode 100644 index 00000000..f32d4112 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_encrypt.3 @@ -0,0 +1,184 @@ +.\" $OpenBSD: EVP_PKEY_encrypt.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2013, 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_ENCRYPT 3 +.Os +.Sh NAME +.Nm EVP_PKEY_encrypt_init , +.Nm EVP_PKEY_encrypt +.Nd encrypt using a public key algorithm +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_encrypt_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_encrypt +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *out" +.Fa "size_t *outlen" +.Fa "const unsigned char *in" +.Fa "size_t inlen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_encrypt_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for an encryption operation. +.Pp +The +.Fn EVP_PKEY_encrypt +function performs a public key encryption operation using +.Fa ctx . +The data to be encrypted is specified using the +.Fa in +and +.Fa inlen +parameters. +If +.Fa out +is +.Dv NULL , +then the maximum size of the output buffer is written to the +.Fa outlen +parameter. +If +.Fa out +is not +.Dv NULL , +then before the call the +.Fa outlen +parameter should contain the length of the +.Fa out +buffer. +If the call is successful, the encrypted data is written to +.Fa out +and the amount of data written to +.Fa outlen . +.Pp +After the call to +.Fn EVP_PKEY_encrypt_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The function +.Fn EVP_PKEY_encrypt +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_encrypt_init +and +.Fn EVP_PKEY_encrypt +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 +Encrypt data using OAEP (for RSA keys). +See also +.Xr PEM_read_PUBKEY 3 +and +.Xr d2i_X509 3 +for means to load a public key. +You may also simply set +.Dq eng +to +.Dv NULL +to start with the default OpenSSL RSA implementation: +.Bd -literal -offset indent +#include +#include + +EVP_PKEY_CTX *ctx; +unsigned char *out, *in; +size_t outlen, inlen; +EVP_PKEY *key; +/* NB: assumes that key, in, inlen are already set up + * and that key is an RSA public key + */ +ctx = EVP_PKEY_CTX_new(key, NULL); +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 = 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 */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +.Fn EVP_PKEY_encrypt_init +and +.Fn EVP_PKEY_encrypt +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_PKEY_get_default_digest_nid.3 b/static/openbsd/man3/EVP_PKEY_get_default_digest_nid.3 new file mode 100644 index 00000000..5c5b07bd --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_get_default_digest_nid.3 @@ -0,0 +1,129 @@ +.\" $OpenBSD: EVP_PKEY_get_default_digest_nid.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2013, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_GET_DEFAULT_DIGEST_NID 3 +.Os +.Sh NAME +.Nm EVP_PKEY_get_default_digest_nid +.Nd get default signature digest +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_get_default_digest_nid +.Fa "EVP_PKEY *pkey" +.Fa "int *pnid" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_get_default_digest_nid +function sets +.Pf * Fa pnid +to the default message digest NID for the public key signature +operations associated with +.Fa pkey . +.Pp +Some signature algorithms, for example +.Dv EVP_PKEY_ED25519 , +do not use a digest during signing. +In this case, +.Pf * Fa pnid +is set to +.Dv NID_undef . +.Pp +Support for the following public key algorithms is built into the library: +.Pp +.Bl -column -compact EVP_PKEY_base_id(3) NID_sha256 mandatory +.It Xr EVP_PKEY_base_id 3 Ta Pf * Fa pnid Ta return value +.It Dv EVP_PKEY_DSA Ta Dv NID_sha1 Ta mandatory +.It Dv EVP_PKEY_EC Ta Dv NID_sha1 Ta mandatory +.It Dv EVP_PKEY_ED25519 Ta Dv NID_undef Ta mandatory +.It Dv EVP_PKEY_HMAC Ta Dv NID_sha1 Ta advisory +.It Dv EVP_PKEY_RSA Ta Dv NID_sha256 Ta advisory +.El +.Sh RETURN VALUES +The +.Fn EVP_PKEY_get_default_digest_nid +function returns 1 if the message digest is advisory (that is other +digests can be used) and 2 if it is mandatory (other digests cannot 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 +.Xr EVP_PKEY_CTX_ctrl 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_new 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +.Fn EVP_PKEY_get_default_digest_nid +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_PKEY_keygen.3 b/static/openbsd/man3/EVP_PKEY_keygen.3 new file mode 100644 index 00000000..3c000f8c --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_keygen.3 @@ -0,0 +1,370 @@ +.\" $OpenBSD: EVP_PKEY_keygen.3,v 1.16 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023, 2024 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2013, 2015, 2016, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_KEYGEN 3 +.Os +.Sh NAME +.Nm EVP_PKEY_keygen_init , +.Nm EVP_PKEY_keygen , +.Nm EVP_PKEY_paramgen_init , +.Nm EVP_PKEY_paramgen , +.Nm EVP_PKEY_gen_cb , +.Nm EVP_PKEY_CTX_set_cb , +.Nm EVP_PKEY_CTX_get_cb , +.Nm EVP_PKEY_CTX_set0_keygen_info , +.Nm EVP_PKEY_CTX_get_keygen_info , +.Nm EVP_PKEY_CTX_set_app_data , +.Nm EVP_PKEY_CTX_get_app_data , +.Nm EVP_PKEY_CTX_set_data , +.Nm EVP_PKEY_CTX_get_data +.Nd key and parameter generation functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_keygen_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_keygen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "EVP_PKEY **ppkey" +.Fc +.Ft int +.Fo EVP_PKEY_paramgen_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_paramgen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "EVP_PKEY **ppkey" +.Fc +.Ft typedef int +.Fo EVP_PKEY_gen_cb +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft void +.Fo EVP_PKEY_CTX_set_cb +.Fa "EVP_PKEY_CTX *ctx" +.Fa "EVP_PKEY_gen_cb *cb" +.Fc +.Ft EVP_PKEY_gen_cb * +.Fo EVP_PKEY_CTX_get_cb +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft void +.Fo EVP_PKEY_CTX_set0_keygen_info +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int *dat" +.Fa "int datlen" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_keygen_info +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int idx" +.Fc +.Ft void +.Fo EVP_PKEY_CTX_set_app_data +.Fa "EVP_PKEY_CTX *ctx" +.Fa "void *app_data" +.Fc +.Ft void * +.Fo EVP_PKEY_CTX_get_app_data +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft void +.Fo EVP_PKEY_CTX_set_data +.Fa "EVP_PKEY_CTX *ctx" +.Fa "void *data" +.Fc +.Ft void * +.Fo EVP_PKEY_CTX_get_data +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_keygen_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for a key generation operation. +.Pp +The +.Fn EVP_PKEY_keygen +function performs a key generation operation. +The generated key is written to +.Fa ppkey . +.Pp +The functions +.Fn EVP_PKEY_paramgen_init +and +.Fn EVP_PKEY_paramgen +are similar except parameters are generated. +.Pp +The functions +.Fn EVP_PKEY_CTX_set_cb +and +.Fn EVP_PKEY_CTX_get_cb +set and retrieve the key or parameter generation callback, respectively. +.Pp +The function +.Fn EVP_PKEY_CTX_set0_keygen_info +sets the parameters associated with the generation operation to the array +.Fa dat +containing +.Ft datlen +integer parameters. +The caller retains ownership of the +.Fa dat +array; it will never be freed by the library. +.Pp +The function +.Fn EVP_PKEY_CTX_get_keygen_info +returns parameters associated with the generation operation. +If +.Fa idx +is -1, the total number of parameters available is returned. +Any non-negative value returns the value of that parameter. +.Fn EVP_PKEY_CTX_get_keygen_info +with a non-negative value for +.Fa idx +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 +.Fn EVP_PKEY_CTX_set_app_data +and +.Fn EVP_PKEY_CTX_get_app_data +set and retrieve an opaque pointer. +This can be used to set some application defined value which can be +retrieved in the callback: for example a handle which is used to update +a "progress dialog". +.Pp +The deprecated functions +.Fn EVP_PKEY_CTX_set_data +and +.Fn EVP_PKEY_CTX_get_data +set and retrieve a +.Em different +opaque pointer that is ignored by the library. +.Pp +After the call to +.Fn EVP_PKEY_keygen_init +or +.Fn EVP_PKEY_paramgen_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The functions +.Fn EVP_PKEY_keygen +and +.Fn EVP_PKEY_paramgen +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 +.Vt EVP_PKEY +structure. +.Pp +In OpenSSL, an +.Vt 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 RETURN VALUES +.Fn EVP_PKEY_keygen_init , +.Fn EVP_PKEY_paramgen_init , +.Fn EVP_PKEY_keygen , +and +.Fn EVP_PKEY_paramgen +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 +Callback functions of the type +.Fn EVP_PKEY_gen_cb +are supposed to return 1 on success or 0 on error. +.Pp +.Fn EVP_PKEY_CTX_get_cb +returns a function pointer to the currently installed callback function or +.Dv NULL +if no callback function is installed. +.Pp +.Fn EVP_PKEY_CTX_get_keygen_info +returns the number of available parameters if +.Fa idx +is \-1, one of these parameters if +.Fa idx +is greater than or equal to zero but less than the number +of available parameters, or 0 otherwise. +.Pp +.Fn EVP_PKEY_CTX_get_app_data +and +.Fn EVP_PKEY_CTX_get_data +return the pointer that was last passed to the corresponding set function, or +.Dv NULL +if the corresponding set function was never called on +.Fa ctx . +.Sh EXAMPLES +Generate a 2048-bit RSA key: +.Bd -literal -offset indent +#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 */ +.Ed +.Pp +Generate a key from a set of parameters: +.Bd -literal -offset indent +#include +#include + +EVP_PKEY_CTX *ctx; +EVP_PKEY *pkey = NULL, *param; + +/* Assumes that param is already set up. */ +ctx = EVP_PKEY_CTX_new(param, NULL); +if (!ctx) + /* Error occurred */ +if (EVP_PKEY_keygen_init(ctx) <= 0) + /* Error */ + +/* Generate key */ +if (EVP_PKEY_keygen(ctx, &pkey) <= 0) + /* Error */ +.Ed +.Pp +Example of generation callback for OpenSSL public key implementations: +.Bd -literal -offset indent +/* 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 = '*'; + BIO *b = EVP_PKEY_CTX_get_app_data(ctx); + int p; + + p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); + if (p == 0) + c = '.'; + if (p == 1) + c = '+'; + if (p == 2) + c = '*'; + if (p == 3) + c = '\en'; + BIO_write(b, &c, 1); + (void)BIO_flush(b); + return 1; +} +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 , +.Xr X25519 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.0 +and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_PKEY_new.3 b/static/openbsd/man3/EVP_PKEY_new.3 new file mode 100644 index 00000000..7c13f625 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_new.3 @@ -0,0 +1,348 @@ +.\" $OpenBSD: EVP_PKEY_new.3,v 1.27 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 4dcfdfce May 27 11:50:05 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022, 2024 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Matt Caswell . +.\" Copyright (c) 2002, 2018, 2020 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_NEW 3 +.Os +.Sh NAME +.Nm EVP_PKEY_new , +.Nm EVP_PKEY_up_ref , +.Nm EVP_PKEY_free , +.Nm EVP_PKEY_new_raw_private_key , +.Nm EVP_PKEY_new_raw_public_key , +.Nm EVP_PKEY_new_mac_key , +.Nm EVP_PKEY_get_raw_private_key , +.Nm EVP_PKEY_get_raw_public_key +.Nd public and private key allocation and raw key handling functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft EVP_PKEY * +.Fn EVP_PKEY_new void +.Ft int +.Fo EVP_PKEY_up_ref +.Fa "EVP_PKEY *pkey" +.Fc +.Ft void +.Fo EVP_PKEY_free +.Fa "EVP_PKEY *pkey" +.Fc +.Ft EVP_PKEY * +.Fo EVP_PKEY_new_raw_private_key +.Fa "int type" +.Fa "ENGINE *engine" +.Fa "const unsigned char *rawpriv" +.Fa "size_t rawlen" +.Fc +.Ft EVP_PKEY * +.Fo EVP_PKEY_new_raw_public_key +.Fa "int type" +.Fa "ENGINE *engine" +.Fa "const unsigned char *rawpub" +.Fa "size_t rawlen" +.Fc +.Ft EVP_PKEY * +.Fo EVP_PKEY_new_mac_key +.Fa "int type" +.Fa "ENGINE *engine" +.Fa "const unsigned char *rawpriv" +.Fa "int rawlen" +.Fc +.Ft int +.Fo EVP_PKEY_get_raw_private_key +.Fa "const EVP_PKEY *pkey" +.Fa "unsigned char *rawpriv" +.Fa "size_t *rawlen" +.Fc +.Ft int +.Fo EVP_PKEY_get_raw_public_key +.Fa "const EVP_PKEY *pkey" +.Fa "unsigned char *rawpub" +.Fa "size_t *rawlen" +.Fc +.Sh DESCRIPTION +The +.Vt EVP_PKEY +structure is used by various OpenSSL functions which require a general +private or public key without reference to any particular algorithm. +.Pp +The +.Fn EVP_PKEY_new +function allocates an empty +.Vt EVP_PKEY +structure. +The reference count is set to 1. +To add a private or public key to it, use the functions described in +.Xr EVP_PKEY_set1_RSA 3 . +.Pp +.Fn EVP_PKEY_up_ref +increments the reference count of +.Fa pkey +by 1. +.Pp +.Fn EVP_PKEY_free +decrements the reference count of +.Fa pkey +by 1, and if the reference count reaches zero, frees it up. +If +.Fa pkey +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn EVP_PKEY_new_raw_private_key +allocates a new +.Vt EVP_PKEY . +The NID of a public key algorithm that supports raw private keys, i.e.\& +.Dv EVP_PKEY_HMAC , +.Dv EVP_PKEY_X25519 , +or +.Dv EVP_PKEY_ED25519 , +is provided in the +.Fa type +argument and +.Fa rawlen +bytes of raw private key data of that type in +.Fa rawpriv . +The public key data is automatically derived from the given private +key data, if appropriate for the algorithm type. +The +.Fa ENGINE *engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +.Fn EVP_PKEY_new_raw_public_key +works in the same way as +.Fn EVP_PKEY_new_raw_private_key +except that +.Fa rawpub +points to the raw public key data. +The +.Vt EVP_PKEY +structure is initialised without any private key information. +Algorithm types that support raw public keys are +.Dv EVP_PKEY_X25519 +and +.Dv EVP_PKEY_ED25519 . +.Pp +.Fn EVP_PKEY_new_mac_key +is a deprecated function that achieves the same effect as +.Fn EVP_PKEY_new_raw_private_key +in a more complicated way and only works with a +.Fa type +of +.Dv EVP_PKEY_HMAC . +.Pp +.Fn EVP_PKEY_get_raw_private_key +writes up to +.Pf * Fa rawlen +bytes of raw private key data to the buffer starting at +.Fa rawpriv +and stores the number of bytes written in +.Pf * Fa rawlen . +The calling application is responsible for ensuring that the buffer +is large enough to receive the private key data. +If the +.Fa rawpriv +argument is +.Dv NULL , +the number of bytes required to hold the key is stored in +.Pf * Fa rawlen . +This function only works for algorithms that support raw private keys. +Currently these are +.Dv EVP_PKEY_HMAC , +.Dv EVP_PKEY_X25519 , +and +.Dv EVP_PKEY_ED25519 . +.Pp +.Fn EVP_PKEY_get_raw_public_key +is similar to +.Fn EVP_PKEY_get_raw_private_key +except that it writes raw public key data. +This function only works for algorithms that support raw public keys. +Currently these are +.Dv EVP_PKEY_X25519 +and +.Dv EVP_PKEY_ED25519 . +.Sh RETURN VALUES +.Fn EVP_PKEY_new , +.Fn EVP_PKEY_new_raw_private_key , +.Fn EVP_PKEY_new_raw_public_key , +and +.Fn EVP_PKEY_new_mac_key +return either the newly allocated +.Vt EVP_PKEY +structure or +.Dv NULL +if an error occurred. +.Pp +.Fn EVP_PKEY_up_ref , +.Fn EVP_PKEY_get_raw_private_key , +and +.Fn EVP_PKEY_get_raw_public_key +return 1 for success or 0 for failure. +.Sh EXAMPLES +The following code digests a message with HMAC-SHA256: +.Bd -literal -offset indent +/* Bogus key: would normally be set from another source */ +const unsigned char *key = "key"; +const size_t key_len = strlen(key); + +const char *msg = "The quick brown fox jumps over the lazy dog"; +const size_t msg_len = strlen(msg); + +unsigned char *out_mac; +size_t out_len, i; + +EVP_PKEY *pkey; +EVP_MD_CTX *md_ctx; + +pkey = EVP_PKEY_new_raw_private_key(EVP_PKEY_HMAC, NULL, + key, key_len); +if (pkey == NULL) + err(1, "EVP_PKEY_new_raw_private_key"); + +md_ctx = EVP_MD_CTX_new(); +if (md_ctx == NULL) + err(1, "EVP_MD_CTX_new"); + +if (EVP_DigestSignInit(md_ctx, NULL, EVP_sha256(), NULL, pkey) == 0) + err(1, "EVP_DigestSignInit"); +if (EVP_DigestSign(md_ctx, NULL, &out_len, msg, msg_len) == 0) + err(1, "EVP_DigestSign(NULL)"); +if ((out_mac = calloc(1, out_len)) == NULL) + err(1, "calloc"); +if (EVP_DigestSign(md_ctx, out_mac, &out_len, msg, msg_len) == 0) + err(1, "EVP_DigestSign(MAC)"); + +EVP_MD_CTX_free(md_ctx); +EVP_PKEY_free(pkey); + +printf(" MAC = "); +for (i = 0; i < out_len; i++) + printf("%02x", out_mac[i]); +printf("\en"); +free(out_mac); +.Ed +.Pp +Even though the type name +.Vt EVP_PKEY +was originally intended to stand for +.Dq private key +and the +.Xr EVP_DigestSignInit 3 +API was designed for digital signatures in the context of public key +cryptography, both are also used here because a MAC also requires a key, +even though that is a symmetric key. +.Pp +The same code can be used for signing with Ed25519 by making the key +.Dv ED25519_PRIVATE_KEY_LENGTH No = 32 +bytes long, replacing +.Dv EVP_PKEY_HMAC +with +.Dv EVP_PKEY_ED25519 , +and replacing the call to +.Xr EVP_sha256 3 +with +.Dv NULL . +.Sh SEE ALSO +.Xr CMAC_Init 3 , +.Xr d2i_PrivateKey 3 , +.Xr evp 3 , +.Xr EVP_PKCS82PKEY 3 , +.Xr EVP_PKEY_cmp 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_get_default_digest_nid 3 , +.Xr EVP_PKEY_new_CMAC_key 3 , +.Xr EVP_PKEY_print_private 3 , +.Xr EVP_PKEY_set1_RSA 3 , +.Xr EVP_PKEY_size 3 , +.Xr X509_get_pubkey_parameters 3 +.Sh HISTORY +.Fn EVP_PKEY_new +and +.Fn EVP_PKEY_free +first appeared in SSLeay 0.6.0 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_PKEY_new_mac_key +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Pp +.Fn EVP_PKEY_up_ref +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . +.Pp +.Fn EVP_PKEY_new_raw_private_key , +.Fn EVP_PKEY_new_raw_public_key , +.Fn EVP_PKEY_get_raw_private_key , +and +.Fn EVP_PKEY_get_raw_public_key +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.3 . diff --git a/static/openbsd/man3/EVP_PKEY_new_CMAC_key.3 b/static/openbsd/man3/EVP_PKEY_new_CMAC_key.3 new file mode 100644 index 00000000..e4202fab --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_new_CMAC_key.3 @@ -0,0 +1,160 @@ +.\" $OpenBSD: EVP_PKEY_new_CMAC_key.3,v 1.2 2025/06/08 22:40:29 schwarze Exp $ +.\" +.\" Copyright (c) 2024 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 $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_NEW_CMAC_KEY 3 +.Os +.Sh NAME +.Nm EVP_PKEY_new_CMAC_key +.Nd CMAC in the EVP framework +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft EVP_PKEY * +.Fo EVP_PKEY_new_CMAC_key +.Fa "ENGINE *engine" +.Fa "const unsigned char *key" +.Fa "size_t key_len" +.Fa "const EVP_CIPHER *cipher" +.Fc +.Sh DESCRIPTION +.Fn EVP_PKEY_new_CMAC_key +allocates a new +.Vt EVP_PKEY +object, sets its type to +.Dv EVP_PKEY_CMAC , +and configures it as a wrapper around the low-level functions documented in +.Xr CMAC_Init 3 +using the block +.Fa cipher +with the symmetric +.Fa key +that is +.Fa key_len +bytes long. +.Pp +Functions to obtain suitable +.Vt EVP_CIPHER +objects are listed in the CIPHER LISTING section of the +.Xr EVP_EncryptInit 3 +manual page. +Always use an object that implements the CBC mode of operation. +As in +.Xr CMAC_Init 3 , +only ciphers with a block size of either 64 or 128 bits +are supported by this implementation. +.Pp +The +.Fa engine +argument is ignored; passing +.Dv NULL +is recommended. +.Sh RETURN VALUES +.Fn EVP_PKEY_new_CMAC_key +returns the newly allocated +.Vt EVP_PKEY +structure or +.Dv NULL +if an error occurred. +.Sh EXAMPLES +The following code digests a message with AES-CMAC +using the key length of 128 bits specified in RFC 4493. +.Bd -literal -offset indent +/* Bogus key: would normally be set from another source. */ +const unsigned char key[] = "symmetric secret"; +const size_t key_len = strlen(key); /* 16 = 128/8 */ + +const char *msg = "Hello World!"; +const size_t msg_len = strlen(msg); + +unsigned char out_mac[16]; +size_t out_len = sizeof(out_mac); +size_t i; + +EVP_PKEY *pkey; +EVP_MD_CTX *md_ctx; + +pkey = EVP_PKEY_new_CMAC_key(NULL, key, key_len, EVP_aes_128_cbc()); +if (pkey == NULL) + err(1, "EVP_PKEY_new_CMAC_key"); +md_ctx = EVP_MD_CTX_new(); +if (md_ctx == NULL) + err(1, "EVP_MD_CTX_new"); + +if (EVP_DigestSignInit(md_ctx, NULL, NULL, NULL, pkey) == 0) + err(1, "EVP_DigestSignInit"); +if (EVP_DigestSign(md_ctx, out_mac, &out_len, msg, msg_len) == 0) + err(1, "EVP_DigestSign"); +EVP_MD_CTX_free(md_ctx); +EVP_PKEY_free(pkey); + +printf(" MAC = "); +for (i = 0; i < out_len; i++) + printf("%02x:", out_mac[i]); +printf("\en"); +.Ed +.Pp +Consider the following details: +.Bl -bullet -width 1n +.It +Even though the type name +.Vt EVP_PKEY +was originally intended to stand for +.Dq private key +and the +.Xr EVP_DigestSignInit 3 +API was designed for digital signatures in the context +of public key cryptography, both are also used here because a MAC +also requires a key, even though that is a symmetric key. +.It +In contrast to digital signing which requires both a digest algorithm +and a private key, the CMAC algorithm only requires a block cipher +and a shared key, both of which are stored in the somewhat abused +.Vt EVP_PKEY +object. +Consequently, the +.Vt "EVP_MD *type" +argument of +.Xr EVP_DigestSignInit 3 +has to be set to +.Dv NULL . +.It +The size of the resulting message digest equals the block size +of the used cipher. +.It +The function +.Xr EVP_DigestSignInit 3 +does not transfer ownership of the +.Fa pkey +object to +.Ft md_ctx +but merely increments the reference count. +Consequently, the caller is responsible for freeing the +.Vt EVP_PKEY +object when it is no longer needed. +.El +.Sh SEE ALSO +.Xr CMAC_Init 3 , +.Xr evp 3 , +.Xr EVP_DigestSignInit 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_PKEY_new 3 +.Sh STANDARDS +RFC 4493: The AES-CMAC Algorithm +.Sh HISTORY +.Fn EVP_PKEY_new_CMAC_key +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 6.9 . diff --git a/static/openbsd/man3/EVP_PKEY_print_private.3 b/static/openbsd/man3/EVP_PKEY_print_private.3 new file mode 100644 index 00000000..877385d1 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_print_private.3 @@ -0,0 +1,130 @@ +.\" $OpenBSD: EVP_PKEY_print_private.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_PRINT_PRIVATE 3 +.Os +.Sh NAME +.Nm EVP_PKEY_print_public , +.Nm EVP_PKEY_print_private , +.Nm EVP_PKEY_print_params +.Nd public key algorithm printing routines +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_print_public +.Fa "BIO *out" +.Fa "const EVP_PKEY *pkey" +.Fa "int indent" +.Fa "ASN1_PCTX *pctx" +.Fc +.Ft int +.Fo EVP_PKEY_print_private +.Fa "BIO *out" +.Fa "const EVP_PKEY *pkey" +.Fa "int indent" +.Fa "ASN1_PCTX *pctx" +.Fc +.Ft int +.Fo EVP_PKEY_print_params +.Fa "BIO *out" +.Fa "const EVP_PKEY *pkey" +.Fa "int indent" +.Fa "ASN1_PCTX *pctx" +.Fc +.Sh DESCRIPTION +The functions +.Fn EVP_PKEY_print_public , +.Fn EVP_PKEY_print_private , +and +.Fn EVP_PKEY_print_params +print out the public, private or parameter components of key +.Fa pkey , +respectively. +The key is sent to +.Vt BIO +.Fa out +in human readable form. +The parameter +.Fa indent +indicates how far the printout should be indented. +.Pp +The +.Fa pctx +parameter allows the print output to be finely tuned by using ASN.1 +printing options. +If +.Fa pctx +is set to +.Dv NULL , +then default values will be used. +Currently, no public key algorithms include any options in the +.Fa pctx +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 +.Fn EVP_PKEY_print_private +will only print the public components. +.Sh 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 +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_keygen 3 , +.Xr EVP_PKEY_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.0 +and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_PKEY_set1_RSA.3 b/static/openbsd/man3/EVP_PKEY_set1_RSA.3 new file mode 100644 index 00000000..5e17894b --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_set1_RSA.3 @@ -0,0 +1,499 @@ +.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.27 2025/07/02 06:40:28 tb Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019, 2020, 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: July 2 2025 $ +.Dt EVP_PKEY_SET1_RSA 3 +.Os +.Sh NAME +.Nm EVP_PKEY_set1_RSA , +.Nm EVP_PKEY_set1_DSA , +.Nm EVP_PKEY_set1_DH , +.Nm EVP_PKEY_set1_EC_KEY , +.Nm EVP_PKEY_get1_RSA , +.Nm EVP_PKEY_get1_DSA , +.Nm EVP_PKEY_get1_DH , +.Nm EVP_PKEY_get1_EC_KEY , +.Nm EVP_PKEY_get0_RSA , +.Nm EVP_PKEY_get0_DSA , +.Nm EVP_PKEY_get0_DH , +.Nm EVP_PKEY_get0_EC_KEY , +.Nm EVP_PKEY_get0_hmac , +.Nm EVP_PKEY_get0 , +.Nm EVP_PKEY_assign_RSA , +.Nm EVP_PKEY_assign_DSA , +.Nm EVP_PKEY_assign_DH , +.Nm EVP_PKEY_assign_EC_KEY , +.Nm EVP_PKEY_assign , +.Nm EVP_PKEY_base_id , +.Nm EVP_PKEY_id , +.Nm EVP_PKEY_type , +.Nm EVP_PKEY_set_type , +.Nm EVP_PKEY_set_type_str +.\" The function X509_certificate_type(3) is intentionally undocumented +.\" and scheduled for deletion from the library. BoringSSL already +.\" deleted it and OpenSSL deprecates it in version 3.0. +.\" The following constants are also intentionally undocumented +.\" because they are only used by that function: +.\" EVP_PK_DH EVP_PK_DSA EVP_PK_EC EVP_PK_RSA +.\" EVP_PKS_DSA EVP_PKS_EC EVP_PKS_RSA +.\" EVP_PKT_ENC EVP_PKT_EXCH EVP_PKT_EXP EVP_PKT_SIGN +.Nd EVP_PKEY assignment functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_set1_RSA +.Fa "EVP_PKEY *pkey" +.Fa "RSA *key" +.Fc +.Ft int +.Fo EVP_PKEY_set1_DSA +.Fa "EVP_PKEY *pkey" +.Fa "DSA *key" +.Fc +.Ft int +.Fo EVP_PKEY_set1_DH +.Fa "EVP_PKEY *pkey" +.Fa "DH *key" +.Fc +.Ft int +.Fo EVP_PKEY_set1_EC_KEY +.Fa "EVP_PKEY *pkey" +.Fa "EC_KEY *key" +.Fc +.Ft RSA * +.Fo EVP_PKEY_get1_RSA +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft DSA * +.Fo EVP_PKEY_get1_DSA +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft DH * +.Fo EVP_PKEY_get1_DH +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft EC_KEY * +.Fo EVP_PKEY_get1_EC_KEY +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft RSA * +.Fo EVP_PKEY_get0_RSA +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft DSA * +.Fo EVP_PKEY_get0_DSA +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft DH * +.Fo EVP_PKEY_get0_DH +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft EC_KEY * +.Fo EVP_PKEY_get0_EC_KEY +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft const unsigned char * +.Fo EVP_PKEY_get0_hmac +.Fa "const EVP_PKEY *pkey" +.Fa "size_t *len" +.Fc +.Ft void * +.Fo EVP_PKEY_get0 +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_assign_RSA +.Fa "EVP_PKEY *pkey" +.Fa "RSA *key" +.Fc +.Ft int +.Fo EVP_PKEY_assign_DSA +.Fa "EVP_PKEY *pkey" +.Fa "DSA *key" +.Fc +.Ft int +.Fo EVP_PKEY_assign_DH +.Fa "EVP_PKEY *pkey" +.Fa "DH *key" +.Fc +.Ft int +.Fo EVP_PKEY_assign_EC_KEY +.Fa "EVP_PKEY *pkey" +.Fa "EC_KEY *key" +.Fc +.Ft int +.Fo EVP_PKEY_assign +.Fa "EVP_PKEY *pkey" +.Fa "int type" +.Fa "void *key" +.Fc +.Ft int +.Fo EVP_PKEY_base_id +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_id +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_type +.Fa "int type" +.Fc +.Ft int +.Fo EVP_PKEY_set_type +.Fa "EVP_PKEY *pkey" +.Fa "int type" +.Fc +.Ft int +.Fo EVP_PKEY_set_type_str +.Fa "EVP_PKEY *pkey" +.Fa "const char *str" +.Fa "int len" +.Fc +.Sh DESCRIPTION +.Fn EVP_PKEY_set1_RSA , +.Fn EVP_PKEY_set1_DSA , +.Fn EVP_PKEY_set1_DH , +and +.Fn EVP_PKEY_set1_EC_KEY +set the key referenced by +.Fa pkey +to +.Fa key +and increment the reference count of +.Fa key +by 1 in case of success. +.Pp +.Fn EVP_PKEY_get1_RSA , +.Fn EVP_PKEY_get1_DSA , +.Fn EVP_PKEY_get1_DH , +and +.Fn EVP_PKEY_get1_EC_KEY +return the key referenced in +.Fa pkey , +incrementing its reference count by 1, or +.Dv NULL +if the key is not of the correct type. +.Pp +.Fn EVP_PKEY_get0_RSA , +.Fn EVP_PKEY_get0_DSA , +.Fn EVP_PKEY_get0_DH , +.Fn EVP_PKEY_get0_EC_KEY , +and +.Fn EVP_PKEY_get0 +are identical except that they do not increment the reference count. +Consequently, the returned key must not be freed by the caller. +.Pp +.Fn EVP_PKEY_get0_hmac +returns an internal pointer to the key referenced in +.Fa pkey +and sets +.Pf * Fa len +to its length in bytes. +The returned pointer must not be freed by the caller. +If +.Fa pkey +is not of the correct type, +.Dv NULL +is returned and the content of +.Pf * Fa len +becomes unspecified. +.Pp +.Fn EVP_PKEY_assign_RSA , +.Fn EVP_PKEY_assign_DSA , +.Fn EVP_PKEY_assign_DH , +.Fn EVP_PKEY_assign_EC_KEY , +and +.Fn EVP_PKEY_assign +also set the referenced key to +.Fa key ; +however these use the supplied +.Fa key +internally without incrementing its reference count, such that +.Fa key +will be freed when the parent +.Fa pkey +is freed. +If the +.Fa key +is of the wrong type, these functions report success even though +.Fa pkey +ends up in a corrupted state. +Even the functions explicitly containing the type in their name are +.Em not +type safe because they are implemented as macros. +The following types are supported: +.Dv EVP_PKEY_RSA , +.Dv EVP_PKEY_DSA , +.Dv EVP_PKEY_DH , +and +.Dv EVP_PKEY_EC . +.Pp +.Fn EVP_PKEY_base_id +returns the type of +.Fa pkey +according to the following table: +.Pp +.Bl -column -compact -offset 2n EVP_PKEY_RSA_PSS NID_X9_62_id_ecPublicKey +.It Sy return value Ta Ta Sy PEM type string +.It Dv EVP_PKEY_CMAC Ta = Dv NID_cmac Ta CMAC +.It Dv EVP_PKEY_DH Ta = Dv NID_dhKeyAgreement Ta DH +.It Dv EVP_PKEY_DSA Ta = Dv NID_dsa Ta DSA +.It Dv EVP_PKEY_EC Ta = Dv NID_X9_62_id_ecPublicKey Ta EC +.It Dv EVP_PKEY_HMAC Ta = Dv NID_hmac Ta HMAC +.It Dv EVP_PKEY_RSA Ta = Dv NID_rsaEncryption Ta RSA +.It Dv EVP_PKEY_RSA_PSS Ta = Dv NID_rsassaPss Ta RSA-PSS +.El +.Pp +.Fn EVP_PKEY_id +returns the actual OID associated with +.Fa pkey . +Historically keys using the same algorithm could use different OIDs. +The following deprecated aliases are still supported: +.Pp +.Bl -column -compact -offset 2n EVP_PKEY_DSA4 NID_dsaWithSHA1_2 +.It Sy return value Ta Ta Sy alias for +.It Dv EVP_PKEY_DSA1 Ta = Dv NID_dsa_2 Ta DSA +.It Dv EVP_PKEY_DSA2 Ta = Dv NID_dsaWithSHA Ta DSA +.It Dv EVP_PKEY_DSA3 Ta = Dv NID_dsaWithSHA1 Ta DSA +.It Dv EVP_PKEY_DSA4 Ta = Dv NID_dsaWithSHA1_2 Ta DSA +.It Dv EVP_PKEY_RSA2 Ta = Dv NID_rsa Ta RSA +.El +.Pp +Most applications wishing to know a key type will simply call +.Fn EVP_PKEY_base_id +and will not care about the actual type, +which will be identical in almost all cases. +.Pp +.Fn EVP_PKEY_type +returns the underlying type of the NID +.Fa type . +For example, +.Fn EVP_PKEY_type EVP_PKEY_RSA2 +will return +.Dv EVP_PKEY_RSA . +.Pp +.Fn EVP_PKEY_set_type +frees the key referenced in +.Fa pkey , +if any, and sets the key type of +.Fa pkey +to +.Fa type +without referencing a new key from +.Fa pkey +yet. +For +.Fa type , +any of the possible return values of +.Fn EVP_PKEY_base_id +and +.Fn EVP_PKEY_id +can be passed. +.Pp +.Fn EVP_PKEY_set_type_str +frees the key referenced in +.Fa pkey , +if any, and sets the key type of +.Fa pkey +according to the PEM type string given by the first +.Fa len +bytes of +.Fa str . +If +.Fa len +is \-1, the +.Xr strlen 3 +of +.Fa str +is used instead. +The PEM type strings supported by default are listed in the table above. +This function does not reference a new key from +.Fa pkey . +.Pp +If +.Fa pkey +is a +.Dv NULL +pointer, +.Fn EVP_PKEY_set_type +and +.Fn EVP_PKEY_set_type_str +check that a matching key type exists but do not change any object. +.Pp +In accordance with the OpenSSL naming convention, the key obtained from +or assigned to +.Fa pkey +using the +.Sy 1 +functions must be freed as well as +.Fa pkey . +.Sh RETURN VALUES +.Fn EVP_PKEY_set1_RSA , +.Fn EVP_PKEY_set1_DSA , +.Fn EVP_PKEY_set1_DH , +.Fn EVP_PKEY_set1_EC_KEY , +.Fn EVP_PKEY_assign_RSA , +.Fn EVP_PKEY_assign_DSA , +.Fn EVP_PKEY_assign_DH , +.Fn EVP_PKEY_assign_EC_KEY , +.Fn EVP_PKEY_assign , +.Fn EVP_PKEY_set_type , +and +.Fn EVP_PKEY_set_type_str +return 1 for success or 0 for failure. +.Pp +.Fn EVP_PKEY_get1_RSA , +.Fn EVP_PKEY_get1_DSA , +.Fn EVP_PKEY_get1_DH , +.Fn EVP_PKEY_get1_EC_KEY , +.Fn EVP_PKEY_get0_RSA , +.Fn EVP_PKEY_get0_DSA , +.Fn EVP_PKEY_get0_DH , +.Fn EVP_PKEY_get0_EC_KEY , +.Fn EVP_PKEY_get0_hmac , +and +.Fn EVP_PKEY_get0 +return the referenced key or +.Dv NULL +if an error occurred. +For +.Fn EVP_PKEY_get0 , +the return value points to an +.Vt RSA , +.Vt DSA , +.Vt DH , +.Vt EC_KEY , +or +.Vt ASN1_OCTET_STRING +object depending on the type of +.Fa pkey . +.Pp +.Fn EVP_PKEY_base_id , +.Fn EVP_PKEY_id , +and +.Fn EVP_PKEY_type +return a key type or +.Dv NID_undef +(equivalently +.Dv EVP_PKEY_NONE ) +on error. +.Sh SEE ALSO +.Xr DH_new 3 , +.Xr DSA_new 3 , +.Xr EC_KEY_new 3 , +.Xr EVP_PKEY_get0_asn1 3 , +.Xr EVP_PKEY_new 3 , +.Xr RSA_new 3 +.Sh HISTORY +.Fn EVP_PKEY_assign_RSA , +.Fn EVP_PKEY_assign_DSA , +.Fn EVP_PKEY_assign_DH , +.Fn EVP_PKEY_assign , +and +.Fn EVP_PKEY_type +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_PKEY_set1_RSA , +.Fn EVP_PKEY_set1_DSA , +.Fn EVP_PKEY_set1_DH , +.Fn EVP_PKEY_get1_RSA , +.Fn EVP_PKEY_get1_DSA , +and +.Fn EVP_PKEY_get1_DH +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn EVP_PKEY_set1_EC_KEY , +.Fn EVP_PKEY_get1_EC_KEY , +and +.Fn EVP_PKEY_assign_EC_KEY +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn EVP_PKEY_get0 , +.Fn EVP_PKEY_base_id , +.Fn EVP_PKEY_id , +.Fn EVP_PKEY_set_type , +and +.Fn EVP_PKEY_set_type_str +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +.Fn EVP_PKEY_get0_RSA , +.Fn EVP_PKEY_get0_DSA , +.Fn EVP_PKEY_get0_DH , +and +.Fn EVP_PKEY_get0_EC_KEY +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +.Pp +.Fn EVP_PKEY_get0_hmac +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.5 . diff --git a/static/openbsd/man3/EVP_PKEY_sign.3 b/static/openbsd/man3/EVP_PKEY_sign.3 new file mode 100644 index 00000000..58d7e34c --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_sign.3 @@ -0,0 +1,191 @@ +.\" $OpenBSD: EVP_PKEY_sign.3,v 1.11 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2013, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_SIGN 3 +.Os +.Sh NAME +.Nm EVP_PKEY_sign_init , +.Nm EVP_PKEY_sign +.Nd sign using a public key algorithm +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_sign_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_sign +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *sig" +.Fa "size_t *siglen" +.Fa "const unsigned char *tbs" +.Fa "size_t tbslen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_sign_init +function initializes a public key algorithm context using the key +.Fa ctx->pkey +for a signing operation. +.Pp +The +.Fn EVP_PKEY_sign +function performs a public key signing operation using +.Fa ctx . +The data to be signed is specified using the +.Fa tbs +and +.Fa tbslen +parameters. +If +.Fa sig +is +.Dv NULL , +then the maximum size of the output buffer is written to the +.Fa siglen +parameter. +If +.Fa sig +is not +.Dv NULL , +then before the call the +.Fa siglen +parameter should contain the length of the +.Fa sig +buffer. +If the call is successful, the signature is written to +.Fa sig +and the amount of data written to +.Fa siglen . +.Pp +.Fn EVP_PKEY_sign +does not hash the data to be signed, and therefore is normally used +to sign digests. +For signing arbitrary messages, see the +.Xr EVP_DigestSignInit 3 +and +.Xr EVP_SignInit 3 +signing interfaces instead. +.Pp +After the call to +.Fn EVP_PKEY_sign_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation; see +.Xr EVP_PKEY_CTX_ctrl 3 . +.Pp +The function +.Fn EVP_PKEY_sign +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_sign_init +and +.Fn EVP_PKEY_sign +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 +Sign data using RSA with PKCS#1 padding and SHA-256 digest: +.Bd -literal -offset indent +#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) + /* 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 = malloc(siglen); + +if (!sig) + /* malloc failure */ + +if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0) + /* Error */ + +/* Signature is siglen bytes written to buffer sig */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_ctrl 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +.Fn EVP_PKEY_sign_init +and +.Fn EVP_PKEY_sign +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_PKEY_size.3 b/static/openbsd/man3/EVP_PKEY_size.3 new file mode 100644 index 00000000..dc53de12 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_size.3 @@ -0,0 +1,225 @@ +.\" $OpenBSD: EVP_PKEY_size.3,v 1.5 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL eed9d03b Jan 8 11:04:15 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022, 2023 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. +.\" +.\" The original file was written by Richard Levitte . +.\" Copyright (c) 2020 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_SIZE 3 +.Os +.Sh NAME +.Nm EVP_PKEY_size , +.Nm EVP_PKEY_bits , +.Nm EVP_PKEY_security_bits +.Nd EVP_PKEY information functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_size +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_bits +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_security_bits +.Fa "const EVP_PKEY *pkey" +.Fc +.Sh DESCRIPTION +.Fn EVP_PKEY_size +returns the maximum size in bytes needed for the output buffer +for almost any operation that can be done with +.Fa pkey . +The primary use is with +.Xr EVP_SignFinal 3 +and +.Xr EVP_SealInit 3 . +The returned size is also large enough for the output buffer of +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_decrypt 3 , +and +.Xr EVP_PKEY_derive 3 . +.Pp +Unless the documentation for the operation says otherwise, +the size returned by +.Fn EVP_PKEY_size +is only an upper limit and the final content 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. +For example, +.Xr EVP_PKEY_sign 3 +returns that length in the +.Pf * Fa siglen +argument. +.Pp +Using +.Fn EVP_PKEY_size +is discouraged with +.Xr EVP_DigestSignFinal 3 . +.Pp +Most functions using an output buffer support passing +.Dv NULL +for the buffer and a pointer to an integer +to get the exact size that this function call delivers +in the context that it is 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 to actually output the data. +For those functions, it isn't strictly necessary to call +.Fn EVP_PKEY_size +to find out the buffer size, but it may still be useful in cases +where it's desirable to know the upper limit in advance. +.Pp +.Fn EVP_PKEY_size +is supported for the following algorithms: +.Bl -column ED25519 "EVP_MAX_BLOCK_LENGTH = 32" +.It Ta same result as from: +.It CMAC Ta Dv EVP_MAX_BLOCK_LENGTH No = 32 +.It DH Ta Xr DH_size 3 +.It DSA Ta Xr DSA_size 3 +.It EC Ta Xr ECDSA_size 3 +.It ED25519 Ta 64, but see below +.It HMAC Ta Dv EVP_MAX_MD_SIZE No = 64 +.It RSA Ta Xr RSA_size 3 +.It X25519 Ta Dv X25519_KEYLEN No = 32 +.El +.Pp +For +.Dv EVP_PKEY_ED25519 , +the situation is special: while the key size is +.Dv ED25519_KEYLEN No = 32 bytes , +.Fn EVP_PKEY_size +returns 64 because the signature is longer than the keys. +.Pp +.Fn EVP_PKEY_bits +returns the cryptographic length of the cryptosystem to which the key in +.Fa pkey +belongs, in bits. +The definition of cryptographic length is specific to the key cryptosystem. +The following algorithms are supported: +.Bl -column ED25519 "the public domain parameter p" DSA_bits(3) +.It Ta cryptographic length = Ta same result as from: +.It Ta significant bits in ... Ta +.It DH Ta the public domain parameter Fa p Ta Xr DH_bits 3 +.It DSA Ta the public domain parameter Fa p Ta Xr DSA_bits 3 +.It EC Ta the order of the group Ta Xr EC_GROUP_order_bits 3 +.It ED25519 Ta 253 Ta \(em +.It RSA Ta the public modulus Ta Xr RSA_bits 3 +.It X25519 Ta 253 Ta \(em +.El +.Pp +.Fn EVP_PKEY_security_bits +returns the security strength measured in bits of the given +.Fa pkey +as defined in NIST SP800-57. +The following algorithms are supported: +.Bl -column ED25519 DSA_security_bits(3) +.It Ta same result as from: +.It DH Ta Xr DH_security_bits 3 +.It DSA Ta Xr DSA_security_bits 3 +.It EC Ta Xr EC_GROUP_order_bits 3 divided by 2 +.It ED25519 Ta 128 +.It RSA Ta Xr RSA_security_bits 3 +.It X25519 Ta 128 +.El +.Pp +For EC keys, if the result is greater than 80, it is rounded down +to 256, 192, 128, 112, or 80. +.Sh RETURN VALUES +.Fn EVP_PKEY_size +and +.Fn EVP_PKEY_bits +return a positive number or 0 if this size isn't available. +.Pp +.Fn EVP_PKEY_security_bits +returns a number in the range from 0 to 256 inclusive +or \-2 if this function is unsupported for the algorithm used by +.Fa pkey . +It returns 0 if +.Fa pkey +is +.Dv NULL . +.Sh SEE ALSO +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_new 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_SealInit 3 , +.Xr EVP_SignFinal 3 +.Sh HISTORY +.Fn EVP_PKEY_size +first appeared in SSLeay 0.6.0 and +.Fn EVP_PKEY_bits +in SSLeay 0.9.0. +Both functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_PKEY_security_bits +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.2 . diff --git a/static/openbsd/man3/EVP_PKEY_verify.3 b/static/openbsd/man3/EVP_PKEY_verify.3 new file mode 100644 index 00000000..1a1d19a5 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_verify.3 @@ -0,0 +1,168 @@ +.\" $OpenBSD: EVP_PKEY_verify.3,v 1.10 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2010, 2013, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_VERIFY 3 +.Os +.Sh NAME +.Nm EVP_PKEY_verify_init , +.Nm EVP_PKEY_verify +.Nd signature verification using a public key algorithm +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_verify_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_verify +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const unsigned char *sig" +.Fa "size_t siglen" +.Fa "const unsigned char *tbs" +.Fa "size_t tbslen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_verify_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for a signature verification operation. +.Pp +The +.Fn EVP_PKEY_verify +function performs a public key verification operation using +.Fa ctx . +The signature is specified using the +.Fa sig +and +.Fa siglen +parameters. +The verified data (i.e. the data believed originally signed) is +specified using the +.Fa tbs +and +.Fa tbslen +parameters. +.Pp +After the call to +.Fn EVP_PKEY_verify_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The function +.Fn EVP_PKEY_verify +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_verify_init +and +.Fn EVP_PKEY_verify +return 1 if the verification was successful and 0 if it failed. +Unlike other functions the return value 0 from +.Fn EVP_PKEY_verify +only indicates that the signature did not verify successfully. +That is, +.Fa 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 +Verify signature using PKCS#1 and SHA-256 digest: +.Bd -literal -offset 3n +#include +#include + +EVP_PKEY_CTX *ctx; +unsigned char *md, *sig; +size_t mdlen, siglen; +EVP_PKEY *verify_key; + +/* + * Assumes that 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); +if (!ctx) + /* 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 some other error. + */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +.Fn EVP_PKEY_verify_init +and +.Fn EVP_PKEY_verify +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_PKEY_verify_recover.3 b/static/openbsd/man3/EVP_PKEY_verify_recover.3 new file mode 100644 index 00000000..840307b4 --- /dev/null +++ b/static/openbsd/man3/EVP_PKEY_verify_recover.3 @@ -0,0 +1,189 @@ +.\" $OpenBSD: EVP_PKEY_verify_recover.3,v 1.12 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2006, 2009, 2010, 2013, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_PKEY_VERIFY_RECOVER 3 +.Os +.Sh NAME +.Nm EVP_PKEY_verify_recover_init , +.Nm EVP_PKEY_verify_recover +.Nd recover signature using a public key algorithm +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_verify_recover_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_verify_recover +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *rout" +.Fa "size_t *routlen" +.Fa "const unsigned char *sig" +.Fa "size_t siglen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_verify_recover_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for a verify recover operation. +.Pp +The +.Fn EVP_PKEY_verify_recover +function recovers signed data using +.Fa ctx . +The signature is specified using the +.Fa sig +and +.Fa siglen +parameters. +If +.Fa rout +is +.Dv NULL , +then the maximum size of the output buffer is written to the +.Fa routlen +parameter. +If +.Fa rout +is not +.Dv NULL , +then before the call the +.Fa routlen +parameter should contain the length of the +.Fa rout +buffer. +If the call is successful, recovered data is written to +.Fa rout +and the amount of data written to +.Fa routlen . +.Pp +Normally an application is only interested in whether a signature +verification operation is successful. +In those cases, the +.Xr EVP_PKEY_verify 3 +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 +.Fn EVP_PKEY_verify_recover_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The function +.Fn EVP_PKEY_verify_recover +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_verify_recover_init +and +.Fn EVP_PKEY_verify_recover +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 +Recover digest originally signed using PKCS#1 and SHA-256 digest: +.Bd -literal -offset indent +#include +#include + +EVP_PKEY_CTX *ctx; +unsigned char *rout, *sig; +size_t routlen, siglen; +EVP_PKEY *verify_key; + +/* + * Assumes that 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); +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 = 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 */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 +.Sh HISTORY +.Fn EVP_PKEY_verify_recover_init +and +.Fn EVP_PKEY_verify_recover +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/EVP_SealInit.3 b/static/openbsd/man3/EVP_SealInit.3 new file mode 100644 index 00000000..cae0a55e --- /dev/null +++ b/static/openbsd/man3/EVP_SealInit.3 @@ -0,0 +1,202 @@ +.\" $OpenBSD: EVP_SealInit.3,v 1.11 2026/01/30 14:33:33 tb Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2002, 2003, 2005, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: January 30 2026 $ +.Dt EVP_SEALINIT 3 +.Os +.Sh NAME +.Nm EVP_SealInit , +.Nm EVP_SealUpdate , +.Nm EVP_SealFinal +.Nd EVP envelope encryption +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_SealInit +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "unsigned char **ek" +.Fa "int *ekl" +.Fa "unsigned char *iv" +.Fa "EVP_PKEY **pubk" +.Fa "int npubk" +.Fc +.Ft int +.Fo EVP_SealUpdate +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fa "unsigned char *in" +.Fa "int inl" +.Fc +.Ft int +.Fo EVP_SealFinal +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fc +.Sh 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 +.Fn EVP_SealInit +initializes a cipher context +.Fa ctx +for encryption with cipher +.Fa type +using a random secret key and IV. +.Fa type +is normally supplied by a function such as +.Xr EVP_aes_256_cbc 3 ; +see +.Xr EVP_EncryptInit 3 +for details. +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. +.Fa ek +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 +.Fa ek[i] +must have room for +.Fn EVP_PKEY_size pubk[i] +bytes. +The actual size of each encrypted secret key is written to the array +.Fa ekl . +.Fa pubk +is an array of +.Fa npubk +public keys. +.Pp +The +.Fa iv +parameter is a buffer where the generated IV is written to. +It must contain enough room for the corresponding cipher's IV, as +determined by (for example) +.Fn EVP_CIPHER_iv_length type . +.Pp +If the cipher does not require an IV then the +.Fa iv +parameter is ignored and can be +.Dv NULL . +.Pp +.Fn EVP_SealUpdate +and +.Fn EVP_SealFinal +have exactly the same properties as the +.Xr EVP_EncryptUpdate 3 +and +.Xr EVP_EncryptFinal 3 +routines. +.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 +.Fn EVP_SealInit +twice in the same way as +.Xr EVP_EncryptInit 3 . +The first call should have +.Fa npubk +set to 0 and (after setting any cipher parameters) it should be called +again with +.Fa type +set to NULL. +.Pp +.Fn EVP_SealUpdate +is implemented as a macro. +.Sh RETURN VALUES +.Fn EVP_SealInit +usually +returns 0 on error or +.Fa npubk +if successful. +If +.Fn EVP_SealInit +is called with +.Fa npubk +set to 0 or with +.Fa pubk +set to +.Dv NULL , +it returns 1 for success and 0 for failure. +.Pp +.Fn EVP_SealUpdate +and +.Fn EVP_SealFinal +return 1 for success and 0 for failure. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_OpenInit 3 +.Sh HISTORY +.Fn EVP_SealInit , +.Fn EVP_SealUpdate , +and +.Fn EVP_SealFinal +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_SealFinal +did not return a value before OpenSSL 0.9.7. diff --git a/static/openbsd/man3/EVP_SignInit.3 b/static/openbsd/man3/EVP_SignInit.3 new file mode 100644 index 00000000..d3964abd --- /dev/null +++ b/static/openbsd/man3/EVP_SignInit.3 @@ -0,0 +1,212 @@ +.\" $OpenBSD: EVP_SignInit.3,v 1.22 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000-2002, 2005, 2006, 2014-2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_SIGNINIT 3 +.Os +.Sh NAME +.Nm EVP_SignInit_ex , +.Nm EVP_SignUpdate , +.Nm EVP_SignFinal , +.Nm EVP_SignInit +.Nd EVP signing functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_SignInit_ex +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fa "ENGINE *engine" +.Fc +.Ft int +.Fo EVP_SignUpdate +.Fa "EVP_MD_CTX *ctx" +.Fa "const void *d" +.Fa "unsigned int cnt" +.Fc +.Ft int +.Fo EVP_SignFinal +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *sig" +.Fa "unsigned int *s" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft void +.Fo EVP_SignInit +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fc +.Sh DESCRIPTION +The EVP signature routines are a high-level interface to digital +signatures. +.Pp +.Fn EVP_SignInit_ex +sets up the signing context +.Fa ctx +to use the digest +.Fa type . +Before calling this function, obtain +.Fa ctx +from +.Xr EVP_MD_CTX_new 3 +or call +.Xr EVP_MD_CTX_reset 3 +on it. +The +.Fa engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +.Fn EVP_SignUpdate +hashes +.Fa cnt +bytes of data at +.Fa d +into the signature context +.Fa ctx . +This function can be called several times on the same +.Fa ctx +to include additional data. +.Pp +.Fn EVP_SignFinal +signs the data in +.Fa ctx +using the private key +.Fa pkey +and places the signature in +.Fa sig . +.Fa sig +must be at least +.Xr EVP_PKEY_size 3 +bytes in size. +.Fa s +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 +.Fa s . +At most +.Xr EVP_PKEY_size 3 +bytes will be written. +.Pp +.Fn EVP_SignInit +initializes a signing context +.Fa ctx +to use the default implementation of digest +.Fa type . +.Pp +The EVP 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 +.Fn EVP_SignFinal +internally finalizes a copy of the digest context. +This means that calls to +.Fn EVP_SignUpdate +and +.Fn EVP_SignFinal +can be called later to digest and sign additional data. +.Pp +Since only a copy of the digest context is ever finalized, the context +must be cleaned up after use by calling +.Xr EVP_MD_CTX_free 3 +or a memory leak will occur. +.Pp +.Fn EVP_SignInit_ex , +.Fn EVP_SignUpdate , +and +.Fn EVP_SignInit +are implemented as macros. +.Sh RETURN VALUES +.Fn EVP_SignInit_ex , +.Fn EVP_SignUpdate , +and +.Fn EVP_SignFinal +return 1 for success and 0 for failure. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_PKEY_size 3 , +.Xr EVP_VerifyInit 3 +.Sh HISTORY +.Fn EVP_SignInit , +.Fn EVP_SignUpdate , +and +.Fn EVP_SignFinal +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_SignInit_ex +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Sh BUGS +Older versions of this documentation wrongly stated that calls to +.Fn EVP_SignUpdate +could not be made after calling +.Fn EVP_SignFinal . +.Pp +Since the private key is passed in the call to +.Fn EVP_SignFinal , +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 +.Fn EVP_SignUpdate . +.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* function. diff --git a/static/openbsd/man3/EVP_VerifyInit.3 b/static/openbsd/man3/EVP_VerifyInit.3 new file mode 100644 index 00000000..9bf1f1e1 --- /dev/null +++ b/static/openbsd/man3/EVP_VerifyInit.3 @@ -0,0 +1,206 @@ +.\" $OpenBSD: EVP_VerifyInit.3,v 1.14 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2001, 2006, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_VERIFYINIT 3 +.Os +.Sh NAME +.Nm EVP_VerifyInit_ex , +.Nm EVP_VerifyUpdate , +.Nm EVP_VerifyFinal , +.Nm EVP_VerifyInit +.Nd EVP signature verification functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_VerifyInit_ex +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fa "ENGINE *engine" +.Fc +.Ft int +.Fo EVP_VerifyUpdate +.Fa "EVP_MD_CTX *ctx" +.Fa "const void *d" +.Fa "unsigned int cnt" +.Fc +.Ft int +.Fo EVP_VerifyFinal +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *sigbuf" +.Fa "unsigned int siglen" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_VerifyInit +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fc +.Sh DESCRIPTION +The EVP signature verification routines are a high-level interface to +digital signatures. +.Pp +.Fn EVP_VerifyInit_ex +sets up the verification context +.Fa ctx +to use the digest +.Fa type . +Before calling this function, obtain +.Fa ctx +from +.Xr EVP_MD_CTX_new 3 +or call +.Xr EVP_MD_CTX_reset 3 +on it. +The +.Fa engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +.Fn EVP_VerifyUpdate +hashes +.Fa cnt +bytes of data at +.Fa d +into the verification context +.Fa ctx . +This function can be called several times on the same +.Fa ctx +to include additional data. +.Pp +.Fn EVP_VerifyFinal +verifies the data in +.Fa ctx +using the public key +.Fa pkey +and against the +.Fa siglen +bytes at +.Fa sigbuf . +.Pp +.Fn EVP_VerifyInit +initializes a verification context +.Fa ctx +to use the default implementation of digest +.Fa type . +.Pp +The EVP 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 +.Fn EVP_VerifyFinal +internally finalizes a copy of the digest context. +This means that calls to +.Fn EVP_VerifyUpdate +and +.Fn EVP_VerifyFinal +can be called later to digest and verify additional data. +.Pp +Since only a copy of the digest context is ever finalized, the context +must be cleaned up after use by calling +.Xr EVP_MD_CTX_free 3 , +or a memory leak will occur. +.Pp +.Fn EVP_VerifyInit_ex , +.Fn EVP_VerifyUpdate , +and +.Fn EVP_VerifyInit +are implemented as macros. +.Sh RETURN VALUES +.Fn EVP_VerifyInit_ex +and +.Fn EVP_VerifyUpdate +return 1 for success and 0 for failure. +.Pp +.Fn EVP_VerifyFinal +returns 1 for a correct signature, 0 for failure, and -1 if some other +error occurred. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_SignInit 3 +.Sh HISTORY +.Fn EVP_VerifyInit , +.Fn EVP_VerifyUpdate , +and +.Fn EVP_VerifyFinal +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_VerifyInit_ex +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Sh BUGS +Older versions of this documentation wrongly stated that calls to +.Fn EVP_VerifyUpdate +could not be made after calling +.Fn EVP_VerifyFinal . +.Pp +Since the public key is passed in the call to +.Xr EVP_SignFinal 3 , +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 +.Xr EVP_SignUpdate 3 . +.Pp +It is not possible to change the signing parameters using these +functions. +.Pp +The previous two bugs are fixed in the newer functions of the +.Xr EVP_DigestVerifyInit 3 +family. diff --git a/static/openbsd/man3/EVP_aes_128_cbc.3 b/static/openbsd/man3/EVP_aes_128_cbc.3 new file mode 100644 index 00000000..72f654b7 --- /dev/null +++ b/static/openbsd/man3/EVP_aes_128_cbc.3 @@ -0,0 +1,305 @@ +.\" $OpenBSD: EVP_aes_128_cbc.3,v 1.9 2025/06/08 22:40:29 schwarze Exp $ +.\" selective merge up to: OpenSSL 7c6d372a Nov 20 13:20:01 2018 +0000 +.\" +.\" This file was written by Ronald Tse +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_AES_128_CBC 3 +.Os +.Sh NAME +.Nm EVP_aes_128_cbc , +.Nm EVP_aes_192_cbc , +.Nm EVP_aes_256_cbc , +.Nm EVP_aes_128_cfb1 , +.Nm EVP_aes_192_cfb1 , +.Nm EVP_aes_256_cfb1 , +.Nm EVP_aes_128_cfb8 , +.Nm EVP_aes_192_cfb8 , +.Nm EVP_aes_256_cfb8 , +.Nm EVP_aes_128_cfb128 , +.Nm EVP_aes_192_cfb128 , +.Nm EVP_aes_256_cfb128 , +.Nm EVP_aes_128_cfb , +.Nm EVP_aes_192_cfb , +.Nm EVP_aes_256_cfb , +.Nm EVP_aes_128_ctr , +.Nm EVP_aes_192_ctr , +.Nm EVP_aes_256_ctr , +.Nm EVP_aes_128_ecb , +.Nm EVP_aes_192_ecb , +.Nm EVP_aes_256_ecb , +.Nm EVP_aes_128_ofb , +.Nm EVP_aes_192_ofb , +.Nm EVP_aes_256_ofb , +.Nm EVP_aes_128_cbc_hmac_sha1 , +.Nm EVP_aes_256_cbc_hmac_sha1 , +.Nm EVP_aes_128_wrap , +.Nm EVP_aes_192_wrap , +.Nm EVP_aes_256_wrap , +.Nm EVP_aes_128_xts , +.Nm EVP_aes_256_xts +.Nd EVP AES cipher +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_cfb1 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_cfb1 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_cfb1 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_cfb8 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_cfb8 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_cfb8 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_cfb128 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_cfb128 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_cfb128 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_ctr void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_ctr void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_ctr void +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_cbc_hmac_sha1 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_cbc_hmac_sha1 void +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_wrap void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_wrap void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_wrap void +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_xts void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_xts void +.Sh DESCRIPTION +These functions provide the AES encryption algorithm in the +.Xr evp 3 +framework. +AES is a family of block ciphers operating on 128 bit blocks +using key lengths of 128, 192, and 256 bits. +.Pp +.Fn EVP_aes_128_cbc , +.Fn EVP_aes_192_cbc , +.Fn EVP_aes_256_cbc , +.Fn EVP_aes_128_cfb1 , +.Fn EVP_aes_192_cfb1 , +.Fn EVP_aes_256_cfb1 , +.Fn EVP_aes_128_cfb8 , +.Fn EVP_aes_192_cfb8 , +.Fn EVP_aes_256_cfb8 , +.Fn EVP_aes_128_cfb128 , +.Fn EVP_aes_192_cfb128 , +.Fn EVP_aes_256_cfb128 , +.Fn EVP_aes_128_ctr , +.Fn EVP_aes_192_ctr , +.Fn EVP_aes_256_ctr , +.Fn EVP_aes_128_ecb , +.Fn EVP_aes_192_ecb , +.Fn EVP_aes_256_ecb , +.Fn EVP_aes_128_ofb , +.Fn EVP_aes_192_ofb , +and +.Fn EVP_aes_256_ofb +provide AES for 128, 192, and 256-bit keys in the following modes: +CBC, CFB with 1-bit shift, CFB with 8-bit shift, CFB with 128-bit shift, +CTR, ECB, and OFB. +.Pp +.Fn EVP_aes_128_cfb , +.Fn EVP_aes_192_cfb , +and +.Fn EVP_aes_256_cfb +are aliases for +.Fn EVP_aes_128_cfb128 , +.Fn EVP_aes_192_cfb128 , +and +.Fn EVP_aes_256_cfb128 , +implemented as macros. +.Pp +.Fn EVP_aes_128_cbc_hmac_sha1 +and +.Fn EVP_aes_256_cbc_hmac_sha1 +provide authenticated encryption with AES in CBC mode using SHA-1 as HMAC, +with keys of 128 and 256-bit length respectively. +The authentication tag is 160 bits long. +This is not intended for usage outside of TLS and requires +calling of some undocumented control functions. +These ciphers do not conform to the EVP AEAD interface. +.Pp +.Fn EVP_aes_128_wrap , +.Fn EVP_aes_192_wrap , +and +.Fn EVP_aes_256_wrap +provide AES key wrap with 128, 192 and 256-bit keys +according to RFC 3394 section 2.2.1 ("wrap"). +When the returned +.Vt EVP_CIPHER +object is later passed to +.Xr EVP_CipherInit_ex 3 , +.Xr EVP_EncryptInit_ex 3 , +or +.Xr EVP_DecryptInit_ex 3 +together with an +.Vt EVP_CIPHER_CTX +object, the flag +.Dv EVP_CIPHER_CTX_FLAG_WRAP_ALLOW +must have been set in the +.Vt EVP_CIPHER_CTX +using +.Xr EVP_CIPHER_CTX_set_flags 3 . +Otherwise, or when passing the returned +.Vt EVP_CIPHER +object to +.Xr EVP_CipherInit 3 , +.Xr EVP_EncryptInit 3 , +or +.Xr EVP_DecryptInit 3 , +initialization fails with a +.Dq wrap not allowed +error. +.Pp +.Fn EVP_aes_128_xts +and +.Fn EVP_aes_256_xts +provide XEX-based tweaked-codebook mode with ciphertext stealing (XTS-AES) +as specified in IEEE Std. 1619-2007 and described in NIST SP 800-38E. +It was designed for encrypting data on a storage device, +provides confidentiality but not authentication of data, +and requires a key of double length for protection of a certain key size. +In particular, XTS-AES-128 takes input of a 256-bit key to achieve +AES 128-bit security, and XTS-AES-256 takes input of a 512-bit key +to achieve AES 256-bit security. +.Sh RETURN VALUES +These functions return an +.Vt EVP_CIPHER +structure that provides the implementation of the symmetric cipher. +.Sh SEE ALSO +.Xr AES_encrypt 3 , +.Xr evp 3 , +.Xr EVP_aes_128_ccm 3 , +.Xr EVP_aes_128_gcm 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn EVP_aes_128_cbc , +.Fn EVP_aes_192_cbc , +.Fn EVP_aes_256_cbc , +.Fn EVP_aes_128_cfb , +.Fn EVP_aes_192_cfb , +.Fn EVP_aes_256_cfb , +.Fn EVP_aes_128_ebc , +.Fn EVP_aes_192_ebc , +.Fn EVP_aes_256_ebc , +.Fn EVP_aes_128_ofb , +.Fn EVP_aes_192_ofb , +and +.Fn EVP_aes_256_ofb +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EVP_aes_128_cfb1 , +.Fn EVP_aes_192_cfb1 , +.Fn EVP_aes_256_cfb1 , +.Fn EVP_aes_128_cfb8 , +.Fn EVP_aes_192_cfb8 , +.Fn EVP_aes_256_cfb8 , +.Fn EVP_aes_128_cfb128 , +.Fn EVP_aes_192_cfb128 , +and +.Fn EVP_aes_256_cfb128 +first appeared in OpenSSL 0.9.7e and have been available since +.Ox 3.8 . +.Pp +.Fn EVP_aes_128_ctr , +.Fn EVP_aes_192_ctr , +.Fn EVP_aes_256_ctr , +.Fn EVP_aes_128_cbc_hmac_sha1 , +.Fn EVP_aes_256_cbc_hmac_sha1 , +.Fn EVP_aes_128_xts , +and +.Fn EVP_aes_256_xts +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . +.Pp +.Fn EVP_aes_128_wrap , +.Fn EVP_aes_192_wrap , +and +.Fn EVP_aes_256_wrap +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 6.5 . diff --git a/static/openbsd/man3/EVP_aes_128_ccm.3 b/static/openbsd/man3/EVP_aes_128_ccm.3 new file mode 100644 index 00000000..eaba95c9 --- /dev/null +++ b/static/openbsd/man3/EVP_aes_128_ccm.3 @@ -0,0 +1,574 @@ +.\" $OpenBSD: EVP_aes_128_ccm.3,v 1.6 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100 +.\" OpenSSL EVP_aes.pod a1ec85c1 Apr 21 10:49:12 2020 +0100 +.\" +.\" Copyright (c) 2024 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. +.\" +.\" This file is a derived work containing a few sentences +.\" written by Dr. Stephen Henson +.\" covered by the following license: +.\" +.\" Copyright (c) 2012 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_AES_128_CCM 3 +.Os +.Sh NAME +.Nm EVP_aes_128_ccm , +.Nm EVP_aes_192_ccm , +.Nm EVP_aes_256_ccm +.Nd EVP AES cipher in Counter with CBC-MAC mode +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_ccm void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_ccm void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_ccm void +.\" The following #define'd constants are intentionally undocumented: +.\" Completely unused by anything: +.\" EVP_CTRL_CCM_SET_MSGLEN, EVP_CCM_TLS_FIXED_IV_LEN, EVP_CCM_TLS_IV_LEN +.\" Very rarely used and unused in LibreSSL: +.\" EVP_CCM_TLS_EXPLICIT_IV_LEN, EVP_CCM_TLS_TAG_LEN, EVP_CCM8_TLS_TAG_LEN +.Sh DESCRIPTION +.Fn EVP_aes_128_ccm , +.Fn EVP_aes_192_ccm , +and +.Fn EVP_aes_256_ccm +provide the Advanced Encryption Standard algorithm for 128, 192 and 256-bit +keys in Counter with CBC-MAC (CCM) mode in the +.Xr evp 3 +framework. +This mode supports Authenticated Encryption with Additional Data (AEAD) +and can be used in a number of communication protocols. +Longer keys make precomputation attacks harder at a cost in performance. +.Pp +For CCM mode ciphers, the behaviour of the EVP interface is subtly +altered and several additional +.Xr EVP_CIPHER_CTX_ctrl 3 +operations are required to function correctly. +Some of the +.Dv EVP_CTRL_CCM_* +control commands are older aliases for corresponding +.Dv EVP_CTRL_AEAD_* +constants as indicated below. +.Pp +The less cumbersome and less error-prone +.Xr EVP_AEAD_CTX_new 3 +API does not provide CCM modes. +Some communication protocols support alternatives to CCM, which may +sometimes allow choosing the better API by avoiding CCM. +.Ss Configuration controls +The following two control commands can be issued as soon as +.Xr EVP_EncryptInit 3 +has been called with a CCM +.Fa type +and +.Dv NULL +pointers for +.Fa key +and +.Fa iv . +Both commands are optional and override each other. +If issued when a nonce is already set, they silently cause data corruption. +The +.Fa ptr +argument is ignored by both; passing +.Dv NULL +is recommended. +.Bl -tag -width Ds +.It Dv EVP_CTRL_CCM_SET_L +Set the size +.Ms L +of the length field to +.Fa arg +bytes and the size of the nonce to +.No 15 \- Fa arg +bytes. +By default, 8 bytes are used for the length field and 7 for the nonce. +Selecting a smaller size +.Ms L +for the length field reduces des maximum size of messages that can be sent, +but in return allows transmitting more messages with the same key. +It is an error to pass less than 2 or more than the default value of 8 for +.Fa arg . +.It Dv EVP_CTRL_AEAD_SET_IVLEN Pq == Dv EVP_CTRL_CCM_SET_IVLEN +Set the size of the nonce to +.Fa arg +bytes and the size +.Ms L +of the length field to +.No 15 \- Fa arg +bytes. +By default, 7 bytes are used for the nonce and 8 for the length field. +Selecting a larger size of the nonce allows transmitting more messages with +the same key at the expense of reducing the maximum size for each message. +It is an error to pass more than 13 or less than the default value of 7 for +.Fa arg . +.El +.Pp +After optionally issuing one of the above control commands, +.Xr EVP_EncryptInit 3 +can be called a second time, this time passing +.Dv NULL +for the +.Fa type +argument, with the other two arguments pointing to the desired AES key +and to the desired nonce. +.Ss Encryption controls +.Bl -tag -width Ds +.It Dv EVP_CTRL_AEAD_SET_TAG Pq == Dv EVP_CTRL_CCM_SET_TAG +If the +.Fa ptr +argument is +.Dv NULL , +set the tag length +.Ms M +to +.Fa arg +bytes. +The default value is 12. +Selecting a larger value makes tampering harder for an attacker, +at a small expense of making the messages slightly longer. +Selecting a smaller value is not recommended. +It is an error to pass an odd number for +.Fa arg , +or a number that is less than 4 or greater than 16, or to pass +.Dv NULL +to +.Fa ptr +when +.Fa ctx +is not configured for encrypting. +Issuing this control command when an encryption key is already configured +silently causes data corruption. +.It Dv EVP_CTRL_AEAD_GET_TAG Pq == Dv EVP_CTRL_CCM_GET_TAG +Store the +.Fa arg +bytes of the tag in the memory provided by the caller starting at +.Fa ptr . +It is an error to issue this control command when +.Fa ctx +is not configured for encrypting, when no data was encrypted yet, with an +.Fa arg +that does not match the configured tag length +.Ms M , +or when the tag has already been retrieved earlier. +.El +.Pp +Before passing any plaintext data to +.Xr EVP_EncryptUpdate 3 , +call +.Xr EVP_EncryptUpdate 3 +with both +.Fa in +and +.Fa out +set to +.Dv NULL , +passing the total plaintext length in bytes as +.Fa in_len . +This constructs the first block to be digested with CBC-MAC +and copies the text length to +.Pf * Fa out_len . +It does not check whether +.Fa in_len +exceeds the limit of +.Pf 256\(ha Ms L ; +the most significant bytes of excessive values are silently discarded. +.Pp +It is an error if the +.Fa in_len +argument of the +.Xr EVP_EncryptUpdate 3 +call passing the plaintext data does not match the total length +specified earlier. +Splitting the text into more than one chunks to be passed in multiple calls of +.Xr EVP_EncryptUpdate 3 +is not supported for CCM. +.Pp +To specify any additional authenticated data (AAD), call +.Xr EVP_EncryptUpdate 3 +with the +.Fa out +argument set to +.Dv NULL . +.Ss Decryption controls +.Bl -tag -width Ds +.It Dv EVP_CTRL_AEAD_SET_TAG Pq == Dv EVP_CTRL_CCM_SET_TAG +If the +.Fa ptr +argument is not +.Dv NULL , +copy +.Fa arg +bytes starting at +.Fa ptr +to the expected CCM tag value. +It is an error to pass an odd number for +.Fa arg , +or a number that is less than 4 or greater than 16. +Passing a number that does not correspond to the tag length +.Ms M +that was used for encryption does not raise an error right away, +but results in undefined behaviour +and typically causes subsequent authentication failure. +It is also an error to pass a +.Pf non- Dv NULL +.Fa ptr +when +.Fa ctx +is configured for encryption. +.El +.Pp +Before passing any ciphertext data to +.Xr EVP_DecryptUpdate 3 , +call +.Xr EVP_DecryptUpdate 3 +with both +.Fa in +and +.Fa out +set to +.Dv NULL , +passing the total ciphertext length in bytes as +.Fa in_len . +This constructs the first block to be digested with CBC-MAC +and copies the text length to +.Pf * Fa out_len . +It does not check whether +.Fa in_len +exceeds the limit of +.Pf 256\(ha Ms L ; +the most significant bytes of excessive values are silently discarded. +.Pp +It is an error if the +.Fa in_len +argument of the +.Xr EVP_DecryptUpdate 3 +call passing the ciphertext data does not match the total length +specified earlier. +Splitting the text into more than one chunks to be passed in multiple calls of +.Xr EVP_DecryptUpdate 3 +is not supported for CCM. +.Pp +To specify any additional authenticated data (AAD), call +.Xr EVP_DecryptUpdate 3 +with the +.Fa out +argument set to +.Dv NULL . +.Pp +If the return value of +.Xr EVP_DecryptUpdate 3 +does not indicate success, the authentication operation may have failed. +In that case, regard any output data as corrupted. +.Pp +Do not call +.Xr EVP_DecryptFinal 3 +when using CCM. +Such a call would not do anything useful, and it would fail +because the tag that was set with +.Dv EVP_CTRL_CCM_SET_TAG +was already consumed by +.Xr EVP_DecryptUpdate 3 . +.Sh RETURN VALUES +These functions return a static constant +.Vt EVP_CIPHER +structure that provides the implementation of the respective AEAD cipher mode. +.Sh EXAMPLES +The following code encrypts and digests some secret text +and some additional, public data with AES-CCM. +Specifically, it implements the Test Vector #1 +given in section 8 of RFC 3610. +.Bd -literal -offset indent +/* input data */ +const unsigned char key[] = { + 0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, + 0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF +}; +const unsigned char nonce[] = { + 0x00, 0x00, 0x00, 0x03, 0x02, 0x01, 0x00, 0xA0, + 0xA1, 0xA2, 0xA3, 0xA4, 0xA5 +}; +const int nonce_len = sizeof(nonce); +const int size_len = 15 - nonce_len; + +const unsigned char aad[] = { + 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07 +}; +const int aad_len = sizeof(aad); + +const unsigned char plaintext[] = { + 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, + 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, + 0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E +}; +const int text_len = sizeof(plaintext); + +/* expected output data */ +const unsigned char ciphertext[] = { + 0x58, 0x8C, 0x97, 0x9A, 0x61, 0xC6, 0x63, 0xD2, + 0xF0, 0x66, 0xD0, 0xC2, 0xC0, 0xF9, 0x89, 0x80, + 0x6D, 0x5F, 0x6B, 0x61, 0xDA, 0xC3, 0x84 +}; + +const unsigned char wanted_tag[] = { + 0x17, 0xE8, 0xD1, 0x2C, 0xFD, 0xF9, 0x26, 0xE0 +}; +const int tag_len = sizeof(wanted_tag); + +const int out_len = aad_len + text_len + tag_len; +unsigned char out_buf[out_len]; +unsigned char *out_p = out_buf; +unsigned char *out_end = out_buf + out_len; + +/* auxiliary variables */ +EVP_CIPHER_CTX *ctx; +int irv, i; + +/* configuration */ +ctx = EVP_CIPHER_CTX_new(); +if (ctx == NULL) + err(1, "EVP_CIPHER_CTX_new"); + +if (EVP_EncryptInit(ctx, EVP_aes_128_ccm(), NULL, NULL) != 1) + err(1, "EVP_EncryptInit(NULL)"); + +if (EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, + size_len, NULL) <= 0) + err(1, "EVP_CTRL_CCM_SET_L(%d)", size_len); + +if (EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, + tag_len, NULL) <= 0) + err(1, "EVP_CTRL_CCM_SET_TAG(%d)", tag_len); + +/* process input data */ +if (EVP_EncryptInit(ctx, NULL, key, nonce) != 1) + err(1, "EVP_EncryptInit(key, nonce)"); + +if (EVP_EncryptUpdate(ctx, NULL, &irv, NULL, text_len) != 1) + err(1, "EVP_EncryptUpdate(len = %d)", text_len); +if (irv != text_len) + errx(1, "text length: want %d, got %d", text_len, irv); + +irv = -1; +if (EVP_EncryptUpdate(ctx, NULL, &irv, aad, aad_len) != 1) + err(1, "EVP_EncryptUpdate(AAD)"); +memcpy(out_p, aad, aad_len); +out_p += aad_len; + +irv = -1; +if (EVP_EncryptUpdate(ctx, out_p, &irv, plaintext, text_len) != 1) + err(1, "EVP_EncryptUpdate(plaintext)"); +if (irv != text_len) + errx(1, "text_len: want %d, got %d", text_len, irv); +out_p += irv; + +/* + * EVP_EncryptFinal(3) doesn't really do anything for CCM. + * Call it anyway to stay closer to normal EVP_Encrypt*(3) idioms, + * to match what the OpenSSL Wiki suggests since 2013, and to ease + * later migration of the code to a different AEAD algorithm. + */ +irv = -1; +if (EVP_EncryptFinal(ctx, out_p, &irv) != 1) + err(1, "EVP_EncryptFinal"); +if (irv != 0) + errx(1, "final_len: want 0, got %d", irv); + +/* check output data */ +if (memcmp(out_buf + aad_len, ciphertext, text_len) != 0) + errx(1, "ciphertext mismatch"); + +if (EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_GET_TAG, + tag_len, out_p) <= 0) + err(1, "EVP_CTRL_CCM_GET_TAG"); +if (memcmp(out_p, wanted_tag, tag_len) != 0) + errx(1, "tag mismatch"); +out_p += tag_len; +if (out_p != out_end) + errx(1, "end of output: want %p, got %p", out_end, out_p); + +printf("Total packet length = %d.", out_len); +printf(" [Authenticated and Encrypted Output]"); +for (i = 0; i < out_len; i++) { + if (i % 16 == 0) + printf("\en "); + if (i % 4 == 0) + putchar(' '); + printf(" %02X", out_buf[i]); +} +putchar('\en'); + +EVP_CIPHER_CTX_free(ctx); +.Ed +.Pp +The reverse operation for the same test vector, +i.e. decrypting and comparing the digest, +is implemented by the following code. +.Pp +The variable declarations and definitions up to the call of +.Xr EVP_CIPHER_CTX_new 3 +are the same as above. +The chief differences are: +.Bl -dash -width 1n -compact +.It +The tag is not part of the output, +so the total output length is shorter. +.It +No +.Xr memcmp 3 +of the tag takes place. +Instead, the control command +.Dv EVP_CTRL_CCM_SET_TAG +requires the tag that is going to be verified as an additional argument. +.It +While +.Xr EVP_EncryptFinal 3 +is an optional no-op, +.Xr EVP_DecryptFinal 3 +is not called and would fail. +.El +.Bd -literal -offset indent +const int out_len = aad_len + text_len; + +/* configuration */ +ctx = EVP_CIPHER_CTX_new(); +if (ctx == NULL) + err(1, "EVP_CIPHER_CTX_new"); + +if (EVP_DecryptInit(ctx, EVP_aes_128_ccm(), NULL, NULL) != 1) + err(1, "EVP_DecryptInit(NULL)"); + +if (EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, size_len, NULL) <= 0) + err(1, "EVP_CTRL_CCM_SET_L(%d)", size_len); + +if (EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, + tag_len, (void *)wanted_tag) <= 0) + err(1, "EVP_CTRL_CCM_SET_TAG(%d)", tag_len); + +/* process input data */ +if (EVP_DecryptInit(ctx, NULL, key, nonce) != 1) + err(1, "EVP_DecryptInit(key, nonce)"); + +if (EVP_DecryptUpdate(ctx, NULL, &irv, NULL, text_len) != 1) + err(1, "EVP_DecryptUpdate(len = %d)", text_len); +if (irv != text_len) + errx(1, "text length: want %d, got %d", text_len, irv); + +irv = -1; +if (EVP_DecryptUpdate(ctx, NULL, &irv, aad, aad_len) != 1) + err(1, "EVP_DecryptUpdate(AAD)"); +memcpy(out_p, aad, aad_len); +out_p += aad_len; + +irv = -1; +if (EVP_DecryptUpdate(ctx, out_p, &irv, ciphertext, text_len) != 1) + err(1, "EVP_DecryptUpdate(ciphertext)"); +if (irv != text_len) + errx(1, "text_len: want %d, got %d", text_len, irv); +out_p += irv; + +/* Do not call EVP_DecryptFinal(3); it would fail and do nothing. */ + +/* check output data */ +if (memcmp(out_buf + aad_len, plaintext, text_len) != 0) + errx(1, "plaintext mismatch"); +if (out_p != out_end) + errx(1, "end of output: want %p, got %p", out_end, out_p); + +printf("Total packet length = %d.", out_len); +printf(" [Decrypted and Authenticated Input]"); +for (i = 0; i < out_len; i++) { + if (i % 16 == 0) + printf("\n "); + if (i % 4 == 0) + putchar(' '); + printf(" %02X", out_buf[i]); +} +putchar('\n'); + +EVP_CIPHER_CTX_free(ctx); +.Ed +.Sh SEE ALSO +.Xr AES_encrypt 3 , +.Xr evp 3 , +.Xr EVP_aes_128_cbc 3 , +.Xr EVP_aes_128_gcm 3 , +.Xr EVP_EncryptInit 3 +.Sh STANDARDS +.Rs +.%A Doug Whiting +.%A Russ Housley +.%A Niels Ferguson +.%T Counter with CBC-MAC (CCM) +.%R RFC 3610 +.%D September 2003 +.Re +.Sh HISTORY +.Fn EVP_aes_128_ccm , +.Fn EVP_aes_192_ccm , +and +.Fn EVP_aes_256_ccm +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/EVP_aes_128_gcm.3 b/static/openbsd/man3/EVP_aes_128_gcm.3 new file mode 100644 index 00000000..fa4a8861 --- /dev/null +++ b/static/openbsd/man3/EVP_aes_128_gcm.3 @@ -0,0 +1,255 @@ +.\" $OpenBSD: EVP_aes_128_gcm.3,v 1.3 2025/06/08 22:40:29 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100 +.\" OpenSSL EVP_aes.pod a1ec85c1 Apr 21 10:49:12 2020 +0100 +.\" +.\" Copyright (c) 2024 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. +.\" +.\" This file is a derived work containing a few sentences +.\" written by Dr. Stephen Henson +.\" covered by the following license: +.\" +.\" Copyright (c) 2012 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_AES_128_GCM 3 +.Os +.Sh NAME +.Nm EVP_aes_128_gcm , +.Nm EVP_aes_192_gcm , +.Nm EVP_aes_256_gcm +.Nd EVP AES cipher in Galois Counter Mode +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_gcm void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_gcm void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_gcm void +.Sh DESCRIPTION +.Fn EVP_aes_128_gcm , +.Fn EVP_aes_192_gcm , +and +.Fn EVP_aes_256_gcm +provide the Advanced Encryption Standard algorithm for 128, 192 and 256-bit +keys in and Galois Counter Mode in the +.Xr evp 3 +framework. +.Pp +For GCM mode ciphers, the behaviour of the EVP interface is subtly +altered and several additional +.Xr EVP_CIPHER_CTX_ctrl 3 +operations are required to function correctly. +Some of the +.Dv EVP_CTRL_GCM_* +control commands are older aliases for corresponding +.Dv EVP_CTRL_AEAD_* +constants as indicated below. +.Pp +To avoid using the cumbersome and error-prone API documented +in the present manual page, consider using the functions documented in +.Xr EVP_AEAD_CTX_init 3 +instead. +.Ss Configuration controls +.\" The following constants are intentionally undocumented +.\" because they are very rarely used in application programs: +.\" EVP_GCM_TLS_FIXED_IV_LEN (unused in the library) +.\" EVP_GCM_TLS_EXPLICIT_IV_LEN and EVP_GCM_TLS_TAG_LEN (used internally +.\" only in aes_gcm_tls_cipher(), which is unused) +.Bl -tag -width Ds +.It Dv EVP_CTRL_AEAD_SET_IVLEN Pq == Dv EVP_CTRL_GCM_SET_IVLEN +Set the length of the initialization vector to +.Fa arg +bytes; the +.Fa ptr +argument is ignored and passing +.Dv NULL +is recommended. +This call can only be made before specifying an initialization vector. +If not called, the default IV length of 12 bytes is used. +.Pp +Using this control command is discouraged because section 5.2.1.1 of the +specification explicitly recommends that implementations of GCM restrict +support to the default IV length of 12 bytes for interoperability, +efficiency, and simplicity of design. +.It Dv EVP_CTRL_AEAD_SET_IV_FIXED Pq == Dv EVP_CTRL_GCM_SET_IV_FIXED +Usually, \-1 is passed for +.Fa arg . +In that case, the complete initialization vector is copied from +.Fa ptr . +.Pp +Otherwise, set the fixed field at the beginning of the initialization +vector to the +.Fa arg +bytes pointed to by +.Fa ptr . +When encrypting, also generate the remaining bytes +of the initialization vector at random. +It is an error to specify an +.Fa arg +that is less than 4 or so large that less than 8 bytes remain. +.El +.Ss Encryption controls +.Bl -tag -width Ds +.It Dv EVP_CTRL_GCM_IV_GEN +Generate the precounter block from the initialization vector, +copy the last +.Fa arg +bytes of the initialization vector to the location pointed to by +.Fa ptr , +or all of it if +.Fa arg +is less than 1 or greater than the length of the initialization vector, +and increment the initialization vector by 1. +Incrementing ignores the IV length and the fixed field length +that may have been configured earlier and always operates on the +last eight bytes of the initialization vector. +It is an error to issue this command +when no key or no initialization vector is set. +.It Dv EVP_CTRL_AEAD_GET_TAG Pq == Dv EVP_CTRL_GCM_GET_TAG +Write +.Fa arg +bytes of the tag value to the location pointed to by +.Fa ptr . +This control command only makes sense after all data has been processed, +e.g. after calling +.Xr EVP_EncryptFinal 3 . +It is an error to issue this command while decrypting, +before any data has been processed, or to specify an +.Fa arg +that is less than 1 or greater than 16. +.El +.Pp +To specify any additional authenticated data (AAD), call +.Xr EVP_EncryptUpdate 3 +with the +.Fa out +argument set to +.Dv NULL . +.Ss Decryption controls +.Bl -tag -width Ds +.It Dv EVP_CTRL_GCM_SET_IV_INV +Copy +.Fa arg +bytes from +.Fa ptr +to the last bytes of the initialization vector +and generate the precounter block from the initialization vector. +The library does not check whether the arguments are consistent +with the configured initialization vector and fixed field lengths. +When default lengths are in use, pass 8 for +.Fa arg . +In that case, this control command sets the invocation field. +It is an error to issue this command +when no key or no initialization vector is set, or when encrypting. +.It Dv EVP_CTRL_AEAD_SET_TAG Pq == Dv EVP_CTRL_GCM_SET_TAG +Set the expected tag to the +.Fa arg +bytes located at +.Fa ptr . +This control command is mandatory before any data is processed, +e.g. before calling +.Xr EVP_DecryptUpdate 3 . +It is an error to issue this command while encrypting or to specify an +.Fa arg +that is less than 1 or greater than 16. +.El +.Pp +To specify any additional authenticated data (AAD), call +.Xr EVP_DecryptUpdate 3 +with the +.Fa out +argument set to +.Dv NULL . +.Pp +If the return value of +.Xr EVP_DecryptFinal 3 , +.Xr EVP_DecryptFinal_ex 3 , +.Xr EVP_CipherFinal 3 , +or +.Xr EVP_CipherFinal_ex 3 +does not indicate success when decrypting, +the authentication operation failed. +In that case, regard any output data as corrupted. +.Sh SEE ALSO +.Xr AES_encrypt 3 , +.Xr evp 3 , +.Xr EVP_AEAD_CTX_init 3 , +.Xr EVP_aes_128_cbc 3 , +.Xr EVP_CIPHER_CTX_ctrl 3 , +.Xr EVP_EncryptInit 3 +.Sh STANDARDS +.Rs +.%A Morris Dworkin +.%I National Institute of Standards and Technology +.%R Recommendation for Block Cipher Modes of Operation:\ + Galois/Counter Mode (GCM) and GMAC +.%N NIST Special Publication 800-38D +.%C Gaithersburg, Maryland +.%D November 2007 +.Re +.Sh HISTORY +.Fn EVP_aes_128_gcm , +.Fn EVP_aes_192_gcm , +and +.Fn EVP_aes_256_gcm +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/EVP_camellia_128_cbc.3 b/static/openbsd/man3/EVP_camellia_128_cbc.3 new file mode 100644 index 00000000..3ff5d5a0 --- /dev/null +++ b/static/openbsd/man3/EVP_camellia_128_cbc.3 @@ -0,0 +1,152 @@ +.\" $OpenBSD: EVP_camellia_128_cbc.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" selective merge up to: OpenSSL 7c6d372a Nov 20 13:20:01 2018 +0000 +.\" +.\" This file was written by Ronald Tse +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_CAMELLIA_128_CBC 3 +.Os +.Sh NAME +.Nm EVP_camellia_128_cbc , +.Nm EVP_camellia_192_cbc , +.Nm EVP_camellia_256_cbc , +.Nm EVP_camellia_128_cfb , +.Nm EVP_camellia_192_cfb , +.Nm EVP_camellia_256_cfb , +.Nm EVP_camellia_128_cfb1 , +.Nm EVP_camellia_192_cfb1 , +.Nm EVP_camellia_256_cfb1 , +.Nm EVP_camellia_128_cfb8 , +.Nm EVP_camellia_192_cfb8 , +.Nm EVP_camellia_256_cfb8 , +.Nm EVP_camellia_128_cfb128 , +.Nm EVP_camellia_192_cfb128 , +.Nm EVP_camellia_256_cfb128 , +.Nm EVP_camellia_128_ecb , +.Nm EVP_camellia_192_ecb , +.Nm EVP_camellia_256_ecb , +.Nm EVP_camellia_128_ofb , +.Nm EVP_camellia_192_ofb , +.Nm EVP_camellia_256_ofb +.Nd EVP Camellia cipher +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_camellia_128_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_192_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_256_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_128_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_192_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_256_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_128_cfb1 void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_192_cfb1 void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_256_cfb1 void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_128_cfb8 void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_192_cfb8 void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_256_cfb8 void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_128_cfb128 void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_192_cfb128 void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_256_cfb128 void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_128_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_192_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_256_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_128_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_192_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_camellia_256_ofb void +.Sh DESCRIPTION +These functions provide the Camellia encryption algorithm in the +.Xr evp 3 +framework. +Camellia is a block cipher operating on 128 bit blocks. +These functions use 128, 192, and 256-bit keys +in the following modes, respectively: +CBC, CFB with 1-bit shift, CFB with 8-bit shift, CFB with 128-bit shift, +ECB, and OFB. +.Pp +.Fn EVP_camellia_128_cfb , +.Fn EVP_camellia_192_cfb , +and +.Fn EVP_camellia_256_cfb +are aliases for +.Fn EVP_camellia_128_cfb128 , +.Fn EVP_camellia_192_cfb128 , +and +.Fn EVP_camellia_256_cfb128 , +implemented as macros. +.Sh RETURN VALUES +These functions return an +.Vt EVP_CIPHER +structure that provides the implementation of the symmetric cipher. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8c +and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/EVP_chacha20.3 b/static/openbsd/man3/EVP_chacha20.3 new file mode 100644 index 00000000..45584f3e --- /dev/null +++ b/static/openbsd/man3/EVP_chacha20.3 @@ -0,0 +1,293 @@ +.\" $OpenBSD: EVP_chacha20.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Ronald Tse . +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_CHACHA20 3 +.Os +.Sh NAME +.Nm EVP_chacha20 , +.Nm EVP_chacha20_poly1305 +.Nd ChaCha20 stream cipher for EVP +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_chacha20 void +.Ft const EVP_CIPHER * +.Fn EVP_chacha20_poly1305 void +.Sh DESCRIPTION +.Fn EVP_chacha20 +provides the ChaCha20 stream cipher in the EVP framework. +.Xr EVP_EncryptInit_ex 3 , +.Xr EVP_DecryptInit_ex 3 , +and +.Xr EVP_CipherInit_ex 3 +take a +.Fa key +argument of 32 bytes = 256 bits and an +.Fa iv +argument of 16 bytes = 128 bits, internally using +.Xr ChaCha_set_key 3 +and +.Xr ChaCha_set_iv 3 . +The lower 8 bytes = 64 bits of +.Fa iv +are used as counter and the remaining 8 bytes are used as +the initialization vector of +.Xr ChaCha_set_iv 3 . +.Xr EVP_EncryptUpdate 3 , +.Xr EVP_EncryptFinal_ex 3 , +.Xr EVP_DecryptUpdate 3 , +and +.Xr EVP_DecryptFinal_ex 3 +internally use +.Xr ChaCha 3 +to perform encryption and decryption. +.Xr EVP_CIPHER_CTX_ctrl 3 +always fails for +.Fa ctx +objects created from +.Fn EVP_chacha20 . +.Pp +.Fn EVP_chacha20_poly1305 +provides authenticated encryption with ChaCha20-Poly1305. +Unless compatibility with other implementations +like OpenSSL or BoringSSL is required, using +.Xr EVP_AEAD_CTX_init 3 +with +.Xr EVP_aead_chacha20_poly1305 3 +is recommended instead because the code then becomes transparent +to the AEAD cipher used, more flexible, and less error prone. +.Pp +With +.Fn EVP_chacha20_poly1305 , +.Xr EVP_EncryptInit_ex 3 , +.Xr EVP_DecryptInit_ex 3 , +and +.Xr EVP_CipherInit_ex 3 +take a +.Fa key +argument of 32 bytes = 256 bits and an +.Fa iv +argument of 12 bytes = 96 bits. +This supports additional authenticated data (AAD) and produces a 128-bit +authentication tag. +The constant +.Dv EVP_CHACHAPOLY_TLS_TAG_LEN +specifies the length of the authentication tag in bytes and has a value of 16. +.Pp +The following +.Fa type +arguments are supported for +.Xr EVP_CIPHER_CTX_ctrl 3 : +.Bl -tag -width Ds +.It Dv EVP_CTRL_AEAD_GET_TAG +Copy the number of bytes indicated by the +.Fa arg +argument from the tag to the location indicated by the +.Fa ptr +argument; +to be called after +.Xr EVP_EncryptFinal_ex 3 . +This control operation fails if the +.Fa ctx +is not configured for encryption or if +.Fa arg +is less than 1 or greater than 16. +.It Dv EVP_CTRL_AEAD_SET_TAG +Copy the number of bytes indicated by the +.Fa arg +argument from the location indicated by the +.Fa ptr +argument and designate them as the expected tag length and tag, +causing subsequent +.Xr EVP_DecryptFinal_ex 3 +to fail if the tag calculated during decryption does not match. +It is strongly recommended to specify +.Fa arg +as exactly 16. +Otherwise, only the initial part of the tag may be compared +and mismatches near the end of the tag may get silently ignored. +This control operation fails if the +.Fa ctx +is configured for encryption or if +.Fa arg +is less than 1 or greater than 16. +If the +.Fa ptr +argument is a +.Dv NULL +pointer, this control operation succeeds without having any effect. +.It Dv EVP_CTRL_AEAD_SET_IV_FIXED +Set the initialization vector by reading the 12 bytes pointed to by the +.Fa ptr +argument, independently of +.Xr EVP_EncryptInit_ex 3 , +.Xr EVP_DecryptInit_ex 3 , +and +.Xr EVP_CipherInit_ex 3 . +This control operation fails if the +.Fa arg +argument is not exactly 12. +.It Dv EVP_CTRL_AEAD_SET_IVLEN +Instruct subsequent +.Xr EVP_EncryptInit_ex 3 , +.Xr EVP_DecryptInit_ex 3 , +or +.Xr EVP_CipherInit_ex 3 +to expect an +.Fa iv +argument shorter than the default of 12 bytes; the +.Fa arg +argument specifies the number of bytes to be used. +The initialization functions will only read +the specified smaller number of bytes from +.Fa iv +and internally zero-pad them on the left. +Using this is not recommended because it is likely more fragile +and less often tested than the equivalent method of simply providing +a full-sized +.Fa iv . +This control operation fails if +.Fa arg +is less than 1 or greater than 16. +.It Dv EVP_CTRL_INIT +Set the length of the initialization vector to the default value +of 12 bytes and clear the Poly1305 internal state. +The application program usually does not need to invoke this control +operation manually because it is automatically called internally by +.Xr EVP_EncryptInit_ex 3 , +.Xr EVP_DecryptInit_ex 3 , +and +.Xr EVP_CipherInit_ex 3 . +.El +.Sh RETURN VALUES +.Fn EVP_chacha20 +and +.Fn EVP_chacha20_poly1305 +return pointers to static +.Vt EVP_CIPHER +objects that contain the implementations of the symmetric cipher. +.Pp +If +.Fa ctx +was created from +.Fn EVP_chacha20 +or +.Fn EVP_chacha20_poly1305 , +.Xr EVP_CIPHER_CTX_ctrl 3 +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr ChaCha 3 , +.Xr evp 3 , +.Xr EVP_aead_chacha20_poly1305 3 , +.Xr EVP_CIPHER_meth_new 3 , +.Xr EVP_EncryptInit 3 +.Sh STANDARDS +.Rs +.%A A. Langley +.%A W. Chang +.%A N. Mavrogiannopoulos +.%A J. Strombergson +.%A S. Josefsson +.%D June 2016 +.%R RFC 7905 +.%T ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS) +.Re +.Sh HISTORY +.Fn EVP_chacha20 +first appeared in +.Ox 5.6 . +.Pp +.Fn EVP_chacha20_poly1305 +first appeared in OpenSSL 1.1.0 +.\" OpenSSL commit bd989745 Dec 9 21:30:56 2015 +0100 Andy Polyakov +and has been available since +.Ox 7.2 . +.Sh CAVEATS +The original publications and code by +.An Adam Langley +used a modified AEAD construction that is incompatible with the common +style used by AEAD in TLS and incompatible with RFC 7905: +.Pp +.Rs +.%A A. Langley +.%A W. Chang +.%D November 2013 +.%R draft-agl-tls-chacha20poly1305-04 +.%T ChaCha20 and Poly1305 based Cipher Suites for TLS +.Re +.Pp +.Rs +.%A Y. Nir +.%A A. Langley +.%D May 2018 +.%R RFC 8439 +.%T ChaCha20 and Poly1305 for IETF Protocols +.Re +.Pp +In particular, the original version used a nonce of 8 instead of 12 bytes. diff --git a/static/openbsd/man3/EVP_des_cbc.3 b/static/openbsd/man3/EVP_des_cbc.3 new file mode 100644 index 00000000..84ee9aaa --- /dev/null +++ b/static/openbsd/man3/EVP_des_cbc.3 @@ -0,0 +1,231 @@ +.\" $OpenBSD: EVP_des_cbc.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL EVP_desx_cbc.pod 8fa4d95e Oct 21 11:59:09 2017 +0900 +.\" selective merge up to: +.\" OpenSSL EVP_des.pod 7c6d372a Nov 20 13:20:01 2018 +0000 +.\" +.\" This file was written by Ronald Tse +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_DES_CBC 3 +.Os +.Sh NAME +.Nm EVP_des_cbc , +.Nm EVP_des_cfb , +.Nm EVP_des_cfb1 , +.Nm EVP_des_cfb8 , +.Nm EVP_des_cfb64 , +.Nm EVP_des_ecb , +.Nm EVP_des_ofb , +.Nm EVP_des_ede , +.Nm EVP_des_ede_cbc , +.Nm EVP_des_ede_cfb , +.Nm EVP_des_ede_cfb64 , +.Nm EVP_des_ede_ecb , +.Nm EVP_des_ede_ofb , +.Nm EVP_des_ede3 , +.Nm EVP_des_ede3_cbc , +.Nm EVP_des_ede3_cfb , +.Nm EVP_des_ede3_cfb1 , +.Nm EVP_des_ede3_cfb8 , +.Nm EVP_des_ede3_cfb64 , +.Nm EVP_des_ede3_ecb , +.Nm EVP_des_ede3_ofb , +.Nm EVP_desx_cbc +.Nd EVP DES cipher +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_des_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_des_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_des_cfb1 void +.Ft const EVP_CIPHER * +.Fn EVP_des_cfb8 void +.Ft const EVP_CIPHER * +.Fn EVP_des_cfb64 void +.Ft const EVP_CIPHER * +.Fn EVP_des_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_des_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede_cfb64 void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede3 void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede3_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede3_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede3_cfb1 void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede3_cfb8 void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede3_cfb64 void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede3_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_des_ede3_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_desx_cbc void +.Sh DESCRIPTION +These functions provide the DES encryption algorithm in the +.Xr evp 3 +framework. +DES is a block cipher operating on 64 bit blocks. +The key length to be used for +.Xr EVP_EncryptInit 3 +is 64 bits. +However, only 56 of these bits are used in the encryption algorithm. +The least significant bit in each of the eight bytes is only used +for checking parity. +Using this algorithm is discouraged because the short key length +makes it vulnerable to brute force attacks. +.Pp +.Fn EVP_des_cbc , +.Fn EVP_des_cfb1 , +.Fn EVP_des_cfb8 , +.Fn EVP_des_cfb64 , +.Fn EVP_des_ecb , +and +.Fn EVP_des_ofb +provide DES in CBC, CFB with 1-bit shift, CFB with 8-bit shift, +CFB with 64-bit shift, ECB, and OFB modes. +.Fn EVP_des_cfb +is an alias for +.Fn EVP_des_cfb64 , +implemented as a macro. +.Pp +.Fn EVP_des_ede_cbc , +.Fn EVP_des_ede_cfb64 , +.Fn EVP_des_ede_ecb , +and +.Fn EVP_des_ede_ofb +provide two key triple DES in CBC, CFB with 64-bit shift, ECB, and OFB modes. +.Fn EVP_des_ede_cfb +is an alias for +.Fn EVP_des_ede_cfb64 , +implemented as a macro. +.Fn EVP_des_ede +is an alias for +.Fn EVP_des_ede_ecb . +.Pp +.Fn EVP_des_ede3_cbc , +.Fn EVP_des_ede3_cfb1 , +.Fn EVP_des_ede3_cfb8 , +.Fn EVP_des_ede3_cfb64 , +.Fn EVP_des_ede3_ecb , +.Fn EVP_des_ede3_ofb +provide three key triple DES in CBC, CFB with 1-bit shift, CFB with 8-bit +shift, CFB with 64-bit shift, ECB, and OFB modes. +.Fn EVP_des_ede3_cfb +is an alias for +.Fn EVP_des_ede3_cfb64 , +implemented as a macro. +.Fn EVP_des_ede3 +is an alias for +.Fn EVP_des_ede3_ecb . +.Pp +.Fn EVP_desx_cbc +provides the DES-X encryption algorithm in CBC mode. +It uses a key length of 128 bits and acts on blocks of 128 bits. +.Sh RETURN VALUES +These functions return an +.Vt EVP_CIPHER +structure that provides the implementation of the symmetric cipher. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn EVP_des_cbc , +.Fn EVP_des_cfb , +.Fn EVP_des_ecb , +.Fn EVP_des_ofb , +.Fn EVP_des_ede , +.Fn EVP_des_ede_cbc , +.Fn EVP_des_ede_cfb , +.Fn EVP_des_ede_ofb , +.Fn EVP_des_ede3 , +.Fn EVP_des_ede3_cbc , +.Fn EVP_des_ede3_cfb , +and +.Fn EVP_des_ede3_ofb +first appeared in SSLeay 0.5.1. +.Fn EVP_desx_cbc +first appeared in SSLeay 0.6.2. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_des_ede_ecb +and +.Fn EVP_des_ede3_ecb +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EVP_des_cfb1 , +.Fn EVP_des_cfb8 , +.Fn EVP_des_cfb64 , +.Fn EVP_des_ede_cfb64 , +.Fn EVP_des_ede3_cfb1 , +.Fn EVP_des_ede3_cfb8 , +and +.Fn EVP_des_ede3_cfb64 +first appeared in OpenSSL 0.9.7e and have been available since +.Ox 3.8 . diff --git a/static/openbsd/man3/EVP_rc2_cbc.3 b/static/openbsd/man3/EVP_rc2_cbc.3 new file mode 100644 index 00000000..9a3bc293 --- /dev/null +++ b/static/openbsd/man3/EVP_rc2_cbc.3 @@ -0,0 +1,202 @@ +.\" $OpenBSD: EVP_rc2_cbc.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2024 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 $Mdocdate: June 8 2025 $ +.Dt EVP_RC2_CBC 3 +.Os +.Sh NAME +.Nm EVP_rc2_cbc , +.Nm EVP_rc2_ecb , +.Nm EVP_rc2_cfb64 , +.Nm EVP_rc2_cfb , +.Nm EVP_rc2_ofb , +.Nm EVP_rc2_40_cbc , +.Nm EVP_rc2_64_cbc +.Nd Rivest Cipher 2 in the EVP framework +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_rc2_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_cfb64 void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_40_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_rc2_64_cbc void +.In openssl/rc2.h +.Fd #define RC2_BLOCK 8 +.Fd #define RC2_KEY_LENGTH 16 +.Sh DESCRIPTION +RC2 is a block cipher operating on blocks of +.Dv RC2_BLOCK No = 8 +bytes, equivalent to 64 bits, using a variable +.Fa key +length with an additional parameter called +.Dq effective key bits +or +.Dq effective key length . +.Pp +.Fn EVP_rc2_cbc , +.Fn EVP_rc2_ecb , +.Fn EVP_rc2_cfb64 , +and +.Fn EVP_rc2_ofb +provide the RC2 encryption algorithm in CBC, ECB, CFB and OFB mode, +respectively. +.Fn EVP_rc2_cfb +is an alias for +.Fn EVP_rc2_cfb64 , +implemented as a macro. +.Pp +By default, these functions set both the key length +and the effective key length to +.Dv RC2_KEY_LENGTH No = 16 +bytes, which is not a very useful value because it is quite short. +.Pp +Configuring normally requires a multi-step process: +.Bl -enum -width 2n +.It +Create a new, empty +.Vt EVP_CIPHER_CTX +object with +.Xr EVP_CIPHER_CTX_new 3 . +.It +Select the operation mode by calling +.Xr EVP_EncryptInit 3 +with the desired +.Fa type +argument, passing +.Dv NULL +pointers for the +.Fa key +and +.Fa iv +arguments. +.It +Select the +.Fa key +length by passing the desired number of bytes to +.Xr EVP_CIPHER_CTX_set_key_length 3 . +Doing so overrides the default key length of +.Dv RC2_KEY_LENGTH No = 16 . +Valid values for +.Fa keylen +are positive and less than or equal to 128. +.It +Select the effective key length by calling +.Xr EVP_CIPHER_CTX_ctrl 3 +with a +.Fa type +argument of +.Dv EVP_CTRL_SET_RC2_KEY_BITS , +passing the desired number of bits in +.Fa arg . +Doing so overrides the default effective key length of 128 bits. +Valid values for +.Fa arg +are positive and less than or equal to 1024. +The +.Fa ptr +argument is ignored; passing +.Dv NULL +is recommended. +.It +Call +.Xr EVP_EncryptInit 3 +a second time, this time passing +.Dv NULL +for the type argument. +The +.Fa key +argument points to an array containing the number of bytes that was passed to +.Xr EVP_CIPHER_CTX_set_key_length 3 , +and the +.Fa iv +argument points to an array of eight bytes. +.It +Finally, +.Xr EVP_EncryptUpdate 3 +and +.Xr EVP_EncryptFinal 3 +can be used in the normal way. +.El +.Pp +Once a +.Fa ctx +object is fully configured, calling +.Xr EVP_CIPHER_CTX_ctrl 3 +with a +.Fa type +argument of +.Dv EVP_CTRL_GET_RC2_KEY_BITS +interprets +.Fa ptr +as a pointer to +.Vt int +and stores the effective key length in bits at that location. +In this case, +.Fa arg +is ignored and passing 0 is recommended. +.Pp +In the CFB and OFB modes, the minimum required total length in bytes +of the output buffer is equal to the total number of input bytes to +be encoded. +In the CBC and ECB modes, the minimum required total length +of the output buffer has to be rounded up to the next multiple +of the block size of eight bytes. +.Pp +.Fn EVP_rc2_40_cbc +and +.Fn EVP_rc2_64_cbc +are obsolete functions that provide the RC2 algorithm in CBC mode +with a key length and an effective key length of 40 and 64 bits, +respectively. +.Sh RETURN VALUES +With the +.Vt EVP_CIPHER +objects documented in the present manual page, +.Fn EVP_CIPHER_CTX_ctrl +returns 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_CIPHER_CTX_set_key_length 3 , +.Xr EVP_EncryptInit 3 , +.Xr RC2_encrypt 3 +.Sh HISTORY +.Fn EVP_rc2_cbc , +.Fn EVP_rc2_ecb , +.Fn EVP_rc2_cfb , +and +.Fn EVP_rc2_ofb +first appeared in SSLeay 0.5.2 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_rc2_40_cbc +and +.Fn EVP_rc2_64_cbc +first appeared in SSLeay 0.9.1 and have been available since +.Ox 2.6 . +.Pp +.Fn EVP_rc2_cfb64 +first appeared in OpenSSL 0.9.7e and has been available since +.Ox 3.8 . diff --git a/static/openbsd/man3/EVP_rc4.3 b/static/openbsd/man3/EVP_rc4.3 new file mode 100644 index 00000000..40dd27e4 --- /dev/null +++ b/static/openbsd/man3/EVP_rc4.3 @@ -0,0 +1,110 @@ +.\" $OpenBSD: EVP_rc4.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 8fa4d95e Oct 21 11:59:09 2017 +0900 +.\" +.\" This file was written by Ronald Tse +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_RC4 3 +.Os +.Sh NAME +.Nm EVP_rc4 , +.Nm EVP_rc4_40 , +.Nm EVP_rc4_hmac_md5 +.Nd EVP RC4 stream cipher +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_rc4 void +.Ft const EVP_CIPHER * +.Fn EVP_rc4_40 void +.Ft const EVP_CIPHER * +.Fn EVP_rc4_hmac_md5 void +.Sh DESCRIPTION +These functions provide the RC4 stream cipher in the +.Xr evp 3 +framework. +It is a variable key length cipher. +.Pp +.Fn EVP_rc4 +uses a default key length of 128 bits. +.Pp +.Fn EVP_rc4_40 +uses a key length of 40 bits instead. +This function is deprecated. +Use +.Fn EVP_rc4 +and +.Xr EVP_CIPHER_CTX_set_key_length 3 +instead. +.Pp +.Fn EVP_rc4_hmac_md5 +provides authenticated encryption with the RC4 stream cipher +with MD5 as HMAC. +This function is not intended for usage outside of TLS +and requires calling of some undocumented control functions. +It does not conform to the EVP AEAD interface. +.Sh RETURN VALUES +These functions return an +.Vt EVP_CIPHER +structure that provides the implementation of the symmetric cipher. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn EVP_rc4 +first appeared in SSLeay 0.5.1 +and +.Fn EVP_rc4_40 +in OpenSSL 0.9.1. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_rc4_hmac_md5 +first appeared in OpenSSL 1.0.1 and has been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/EVP_sha1.3 b/static/openbsd/man3/EVP_sha1.3 new file mode 100644 index 00000000..d1e336cc --- /dev/null +++ b/static/openbsd/man3/EVP_sha1.3 @@ -0,0 +1,121 @@ +.\" $OpenBSD: EVP_sha1.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2023 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 $Mdocdate: June 8 2025 $ +.Dt EVP_SHA1 3 +.Os +.Sh NAME +.Nm EVP_sha1 , +.Nm EVP_md5 , +.Nm EVP_md5_sha1 , +.Nm EVP_md4 +.Nd legacy message digest algorithms +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_MD * +.Fn EVP_sha1 void +.Ft const EVP_MD * +.Fn EVP_md5 void +.Ft const EVP_MD * +.Fn EVP_md5_sha1 void +.Ft const EVP_MD * +.Fn EVP_md4 void +.Sh DESCRIPTION +The following message digest algorithms are cryptographically broken. +None of them should be used in new code unless there is no way around it. +.Pp +.Fn EVP_sha1 +implements the SHA-1 algorithm and produces 160 bits of output +from a given input. +Examples of protocols and software still requiring it +include OCSP, DNS, and the +.Sy git +version control system. +.Pp +.Fn EVP_md5 +implements the MD5 algorithm and produces 128 bits of output +from a given input. +It is still occasionally used when no security is required +but a fast hash algorithm is beneficial. +.Pp +.Fn EVP_md5_sha1 +produces concatenated MD5 and SHA-1 message digests. +Do not use this except where it is required for the historic SSLv3 protocol. +.Pp +.Fn EVP_md4 +implements the MD4 algorithm and produces 128 bits of output +from a given input. +It has been marked as +.Dq historic +by the Internet Engineering Task Force since 2011. +.Sh RETURN VALUES +These functions return pointers to static +.Vt EVP_MD +objects implementing the hash functions. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 +.Sh STANDARDS +.Rs +.%A T. Polk +.%A L. Chen +.%A S. Turner +.%A P. Hoffman +.%T Security Considerations for the SHA-0 and SHA-1 Message-Digest Algorithms +.%R RFC 6194 +.%D March 2011 +.Re +.Pp +.Rs +.%A S. Turner +.%A L. Chen +.%T Updated Security Considerations for the MD5 Message-Digest\ + and the HMAC-MD5 Algorithms +.%R RFC 6151 +.%D March 2011 +.Re +.Pp +.Rs +.%A S. Turner +.%A L. Chen +.%T MD4 to Historic Status +.%R RFC 6150 +.%D March 2011 +.Re +.Pp +.Rs +.%A P. Kocher +.%A P. Karlton +.%A A. Freier +.%T The Secure Sockets Layer (SSL) Protocol Version 3.0 +.%R RFC 6101 +.%D August 2011 +.Re +.Sh HISTORY +.Fn EVP_sha1 +and +.Fn EVP_md5 +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_md4 +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Pp +.Fn EVP_md5_sha1 +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/EVP_sha3_224.3 b/static/openbsd/man3/EVP_sha3_224.3 new file mode 100644 index 00000000..19a91148 --- /dev/null +++ b/static/openbsd/man3/EVP_sha3_224.3 @@ -0,0 +1,92 @@ +.\" $OpenBSD: EVP_sha3_224.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" selective merge up to: OpenSSL bbda8ce9 Oct 31 15:43:01 2017 +0800 +.\" +.\" This file was written by Ronald Tse . +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_SHA3_224 3 +.Os +.Sh NAME +.Nm EVP_sha3_224 , +.Nm EVP_sha3_256 , +.Nm EVP_sha3_384 , +.Nm EVP_sha3_512 +.Nd Secure Hash Algorithm 3 for EVP +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_MD * +.Fn EVP_sha3_224 void +.Ft const EVP_MD * +.Fn EVP_sha3_256 void +.Ft const EVP_MD * +.Fn EVP_sha3_384 void +.Ft const EVP_MD * +.Fn EVP_sha3_512 void +.Sh 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. +.Pp +.Fn EVP_sha3_224 , +.Fn EVP_sha3_256 , +.Fn EVP_sha3_384 , +and +.Fn EVP_sha3_512 +implement the SHA3-224, SHA3-256, SHA3-384, and SHA3-512 algorithms +and produce 224, 256, 384 and 512 bits of output from a given input, +respectively. +.Sh RETURN VALUES +These functions return pointers to static +.Vt EVP_MD +objects implementing the hash functions. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 +.Sh STANDARDS +NIST FIPS 202 diff --git a/static/openbsd/man3/EVP_sm3.3 b/static/openbsd/man3/EVP_sm3.3 new file mode 100644 index 00000000..33621bef --- /dev/null +++ b/static/openbsd/man3/EVP_sm3.3 @@ -0,0 +1,83 @@ +.\" $OpenBSD: EVP_sm3.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 21ebd2fc Aug 24 20:38:04 2018 +0800 +.\" +.\" This file was written by Jack Lloyd +.\" and Ronald Tse . +.\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. +.\" Copyright (c) 2017 Ribose 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 acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt EVP_SM3 3 +.Os +.Sh NAME +.Nm EVP_sm3 +.Nd SM3 hash function for EVP +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_MD * +.Fn EVP_sm3 void +.Sh DESCRIPTION +SM3 is a cryptographic hash function with a 256-bit output. +It is part of the Chinese +.Dq Commercial Cryptography +suite of algorithms which is required +for certain commercial applications in China. +.Sh RETURN VALUES +.Fn EVP_sm3 +returns a pointer to a static +.Vt EVP_MD +object implementing the SM3 hash function. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 +.Sh STANDARDS +GB/T 32905-2016 and GM/T 0004-2012 +.Sh HISTORY +.Fn EVP_sm3 +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 6.5 . diff --git a/static/openbsd/man3/EVP_sm4_cbc.3 b/static/openbsd/man3/EVP_sm4_cbc.3 new file mode 100644 index 00000000..eba31aff --- /dev/null +++ b/static/openbsd/man3/EVP_sm4_cbc.3 @@ -0,0 +1,83 @@ +.\" $OpenBSD: EVP_sm4_cbc.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 87103969 Oct 1 14:11:57 2018 -0700 +.\" +.\" Copyright (c) 2017 Ribose Inc +.\" Copyright (c) 2019 Ingo Schwarze +.\" The original version of this file +.\" was written by Ronald Tse . +.\" +.\" 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 THE AUTHORS DISCLAIM ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS 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: June 8 2025 $ +.Dt EVP_SM4_CBC 3 +.Os +.Sh NAME +.Nm EVP_sm4_cbc , +.Nm EVP_sm4_ecb , +.Nm EVP_sm4_cfb , +.Nm EVP_sm4_cfb128 , +.Nm EVP_sm4_ofb , +.Nm EVP_sm4_ctr +.Nd EVP SM4 cipher +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_sm4_cbc void +.Ft const EVP_CIPHER * +.Fn EVP_sm4_ecb void +.Ft const EVP_CIPHER * +.Fn EVP_sm4_cfb void +.Ft const EVP_CIPHER * +.Fn EVP_sm4_cfb128 void +.Ft const EVP_CIPHER * +.Fn EVP_sm4_ofb void +.Ft const EVP_CIPHER * +.Fn EVP_sm4_ctr void +.Sh DESCRIPTION +These functions provide the SM4 blockcipher in the +.Xr evp 3 +framework. +.Pp +All modes use a key length of 128 bits and act on blocks of 128 +bits. +.Pp +.Fn EVP_sm4_cfb +is an alias for +.Fn EVP_sm4_cfb128 , +implemented as a macro. +.Pp +With an argument of +.Qq sm4 +or +.Qq SM4 , +.Xr EVP_get_cipherbyname 3 +returns +.Fn EVP_sm4_cbc . +.Sh RETURN VALUES +These functions return an +.Vt EVP_CIPHER +structure that provides the implementation of the symmetric cipher. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 +.Sh STANDARDS +.Rs +.%T Information security technology - SM4 block cipher algorithm +.%I National Standards of People's Republic of China +.%N GB/T 32907-2016 +.%D August 29, 2016 +.Re +.Sh HISTORY +These functions appeared in OpenSSL 1.1.1 and have been available since +.Ox 6.5 . diff --git a/static/openbsd/man3/EXTENDED_KEY_USAGE_new.3 b/static/openbsd/man3/EXTENDED_KEY_USAGE_new.3 new file mode 100644 index 00000000..3258c979 --- /dev/null +++ b/static/openbsd/man3/EXTENDED_KEY_USAGE_new.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: EXTENDED_KEY_USAGE_new.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt EXTENDED_KEY_USAGE_NEW 3 +.Os +.Sh NAME +.Nm EXTENDED_KEY_USAGE_new , +.Nm EXTENDED_KEY_USAGE_free +.Nd X.509 key usage restrictions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft EXTENDED_KEY_USAGE +.Fn EXTENDED_KEY_USAGE_new void +.Ft void +.Fn EXTENDED_KEY_USAGE_free "EXTENDED_KEY_USAGE *eku" +.Sh DESCRIPTION +By using the key usage extension, the extended key usage extension, +or both of them, +.Vt X509 +end entity certificates may indicate that the key contained in them +is only intended to be used for the specified purposes. +If both extensions are present, only uses compatible with both +extensions are intended. +.Pp +.Fn EXTENDED_KEY_USAGE_new +allocates and initializes an empty +.Vt EXTENDED_KEY_USAGE +object, which is a +.Vt STACK_OF(ASN1_OBJECT) +and represents an ASN.1 +.Vt ExtKeyUsageSyntax +structure defined in RFC 5280 section 4.2.1.12. +It can hold key purpose identifiers. +.Pp +.Fn EXTENDED_KEY_USAGE_free +frees +.Fa eku . +.Pp +The key usage extension uses the ASN.1 BIT STRING data type +and doesn't require any dedicated object. +.Sh RETURN VALUES +.Fn EXTENDED_KEY_USAGE_new +returns the new +.Vt EXTENDED_KEY_USAGE +object or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr BASIC_CONSTRAINTS_new 3 , +.Xr d2i_EXTENDED_KEY_USAGE 3 , +.Xr POLICYINFO_new 3 , +.Xr X509_check_purpose 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_get_extension_flags 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile: +.Bl -dash -compact +.It +section 4.2.1.3: Key Usage +.It +section 4.2.1.12: Extended Key Usage +.El +.Sh HISTORY +.Fn EXTENDED_KEY_USAGE_new +and +.Fn EXTENDED_KEY_USAGE_free +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/GENERAL_NAME_new.3 b/static/openbsd/man3/GENERAL_NAME_new.3 new file mode 100644 index 00000000..84ad2edb --- /dev/null +++ b/static/openbsd/man3/GENERAL_NAME_new.3 @@ -0,0 +1,166 @@ +.\" $OpenBSD: GENERAL_NAME_new.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt GENERAL_NAME_NEW 3 +.Os +.Sh NAME +.Nm GENERAL_NAME_new , +.Nm GENERAL_NAME_free , +.Nm GENERAL_NAMES_new , +.Nm GENERAL_NAMES_free , +.Nm EDIPARTYNAME_new , +.Nm EDIPARTYNAME_free , +.Nm OTHERNAME_new , +.Nm OTHERNAME_free +.Nd names for use in X.509 extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft GENERAL_NAME * +.Fn GENERAL_NAME_new void +.Ft void +.Fn GENERAL_NAME_free "GENERAL_NAME *name" +.Ft GENERAL_NAMES * +.Fn GENERAL_NAMES_new void +.Ft void +.Fn GENERAL_NAMES_free "GENERAL_NAMES *names" +.Ft EDIPARTYNAME * +.Fn EDIPARTYNAME_new void +.Ft void +.Fn EDIPARTYNAME_free "EDIPARTYNAME *name" +.Ft OTHERNAME * +.Fn OTHERNAME_new void +.Ft void +.Fn OTHERNAME_free "OTHERNAME *name" +.Sh DESCRIPTION +Even though the X.501 +.Vt Name +documented in +.Xr X509_NAME_new 3 +is a complicated multi-layered structure, it is very rigid and not +flexible enough to represent various entities that many people want +to use as names in certificates. +For that reason, X.509 extensions use the X.509 +.Vt GeneralName +wrapper structure rather than using the X.501 +.Vt Name +structure directly, at the expense of adding one or two additional +layers of indirection. +.Pp +.Fn GENERAL_NAME_new +allocates and initializes an empty +.Vt GENERAL_NAME +object, representing the ASN.1 +.Vt GeneralName +structure defined in RFC 5280 section 4.2.1.6. +It can for example hold an +.Vt X509_name +object, an IP address, a DNS host name, a uniform resource identifier, +an email address, or an +.Vt EDIPARTYNAME +or +.Vt OTHERNAME +object described below. +.Fn GENERAL_NAME_free +frees +.Fa name . +.Pp +.Fn GENERAL_NAMES_new +allocates and initializes an empty +.Vt GENERAL_NAMES +object, which is a +.Vt STACK_OF(GENERAL_NAME) +and represents the ASN.1 +.Vt GeneralNames +structure defined in RFC 5280 section 4.2.1.6. +It is used by extension structures that can contain multiple names, +for example key identifier, alternative name, and distribution point +extensions. +.Fn GENERAL_NAMES_free +frees +.Fa names . +.Pp +.Fn EDIPARTYNAME_new +allocates and initializes an empty +.Vt EDIPARTYNAME +object, representing the ASN.1 +.Vt EDIPartyName +structure defined in RFC 5280 section 4.2.1.6, where +.Dq EDI +stands for +.Dq electronic data identifier . +It can hold two strings, the name itself and the name of the authority +that assigned that name. +.Fn EDIPARTYNAME_free +frees +.Fa name . +.Pp +.Fn OTHERNAME_new +allocates and initializes an empty +.Vt OTHERNAME +object, representing the ASN.1 +.Vt OtherName +structure defined in RFC 5280 section 4.2.1.6. +It can hold data of any +.Vt ASN1_TYPE +together with a type identifier. +.Fn OTHERNAME_free +frees +.Fa name . +.Sh RETURN VALUES +.Fn GENERAL_NAME_new , +.Fn GENERAL_NAMES_new , +.Fn EDIPARTYNAME_new , +and +.Fn OTHERNAME_new +return a new +.Vt GENERAL_NAME , +.Vt GENERAL_NAMES , +.Vt EDIPARTYNAME , +or +.Vt OTHERNAME +object or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_GENERAL_NAME 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_NAME_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 4.2: Certificate Extensions +.Sh HISTORY +.Fn GENERAL_NAME_new , +.Fn GENERAL_NAME_free , +.Fn GENERAL_NAMES_new , +and +.Fn GENERAL_NAMES_free +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . +.Pp +.Fn OTHERNAME_new +and +.Fn OTHERNAME_free +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn EDIPARTYNAME_new +and +.Fn EDIPARTYNAME_free +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/HMAC.3 b/static/openbsd/man3/HMAC.3 new file mode 100644 index 00000000..0b9e24a7 --- /dev/null +++ b/static/openbsd/man3/HMAC.3 @@ -0,0 +1,325 @@ +.\" $OpenBSD: HMAC.3,v 1.24 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL crypto/hmac a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" selective merge up to: OpenSSL man3/HMAC b3696a55 Sep 2 09:35:50 2017 -0400 +.\" +.\" This file was written by Ulf Moeller , +.\" Richard Levitte , and +.\" Matt Caswell . +.\" Copyright (c) 2000-2002, 2006, 2008, 2009, 2013, 2015, 2016 +.\" The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt HMAC 3 +.Os +.Sh NAME +.Nm HMAC , +.Nm HMAC_CTX_new , +.Nm HMAC_CTX_reset , +.Nm HMAC_CTX_free , +.Nm HMAC_Init_ex , +.Nm HMAC_Update , +.Nm HMAC_Final , +.Nm HMAC_CTX_copy , +.Nm HMAC_CTX_set_flags , +.Nm HMAC_CTX_get_md , +.Nm HMAC_size +.Nd HMAC message authentication code +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/hmac.h +.Ft unsigned char * +.Fo HMAC +.Fa "const EVP_MD *evp_md" +.Fa "const void *key" +.Fa "int key_len" +.Fa "const unsigned char *d" +.Fa "size_t n" +.Fa "unsigned char *md" +.Fa "unsigned int *md_len" +.Fc +.Ft HMAC_CTX * +.Fn HMAC_CTX_new void +.Ft int +.Fo HMAC_CTX_reset +.Fa "HMAC_CTX *ctx" +.Fc +.Ft void +.Fo HMAC_CTX_free +.Fa "HMAC_CTX *ctx" +.Fc +.Ft int +.Fo HMAC_Init_ex +.Fa "HMAC_CTX *ctx" +.Fa "const void *key" +.Fa "int key_len" +.Fa "const EVP_MD *md" +.Fa "ENGINE *engine" +.Fc +.Ft int +.Fo HMAC_Update +.Fa "HMAC_CTX *ctx" +.Fa "const unsigned char *data" +.Fa "size_t len" +.Fc +.Ft int +.Fo HMAC_Final +.Fa "HMAC_CTX *ctx" +.Fa "unsigned char *md" +.Fa "unsigned int *len" +.Fc +.Ft int +.Fo HMAC_CTX_copy +.Fa "HMAC_CTX *dctx" +.Fa "HMAC_CTX *sctx" +.Fc +.Ft void +.Fo HMAC_CTX_set_flags +.Fa "HMAC_CTX *ctx" +.Fa "unsigned long flags" +.Fc +.Ft const EVP_MD * +.Fo HMAC_CTX_get_md +.Fa "const HMAC_CTX *ctx" +.Fc +.Ft size_t +.Fo HMAC_size +.Fa "const HMAC_CTX *e" +.Fc +.Sh 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 +.Fn HMAC +computes the message authentication code of the +.Fa n +bytes at +.Fa d +using the hash function +.Fa evp_md +and the key +.Fa key +which is +.Fa key_len +bytes long. +.Pp +It places the result in +.Fa md , +which must have space for the output of the hash function, which is no +more than +.Dv EVP_MAX_MD_SIZE +bytes. +The size of the output is placed in +.Fa md_len , +unless it is +.Dv NULL . +.Pp +.Fa evp_md +can be +.Xr EVP_sha1 3 , +.Xr EVP_ripemd160 3 , +etc. +.Pp +.Fn HMAC_CTX_new +allocates and initializes a new +.Vt HMAC_CTX +object. +.Pp +.Fn HMAC_CTX_reset +zeroes and re-initializes +.Fa ctx +and associated resources, making it suitable for new computations +as if it was deleted with +.Fn HMAC_CTX_free +and newly created with +.Fn HMAC_CTX_new . +.Pp +.Fn HMAC_CTX_free +erases the key and other data from +.Fa ctx , +releases any associated resources, and finally frees +.Fa ctx +itself. +.Pp +The following functions may be used if the message is not completely +stored in memory: +.Pp +.Fn HMAC_Init_ex +sets up or reuses +.Fa ctx +to use the hash function +.Fa evp_md +and the key +.Fa key . +Either can be +.Dv NULL , +in which case the existing one is reused. +The +.Fa ctx +must have been created with +.Fn HMAC_CTX_new +before the first use in this function. +If +.Fn HMAC_Init_ex +is called with a +.Dv NULL +.Fa key +but +.Fa evp_md +is neither +.Dv NULL +nor the same as the previous digest used by +.Fa ctx , +then an error is returned because reuse of an existing key with a +different digest is not supported. +The +.Fa ENGINE *engine +argument is always ignored and passing +.Dv NULL +is recommended. +.Pp +.Fn HMAC_Update +can be called repeatedly with chunks of the message to be authenticated +.Pq Fa len No bytes at Fa data . +.Pp +.Fn HMAC_Final +places the message authentication code in +.Fa md , +which must have space for the hash function output. +.Pp +.Fn HMAC_CTX_copy +copies all of the internal state from +.Fa sctx +into +.Fa dctx . +.Pp +.Fn HMAC_CTX_set_flags +applies the specified flags to the internal +.Vt EVP_MD_CTX +objects. +Possible flag values +.Dv EVP_MD_CTX_FLAG_* +are defined in +.In openssl/evp.h . +.Pp +.Fn HMAC_size +returns the length in bytes of the underlying hash function output. +It is implemented as a macro. +.Sh RETURN VALUES +.Fn HMAC +returns a pointer to the message authentication code or +.Dv NULL +if an error occurred. +.Pp +.Fn HMAC_CTX_new +returns a pointer to the new +.Vt HMAC_CTX +object or +.Dv NULL +if an error occurred. +.Pp +.Fn HMAC_CTX_reset , +.Fn HMAC_Init_ex , +.Fn HMAC_Update , +.Fn HMAC_Final , +and +.Fn HMAC_CTX_copy +return 1 for success or 0 if an error occurred. +.Pp +.Fn HMAC_CTX_get_md +returns the message digest that was previously set for +.Fa ctx +with +.Fn HMAC_Init_ex , +or +.Dv NULL +if none was set. +.Pp +.Fn HMAC_size +returns the length in bytes of the underlying hash function output +or 0 on error. +.Sh SEE ALSO +.Xr CMAC_Init 3 , +.Xr EVP_DigestInit 3 +.Sh STANDARDS +RFC 2104 +.Sh HISTORY +.Fn HMAC , +.Fn HMAC_Update , +.Fn HMAC_Final , +and +.Fn HMAC_size +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . +.Pp +.Fn HMAC_Init_ex +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn HMAC_CTX_set_flags +first appeared in OpenSSL 0.9.7f and have been available since +.Ox 3.8 . +.Pp +.Fn HMAC_CTX_copy +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Pp +.Fn HMAC_CTX_new , +.Fn HMAC_CTX_reset , +.Fn HMAC_CTX_free , +and +.Fn HMAC_CTX_get_md +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +.Sh CAVEATS +Other implementations allow +.Fa md +in +.Fn HMAC +to be +.Dv NULL +and return a static array, which is not thread safe. diff --git a/static/openbsd/man3/IPAddressRange_new.3 b/static/openbsd/man3/IPAddressRange_new.3 new file mode 100644 index 00000000..79e3751b --- /dev/null +++ b/static/openbsd/man3/IPAddressRange_new.3 @@ -0,0 +1,526 @@ +.\" $OpenBSD: IPAddressRange_new.3,v 1.11 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: June 13 2025 $ +.Dt IPADDRESSRANGE_NEW 3 +.Os +.Sh NAME +.Nm IPAddressRange_new , +.Nm IPAddressRange_free , +.Nm d2i_IPAddressRange , +.Nm i2d_IPAddressRange , +.Nm IPAddressOrRange_new , +.Nm IPAddressOrRange_free , +.Nm d2i_IPAddressOrRange , +.Nm i2d_IPAddressOrRange , +.Nm IPAddressChoice_new , +.Nm IPAddressChoice_free , +.Nm d2i_IPAddressChoice , +.Nm i2d_IPAddressChoice , +.Nm IPAddressFamily_new , +.Nm IPAddressFamily_free , +.Nm d2i_IPAddressFamily , +.Nm i2d_IPAddressFamily +.Nd RFC 3779 IP address prefixes and ranges +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft IPAddressRange * +.Fn IPAddressRange_new void +.Ft void +.Fn IPAddressRange_free "IPAddressRange *range" +.Ft IPAddressRange * +.Fo d2i_IPAddressRange +.Fa "IPAddressRange **range" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_IPAddressRange +.Fa "IPAddressRange *range" +.Fa "unsigned char **der_out" +.Fc +.Ft IPAddressOrRange * +.Fn IPAddressOrRange_new void +.Ft void +.Fn IPAddressOrRange_free "IPAddressOrRange *aor" +.Ft IPAddressOrRange * +.Fo d2i_IPAddressOrRange +.Fa "IPAddressOrRange **aor" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_IPAddressOrRange +.Fa "IPAddressOrRange *aor" +.Fa "unsigned char **der_out" +.Fc +.Ft IPAddressChoice * +.Fn IPAddressChoice_new void +.Ft void +.Fn IPAddressChoice_free "IPAddressChoice *ac" +.Ft IPAddressChoice * +.Fo d2i_IPAddressChoice +.Fa "IPAddressChoice **ac" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_IPAddressChoice +.Fa "IPAddressChoice *ac" +.Fa "unsigned char **der_out" +.Fc +.Ft IPAddressFamily * +.Fn IPAddressFamily_new void +.Ft void +.Fn IPAddressFamily_free "IPAddressFamily *af" +.Ft IPAddressFamily * +.Fo d2i_IPAddressFamily +.Fa "IPAddressFamily **af" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_IPAddressFamily +.Fa "IPAddressFamily *af" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +.Vt IPAddressRange , +.Vt IPAddressOrRange , +.Vt IPAddressChoice , +and +.Vt IPAddressFamily +are building blocks of the +.Vt IPAddrBlocks +type representing the RFC 3779 IP address delegation extension. +.Pp +Per RFC 3779, section 2.1.1, +an IPv4 or an IPv6 address is encoded in network byte order in an +ASN.1 BIT STRING of bit size 32 or 128 bits, respectively. +The bit size of a prefix is its prefix length; +all insignificant zero bits are omitted +from the encoding. +Per section 2.1.2, +an address range is expressed as a pair of BIT STRINGs +where all the least significant zero bits of the lower bound +and all the least significant one bits of the upper bound are omitted. +.Pp +The library provides no API for directly converting an IP address or +prefix (in any form) to and from an +.Vt ASN1_BIT_STRING . +It also provides no API for directly handling ranges. +The +.Vt ASN1_BIT_STRING +internals are subtle and directly manipulating them in the +context of the RFC 3779 API is discouraged. +The bit size of an +.Vt ASN1_BIT_STRING +representing an IP address prefix or range is eight times its +.Fa length +member minus the lowest three bits of its +.Fa flags , +provided the +.Dv ASN1_STRING_FLAG_BITS_LEFT +flag is set. +.Pp +The +.Vt IPAddressRange +type defined in RFC 3779 section 2.2.3.9 is implemented as +.Bd -literal -offset indent +typedef struct IPAddressRange_st { + ASN1_BIT_STRING *min; + ASN1_BIT_STRING *max; +} IPAddressRange; +.Ed +.Pp +It represents the closed range [min,max] of IP addresses between +.Fa min +and +.Fa max , +where +.Fa min +should be strictly smaller than +.Fa max +and the range should not be expressible as a prefix. +.Pp +.Fn IPAddressRange_new +allocates a new +.Vt IPAddressRange +object with allocated, empty +.Fa min +and +.Fa max , +thus representing the entire address space invalidly as a non-prefix. +.Pp +.Fn IPAddressRange_free +frees +.Fa range +including any data contained in it. +If +.Fa range +is +.Dv NULL , +no action occurs. +.Pp +There is no dedicated type representing the +.Vt IPAddress +type defined in RFC 3779 section 2.2.3.8. +The API uses +.Vt ASN1_BIT_STRING +for this. +.Pp +The +.Vt IPAddressOrRange +type defined in RFC 3779 section 2.2.3.7 is implemented as +.Bd -literal -offset indent +typedef struct IPAddressOrRange_st { + int type; + union { + ASN1_BIT_STRING *addressPrefix; + IPAddressRange *addressRange; + } u; +} IPAddressOrRange; +.Ed +.Pp +representing an individual address prefix or an address range. +The +.Fa type +member should be set to +.Dv IPAddressOrRange_addressPrefix +or +.Dv IPAddressOrRange_addressRange +to indicate which member of the union +.Fa u +is valid. +.Pp +.Fn IPAddressOrRange_new +returns a new +.Vt IPAddressOrRange +object with invalid type and +.Dv NULL +members of the union +.Fa u . +.Pp +.Fn IPAddressOrRange_free +frees +.Fa aor +including any data contained in it, +provided +.Fa type +is set correctly. +If +.Fa aor +is +.Dv NULL , +no action occurs. +.Pp +In order to express a list of address prefixes and address ranges, +RFC 3779 section 2.2.3.6 +uses an ASN.1 SEQUENCE, +which is implemented via a +.Xr STACK_OF 3 +construction over +.Vt IPAddressOrRange : +.Bd -literal -offset indent +typedef STACK_OF(IPAddressOrRange) IPAddressOrRanges; +.Ed +.Pp +Since an +.Vt IPAddressOrRanges +object should be sorted in a specific way (see +.Xr X509v3_addr_canonize 3 ) , +a comparison function is needed for a correct instantiation +with +.Xr sk_new 3 . +The +.Fn v4IPAddressOrRange_cmp +and +.Fn v6IPAddressOrRange_cmp +functions are not directly exposed and not easily accessible +from outside the library, +and they are non-trivial to implement. +It is therefore discouraged to use +.Vt IPAddressOrRanges +objects that are not part of an +.Vt IPAddrBlocks +object. +.Pp +The +.Dq inherit +marker from RFC 3779 section 2.2.3.5 is implemented as +.Vt ASN1_NULL . +It has no dedicated type or API and can be instantiated with +.Xr ASN1_NULL_new 3 . +.Pp +The +.Vt IPAddressChoice +type defined in RFC 3779 section 2.2.3.4 is implemented as +.Bd -literal -offset indent +typedef struct IPAddressChoice_st { + int type; + union { + ASN1_NULL *inherit; + IPAddressOrRanges *addressesOrRanges; + } u; +} IPAddressChoice; +.Ed +.Pp +where the +.Fa type +member should be set to +.Dv IPAddressChoice_inherit +or +.Dv IPAddressChoice_addressesOrRanges +to indicate whether a given +.Vt IPAddressChoice +object represents an inherited list or an explicit list. +.Pp +.Fn IPAddressChoice_new +returns a new +.Vt IPAddressChoice +object with invalid type and +.Dv NULL +members of the union +.Fa u . +.Pp +.Fn IPAddressChoice_free +frees +.Fa ac +including any data contained in it, +provided +.Fa type +is set correctly. +.Pp +The +.Fa addressFamily +element defined in RFC 3779 section 2.2.3.3 is implemented as an +.Vt ASN1_OCTET_STRING +and it contains two or three octets. +The first two octets are always present and represent the +address family identifier (AFI) +in network byte order. +The optional subsequent address family identifier (SAFI) +occupies the third octet. +For IPv4 and IPv6, +.Dv IANA_AFI_IPV4 +and +.Dv IANA_AFI_IPV6 +are predefined. +Other AFIs are not supported by this implementation. +.Pp +The +.Vt IPAddressFamily +type defined in RFC 3779 section 2.2.3.2 is implemented as +.Bd -literal -offset indent +typedef struct IPAddressFamily_st { + ASN1_OCTET_STRING *addressFamily; + IPAddressChoice *ipAddressChoice; +} IPAddressFamily; +.Ed +.Pp +The +.Fa addressFamily +member indicates the address family the +.Fa ipAddressChoice +represents. +.Pp +.Fn IPAddressFamily_new +returns a new +.Vt IPAddressFamily +object with empty +.Fa addressFamily +and invalid +.Fa ipAddressChoice +members. +.Pp +.Fn IPAddressFamily_free +frees +.Fa af +including any data contained in it. +If +.Fa af +is +.Dv NULL , +no action occurs. +.Pp +The +.Vt IPAddrBlocks +type defined in RFC 3779 section 2.2.3.1 +uses an ASN.1 SEQUENCE, +which is implemented via a +.Xr STACK_OF 3 +construction over +.Vt IPAddressFamily : +.Bd -literal -offset indent +typedef STACK_OF(IPAddressFamily) IPAddrBlocks; +.Ed +.Pp +It can be instantiated with +.Fn sk_IPAddressFamily_new_null +and the correct sorting function can be installed with +.Xr X509v3_addr_canonize 3 . +To populate it, use +.Xr X509v3_addr_add_prefix 3 +and related functions. +.Pp +.Fn d2i_IPAddressRange , +.Fn i2d_IPAddressRange , +.Fn d2i_IPAddressOrRange , +.Fn i2d_IPAddressOrRange , +.Fn d2i_IPAddressChoice , +.Fn i2d_IPAddressChoice , +.Fn d2i_IPAddressFamily , +and +.Fn i2d_IPAddressFamily +decode and encode ASN.1 +.Vt IPAddressRange , +.Vt IPAddressOrRange , +.Vt IPAddressChoice , +and +.Vt IPAddressFamily +objects. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +There is no easy way of ensuring that the encodings generated by +these functions are correct, unless they are applied to objects +that are part of a canonical +.Vt IPAddrBlocks +structure, see +.Xr X509v3_addr_is_canonical 3 . +.Sh RETURN VALUES +.Fn IPAddressRange_new +returns a new +.Vt IPAddressRange +object with allocated, empty members, or +.Dv NULL +if an error occurs. +.Pp +.Fn IPAddressOrRange_new +returns a new, empty +.Vt IPAddressOrRange +object or +.Dv NULL +if an error occurs. +.Pp +.Fn IPAddressChoice_new +returns a new, empty +.Vt IPAddressChoice +object or +.Dv NULL +if an error occurs. +.Pp +.Fn IPAddressFamily_new +returns a new +.Vt IPAddressFamily +object with allocated, empty members, or +.Dv NULL +if an error occurs. +.Pp +The decoding functions +.Fn d2i_IPAddressRange , +.Fn d2i_IPAddressOrRange , +.Fn d2i_IPAddressChoice , +and +.Fn d2i_IPAddressFamily +return an +.Vt IPAddressRange , +an +.Vt IPAddressOrRange , +an +.Vt IPAddressChoice , +or an +.Vt IPAddressFamily +object, respectively, +or +.Dv NULL +if an error occurs. +.Pp +The encoding functions +.Fn i2d_IPAddressRange , +.Fn i2d_IPAddressOrRange , +.Fn i2d_IPAddressChoice , +and +.Fn i2d_IPAddressFamily +return the number of bytes successfully encoded +or a value <= 0 if an error occurs. +.Sh SEE ALSO +.Xr ASIdentifiers_new 3 , +.Xr ASN1_BIT_STRING_new 3 , +.Xr ASN1_OCTET_STRING_new 3 , +.Xr ASN1_OCTET_STRING_set 3 , +.Xr crypto 3 , +.Xr X509_new 3 , +.Xr X509v3_addr_add_inherit 3 , +.Xr X509v3_addr_inherits 3 , +.Xr X509v3_addr_subset 3 +.Sh STANDARDS +RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: +.Bl -dash -compact +.It +section 2.1.1: Encoding of an IP Address or Prefix +.It +section 2.1.2: Encoding of a Range of IP Addresses +.It +section 2.2.3: Syntax +.It +section 2.2.3.1: Type IPAddrBlocks +.It +section 2.2.3.2: Type IPAddressFamily +.It +section 2.2.3.3: Element addressFamily +.It +section 2.2.3.4: Element ipAddressChoice and Type IPAddressChoice +.It +section 2.2.3.5: Element inherit +.It +section 2.2.3.6: Element addressesOrRanges +.It +section 2.2.3.7: Type IPAddressOrRange +.It +section 2.2.3.8: Element addressPrefix and Type IPAddress +.It +section 2.2.3.9: Element addressRange and Type IPAddressRange +.El +.Pp +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules: +Specification of Basic Encoding Rules (BER), Canonical Encoding +Rules (CER) and Distinguished Encoding Rules (DER), +section 8.6: Encoding of a bitstring value +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . +.Sh BUGS +.\" The internals do not seem to consistently apply and check +.\" .Dv ASN1_STRING_FLAG_BITS_LEFT +.\" which may lead to incorrect encoding and misinterpretation +As it stands, the API is barely usable +due to missing convenience accessors, constructors and destructors +and due to the complete absence of API that checks that the +individual building blocks are correct. +Extracting information from a given object can be done relatively +safely. +However, constructing objects is very error prone, be it +by hand or using the bug-ridden +.Xr X509v3_addr_add_inherit 3 +API. +.Pp +RFC 3779 has element +.Dq addressesOrRanges . +Its type in this API is +.Vt IPAddressOrRanges . diff --git a/static/openbsd/man3/MB_CUR_MAX.3 b/static/openbsd/man3/MB_CUR_MAX.3 new file mode 100644 index 00000000..6146bd11 --- /dev/null +++ b/static/openbsd/man3/MB_CUR_MAX.3 @@ -0,0 +1,118 @@ +.\" $OpenBSD: MB_CUR_MAX.3,v 1.1 2023/08/25 12:45:45 schwarze Exp $ +.\" +.\" Copyright (c) 2023 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 $Mdocdate: August 25 2023 $ +.Dt MB_CUR_MAX 3 +.Os +.Sh NAME +.Nm MB_CUR_MAX +.Nd maximum number of bytes in a multibyte character +.Sh SYNOPSIS +.In stdlib.h +.Ft size_t +.Sy MB_CUR_MAX +.Pp +.In limits.h +.Fd #define MB_LEN_MAX 4 +.Sh DESCRIPTION +.Nm +is a macro that returns the maximum number of bytes needed to +represent any multibyte character in the current character encoding. +Usually, the character encoding is selected for the whole program using +.Xr setlocale 3 +with a +.Fa category +argument of +.Dv LC_CTYPE , +but it can be overridden on a per-thread basis using +.Xr uselocale 3 . +.Pp +By default and in the +.Qq C +locale, +.Nm MB_CUR_MAX +returns 1. +On +.Ox , +the only other possible return value is 4; +it occurs when using a UTF-8 locale. +On other systems, +.Nm +may return positive values other than 1 or 4. +.Pp +.Dv MB_LEN_MAX +is a constant specifying the maximum number of bytes needed to +represent any multibyte character in any supported character encoding. +On +.Ox , +it is always 4. +On other systems, it may have a different value greater than or equal to 1. +.Sh RETURN VALUES +On any system, +.Nm +returns an integral value in the range from 1 to +.Dv MB_LEN_MAX , +inclusive. +.Sh EXAMPLES +Size a buffer in a portable way to hold one single multibyte character: +.Bd -literal -offset indent +char buf[MB_LEN_MAX]; +wchar_t wchar; /* input value */ + +if (wctomb(buf, wchar) == -1) + /* error */ +.Ed +.Pp +Switch between code handling the +.Xr ascii 7 +and +UTF-8 character encodings in an +.Ox Ns -specific +way +.Pq not portable : +.Bd -literal -offset indent +if (MB_CUR_MAX == 1) { + /* Code to handle ASCII-encoded single-byte strings. */ +} else { + /* Code to handle UTF-8-encoded multibyte strings. */ +} +.Ed +.Sh SEE ALSO +.Xr mblen 3 , +.Xr setlocale 3 , +.Xr uselocale 3 , +.Xr wctomb 3 +.Sh STANDARDS +.Nm MB_CUR_MAX +and +.Dv MB_LEN_MAX +conform to +.St -ansiC . +.Sh HISTORY +.Nm MB_CUR_MAX +has been non-constant and thread-dependent since +.Ox 6.2 . +.Sh CAVEATS +Since +.Nm +is thread-dependent, calling it in a loop that processes individual +bytes or characters is likely to slow down the loop considerably. +If possible, consider calling it once before the loop and caching +the return value in a local variable to improve performance. +The value remains valid as long as the thread does not call +.Xr setlocale 3 +or +.Xr uselocale 3 . diff --git a/static/openbsd/man3/MD5.3 b/static/openbsd/man3/MD5.3 new file mode 100644 index 00000000..c9c89c33 --- /dev/null +++ b/static/openbsd/man3/MD5.3 @@ -0,0 +1,202 @@ +.\" $OpenBSD: MD5.3,v 1.10 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Ulf Moeller and +.\" Richard Levitte . +.\" Copyright (c) 2000, 2006 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt MD5 3 +.Os +.Sh NAME +.Nm MD4 , +.Nm MD5 , +.Nm MD4_Init , +.Nm MD4_Update , +.Nm MD4_Final , +.Nm MD5_Init , +.Nm MD5_Update , +.Nm MD5_Final +.Nd MD4 and MD5 hash functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/md4.h +.Ft unsigned char * +.Fo MD4 +.Fa "const unsigned char *d" +.Fa "unsigned long n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo MD4_Init +.Fa "MD4_CTX *c" +.Fc +.Ft int +.Fo MD4_Update +.Fa "MD4_CTX *c" +.Fa "const void *data" +.Fa "unsigned long len" +.Fc +.Ft int +.Fo MD4_Final +.Fa "unsigned char *md" +.Fa "MD4_CTX *c" +.Fc +.In openssl/md5.h +.Ft unsigned char * +.Fo MD5 +.Fa "const unsigned char *d" +.Fa "unsigned long n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo MD5_Init +.Fa "MD5_CTX *c" +.Fc +.Ft int +.Fo MD5_Update +.Fa "MD5_CTX *c" +.Fa "const void *data" +.Fa "unsigned long len" +.Fc +.Ft int +.Fo MD5_Final +.Fa "unsigned char *md" +.Fa "MD5_CTX *c" +.Fc +.Sh DESCRIPTION +MD4 and MD5 are cryptographic hash functions with a 128-bit +output. +.Pp +.Fn MD4 +and +.Fn MD5 +compute the MD4 and MD5 message digest of the +.Fa n +bytes at +.Fa d +and place it in +.Fa md , +which must have space for +.Dv MD4_DIGEST_LENGTH No == Dv MD5_DIGEST_LENGTH No == 16 +bytes of output. +.Pp +The following functions may be used if the message is not completely +stored in memory: +.Pp +.Fn MD5_Init +initializes a +.Vt MD5_CTX +structure. +.Pp +.Fn MD5_Update +can be called repeatedly with chunks of the message to be hashed +.Pq Fa len No bytes at Fa data . +.Pp +.Fn MD5_Final +places the message digest in +.Fa md , +which must have space for +.Dv MD5_DIGEST_LENGTH No == 16 +bytes of output, and erases the +.Vt MD5_CTX . +.Pp +.Fn MD4_Init , +.Fn MD4_Update , +and +.Fn MD4_Final +are analogous using an +.Vt MD4_CTX +structure. +.Pp +Applications should use the higher level functions +.Xr EVP_DigestInit 3 +etc. instead of calling these hash functions directly. +.Sh RETURN VALUES +.Fn MD4 +and +.Fn MD5 +return pointers to the hash value. +.Pp +.Fn MD4_Init , +.Fn MD4_Update , +.Fn MD4_Final , +.Fn MD5_Init , +.Fn MD5_Update , +and +.Fn MD5_Final +return 1 for success or 0 otherwise. +.Sh SEE ALSO +.Xr EVP_DigestInit 3 +.Sh STANDARDS +RFC 1320, RFC 1321 +.Sh HISTORY +.Fn MD5 , +.Fn MD5_Init , +.Fn MD5_Update , +and +.Fn MD5_Final +appeared in SSLeay 0.4 or earlier and have been available since +.Ox 2.4 . +.Pp +.Fn MD4 , +.Fn MD4_Init , +.Fn MD4_Update , +and +.Fn MD4_Final +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Sh CAVEATS +Other implementations allow +.Fa md +in +.Fn MD4 +and +.Fn MD5 +to be +.Dv NULL +and return a static array, which is not thread safe. diff --git a/static/openbsd/man3/MD5Init.3 b/static/openbsd/man3/MD5Init.3 new file mode 100644 index 00000000..5bb3c697 --- /dev/null +++ b/static/openbsd/man3/MD5Init.3 @@ -0,0 +1,213 @@ +.\" +.\" Copyright (c) 2000 Poul-Henning Kamp +.\" +.\" 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. +.\" +.\" If we meet some day, and you think this stuff is worth it, you +.\" can buy me a beer in return. Poul-Henning Kamp +.\" +.\" $OpenBSD: MD5Init.3,v 1.4 2025/06/13 18:34:00 schwarze Exp $ +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt MD5INIT 3 +.Os +.Sh NAME +.Nm MD5Init , +.Nm MD5Update , +.Nm MD5Pad , +.Nm MD5Final , +.Nm MD5Transform , +.Nm MD5End , +.Nm MD5File , +.Nm MD5FileChunk , +.Nm MD5Data +.Nd calculate MD5 message digest +.Sh SYNOPSIS +.In sys/types.h +.In md5.h +.Ft void +.Fn MD5Init "MD5_CTX *context" +.Ft void +.Fn MD5Update "MD5_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn MD5Pad "MD5_CTX *context" +.Ft void +.Fn MD5Final "u_int8_t digest[MD5_DIGEST_LENGTH]" "MD5_CTX *context" +.Ft void +.Fn MD5Transform "u_int32_t state[4]" "u_int8_t block[MD5_BLOCK_LENGTH]" +.Ft char * +.Fn MD5End "MD5_CTX *context" "char *buf" +.Ft char * +.Fn MD5File "const char *filename" "char *buf" +.Ft char * +.Fn MD5FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft char * +.Fn MD5Data "const u_int8_t *data" "size_t len" "char *buf" +.Sh DESCRIPTION +The MD5 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 +.Dq fingerprint +of the input-data, which doesn't disclose the actual input. +.Pp +MD5 has been broken; it should only be used where necessary for +backward compatibility. +The attack on MD5 is in the nature of finding +.Dq collisions +\(em that is, multiple inputs which hash to the same value. +It is still unlikely for an attacker to be able to determine the exact +original input given a hash value. +.Pp +The +.Fn MD5Init , +.Fn MD5Update , +and +.Fn MD5Final +functions are the core functions. +Allocate an +.Vt MD5_CTX , +initialize it with +.Fn MD5Init , +run over the data with +.Fn MD5Update , +and finally extract the result using +.Fn MD5Final . +.Pp +The +.Fn MD5Pad +function can be used to apply padding to the message digest as in +.Fn MD5Final , +but the current context can still be used with +.Fn MD5Update . +.Pp +The +.Fn MD5Transform +function is used by +.Fn MD5Update +to hash 512-bit blocks and forms the core of the algorithm. +Most programs should use the interface provided by +.Fn MD5Init , +.Fn MD5Update +and +.Fn MD5Final +instead of calling +.Fn MD5Transform +directly. +.Pp +.Fn MD5End +is a wrapper for +.Fn MD5Final +which converts the return value to an MD5_DIGEST_STRING_LENGTH-character +(including the terminating '\e0') +ASCII string which represents the 128 bits in hexadecimal. +.Pp +.Fn MD5File +calculates the digest of a file, and uses +.Fn MD5End +to return the result. +If the file cannot be opened, a null pointer is returned. +.Pp +.Fn MD5FileChunk +behaves like +.Fn MD5File +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. +.Fn MD5Data +calculates the digest of a chunk of data in memory, and uses +.Fn MD5End +to return the result. +.Pp +When using +.Fn MD5End , +.Fn MD5File , +.Fn MD5FileChunk , +or +.Fn MD5Data , +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 MD5_DIGEST_STRING_LENGTH +characters of buffer space. +.Sh SEE ALSO +.Xr cksum 1 , +.Xr md5 1 , +.Xr RMD160Init 3 , +.Xr SHA1Init 3 , +.Xr SHA256Init 3 +.Rs +.%A H. Dobbertin +.%D 1995 +.%J CryptoBytes +.%N 1(3):5 +.%T Alf Swindles Ann +.Re +.Rs +.%A MJ. B. Robshaw +.%D November 12, 1996 +.%J RSA Laboratories Bulletin +.%N 4 +.%T On Recent Results for MD4 and MD5 +.Re +.Rs +.%A Hans Dobbertin +.%T Cryptanalysis of MD5 Compress +.Re +.Sh STANDARDS +.Rs +.%A R. Rivest +.%D April 1992 +.%R RFC 1321 +.%T The MD5 Message Digest Algorithm +.Re +.Sh HISTORY +These functions appeared in +.Ox 2.0 . +.Sh AUTHORS +.An -nosplit +The original MD5 routines were developed by +RSA Data Security, Inc., and published in the above references. +This code is derived from a public domain implementation written by +.An Colin Plumb . +.Pp +The +.Fn MD5End , +.Fn MD5File , +.Fn MD5FileChunk , +and +.Fn MD5Data +helper functions are derived from code written by +.An Poul-Henning Kamp . +.Sh BUGS +Collisions have been found for the full version of MD5. +The use of the SHA2 functions is recommended instead. diff --git a/static/openbsd/man3/NAME_CONSTRAINTS_new.3 b/static/openbsd/man3/NAME_CONSTRAINTS_new.3 new file mode 100644 index 00000000..7d397548 --- /dev/null +++ b/static/openbsd/man3/NAME_CONSTRAINTS_new.3 @@ -0,0 +1,101 @@ +.\" $OpenBSD: NAME_CONSTRAINTS_new.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt NAME_CONSTRAINTS_NEW 3 +.Os +.Sh NAME +.Nm NAME_CONSTRAINTS_new , +.Nm NAME_CONSTRAINTS_free , +.Nm GENERAL_SUBTREE_new , +.Nm GENERAL_SUBTREE_free +.\" .Nm NAME_CONSTRAINTS_check is intentionally undocumented. +.\" beck@ said in the x509/x509_ncons.c rev. 1.4 commit message: +.\" We probably need to deprecate it thoughtfully. +.Nd X.509 CA name constraints extension +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft NAME_CONSTRAINTS * +.Fn NAME_CONSTRAINTS_new void +.Ft void +.Fn NAME_CONSTRAINTS_free "NAME_CONSTRAINTS *names" +.Ft GENERAL_SUBTREE * +.Fn GENERAL_SUBTREE_new void +.Ft void +.Fn GENERAL_SUBTREE_free "GENERAL_SUBTREE *name" +.Sh DESCRIPTION +X.509 CA certificates can use the name constraints extension +to restrict the subject names of subsequent certificates in a +certification path. +.Pp +.Fn NAME_CONSTRAINTS_new +allocates and initializes an empty +.Vt NAME_CONSTRAINTS +object, representing an ASN.1 +.Vt NameConstraints +structure defined in RFC 5280 section 4.2.1.10. +It consists of two +.Vt STACK_OF(GENERAL_SUBTREE) +objects, one specifying permitted names, the other excluded names. +.Fn NAME_CONSTRAINTS_free +frees +.Fa names . +.Pp +.Fn GENERAL_SUBTREE_new +allocates and initializes an empty +.Vt GENERAL_SUBTREE +object, representing an ASN.1 +.Vt GeneralSubtree +structure defined in RFC 5280 section 4.2.1.10. +It is a trivial wrapper around the +.Vt GENERAL_NAME +object documented in +.Xr GENERAL_NAME_new 3 . +The standard requires the other fields of +.Vt GENERAL_SUBTREE +to be ignored. +.Fn GENERAL_SUBTREE_free +frees +.Fa name . +.Sh RETURN VALUES +.Fn NAME_CONSTRAINTS_new +and +.Fn GENERAL_SUBTREE_new +return the new +.Vt NAME_CONSTRAINTS +or +.Vt GENERAL_SUBTREE +object, respectively, or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr BASIC_CONSTRAINTS_new 3 , +.Xr GENERAL_NAMES_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 4.2.1.10: Name Constraints +.Sh HISTORY +.Fn NAME_CONSTRAINTS_new , +.Fn NAME_CONSTRAINTS_free , +.Fn GENERAL_SUBTREE_new , +and +.Fn GENERAL_SUBTREE_free +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/OBJ_create.3 b/static/openbsd/man3/OBJ_create.3 new file mode 100644 index 00000000..75d51f4b --- /dev/null +++ b/static/openbsd/man3/OBJ_create.3 @@ -0,0 +1,249 @@ +.\" $OpenBSD: OBJ_create.3,v 1.11 2025/06/08 22:37:23 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL OBJ_nid2obj.pod 9b86974e Aug 17 15:21:33 2015 -0400 +.\" selective merge up to: +.\" OpenSSL OBJ_nid2obj.pod 0c5bc96f Mar 15 13:57:22 2022 +0000 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2017, 2021, 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2006 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt OBJ_CREATE 3 +.Os +.Sh NAME +.Nm OBJ_new_nid , +.Nm OBJ_add_object , +.Nm OBJ_create , +.Nm OBJ_create_objects , +.Nm OBJ_cleanup +.Nd modify the table of ASN.1 object identifiers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/objects.h +.Ft int +.Fn OBJ_new_nid "int increment" +.Ft int +.Fn OBJ_add_object "const ASN1_OBJECT *object" +.Ft int +.Fo OBJ_create +.Fa "const char *oid" +.Fa "const char *sn" +.Fa "const char *ln" +.Fc +.Ft int +.Fn OBJ_create_objects "BIO *in_bio" +.Ft void +.Fn OBJ_cleanup void +.Sh DESCRIPTION +.Fn OBJ_new_nid +returns the smallest currently unassigned ASN.1 numeric +object identifier (NID) and reserves +.Fa increment +consecutive NIDs starting with it. +Passing an argument of 1 is usually recommended. +The return value can be assigned to a new object by passing it as the +.Fa nid +argument to +.Xr ASN1_OBJECT_create 3 +and by passing the resulting object to +.Fn OBJ_add_object . +.Pp +.Fn OBJ_add_object +adds a copy of the +.Fa object +to the internal table of ASN.1 object identifiers for use by +.Xr OBJ_nid2obj 3 +and related functions. +.Pp +.Fn OBJ_create +provides a simpler way to add a new object to the internal table. +.Fa oid +is the numerical form of the object, +.Fa sn +the short name and +.Fa ln +the long name. +A new NID is automatically assigned using +.Fn OBJ_new_nid . +.Pp +.Fn OBJ_create_objects +reads text lines of the form +.Pp +.D1 Fa oid sn ln +.Pp +from +.Fa in_bio +and calls +.Fn OBJ_create oid sn ln +for every line read. +The three fields of the input lines +are separated by one or more whitespace characters. +.Pp +For all three functions, the objects added to the internal table and +all the data contained in them is marked as not dynamically allocated. +Consequently, retrieving them with +.Xr OBJ_nid2obj 3 +or a similar function and then calling +.Xr ASN1_OBJECT_free 3 +on the returned pointer will have no effect. +.Pp +.Fn OBJ_cleanup +resets the internal object table to its default state, +removing and freeing all objects that were added with +.Fn OBJ_add_object , +.Fn OBJ_create , +or +.Fn OBJ_create_objects . +.Sh RETURN VALUES +.Fn OBJ_new_nid +returns the new NID. +.Pp +.Fn OBJ_add_object +returns the NID of the added +.Fa object +or +.Dv NID_undef +if no object was added because the +.Fa object +argument was +.Dv NULL , +did not contain an NID, or memory allocation failed. +.Pp +.Fn OBJ_create +returns the new NID or +.Dv NID_undef +if +.Fa oid +is not a valid representation of an object identifier +or if memory allocation fails. +.Pp +.Fn OBJ_create_objects +returns the number of objects added. +.Pp +In some cases of failure of +.Fn OBJ_add_object , +.Fn OBJ_create , +and +.Fn OBJ_create_objects , +the reason can be determined with +.Xr ERR_get_error 3 . +.Sh EXAMPLES +Create a new NID and initialize an object from it: +.Bd -literal -offset indent +int new_nid; +ASN1_OBJECT *obj; + +new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); +obj = OBJ_nid2obj(new_nid); +.Ed +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr OBJ_nid2obj 3 +.Sh HISTORY +.Fn OBJ_new_nid , +.Fn OBJ_add_object , +and +.Fn OBJ_cleanup +first appeared in SSLeay 0.8.0 and +.Fn OBJ_create +in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . +.Sh CAVEATS +.Fn OBJ_add_object +indicates success even after adding an incomplete object that was created with +.Xr ASN1_OBJECT_create 3 +but lacks a short name, a long name, or an OID. +.Pp +Even +.Fn OBJ_create +tolerates +.Dv NULL +pointers being passed for the +.Fa sn +and/or +.Fa ln +arguments, in which case +.Xr OBJ_nid2sn 3 +and +.Xr OBJ_sn2nid 3 +or +.Xr OBJ_nid2ln 3 +and +.Xr OBJ_ln2nid 3 +will not work on the added object, respectively. +.Sh BUGS +.Fn OBJ_new_nid +does not reserve any return value to indicate an error. +Consequently, to avoid conflicting NID assignments and integer overflows, +care must be taken to not pass negative, zero, or large arguments to +.Fn OBJ_new_nid . +.Pp +.Fn OBJ_create_objects +does not distinguish between end of file, I/O errors, temporary +unavailability of data on a non-blocking BIO, invalid input syntax, +and memory allocation failure. +In all these cases, reading is aborted and the number of objects +that were already added is returned. diff --git a/static/openbsd/man3/OBJ_find_sigid_algs.3 b/static/openbsd/man3/OBJ_find_sigid_algs.3 new file mode 100644 index 00000000..4c071c6c --- /dev/null +++ b/static/openbsd/man3/OBJ_find_sigid_algs.3 @@ -0,0 +1,89 @@ +.\" $OpenBSD: OBJ_find_sigid_algs.3,v 1.4 2025/06/09 12:42:46 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 9 2025 $ +.Dt OBJ_FIND_SIGID_ALGS 3 +.Os +.Sh NAME +.Nm OBJ_find_sigid_algs , +.Nm OBJ_find_sigid_by_algs +.Nd signature algorithm mappings +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/objects.h +.Ft int +.Fo OBJ_find_sigid_algs +.Fa "int signature" +.Fa "int *pdigest" +.Fa "int *pencryption" +.Fc +.Ft int +.Fo OBJ_find_sigid_by_algs +.Fa "int *psignature" +.Fa "int digest" +.Fa "int encryption" +.Fc +.Sh DESCRIPTION +.Fn OBJ_find_sigid_algs +looks up the +.Fa signature +algorithm. +If it is found, the associated digest algorithm is stored in +.Pf * Fa pdigest +unless +.Fa pdigest +is a +.Dv NULL +pointer, and the associated encryption algorithm is stored in +.Pf * Fa pencryption +unless +.Fa pencryption +is a +.Dv NULL +pointer. +.Pp +.Fn OBJ_find_sigid_by_algs +looks up the pair +.Pq Fa digest , encryption . +If it is found, the associated signature algorithm is stored in +.Pf * Fa psignature +unless +.Fa psignature +is a +.Dv NULL +pointer. +.Sh RETURN VALUES +.Fn OBJ_find_sigid_algs +returns 1 if a definition of the +.Fa signature +algorithm is found or 0 if a definition of the +.Fa signature +algorithm is not built into the library. +.Pp +.Fn OBJ_find_sigid_by_algs +returns 1 if a signature algorithm using the specified +.Fa digest +and +.Fa encryption +algorithms is defined or 0 if the definition of such an algorithm +is not built into the library. +.Sh SEE ALSO +.Xr OBJ_create 3 , +.Xr OBJ_nid2obj 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.0 +and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/OBJ_nid2obj.3 b/static/openbsd/man3/OBJ_nid2obj.3 new file mode 100644 index 00000000..9261ac9a --- /dev/null +++ b/static/openbsd/man3/OBJ_nid2obj.3 @@ -0,0 +1,522 @@ +.\" $OpenBSD: OBJ_nid2obj.3,v 1.23 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL c264592d May 14 11:28:00 2006 +0000 +.\" selective merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2017, 2021, 2023 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2006, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt OBJ_NID2OBJ 3 +.Os +.Sh NAME +.Nm OBJ_nid2obj , +.Nm OBJ_nid2ln , +.Nm OBJ_nid2sn , +.Nm OBJ_obj2nid , +.Nm OBJ_ln2nid , +.Nm OBJ_sn2nid , +.Nm OBJ_txt2nid , +.Nm OBJ_txt2obj , +.Nm OBJ_obj2txt , +.Nm OBJ_cmp , +.Nm OBJ_dup , +.Nm i2t_ASN1_OBJECT , +.Nm i2a_ASN1_OBJECT +.Nd inspect and create ASN.1 object identifiers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/objects.h +.Ft ASN1_OBJECT * +.Fo OBJ_nid2obj +.Fa "int nid" +.Fc +.Ft const char * +.Fo OBJ_nid2ln +.Fa "int nid" +.Fc +.Ft const char * +.Fo OBJ_nid2sn +.Fa "int nid" +.Fc +.Ft int +.Fo OBJ_obj2nid +.Fa "const ASN1_OBJECT *object" +.Fc +.Ft int +.Fo OBJ_ln2nid +.Fa "const char *ln" +.Fc +.Ft int +.Fo OBJ_sn2nid +.Fa "const char *sn" +.Fc +.Ft int +.Fo OBJ_txt2nid +.Fa "const char *s" +.Fc +.Ft ASN1_OBJECT * +.Fo OBJ_txt2obj +.Fa "const char *s" +.Fa "int no_name" +.Fc +.Ft int +.Fo OBJ_obj2txt +.Fa "char *buf" +.Fa "int buf_len" +.Fa "const ASN1_OBJECT *object" +.Fa "int no_name" +.Fc +.Ft int +.Fo OBJ_cmp +.Fa "const ASN1_OBJECT *a" +.Fa "const ASN1_OBJECT *b" +.Fc +.Ft ASN1_OBJECT * +.Fo OBJ_dup +.Fa "const ASN1_OBJECT *object" +.Fc +.In openssl/asn1.h +.Ft int +.Fo i2t_ASN1_OBJECT +.Fa "char *buf" +.Fa "int buf_len" +.Fa "const ASN1_OBJECT *object" +.Fc +.Ft int +.Fo i2a_ASN1_OBJECT +.Fa "BIO *out_bio" +.Fa "const ASN1_OBJECT *object" +.Fc +.Sh DESCRIPTION +The ASN.1 object utility functions process +.Vt ASN1_OBJECT +structures, in the following called +.Dq objects . +An object represents an ASN.1 +.Vt OBJECT IDENTIFIER +.Pq OID . +The library maintains an internal global table of objects. +Many of these objects are built into the library +and contained in the global table by default. +The application program can add additional objects to the global table +by using functions documented in the +.Xr OBJ_create 3 +manual page. +Consequently, there are three classes of objects: +built-in table objects, user-defined table objects, and non-table objects. +.Pp +In addition to the OID, each object can hold +a long name, a short name, and a numerical identifier (NID). +Even though the concept of NIDs is specific to the library +and not standardized, using the NID is often the most convenient way +for source code to refer to a specific OID. +The NIDs of the built-in objects are available as defined constants. +.Pp +Built-in table objects have certain advantages +over objects that are not in the global table: +for example, their NIDs can be used in C language switch statements. +They are also shared: +there is only a single static constant structure for each built-on OID. +.Pp +Some functions operate on table objects only: +.Pp +.Fn OBJ_nid2obj +retrieves the table object associated with the +.Fa nid . +.Fn OBJ_nid2ln +and +.Fn OBJ_nid2sn +retrieve its long and short name, respectively. +.Pp +.Fn OBJ_obj2nid +retrieves the NID associated with the given +.Fa object , +which is either the NID stored in the +.Fa object +itself, if any, or otherwise the NID stored in a table object +containing the same OID. +.Pp +.Fn OBJ_ln2nid +and +.Fn OBJ_sn2nid +retrieve the NID from the table object with the long name +.Fa ln +or the short name +.Fa sn , +respectively. +.Pp +.Fn OBJ_txt2nid +retrieves the NID from the table object described by the text string +.Fa s , +which can be a long name, a short name, +or the numerical representation of an OID. +.Pp +The remaining functions can be used both on table objects +and on objects that are not in the global table: +.Pp +.Fn OBJ_txt2obj +retrieves or creates an object matching the text string +.Fa s . +If +.Fa no_name +is 1, only the numerical representation of an OID is accepted. +If +.Fa no_name +is 0, long names and short names are accepted as well. +.Pp +.Fn OBJ_obj2txt +writes a NUL terminated textual representation +of the OID contained in the given +.Fa object +into +.Fa buf . +At most +.Fa buf_len +bytes are written, truncating the result if necessary. +The total amount of space required is returned. +If +.Fa no_name +is 0 and the table object containing the same OID +contains a long name, the long name is written. +Otherwise, if +.Fa no_name +is 0 and the table object containing the same OID +contains a short name, the short name is written. +Otherwise, the numerical representation of the OID is written. +.Pp +.Fn i2t_ASN1_OBJECT +is the same as +.Fn OBJ_obj2txt +with +.Fa no_name +set to 0. +.Pp +.Fn i2a_ASN1_OBJECT +writes a textual representation of the OID contained in the given +.Fa object +to +.Fa out_bio +using +.Xr BIO_write 3 . +It does not write a terminating NUL byte. +If the +.Fa object +argument is +.Dv NULL +or contains no OID, it writes the 4-byte string +.Qq NULL . +If +.Fn i2t_ASN1_OBJECT +fails, +.Fn i2a_ASN1_OBJECT +writes the 9-byte string +.Qq . +Otherwise, it writes the string constructed with +.Fn i2t_ASN1_OBJECT . +.Pp +.Fn OBJ_cmp +tests whether +.Fa a +and +.Fa b +represent the same ASN.1 +.Vt OBJECT IDENTIFIER . +Any names and NIDs contained in the two objects are ignored, +even if they differ between both objects. +.Pp +.Fn OBJ_dup +returns a deep copy of the given +.Fa object +if it is marked as dynamically allocated. +The new object and all data contained in it are marked as dynamically +allocated. +If the given +.Fa object +is not marked as dynamically allocated, +.Fn OBJ_dup +just returns a pointer to the +.Fa object +itself. +.Sh RETURN VALUES +Application code should treat all returned values \(em +objects, names, and NIDs \(em as constants. +.Pp +.Fn OBJ_nid2obj +returns a pointer to a table object owned by the library or +.Dv NULL +if no matching table object is found. +.Pp +.Fn OBJ_nid2ln +and +.Fn OBJ_nid2sn +return a pointer to a string owned by a table object or +.Dv NULL +if no matching table object is found. +For +.Dv NID_undef , +they return the constant static strings +.Qq undefined +and +.Qq UNDEF , +respectively. +.Pp +.Fn OBJ_obj2nid +returns an NID on success, or +.Dv NID_undef +if +.Fa object +is +.Dv NULL , +does not contain an OID, +if no table object matching the OID is found, +or if the matching object does not contain an NID. +.Pp +.Fn OBJ_ln2nid +and +.Fn OBJ_sn2nid +return an NID on success or +.Dv NID_undef +if no matching table object is found +or if the matching object does not contain an NID. +.Pp +.Fn OBJ_txt2nid +returns an NID on success or +.Dv NID_undef +if parsing of +.Fa s +or memory allocation fails, if no matching table object is found, +or if the matching object does not contain an NID. +.Pp +.Fn OBJ_txt2obj +returns a pointer to a table object owned by the library if lookup of +.Fa s +as a long or short name succeeds. +Otherwise, it returns a newly created object, +transferring ownership to the caller, or +.Dv NULL +if parsing of +.Fa s +or memory allocation fails. +.Pp +.Fn OBJ_obj2txt +and +.Fn i2t_ASN1_OBJECT +return the amount of space required in bytes, +including the terminating NUL byte, +or zero if an error occurs before the required space can be calculated, +in particular if +.Fa buf_len +is negative, +.Fa object +is +.Dv NULL +or does not contain an OID, +or if memory allocation fails. +.Pp +.Fn OBJ_cmp +returns 0 if both objects refer to the same OID +or neither of them are associated with any OID, +or a non-zero value if at least one of them refers to an OID +but the other one does not refer to the same OID. +.Pp +.Fn OBJ_dup +returns the pointer to the original +.Fa object +if it is not marked as dynamically allocated. +Otherwise, it returns a newly created object, +transferring ownership to the caller, or +.Dv NULL +if +.Fa object +is +.Dv NULL +or memory allocation fails. +.Pp +.Fn i2a_ASN1_OBJECT +returns the number of bytes written, even if the given +.Fa object +is invalid or contains invalid data, +but a negative value if memory allocation or a write operation fails. +.Pp +In some cases of failure of +.Fn OBJ_nid2obj , +.Fn OBJ_nid2ln , +.Fn OBJ_nid2sn , +.Fn OBJ_txt2nid , +.Fn OBJ_txt2obj , +.Fn OBJ_obj2txt , +.Fn OBJ_dup , +.Fn i2t_ASN1_OBJECT , +and +.Fn i2a_ASN1_OBJECT , +the reason can be determined with +.Xr ERR_get_error 3 . +.Sh EXAMPLES +Retrieve the object for +.Sy commonName : +.Bd -literal -offset indent +ASN1_OBJECT *object; +object = OBJ_nid2obj(NID_commonName); +.Ed +.Pp +Check whether an object contains the OID for +.Sy commonName : +.Bd -literal -offset indent +if (OBJ_obj2nid(object) == NID_commonName) + /* Do something */ +.Ed +.Pp +Create a new object directly: +.Bd -literal -offset indent +object = OBJ_txt2obj("1.2.3.4", 1); +.Ed +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr BIO_new 3 , +.Xr d2i_ASN1_OBJECT 3 , +.Xr OBJ_create 3 +.Sh HISTORY +.Fn OBJ_nid2obj , +.Fn OBJ_nid2ln , +.Fn OBJ_nid2sn , +.Fn OBJ_obj2nid , +.Fn OBJ_ln2nid , +.Fn OBJ_sn2nid , +.Fn OBJ_txt2nid , +.Fn OBJ_cmp , +and +.Fn OBJ_dup +first appeared in SSLeay 0.5.1. +.Fn i2a_ASN1_OBJECT +first appeared in SSLeay 0.6.0, and +.Fn i2t_ASN1_OBJECT +in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn OBJ_txt2obj +first appeared in OpenSSL 0.9.2b. +.Fn OBJ_obj2txt +first appeared in OpenSSL 0.9.4. +Both functions have been available since +.Ox 2.6 . +.Sh CAVEATS +The API contract of +.Fn OBJ_txt2obj +when called with a +.Fa no_name +argument of 0 and of +.Fn OBJ_dup +is scary in so far as the caller cannot find out from the returned +object whether it is owned by the library or whether ownership was +transferred to the caller. +Consequently, it is best practice to assume that ownership of the object +may have been transferred and call +.Xr ASN1_OBJECT_free 3 +on the returned object when the caller no longer needs it. +In case the library retained ownership of the returned object, +.Xr ASN1_OBJECT_free 3 +has no effect and is harmless. +.Pp +Objects returned from +.Fn OBJ_txt2obj +with a +.Fa no_name +argument of 1 always require +.Xr ASN1_OBJECT_free 3 +to prevent memory leaks. +.Pp +Objects returned from +.Fn OBJ_nid2obj +never require +.Xr ASN1_OBJECT_free 3 , +but calling it anyway has no effect and is harmless. +.Sh BUGS +Usually, an object is expected to contain an NID other than +.Dv NID_undef +if and only if it is a table object. +However, this is not an invariant guaranteed by the API. +In particular, +.Xr ASN1_OBJECT_create 3 +allows the creation of non-table objects containing bogus NIDs. +.Fn OBJ_obj2nid +returns such bogus NIDs even though +.Fn OBJ_nid2obj +cannot use them for retrieval. +On top of that, the global table contains one built-in object with an NID of +.Dv NID_undef . +.Pp +.Fn OBJ_obj2txt +is awkward and messy to use: it doesn't follow the convention of other +OpenSSL functions where the buffer can be set to +.Dv NULL +to determine the amount of data that should be written. +Instead +.Fa buf +must point to a valid buffer and +.Fa buf_len +should be set to a positive value. +A buffer length of 80 should be more than enough to handle any OID +encountered in practice. diff --git a/static/openbsd/man3/OCSP_CRLID_new.3 b/static/openbsd/man3/OCSP_CRLID_new.3 new file mode 100644 index 00000000..9b0126fe --- /dev/null +++ b/static/openbsd/man3/OCSP_CRLID_new.3 @@ -0,0 +1,114 @@ +.\" $OpenBSD: OCSP_CRLID_new.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt OCSP_CRLID_NEW 3 +.Os +.Sh NAME +.Nm OCSP_CRLID_new , +.Nm OCSP_CRLID_free , +.Nm OCSP_crlID_new +.Nd OCSP CRL extension +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ocsp.h +.Ft OCSP_CRLID * +.Fn OCSP_CRLID_new void +.Ft void +.Fn OCSP_CRLID_free "OCSP_CRLID *crlid" +.Ft X509_EXTENSION * +.Fo OCSP_crlID_new +.Fa "const char *url" +.Fa "long *number" +.Fa "char *time" +.Fc +.Sh DESCRIPTION +If a client asks about the validity of a certificate and it turns +out to be invalid, the responder may optionally communicate which +certificate revocation list the certificate was found on. +The required data is stored as an ASN.1 +.Vt CrlID +structure in the singleExtensions field of the +.Vt SingleResponse +structure. +The +.Vt CrlID +is represented by an +.Vt OCSP_CRLID +object, which will be stored inside the +.Vt OCSP_SINGLERESP +object documented in +.Xr OCSP_SINGLERESP_new 3 . +.Pp +.Fn OCSP_CRLID_new +allocates and initializes an empty +.Vt OCSP_CRLID +object. +.Fn OCSP_CRLID_free +frees +.Fa crlid . +.Pp +.Fn OCSP_crlID_new +accepts the +.Fa url +at which the CRL is available, the CRL +.Fa number , +and/or the +.Fa time +at which the CRL was created. +Each argument can be +.Dv NULL , +in which case the respective field is omitted. +The resulting +.Vt CrlID +structure is encoded in ASN.1 using +.Xr X509V3_EXT_i2d 3 +with criticality 0. +.Sh RETURN VALUES +.Fn OCSP_CRLID_new +returns a new +.Vt OCSP_CRLID +object or +.Dv NULL +if an error occurred. +.Pp +.Fn OCSP_crlID_new +returns a new +.Vt X509_EXTENSION +object or +.Dv NULL +if an error occurred. +.Sh SEE ALSO +.Xr OCSP_REQUEST_new 3 , +.Xr OCSP_resp_find_status 3 , +.Xr OCSP_response_status 3 , +.Xr X509_EXTENSION_new 3 +.Sh STANDARDS +RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate +Status Protocol, section 4.4.2: CRL References +.Sh HISTORY +.Fn OCSP_CRLID_new , +.Fn OCSP_CRLID_free , +and +.Fn OCSP_crlID_new +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Sh CAVEATS +The function names +.Fn OCSP_CRLID_new +and +.Fn OCSP_crlID_new +only differ in case. diff --git a/static/openbsd/man3/OCSP_REQUEST_new.3 b/static/openbsd/man3/OCSP_REQUEST_new.3 new file mode 100644 index 00000000..0e4e0ffb --- /dev/null +++ b/static/openbsd/man3/OCSP_REQUEST_new.3 @@ -0,0 +1,330 @@ +.\" $OpenBSD: OCSP_REQUEST_new.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt OCSP_REQUEST_NEW 3 +.Os +.Sh NAME +.Nm OCSP_REQUEST_new , +.Nm OCSP_REQUEST_free , +.Nm OCSP_SIGNATURE_new , +.Nm OCSP_SIGNATURE_free , +.Nm OCSP_REQINFO_new , +.Nm OCSP_REQINFO_free , +.Nm OCSP_ONEREQ_new , +.Nm OCSP_ONEREQ_free , +.Nm OCSP_request_add0_id , +.Nm OCSP_request_sign , +.Nm OCSP_request_add1_cert , +.Nm OCSP_request_onereq_count , +.Nm OCSP_request_onereq_get0 +.Nd OCSP request functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ocsp.h +.Ft OCSP_REQUEST * +.Fn OCSP_REQUEST_new void +.Ft void +.Fn OCSP_REQUEST_free "OCSP_REQUEST *req" +.Ft OCSP_SIGNATURE * +.Fn OCSP_SIGNATURE_new void +.Ft void +.Fn OCSP_SIGNATURE_free "OCSP_SIGNATURE *signature" +.Ft OCSP_REQINFO * +.Fn OCSP_REQINFO_new void +.Ft void +.Fn OCSP_REQINFO_free "OCSP_REQINFO *reqinfo" +.Ft OCSP_ONEREQ * +.Fn OCSP_ONEREQ_new void +.Ft void +.Fn OCSP_ONEREQ_free "OCSP_ONEREQ *onereq" +.Ft OCSP_ONEREQ * +.Fo OCSP_request_add0_id +.Fa "OCSP_REQUEST *req" +.Fa "OCSP_CERTID *cid" +.Fc +.Ft int +.Fo OCSP_request_sign +.Fa "OCSP_REQUEST *req" +.Fa "X509 *signer" +.Fa "EVP_PKEY *key" +.Fa "const EVP_MD *dgst" +.Fa "STACK_OF(X509) *certs" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo OCSP_request_add1_cert +.Fa "OCSP_REQUEST *req" +.Fa "X509 *cert" +.Fc +.Ft int +.Fo OCSP_request_onereq_count +.Fa "OCSP_REQUEST *req" +.Fc +.Ft OCSP_ONEREQ * +.Fo OCSP_request_onereq_get0 +.Fa "OCSP_REQUEST *req" +.Fa "int i" +.Fc +.Sh DESCRIPTION +.Fn OCSP_REQUEST_new +allocates and initializes an empty +.Vt OCSP_REQUEST +object, representing an ASN.1 +.Vt OCSPRequest +structure defined in RFC 6960. +.Fn OCSP_REQUEST_free +frees +.Fa req . +.Pp +.Fn OCSP_SIGNATURE_new +allocates and initializes an empty +.Vt OCSP_SIGNATURE +object, representing an ASN.1 +.Vt Signature +structure defined in RFC 6960. +Such an object is used inside +.Vt OCSP_REQUEST . +.Fn OCSP_SIGNATURE_free +frees +.Fa signature . +.Pp +.Fn OCSP_REQINFO_new +allocates and initializes an empty +.Vt OCSP_REQINFO +object, representing an ASN.1 +.Vt TBSRequest +structure defined in RFC 6960. +Such an object is used inside +.Vt OCSP_REQUEST . +It asks about the validity of one or more certificates. +.Fn OCSP_REQINFO_free +frees +.Fa reqinfo . +.Pp +.Fn OCSP_ONEREQ_new +allocates and initializes an empty +.Vt OCSP_ONEREQ +object, representing an ASN.1 +.Vt Request +structure defined in RFC 6960. +Such objects are used inside +.Vt OCSP_REQINFO . +Each one asks about the validity of one certificate. +.Fn OCSP_ONEREQ_free +frees +.Fa onereq . +.Pp +.Fn OCSP_request_add0_id +adds certificate ID +.Fa cid +to +.Fa req . +It returns the +.Vt OCSP_ONEREQ +object added so an application can add additional extensions to the +request. +The +.Fa cid +parameter must not be freed up after the operation. +.Pp +.Fn OCSP_request_sign +signs OCSP request +.Fa req +using certificate +.Fa signer , +private key +.Fa key , +digest +.Fa dgst , +and additional certificates +.Fa certs . +If the +.Fa flags +option +.Dv OCSP_NOCERTS +is set, then no certificates will be included in the request. +.Pp +.Fn OCSP_request_add1_cert +adds certificate +.Fa cert +to request +.Fa req . +The application is responsible for freeing up +.Fa cert +after use. +.Pp +.Fn OCSP_request_onereq_count +returns the total number of +.Vt OCSP_ONEREQ +objects in +.Fa req . +.Pp +.Fn OCSP_request_onereq_get0 +returns an internal pointer to the +.Vt OCSP_ONEREQ +contained in +.Fa req +of index +.Fa i . +The index value +.Fa i +runs from 0 to +.Fn OCSP_request_onereq_count req No - 1 . +.Pp +.Fn OCSP_request_onereq_count +and +.Fn OCSP_request_onereq_get0 +are mainly used by OCSP responders. +.Sh RETURN VALUES +.Fn OCSP_REQUEST_new , +.Fn OCSP_SIGNATURE_new , +.Fn OCSP_REQINFO_new , +and +.Fn OCSP_ONEREQ_new +return an empty +.Vt OCSP_REQUEST , +.Vt OCSP_SIGNATURE , +.Vt OCSP_REQINFO , +or +.Vt OCSP_ONEREQ +object, respectively, or +.Dv NULL +if an error occurred. +.Pp +.Fn OCSP_request_add0_id +returns the +.Vt OCSP_ONEREQ +object containing +.Fa cid +or +.Dv NULL +if an error occurred. +.Pp +.Fn OCSP_request_sign +and +.Fn OCSP_request_add1_cert +return 1 for success or 0 for failure. +.Pp +.Fn OCSP_request_onereq_count +returns the total number of +.Vt OCSP_ONEREQ +objects in +.Fa req . +.Pp +.Fn OCSP_request_onereq_get0 +returns a pointer to an +.Vt OCSP_ONEREQ +object or +.Dv NULL +if the index value is out of range. +.Sh EXAMPLES +Create an +.Vt OCSP_REQUEST +object for certificate +.Fa cert +with issuer +.Fa issuer : +.Bd -literal -offset indent +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); +.Ed +.Sh SEE ALSO +.Xr ACCESS_DESCRIPTION_new 3 , +.Xr crypto 3 , +.Xr d2i_OCSP_REQUEST 3 , +.Xr d2i_OCSP_RESPONSE 3 , +.Xr EVP_DigestInit 3 , +.Xr OCSP_cert_to_id 3 , +.Xr OCSP_CRLID_new 3 , +.Xr OCSP_request_add1_nonce 3 , +.Xr OCSP_resp_find_status 3 , +.Xr OCSP_response_status 3 , +.Xr OCSP_sendreq_new 3 , +.Xr OCSP_SERVICELOC_new 3 , +.Xr X509_ocspid_print 3 +.Sh STANDARDS +RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate +Status Protocol, section 4.1: Request Syntax +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/OCSP_SERVICELOC_new.3 b/static/openbsd/man3/OCSP_SERVICELOC_new.3 new file mode 100644 index 00000000..42288321 --- /dev/null +++ b/static/openbsd/man3/OCSP_SERVICELOC_new.3 @@ -0,0 +1,110 @@ +.\" $OpenBSD: OCSP_SERVICELOC_new.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt OCSP_SERVICELOC_NEW 3 +.Os +.Sh NAME +.Nm OCSP_SERVICELOC_new , +.Nm OCSP_SERVICELOC_free , +.Nm OCSP_url_svcloc_new +.Nd OCSP service locator extension +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ocsp.h +.Ft OCSP_SERVICELOC * +.Fn OCSP_SERVICELOC_new void +.Ft void +.Fn OCSP_SERVICELOC_free "OCSP_SERVICELOC *sloc" +.Ft X509_EXTENSION * +.Fo OCSP_url_svcloc_new +.Fa "X509_NAME *issuer" +.Fa "const char **urls" +.Fc +.Sh DESCRIPTION +Due to restrictions of network routing, a client may be unable to +directly contact the authoritative OCSP server for a certificate +that needs to be checked. +In that case, the request can be sent via a proxy server. +An ASN.1 +.Vt ServiceLocator +structure is included in the singleRequestExtensions field of the +.Vt Request +structure to indicate where to forward the request. +The +.Vt ServiceLocator +is represented by a +.Vt OCSP_SERVICELOC +object, which will be stored inside the +.Vt OCSP_ONEREQ +object documented in +.Xr OCSP_ONEREQ_new 3 . +.Pp +.Fn OCSP_SERVICELOC_new +allocates and initializes an empty +.Vt OCSP_SERVICELOC +object. +.Fn OCSP_SERVICELOC_free +frees +.Fa sloc . +.Pp +.Fn OCSP_url_svcloc_new +requires an +.Fa issuer +name and optionally accepts an array of +.Fa urls . +If +.Fa urls +or its first element is +.Dv NULL , +the locator field is omitted from the +.Vt ServiceLocator +structure and only the issuer is included. +The resulting +.Vt ServiceLocator +structure is encoded in ASN.1 using +.Xr X509V3_EXT_i2d 3 +with criticality 0. +.Sh RETURN VALUES +.Fn OCSP_SERVICELOC_new +returns a new +.Vt OCSP_SERVICELOC +object or +.Dv NULL +if an error occurred. +.Pp +.Fn OCSP_url_svcloc_new +returns a new +.Vt X509_EXTENSION +object or +.Dv NULL +if an error occurred. +.Sh SEE ALSO +.Xr OCSP_REQUEST_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_get1_ocsp 3 , +.Xr X509_get_issuer_name 3 , +.Xr X509_NAME_new 3 +.Sh STANDARDS +RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate +Status Protocol, section 4.4.6: Service Locator +.Sh HISTORY +.Fn OCSP_SERVICELOC_new , +.Fn OCSP_SERVICELOC_free , +and +.Fn OCSP_url_svcloc_new +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/OCSP_cert_to_id.3 b/static/openbsd/man3/OCSP_cert_to_id.3 new file mode 100644 index 00000000..d0c04fcb --- /dev/null +++ b/static/openbsd/man3/OCSP_cert_to_id.3 @@ -0,0 +1,240 @@ +.\" $OpenBSD: OCSP_cert_to_id.3,v 1.15 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt OCSP_CERT_TO_ID 3 +.Os +.Sh NAME +.Nm OCSP_CERTID_new , +.Nm OCSP_CERTID_free , +.Nm OCSP_cert_to_id , +.Nm OCSP_cert_id_new , +.Nm OCSP_id_issuer_cmp , +.Nm OCSP_id_cmp , +.Nm OCSP_id_get0_info +.Nd OCSP certificate ID utility functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ocsp.h +.Ft OCSP_CERTID * +.Fn OCSP_CERTID_new void +.Ft void +.Fn OCSP_CERTID_free "OCSP_CERTID *id" +.Ft OCSP_CERTID * +.Fo OCSP_cert_to_id +.Fa "const EVP_MD *dgst" +.Fa "const X509 *subject" +.Fa "const X509 *issuer" +.Fc +.Ft OCSP_CERTID * +.Fo OCSP_cert_id_new +.Fa "const EVP_MD *dgst" +.Fa "const X509_NAME *issuerName" +.Fa "const ASN1_BIT_STRING *issuerKey" +.Fa "const ASN1_INTEGER *serialNumber" +.Fc +.Ft int +.Fo OCSP_id_issuer_cmp +.Fa "OCSP_CERTID *a" +.Fa "OCSP_CERTID *b" +.Fc +.Ft int +.Fo OCSP_id_cmp +.Fa "OCSP_CERTID *a" +.Fa "OCSP_CERTID *b" +.Fc +.Ft int +.Fo OCSP_id_get0_info +.Fa "ASN1_OCTET_STRING **piNameHash" +.Fa "ASN1_OBJECT **pmd" +.Fa "ASN1_OCTET_STRING **pikeyHash" +.Fa "ASN1_INTEGER **pserial" +.Fa "OCSP_CERTID *cid" +.Fc +.Sh DESCRIPTION +.Fn OCSP_CERTID_new +allocates and initializes an empty +.Vt OCSP_CERTID +object, representing an ASN.1 +.Vt CertID +structure defined in RFC 6960. +It can store hashes of an issuer's distinguished name and public +key together with a serial number of a certificate. +It is used by the +.Vt OCSP_ONEREQ +object described in +.Xr OCSP_ONEREQ_new 3 +and by the +.Vt OCSP_SINGLERESP +object described in +.Xr OCSP_SINGLERESP_new 3 . +.Fn OCSP_CERTID_free +frees +.Fa id . +.Pp +.Fn OCSP_cert_to_id +creates and returns a new +.Vt OCSP_CERTID +object using message digest +.Fa dgst +for certificate +.Fa subject +with issuer +.Fa issuer . +If +.Fa dgst +is +.Dv NULL +then SHA-1 is used. +.Pp +.Fn OCSP_cert_id_new +creates and returns a new +.Vt OCSP_CERTID +using +.Fa dgst +and issuer name +.Fa issuerName , +issuer key hash +.Fa issuerKey +and serial number +.Fa serialNumber . +.Pp +.Fn OCSP_id_issuer_cmp +compares the hash algorithms, +the hashed issuer distinguished names and +the hashed public keys of +.Vt OCSP_CERTID +.Fa a +and +.Fa b . +.Pp +.Fn OCSP_id_cmp +compares +.Vt OCSP_CERTID +.Fa a +and +.Fa b +using +.Fn OCSP_id_issuer_cmp +followed by a comparison of the certificate serial numbers with +.Xr ASN1_INTEGER_cmp 3 . +.Pp +.Fn OCSP_id_get0_info +returns the issuer name hash, hash OID, issuer key hash and serial +number contained in +.Fa cid . +If any of the values are not required, the corresponding parameter can be +set to +.Dv NULL . +The values returned by +.Fn OCSP_id_get0_info +are internal pointers and must not be freed up by an application: +they will be freed when the corresponding +.Vt OCSP_CERTID +object is freed. +.Pp +OCSP clients will typically only use +.Fn OCSP_cert_to_id +or +.Fn OCSP_cert_id_new : +the other functions are used by responder applications. +.Sh RETURN VALUES +.Fn OCSP_CERTID_new , +.Fn OCSP_cert_to_id , +and +.Fn OCSP_cert_id_new +return either a pointer to a valid +.Vt OCSP_CERTID +object or +.Dv NULL +if an error occurred. +.Pp +.Fn OCSP_id_cmp +and +.Fn OCSP_id_issuer_cmp +return 0 for a match or non-zero otherwise. +.Pp +.Fn OCSP_id_get0_info +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr ASN1_INTEGER_cmp 3 , +.Xr EVP_DigestInit 3 , +.Xr OCSP_request_add1_nonce 3 , +.Xr OCSP_REQUEST_new 3 , +.Xr OCSP_resp_find_status 3 , +.Xr OCSP_response_status 3 , +.Xr OCSP_sendreq_new 3 , +.Xr X509_get_issuer_name 3 , +.Xr X509_NAME_new 3 , +.Xr X509_ocspid_print 3 +.Sh STANDARDS +RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate +Status Protocol, section 4: Details of the Protocol +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/OCSP_request_add1_nonce.3 b/static/openbsd/man3/OCSP_request_add1_nonce.3 new file mode 100644 index 00000000..304d686b --- /dev/null +++ b/static/openbsd/man3/OCSP_request_add1_nonce.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: OCSP_request_add1_nonce.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt OCSP_REQUEST_ADD1_NONCE 3 +.Os +.Sh NAME +.Nm OCSP_request_add1_nonce , +.Nm OCSP_basic_add1_nonce , +.Nm OCSP_check_nonce , +.Nm OCSP_copy_nonce +.Nd OCSP nonce functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ocsp.h +.Ft int +.Fo OCSP_request_add1_nonce +.Fa "OCSP_REQUEST *req" +.Fa "unsigned char *val" +.Fa "int len" +.Fc +.Ft int +.Fo OCSP_basic_add1_nonce +.Fa "OCSP_BASICRESP *resp" +.Fa "unsigned char *val" +.Fa "int len" +.Fc +.Ft int +.Fo OCSP_check_nonce +.Fa "OCSP_REQUEST *req" +.Fa "OCSP_BASICRESP *resp" +.Fc +.Ft int +.Fo OCSP_copy_nonce +.Fa "OCSP_BASICRESP *resp" +.Fa "OCSP_REQUEST *req" +.Fc +.Sh DESCRIPTION +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 +.Fn OCSP_request_add1_nonce +adds a nonce of value +.Fa val +and length +.Fa len +to OCSP request +.Fa req . +If +.Fa val +is +.Dv NULL , +a random nonce is used. +If +.Fa len +is zero or negative, a default length will be used (currently 16 bytes). +For most purposes the nonce value in a request is set to a random value +so the +.Fa val +parameter in +.Fn OCSP_request_add1_nonce +is usually NULL. +.Pp +.Fn OCSP_basic_add1_nonce +is identical to +.Fn OCSP_request_add1_nonce +except it adds a nonce to OCSP basic response +.Fa resp . +.Pp +.Fn OCSP_check_nonce +compares the nonce value in +.Fa req +and +.Fa resp . +.Pp +.Fn OCSP_copy_nonce +copies any nonce value present in +.Fa req +to +.Fa resp . +.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. +.Sh RETURN VALUES +.Fn OCSP_request_add1_nonce +and +.Fn OCSP_basic_add1_nonce +return 1 for success or 0 for failure. +.Pp +.Fn OCSP_copy_nonce +returns 1 if a nonce was successfully copied, 2 if no nonce was +present in +.Fa req , +or 0 if an error occurred. +.Pp +.Fn OCSP_check_nonce +returns positive values for success: 1 if nonces are present and +equal, 2 if both nonces are absent, or 3 if a nonce is present in +the response only. +A zero return value indicates that both nonces are present but +mismatch: this should be treated as an error condition. +A return value of -1 indicates that a nonce is present in the request +only: this will happen if the responder doesn't support nonces. +.Sh SEE ALSO +.Xr OCSP_cert_to_id 3 , +.Xr OCSP_REQUEST_new 3 , +.Xr OCSP_resp_find_status 3 , +.Xr OCSP_response_status 3 , +.Xr OCSP_sendreq_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/OCSP_resp_find_status.3 b/static/openbsd/man3/OCSP_resp_find_status.3 new file mode 100644 index 00000000..5e9ce02f --- /dev/null +++ b/static/openbsd/man3/OCSP_resp_find_status.3 @@ -0,0 +1,495 @@ +.\" $OpenBSD: OCSP_resp_find_status.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL c952780c Jun 21 07:03:34 2016 -0400 +.\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016, 2018, 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and David von Oheimb . +.\" Copyright (c) 2014, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt OCSP_RESP_FIND_STATUS 3 +.Os +.Sh NAME +.Nm OCSP_SINGLERESP_new , +.Nm OCSP_SINGLERESP_free , +.Nm OCSP_CERTSTATUS_new , +.Nm OCSP_CERTSTATUS_free , +.Nm OCSP_REVOKEDINFO_new , +.Nm OCSP_REVOKEDINFO_free , +.Nm OCSP_resp_find_status , +.Nm OCSP_cert_status_str , +.Nm OCSP_resp_count , +.Nm OCSP_resp_get0 , +.Nm OCSP_resp_find , +.Nm OCSP_SINGLERESP_get0_id , +.Nm OCSP_single_get0_status , +.Nm OCSP_check_validity , +.Nm OCSP_basic_verify +.Nd OCSP response utility functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ocsp.h +.Ft OCSP_SINGLERESP * +.Fn OCSP_SINGLERESP_new void +.Ft void +.Fn OCSP_SINGLERESP_free "OCSP_SINGLERESP *single" +.Ft OCSP_CERTSTATUS * +.Fn OCSP_CERTSTATUS_new void +.Ft void +.Fn OCSP_CERTSTATUS_free "OCSP_CERTSTATUS *certstatus" +.Ft OCSP_REVOKEDINFO * +.Fn OCSP_REVOKEDINFO_new void +.Ft void +.Fn OCSP_REVOKEDINFO_free "OCSP_REVOKEDINFO *revokedinfo" +.Ft int +.Fo OCSP_resp_find_status +.Fa "OCSP_BASICRESP *bs" +.Fa "OCSP_CERTID *id" +.Fa "int *status" +.Fa "int *reason" +.Fa "ASN1_GENERALIZEDTIME **revtime" +.Fa "ASN1_GENERALIZEDTIME **thisupd" +.Fa "ASN1_GENERALIZEDTIME **nextupd" +.Fc +.Ft const char * +.Fo OCSP_cert_status_str +.Fa "long status" +.Fc +.Ft int +.Fo OCSP_resp_count +.Fa "OCSP_BASICRESP *bs" +.Fc +.Ft OCSP_SINGLERESP * +.Fo OCSP_resp_get0 +.Fa "OCSP_BASICRESP *bs" +.Fa "int idx" +.Fc +.Ft int +.Fo OCSP_resp_find +.Fa "OCSP_BASICRESP *bs" +.Fa "OCSP_CERTID *id" +.Fa "int last" +.Fc +.Ft const OCSP_CERTID * +.Fo OCSP_SINGLERESP_get0_id +.Fa "const OCSP_SINGLERESP *single" +.Fc +.Ft int +.Fo OCSP_single_get0_status +.Fa "OCSP_SINGLERESP *single" +.Fa "int *reason" +.Fa "ASN1_GENERALIZEDTIME **revtime" +.Fa "ASN1_GENERALIZEDTIME **thisupd" +.Fa "ASN1_GENERALIZEDTIME **nextupd" +.Fc +.Ft int +.Fo OCSP_check_validity +.Fa "ASN1_GENERALIZEDTIME *thisupd" +.Fa "ASN1_GENERALIZEDTIME *nextupd" +.Fa "long sec" +.Fa "long maxsec" +.Fc +.Ft int +.Fo OCSP_basic_verify +.Fa "OCSP_BASICRESP *bs" +.Fa "STACK_OF(X509) *certs" +.Fa "X509_STORE *st" +.Fa "unsigned long flags" +.Fc +.Sh DESCRIPTION +.Fn OCSP_SINGLERESP_new +allocates and initializes an empty +.Vt OCSP_SINGLERESP +object, representing an ASN.1 +.Vt SingleResponse +structure defined in RFC 6960. +Each such object can store the server's answer regarding the validity +of one individual certificate. +Such objects are used inside the +.Vt OCSP_RESPDATA +of +.Vt OCSP_BASICRESP +objects, which are described in +.Xr OCSP_BASICRESP_new 3 . +.Fn OCSP_SINGLERESP_free +frees +.Fa single . +.Pp +.Fn OCSP_CERTSTATUS_new +allocates and initializes an empty +.Vt OCSP_CERTSTATUS +object, representing an ASN.1 +.Vt CertStatus +structure defined in RFC 6960. +Such an object is used inside +.Vt OCSP_SINGLERESP . +.Fn OCSP_CERTSTATUS_free +frees +.Fa certstatus . +.Pp +.Fn OCSP_REVOKEDINFO_new +allocates and initializes an empty +.Vt OCSP_REVOKEDINFO +object, representing an ASN.1 +.Vt RevokedInfo +structure defined in RFC 6960. +Such an object is used inside +.Vt OCSP_CERTSTATUS . +.Fn OCSP_REVOKEDINFO_free +frees +.Fa revokedinfo . +.Pp +.Fn OCSP_resp_find_status +searches +.Fa bs +for an OCSP response for +.Fa id . +If it is successful, the fields of the response are returned in +.Pf * Fa status , +.Pf * Fa reason , +.Pf * Fa revtime , +.Pf * Fa thisupd +and +.Pf * Fa nextupd . +The +.Pf * Fa status +value will be one of +.Dv V_OCSP_CERTSTATUS_GOOD , +.Dv V_OCSP_CERTSTATUS_REVOKED , +or +.Dv V_OCSP_CERTSTATUS_UNKNOWN . +The +.Pf * Fa reason +and +.Pf * Fa revtime +fields are only set if the status is +.Dv V_OCSP_CERTSTATUS_REVOKED . +If set, the +.Pf * Fa reason +field will be set to the revocation reason which will be one of +.Dv OCSP_REVOKED_STATUS_NOSTATUS , +.Dv OCSP_REVOKED_STATUS_UNSPECIFIED , +.Dv OCSP_REVOKED_STATUS_KEYCOMPROMISE , +.Dv OCSP_REVOKED_STATUS_CACOMPROMISE , +.Dv OCSP_REVOKED_STATUS_AFFILIATIONCHANGED , +.Dv OCSP_REVOKED_STATUS_SUPERSEDED , +.Dv OCSP_REVOKED_STATUS_CESSATIONOFOPERATION , +.Dv OCSP_REVOKED_STATUS_CERTIFICATEHOLD +or +.Dv OCSP_REVOKED_STATUS_REMOVEFROMCRL . +.Pp +.Fn OCSP_cert_status_str +converts one of the +.Fa status +codes retrieved by +.Fn OCSP_resp_find_status +to a string consisting of one word. +.Pp +.Fn OCSP_resp_count +returns the number of +.Vt OCSP_SINGLERESP +structures in +.Fa bs . +.Pp +.Fn OCSP_resp_get0 +returns the +.Vt OCSP_SINGLERESP +structure in +.Fa bs +corresponding to index +.Fa idx , +where +.Fa idx +runs from 0 to +.Fn OCSP_resp_count bs No - 1 . +.Pp +.Fn OCSP_resp_find +searches +.Fa bs +for +.Fa id +and returns the index of the first matching entry after +.Fa last +or starting from the beginning if +.Fa last +is -1. +.Pp +.Fn OCSP_single_get0_status +extracts the fields of +.Fa single +in +.Pf * Fa reason , +.Pf * Fa revtime , +.Pf * Fa thisupd , +and +.Pf * Fa nextupd . +.Pp +.Fn OCSP_check_validity +checks the validity of +.Fa thisupd +and +.Fa nextupd +values which will be typically obtained from +.Fn OCSP_resp_find_status +or +.Fn OCSP_single_get0_status . +If +.Fa sec +is non-zero, it indicates how many seconds leeway should be allowed in +the check. +If +.Fa maxsec +is positive, it indicates the maximum age of +.Fa thisupd +in seconds. +.Pp +Applications will typically call +.Fn OCSP_resp_find_status +using the certificate ID of interest and then check its validity using +.Fn OCSP_check_validity . +They can then take appropriate action based on the status of the +certificate. +.Pp +An OCSP response for a certificate contains +.Sy thisUpdate +and +.Sy nextUpdate +fields. +Normally the current time should be between these two values. +To account for clock skew, the +.Fa maxsec +field can be set to non-zero in +.Fn OCSP_check_validity . +Some responders do not set the +.Sy nextUpdate +field. +This would otherwise mean an ancient response would be considered +valid: the +.Fa maxsec +parameter to +.Fn OCSP_check_validity +can be used to limit the permitted age of responses. +.Pp +The values written to +.Pf * Fa revtime , +.Pf * Fa thisupd , +and +.Pf * Fa nextupd +by +.Fn OCSP_resp_find_status +and +.Fn OCSP_single_get0_status +are internal pointers which must not be freed up by the calling +application. +Any or all of these parameters can be set to +.Dv NULL +if their value is not required. +.Pp +.Fn OCSP_basic_verify +checks that the basic response message +.Fa bs +is correctly signed and that the signer certificate can be validated. +It takes +.Fa st +as the trusted store and +.Fa certs +as a set of untrusted intermediate certificates. +The function first tries to find the signer certificate of the response in +.Fa certs . +It also searches the certificates the responder may have included in +.Fa bs +unless the +.Fa flags +contain +.Dv OCSP_NOINTERN . +It fails if the signer certificate cannot be found. +Next, the function checks the signature of +.Fa bs +and fails on error unless the +.Fa flags +contain +.Dv OCSP_NOSIGS . +Then the function already returns +success if the +.Fa flags +contain +.Dv OCSP_NOVERIFY +or if the signer certificate was found in +.Fa certs +and the +.Fa flags +contain +.Dv OCSP_TRUSTOTHER . +Otherwise the function continues by validating the signer certificate. +To this end, all certificates in +.Fa certs +and in +.Fa bs +are considered as untrusted certificates for the construction of +the validation path for the signer certificate unless the +.Dv OCSP_NOCHAIN +flag is set. +After successful path +validation, the function returns success if the +.Dv OCSP_NOCHECKS +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 +.Fa flags +do not contain +.Dv OCSP_NOEXPLICIT , +the function checks for explicit trust for OCSP signing +in the root CA certificate. +.Sh RETURN VALUES +.Fn OCSP_SINGLERESP_new , +.Fn OCSP_CERTSTATUS_new , +and +.Fn OCSP_REVOKEDINFO_new +return a pointer to an empty +.Vt OCSP_SINGLERESP , +.Vt OCSP_CERTSTATUS , +or +.Vt OCSP_REVOKEDINFO +object, respectively, or +.Dv NULL +if an error occurred. +.Pp +.Fn OCSP_resp_find_status +returns 1 if +.Fa id +is found in +.Fa bs +or 0 otherwise. +.Pp +.Fn OCSP_cert_status_str +returns a pointer to a static string. +.Pp +.Fn OCSP_resp_count +returns the total number of +.Vt OCSP_SINGLERESP +fields in +.Fa bs . +.Pp +.Fn OCSP_resp_get0 +returns a pointer to an +.Vt OCSP_SINGLERESP +structure or +.Dv NULL +if +.Fa idx +is out of range. +.Pp +.Fn OCSP_resp_find +returns the index of +.Fa id +in +.Fa bs +(which may be 0) or -1 if +.Fa id +was not found. +.Pp +.Fn OCSP_SINGLERESP_get0_id +returns an internal pointer to the certificate ID object used by +.Fa single ; +the returned pointer should not be freed by the caller. +.Pp +.Fn OCSP_single_get0_status +returns the status of +.Fa single +or -1 if an error occurred. +.Pp +.Fn OCSP_basic_verify +returns 1 on success, 0 on error, or -1 on fatal error such as malloc failure. +.Sh SEE ALSO +.Xr OCSP_cert_to_id 3 , +.Xr OCSP_CRLID_new 3 , +.Xr OCSP_request_add1_nonce 3 , +.Xr OCSP_REQUEST_new 3 , +.Xr OCSP_response_status 3 , +.Xr OCSP_sendreq_new 3 +.Sh STANDARDS +RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate +Status Protocol, section 4.2: Response Syntax +.Sh HISTORY +.Fn OCSP_SINGLERESP_new , +.Fn OCSP_SINGLERESP_free , +.Fn OCSP_CERTSTATUS_new , +.Fn OCSP_CERTSTATUS_free , +.Fn OCSP_REVOKEDINFO_new , +.Fn OCSP_REVOKEDINFO_free , +.Fn OCSP_resp_find_status , +.Fn OCSP_cert_status_str , +.Fn OCSP_resp_count , +.Fn OCSP_resp_get0 , +.Fn OCSP_resp_find , +.Fn OCSP_single_get0_status , +and +.Fn OCSP_check_validity +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn OCSP_SINGLERESP_get0_id +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/OCSP_response_status.3 b/static/openbsd/man3/OCSP_response_status.3 new file mode 100644 index 00000000..7fd8267d --- /dev/null +++ b/static/openbsd/man3/OCSP_response_status.3 @@ -0,0 +1,309 @@ +.\" $OpenBSD: OCSP_response_status.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 +.\" selective merge up to: OpenSSL 6738bf14 Feb 13 12:51:29 2018 +0000 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016, 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2014, 2016, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt OCSP_RESPONSE_STATUS 3 +.Os +.Sh NAME +.Nm OCSP_RESPONSE_new , +.Nm OCSP_RESPONSE_free , +.Nm OCSP_RESPBYTES_new , +.Nm OCSP_RESPBYTES_free , +.Nm OCSP_BASICRESP_new , +.Nm OCSP_BASICRESP_free , +.Nm OCSP_RESPDATA_new , +.Nm OCSP_RESPDATA_free , +.Nm OCSP_RESPID_new , +.Nm OCSP_RESPID_free , +.Nm OCSP_response_create , +.Nm OCSP_response_status , +.Nm OCSP_response_status_str , +.Nm OCSP_response_get1_basic , +.Nm OCSP_basic_sign +.Nd OCSP response functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ocsp.h +.Ft OCSP_RESPONSE * +.Fn OCSP_RESPONSE_new void +.Ft void +.Fn OCSP_RESPONSE_free "OCSP_RESPONSE *resp" +.Ft OCSP_RESPBYTES * +.Fn OCSP_RESPBYTES_new void +.Ft void +.Fn OCSP_RESPBYTES_free "OCSP_RESPBYTES *respbytes" +.Ft OCSP_BASICRESP * +.Fn OCSP_BASICRESP_new void +.Ft void +.Fn OCSP_BASICRESP_free "OCSP_BASICRESP *bs" +.Ft OCSP_RESPDATA * +.Fn OCSP_RESPDATA_new void +.Ft void +.Fn OCSP_RESPDATA_free "OCSP_RESPDATA *respdata" +.Ft OCSP_RESPID * +.Fn OCSP_RESPID_new void +.Ft void +.Fn OCSP_RESPID_free "OCSP_RESPID *respid" +.Ft OCSP_RESPONSE * +.Fo OCSP_response_create +.Fa "int status" +.Fa "OCSP_BASICRESP *bs" +.Fc +.Ft int +.Fo OCSP_response_status +.Fa "OCSP_RESPONSE *resp" +.Fc +.Ft const char * +.Fo OCSP_response_status_str +.Fa "long code" +.Fc +.Ft OCSP_BASICRESP * +.Fo OCSP_response_get1_basic +.Fa "OCSP_RESPONSE *resp" +.Fc +.Ft int +.Fo OCSP_basic_sign +.Fa "OCSP_BASICRESP *bs" +.Fa "X509 *signer" +.Fa "EVP_PKEY *key" +.Fa "const EVP_MD *dgst" +.Fa "STACK_OF(X509) *certs" +.Fa "unsigned long flags" +.Fc +.Sh DESCRIPTION +.Fn OCSP_RESPONSE_new +allocates and initializes an empty +.Vt OCSP_RESPONSE +object, representing an ASN.1 +.Vt OCSPResponse +structure defined in RFC 6960. +.Fn OCSP_RESPONSE_free +frees +.Fa resp . +.Pp +.Fn OCSP_RESPBYTES_new +allocates and initializes an empty +.Vt OCSP_RESPBYTES +object, representing an ASN.1 +.Vt ResponseBytes +structure defined in RFC 6960. +Such an object is used inside +.Vt OCSP_RESPONSE . +.Fn OCSP_RESPBYTES_free +frees +.Fa respbytes . +.Pp +.Fn OCSP_BASICRESP_new +allocates and initializes an empty +.Vt OCSP_BASICRESP +object, representing an ASN.1 +.Vt BasicOCSPResponse +structure defined in RFC 6960. +.Vt OCSP_RESPBYTES +contains the DER-encoded form of an +.Vt OCSP_BASICRESP +object. +.Fn OCSP_BASICRESP_free +frees +.Fa bs . +.Pp +.Fn OCSP_RESPDATA_new +allocates and initializes an empty +.Vt OCSP_RESPDATA +object, representing an ASN.1 +.Vt ResponseData +structure defined in RFC 6960. +Such an object is used inside +.Vt OCSP_BASICRESP . +.Fn OCSP_RESPDATA_free +frees +.Fa respdata . +.Pp +.Fn OCSP_RESPID_new +allocates and initializes an empty +.Vt OCSP_RESPID +object, representing an ASN.1 +.Vt ResponderID +structure defined in RFC 6960. +Such an object is used inside +.Vt OCSP_RESPDATA . +.Fn OCSP_RESPID_free +frees +.Fa respid . +.Pp +.Fn OCSP_response_create +creates an +.Vt OCSP_RESPONSE +object for +.Fa status +and optionally including the basic response +.Fa bs . +.Pp +.Fn OCSP_response_status +returns the OCSP response status of +.Fa resp . +It returns one of the values +.Dv OCSP_RESPONSE_STATUS_SUCCESSFUL , +.Dv OCSP_RESPONSE_STATUS_MALFORMEDREQUEST , +.Dv OCSP_RESPONSE_STATUS_INTERNALERROR , +.Dv OCSP_RESPONSE_STATUS_TRYLATER , +.Dv OCSP_RESPONSE_STATUS_SIGREQUIRED , +or +.Dv OCSP_RESPONSE_STATUS_UNAUTHORIZED . +.Pp +.Fn OCSP_response_status_str +converts one of the +.Fa status +codes returned by +.Fn OCSP_response_status +to a string consisting of one word. +.Pp +.Fn OCSP_response_get1_basic +decodes and returns the +.Vt OCSP_BASICRESP +object contained in +.Fa resp . +It is only called if the status of a response is +.Dv OCSP_RESPONSE_STATUS_SUCCESSFUL . +.Pp +.Fn OCSP_basic_sign +signs the OCSP response +.Fa bs +using the certificate +.Fa signer , +the private key +.Fa key , +the digest +.Fa dgst , +and the additional certificates +.Fa certs . +If the +.Fa flags +option +.Dv OCSP_NOCERTS +is set, then no certificates will be included in the request. +If the +.Fa flags +option +.Dv OCSP_RESPID_KEY +is set, then the responder is identified by key ID +rather than by name. +.Sh RETURN VALUES +.Fn OCSP_RESPONSE_new +and +.Fn OCSP_response_create +return a pointer to an +.Vt OCSP_RESPONSE +object or +.Dv NULL +if an error occurred. +.Pp +.Fn OCSP_BASICRESP_new +and +.Fn OCSP_response_get1_basic +return a pointer to an +.Vt OCSP_BASICRESP +object or +.Dv NULL +if an error occurred. +.Pp +.Fn OCSP_RESPBYTES_new , +.Fn OCSP_RESPDATA_new , +and +.Fn OCSP_RESPID_new +return a pointer to an empty +.Vt OCSP_RESPBYTES , +.Vt OCSP_RESPDATA , +or +.Vt OCSP_RESPID +object, respectively, or +.Dv NULL +if an error occurred. +.Pp +.Fn OCSP_response_status +returns a status value. +.Pp +.Fn OCSP_response_status_str +returns a pointer to a static string. +.Pp +.Fn OCSP_basic_sign +return 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr EVP_DigestInit 3 , +.Xr OCSP_cert_to_id 3 , +.Xr OCSP_request_add1_nonce 3 , +.Xr OCSP_REQUEST_new 3 , +.Xr OCSP_resp_find_status 3 , +.Xr OCSP_sendreq_new 3 +.Sh STANDARDS +RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate +Status Protocol, section 4.2: Response Syntax +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/OCSP_sendreq_new.3 b/static/openbsd/man3/OCSP_sendreq_new.3 new file mode 100644 index 00000000..c6608ecc --- /dev/null +++ b/static/openbsd/man3/OCSP_sendreq_new.3 @@ -0,0 +1,324 @@ +.\" $OpenBSD: OCSP_sendreq_new.3,v 1.11 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2019 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt OCSP_SENDREQ_NEW 3 +.Os +.Sh NAME +.Nm OCSP_sendreq_new , +.Nm OCSP_sendreq_nbio , +.Nm OCSP_REQ_CTX_free , +.Nm OCSP_REQ_CTX_add1_header , +.Nm OCSP_REQ_CTX_set1_req , +.Nm OCSP_parse_url , +.Nm OCSP_sendreq_bio +.Nd OCSP responder query functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ocsp.h +.Ft OCSP_REQ_CTX * +.Fo OCSP_sendreq_new +.Fa "BIO *io" +.Fa "const char *path" +.Fa "OCSP_REQUEST *req" +.Fa "int maxline" +.Fc +.Ft int +.Fo OCSP_sendreq_nbio +.Fa "OCSP_RESPONSE **presp" +.Fa "OCSP_REQ_CTX *rctx" +.Fc +.Ft void +.Fo OCSP_REQ_CTX_free +.Fa "OCSP_REQ_CTX *rctx" +.Fc +.Ft int +.Fo OCSP_REQ_CTX_add1_header +.Fa "OCSP_REQ_CTX *rctx" +.Fa "const char *name" +.Fa "const char *value" +.Fc +.Ft int +.Fo OCSP_REQ_CTX_set1_req +.Fa "OCSP_REQ_CTX *rctx" +.Fa "OCSP_REQUEST *req" +.Fc +.Ft int +.Fo OCSP_parse_url +.Fa "const char *url" +.Fa "char **phost" +.Fa "char **pport" +.Fa "char **ppath" +.Fa "int *pssl" +.Fc +.Ft OCSP_RESPONSE * +.Fo OCSP_sendreq_bio +.Fa "BIO *io" +.Fa "const char *path" +.Fa "OCSP_REQUEST *req" +.Fc +.Sh DESCRIPTION +The function +.Fn OCSP_sendreq_new +returns an +.Vt OCSP_REQ_CTX +structure using the responder +.Fa io , +the URI path +.Fa path , +the OCSP request +.Fa req +and with a response header maximum line length of +.Fa maxline . +If +.Fa maxline +is zero, a default value of 4k is used. +The OCSP request +.Fa req +may be set to +.Dv NULL +and provided later if required. +.Pp +The arguments to +.Fn OCSP_sendreq_new +correspond to the components of the URI. +For example, if the responder URI is +.Pa http://ocsp.com/ocspreq , +the BIO +.Fa io +should be connected to host +.Pa ocsp.com +on port 80 and +.Fa path +should be set to +.Qq /ocspreq . +.Pp +.Fn OCSP_sendreq_nbio +performs non-blocking I/O on the OCSP request context +.Fa rctx . +When the operation is complete, it returns the response in +.Pf * Fa presp . +If +.Fn OCSP_sendreq_nbio +indicates an operation should be retried, the corresponding BIO can +be examined to determine which operation (read or write) should be +retried and appropriate action can be taken, for example a +.Xr select 2 +call on the underlying socket. +.Pp +.Fn OCSP_REQ_CTX_free +frees up the OCSP context +.Fa rctx . +.Pp +.Fn OCSP_REQ_CTX_add1_header +adds header +.Fa name +with value +.Fa value +to the context +.Fa rctx . +The added headers are of the form +.Qq Fa name : value +or just +.Qq Fa name +if +.Fa value +is +.Dv NULL . +.Fn OCSP_REQ_CTX_add1_header +can be called more than once to add multiple headers. +It must be called before any calls to +.Fn OCSP_sendreq_nbio . +The +.Fa req +parameter in the initial to +.Fn OCSP_sendreq_new +call must be set to +.Dv NULL +if additional headers are set. +.Pp +.Fn OCSP_REQ_CTX_set1_req +sets the OCSP request in +.Fa rctx +to +.Fa req . +This function should be called after any calls to +.Fn OCSP_REQ_CTX_add1_header . +.Pp +.Fn OCSP_parse_url +is a utility function to parse a +.Fa url +of the form +.Sm off +.Sy http Op Sy s +.Pf :// Ar host +.Op : Ar port +.Op / Ar path +.Sm on +and store pointers to newly allocated copies of the strings +.Ar host , +.Ar port , +and +.Ar path +in +.Pf * phost , +.Pf * pport , +and +.Pf * ppath , +respectively. +By default, +.Pf * ppath +is set to +.Qq / +and +.Pf * pport +to +.Qq 443 +for +.Sy https +or +.Qq 80 +for +.Sy http . +For +.Sy https , +.Pf * Fa pssl +is set to 1; otherwise, to 0. +.Pp +.Fn OCSP_sendreq_bio +performs an OCSP request using the responder +.Fa io , +the URI path +.Fa path , +the OCSP request +.Fa req . +It does not support retries and so cannot handle non-blocking I/O +efficiently. +It is retained for compatibility and its use in new applications +is not recommended. +.Sh RETURN VALUES +.Fn OCSP_sendreq_new +returns a valid +.Vt OCSP_REQ_CTX +structure or +.Dv NULL +if an error occurred. +.Pp +.Fn OCSP_sendreq_nbio +returns 1 if the operation was completed successfully, +-1 if the operation should be retried, +or 0 if an error occurred. +.Pp +.Fn OCSP_REQ_CTX_add1_header , +.Fn OCSP_REQ_CTX_set1_req , +and +.Fn OCSP_parse_url +return 1 for success or 0 for failure. +.Pp +.Fn OCSP_sendreq_bio +returns the +.Vt OCSP_RESPONSE +structure sent by the responder or +.Dv NULL +if an error occurred. +.Sh EXAMPLES +Add a Host header for +.Pa ocsp.com : +.Pp +.Dl OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com"); +.Sh SEE ALSO +.Xr OCSP_cert_to_id 3 , +.Xr OCSP_request_add1_nonce 3 , +.Xr OCSP_REQUEST_new 3 , +.Xr OCSP_resp_find_status 3 , +.Xr OCSP_response_status 3 , +.Xr X509_get1_ocsp 3 +.Sh HISTORY +.Fn OCSP_parse_url +and +.Fn OCSP_sendreq_bio +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn OCSP_sendreq_new , +.Fn OCSP_sendreq_nbio , +and +.Fn OCSP_REQ_CTX_free +first appeared in OpenSSL 0.9.8h and have been available since +.Ox 4.5 . +.Pp +.Fn OCSP_REQ_CTX_add1_header +and +.Fn OCSP_REQ_CTX_set1_req +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Sh CAVEATS +These functions only perform a minimal HTTP query to a responder. +If an application wishes to support more advanced features, it +should use an alternative, more complete, HTTP library. +.Pp +Currently only HTTP POST queries to responders are supported. diff --git a/static/openbsd/man3/OPENSSL_VERSION_NUMBER.3 b/static/openbsd/man3/OPENSSL_VERSION_NUMBER.3 new file mode 100644 index 00000000..929658c2 --- /dev/null +++ b/static/openbsd/man3/OPENSSL_VERSION_NUMBER.3 @@ -0,0 +1,282 @@ +.\" $OpenBSD: OPENSSL_VERSION_NUMBER.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 1f13ad31 Dec 25 17:50:39 2017 +0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2017, 2018 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. +.\" +.\" The original file was written by Ulf Moeller , +.\" Richard Levitte , and +.\" Bodo Moeller . +.\" Copyright (c) 2000, 2002, 2015, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt OPENSSL_VERSION_NUMBER 3 +.Os +.Sh NAME +.Nm OPENSSL_VERSION_NUMBER , +.Nm LIBRESSL_VERSION_NUMBER , +.Nm LIBRESSL_VERSION_TEXT , +.Nm OPENSSL_VERSION_TEXT , +.Nm OpenSSL_version_num , +.Nm OpenSSL_version , +.Nm SSLeay , +.Nm SSLeay_version +.Nd get OpenSSL version number +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/opensslv.h +.Fd #define OPENSSL_VERSION_NUMBER 0x020000000L +.Fd #define LIBRESSL_VERSION_NUMBER 0x02nnnn00fL +.Fd #define LIBRESSL_VERSION_TEXT \(dqLibreSSL 2.n.n\(dq +.Fd #define OPENSSL_VERSION_TEXT LIBRESSL_VERSION_TEXT +.In openssl/crypto.h +.Ft unsigned long +.Fn OpenSSL_version_num void +.Ft const char * +.Fo OpenSSL_version +.Fa "int t" +.Fc +.Ft long +.Fn SSLeay void +.Ft const char * +.Fo SSLeay_version +.Fa "int t" +.Fc +.Sh DESCRIPTION +.Dv OPENSSL_VERSION_NUMBER +and +.Dv LIBRESSL_VERSION_NUMBER +are numeric release version identifiers. +The first two digits contain the major release number, +the third and fourth digits the minor release number, +and the fifth and sixth digits the fix release number. +For OpenSSL, the seventh and eight digits contain the patch release number +and the final digit is 0 for development, 1 to e for betas 1 to 14, or f +for release. +For LibreSSL, +.Dv OPENSSL_VERSION_NUMBER +is always 0x020000000, +and +.Dv LIBRESSL_VERSION_NUMBER +always ends with 00f. +.Pp +For example: +.Bd -literal -offset indent +OPENSSL_VERSION_NUMBER: +0x000906000 == 0.9.6 dev +0x000906023 == 0.9.6b beta 3 +0x00090605f == 0.9.6e release +0x020000000 == 2.0.0 for any version of LibreSSL + +LIBRESSL_VERSION_NUMBER: +0x02070000f == LibreSSL 2.7.0 +.Ed +.Pp +OpenSSL versions prior to 0.9.3 had identifiers < 0x0930. +For versions between 0.9.3 and 0.9.5, +the seventh digit was 1 for release and 0 otherwise, +and the eighth and ninth digits were the patch release number. +.Pp +For example: +.Bd -literal +0x000904100 == 0.9.4 release +0x000905000 == 0.9.5 dev +.Ed +.Pp +OpenSSL 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 +.Fn OpenSSL_version_num +returns +.Dv OPENSSL_VERSION_NUMBER . +.Pp +.Fn OpenSSL_version +returns different strings depending on +.Fa t : +.Bl -tag -width Ds +.It Dv OPENSSL_VERSION +The text variant of the version number, +.Dv OPENSSL_VERSION_TEXT . +For OpenSSL, it includes the release date, for example +.Qq OpenSSL 0.9.5a 1 Apr 2000 . +For LibreSSL, +.Dv LIBRESSL_VERSION_TEXT +is returned. +.It Dv OPENSSL_CFLAGS +The compiler flags set for the compilation process in the form +.Qq compiler: ... +if available or +.Qq compiler: information not available +otherwise. +LibreSSL never provides compiler information. +.It Dv OPENSSL_BUILT_ON +The date of the build process in the form +.Qq built on: ... +if available or +.Qq built on: date not available +otherwise. +LibreSSL never provides information on the build date. +.It Dv OPENSSL_PLATFORM +The Configure target of the library build in the form +.Qq platform: ... +if available or +.Qq platform: information not available +otherwise. +LibreSSL never provides platform information. +.It Dv OPENSSL_DIR +The +.Dv OPENSSLDIR +setting of the library build in the form +.Qq OPENSSLDIR: Qq ... +if available or +.Qq OPENSSLDIR: N/A +otherwise. +For LibreSSL, the default is +.Qq OPENSSLDIR: Qq /etc/ssl . +.It Dv OPENSSL_ENGINES_DIR +The +.Dv ENGINESDIR +setting of the library build in the form +.Qq ENGINESDIR: Qq ... +if available or +.Qq ENGINESDIR: N/A +otherwise. +LibreSSL never provides or uses an +.Dv ENGINESDIR . +.El +.Pp +For an unknown +.Fa t , +the text +.Qq not available +is returned. +.Pp +For backward compatibility, +.Dv SSLEAY_VERSION_NUMBER +is an alias for +.Dv OPENSSL_VERSION_NUMBER +and +.Fn SSLeay +for +.Fn OpenSSL_version_num . +The legacy function +.Fn SSLeay_version +is similar to +.Fn OpenSSL_version +except that it takes arguments +.Dv SSLEAY_VERSION , +.Dv SSLEAY_CFLAGS , +.Dv SSLEAY_BUILT_ON , +.Dv SSLEAY_PLATFORM , +and +.Dv SSLEAY_DIR +which expand to +.Em other +numerical values than the corresponding +.Dv OPENSSL_* +macros. +.Sh RETURN VALUES +.Fn OpenSSL_version_num +and +.Fn SSLeay +return a constant version number. +.Pp +.Fn OpenSSL_version +and +.Fn SSLeay_version +return pointers to static strings. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr OPENSSL_config 3 +.Sh HISTORY +.Fn SSLeay , +.Fn SSLeay_version , +and +.Dv SSLEAY_VERSION_NUMBER +first appeared in SSLeay 0.6.0 and have been available since +.Ox 2.4 . +.Pp +.Dv OPENSSL_VERSION_NUMBER +first appeared in the first OpenSSL release, OpenSSL 0.9.1c, +and has been available since +.Ox 2.6 . +.Pp +.Dv SSLEAY_DIR +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Dv LIBRESSL_VERSION_NUMBER +first appeared in LibreSSL 2.0.0 and +.Ox 5.6 +and got its final format in LibreSSL 2.3.2 and +.Ox 5.9 . +.Dv LIBRESSL_VERSION_TEXT +first appeared in LibreSSL 2.2.2 and +.Ox 5.8 . +.Pp +.Fn OpenSSL_version_num +and +.Fn OpenSSL_version +first appeared in OpenSSL 1.1.0 +and have been available since LibreSSL 2.7.1 and +.Ox 6.3 . diff --git a/static/openbsd/man3/OPENSSL_cleanse.3 b/static/openbsd/man3/OPENSSL_cleanse.3 new file mode 100644 index 00000000..cf16405d --- /dev/null +++ b/static/openbsd/man3/OPENSSL_cleanse.3 @@ -0,0 +1,43 @@ +.\" $OpenBSD: OPENSSL_cleanse.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt OPENSSL_CLEANSE 3 +.Os +.Sh NAME +.Nm OPENSSL_cleanse +.Nd OpenSSL memory cleaning operation +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/crypto.h +.Ft void +.Fo OPENSSL_cleanse +.Fa "void *ptr" +.Fa "size_t len" +.Fc +.Sh DESCRIPTION +Do not use the interface documented here. +It is provided purely for compatibility with legacy application code. +.Pp +.Fn OPENSSL_cleanse +has the same semantics as, and is a wrapper around, +.Xr explicit_bzero 3 . +.Sh SEE ALSO +.Xr crypto 3 +.Sh HISTORY +.Fn OPENSSL_cleanse +first appeared in OpenSSL 0.9.6h and has been available since +.Ox 3.4 . diff --git a/static/openbsd/man3/OPENSSL_config.3 b/static/openbsd/man3/OPENSSL_config.3 new file mode 100644 index 00000000..e21b9817 --- /dev/null +++ b/static/openbsd/man3/OPENSSL_config.3 @@ -0,0 +1,150 @@ +.\" $OpenBSD: OPENSSL_config.3,v 1.18 2025/06/09 12:43:53 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2004 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 9 2025 $ +.Dt OPENSSL_CONFIG 3 +.Os +.Sh NAME +.Nm OPENSSL_config , +.Nm OPENSSL_no_config +.Nd simple crypto and ssl library configuration +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/conf.h +.Ft void +.Fo OPENSSL_config +.Fa "const char *appname" +.Fc +.Ft void +.Fn OPENSSL_no_config void +.Sh DESCRIPTION +.Fn OPENSSL_config +initializes the crypto library and calls +.Xr CONF_modules_load_file 3 +with the standard configuration file and the given +.Fa appname . +If +.Fa appname +is +.Dv NULL , +then the default name +.Sy openssl_conf +is used. +Any errors are ignored. +Further calls to +.Fn OPENSSL_config +have no effect. +.Pp +.Fn OPENSSL_no_config +suppresses the loading of the standard configuration file, so that any +future calls to +.Fn OPENSSL_config +or to +.Xr OPENSSL_init_crypto 3 +will ensure the library is initialized but no configuration +file will be loaded. +.Pp +Calling these functions is optional. +All required initialization of the crypto libraries happens +automatically when needed. +.Pp +To use a non-standard configuration file, refer to +.Xr CONF_modules_load_file 3 . +.Pp +Internally, +.Fn OPENSSL_config +calls +.Xr OPENSSL_init_crypto 3 . +.Pp +If an application is compiled with the preprocessor symbol +.Dv OPENSSL_LOAD_CONF +defined, +.Xr OpenSSL_add_all_algorithms 3 +automatically calls +.Fn OPENSSL_config . +.Pp +Applications should free up configuration at application closedown by +calling +.Xr CONF_modules_free 3 . +.Sh FILES +.Bl -tag -width /etc/ssl/openssl.cnf -compact +.It Pa /etc/ssl/openssl.cnf +standard configuration file +.El +.Sh SEE ALSO +.Xr CONF_modules_free 3 , +.Xr CONF_modules_load_file 3 , +.Xr crypto 3 , +.Xr OPENSSL_VERSION_NUMBER 3 , +.Xr openssl.cnf 5 , +.Xr x509v3.cnf 5 +.Sh HISTORY +.Fn OPENSSL_config +and +.Fn OPENSSL_no_config +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/OPENSSL_init_crypto.3 b/static/openbsd/man3/OPENSSL_init_crypto.3 new file mode 100644 index 00000000..5c29d55a --- /dev/null +++ b/static/openbsd/man3/OPENSSL_init_crypto.3 @@ -0,0 +1,112 @@ +.\" $OpenBSD: OPENSSL_init_crypto.3,v 1.7 2025/06/09 12:43:53 schwarze Exp $ +.\" Copyright (c) 2018, 2020 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 $Mdocdate: June 9 2025 $ +.Dt OPENSSL_INIT_CRYPTO 3 +.Os +.Sh NAME +.Nm OPENSSL_init_crypto , +.Nm OPENSSL_init +.Nd initialise the crypto library +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/crypto.h +.Ft int +.Fo OPENSSL_init_crypto +.Fa "uint64_t options" +.Fa "const void *dummy" +.Fc +.Ft void +.Fn OPENSSL_init void +.Sh DESCRIPTION +These functions are deprecated. +It is never useful for an application program +to call either of them explicitly. +.Pp +The library automatically calls +.Fn OPENSSL_init_crypto +internally with an +.Fa options +argument of 0 whenever needed. +It is safest to assume that any function may do so. +.Pp +To enable or disable the standard configuration file, instead use +.Xr OPENSSL_config 3 +or +.Xr OPENSSL_no_config 3 , +respectively. +To load a non-standard configuration file, refer to +.Xr CONF_modules_load_file 3 . +.Pp +If +.Fn OPENSSL_init_crypto +is called before any other crypto or ssl functions, the crypto +library is initialised by allocating various internal resources, +in particular calling +.Xr ERR_load_crypto_strings 3 . +.Pp +The following +.Fa options +are supported: +.Bl -tag -width Ds +.It Dv OPENSSL_INIT_LOAD_CONFIG +At the end of the initialization, call +.Xr OPENSSL_config 3 +with a +.Dv NULL +argument, loading the default configuration file. +.It Dv OPENSSL_INIT_NO_LOAD_CONFIG +Ignore any later calls to +.Xr OPENSSL_config 3 . +.El +.Pp +The other +.Fa options +flags defined by OpenSSL are all ignored by LibreSSL. +The +.Fa dummy +argument has no effect. +.Pp +If this function is called more than once, none of the calls except +the first one have any effect. +.Pp +.Fn OPENSSL_init +has no effect at all. +.Sh RETURN VALUES +.Fn OPENSSL_init_crypto +is intended to return 1 on success or 0 on error. +.Sh SEE ALSO +.Xr CONF_modules_load_file 3 , +.Xr OPENSSL_config 3 , +.Xr openssl.cnf 5 +.Sh HISTORY +.Fn OPENSSL_init +first appeared in OpenSSL 1.0.0e and has been available since +.Ox 5.3 . +It stopped having any effect in OpenSSL 1.1.1 and in +.Ox 5.6 . +.Pp +.Fn OPENSSL_init_crypto +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . +.Sh BUGS +.Fn OPENSSL_init_crypto +silently ignores almost all kinds of errors. +In particular, if memory allocation fails, initialisation is likely +to remain incomplete, the library may be in an inconsistent internal +state, but the return value will usually indicate success anyway. +There is no way for the application program to find out whether +library initialisation is actually complete, nor to get back to a +consistent state if it isn't. diff --git a/static/openbsd/man3/OPENSSL_init_ssl.3 b/static/openbsd/man3/OPENSSL_init_ssl.3 new file mode 100644 index 00000000..ec840f5e --- /dev/null +++ b/static/openbsd/man3/OPENSSL_init_ssl.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: OPENSSL_init_ssl.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" Copyright (c) 2018 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 $Mdocdate: June 8 2025 $ +.Dt OPENSSL_INIT_SSL 3 +.Os +.Sh NAME +.Nm OPENSSL_init_ssl +.Nd initialise the crypto and ssl libraries +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo OPENSSL_init_ssl +.Fa "uint64_t options" +.Fa "const void *dummy" +.Fc +.Sh DESCRIPTION +This function is deprecated. +It is never useful for any application program to call it explicitly. +The library automatically calls it internally with an +.Fa options +argument of 0 whenever needed. +It is safest to assume that any function may do so. +.Pp +To enable or disable the standard configuration file, instead use +.Xr OPENSSL_config 3 +or +.Xr OPENSSL_no_config 3 , +respectively. +To load a non-standard configuration file, refer to +.Xr CONF_modules_load_file 3 . +.Pp +.Fn OPENSSL_init_ssl +calls +.Xr OPENSSL_init_crypto 3 , +.Xr SSL_load_error_strings 3 , +and +.Xr SSL_library_init 3 . +.Pp +The +.Fa options +argument is passed on to +.Xr OPENSSL_init_crypto 3 +and the +.Fa dummy +argument is ignored. +.Pp +If this function is called more than once, +none of the calls except the first one have any effect. +.Sh RETURN VALUES +.Fn OPENSSL_init_ssl +is intended to return 1 on success or 0 on error. +.Sh SEE ALSO +.Xr CONF_modules_load_file 3 , +.Xr OPENSSL_config 3 , +.Xr ssl 3 +.Sh HISTORY +.Fn OPENSSL_init_ssl +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . +.Sh BUGS +.Fn OPENSSL_init_ssl +silently ignores even more configuration failures than +.Xr OPENSSL_init_crypto 3 . diff --git a/static/openbsd/man3/OPENSSL_malloc.3 b/static/openbsd/man3/OPENSSL_malloc.3 new file mode 100644 index 00000000..6e87d030 --- /dev/null +++ b/static/openbsd/man3/OPENSSL_malloc.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: OPENSSL_malloc.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt OPENSSL_MALLOC 3 +.Os +.Sh NAME +.Nm OPENSSL_malloc , +.Nm OPENSSL_free , +.Nm OPENSSL_strdup , +.Nm CRYPTO_malloc , +.Nm CRYPTO_free , +.Nm CRYPTO_strdup +.Nd legacy OpenSSL memory allocation wrappers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/crypto.h +.Ft void * +.Fo OPENSSL_malloc +.Fa "size_t num" +.Fc +.Ft void +.Fo OPENSSL_free +.Fa "void *addr" +.Fc +.Ft char * +.Fo OPENSSL_strdup +.Fa "const char *str" +.Fc +.Ft void * +.Fo CRYPTO_malloc +.Fa "size_t num" +.Fa "const char *file" +.Fa "int line" +.Fc +.Ft void +.Fo CRYPTO_free +.Fa "void *str" +.Fa "const char *" +.Fa int +.Fc +.Ft char * +.Fo CRYPTO_strdup +.Fa "const char *p" +.Fa "const char *file" +.Fa "int line" +.Fc +.Sh DESCRIPTION +Do not use any of the interfaces documented here in new code. +They are provided purely for compatibility with legacy application code. +.Pp +These functions are wrappers around the corresponding +standard +.Xr malloc 3 , +.Xr free 3 , +and +.Xr strdup 3 +functions. +.Pp +The +.Fn OPENSSL_* +functions are implemented as macros. +.Sh RETURN VALUES +These functions return the same type and value as the corresponding +standard functions. +.Sh SEE ALSO +.Xr crypto 3 +.Sh HISTORY +.Fn CRYPTO_malloc +and +.Fn CRYPTO_free +first appeared in SSLeay 0.6.4 and have been available since +.Ox 2.4 . +.Pp +.Fn OPENSSL_malloc +and +.Fn OPENSSL_free +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Pp +.Fn CRYPTO_strdup +and +.Fn OPENSSL_strdup +first appeared in OpenSSL 0.9.8j and have been available since +.Ox 4.5 . +.Sh CAVEATS +If interoperability with other implementations is required, +memory returned by the library as bare pointers must be freed with +.Fn OPENSSL_free . diff --git a/static/openbsd/man3/OPENSSL_sk_new.3 b/static/openbsd/man3/OPENSSL_sk_new.3 new file mode 100644 index 00000000..632bc9d3 --- /dev/null +++ b/static/openbsd/man3/OPENSSL_sk_new.3 @@ -0,0 +1,554 @@ +.\" $OpenBSD: OPENSSL_sk_new.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2018 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 $Mdocdate: June 8 2025 $ +.Dt OPENSSL_SK_NEW 3 +.Os +.Sh NAME +.Nm sk_new_null , +.Nm sk_new , +.Nm sk_set_cmp_func , +.Nm sk_dup , +.Nm sk_free , +.Nm sk_pop_free , +.Nm sk_num , +.Nm sk_value , +.Nm sk_find , +.Nm sk_sort , +.Nm sk_is_sorted , +.Nm sk_push , +.Nm sk_unshift , +.Nm sk_insert , +.Nm sk_set , +.Nm sk_pop , +.Nm sk_shift , +.Nm sk_delete , +.Nm sk_delete_ptr , +.Nm sk_zero +.Nd variable-sized arrays of void pointers, called OpenSSL stacks +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/stack.h +.Ft _STACK * +.Fn sk_new_null void +.Ft _STACK * +.Fo sk_new +.Fa "int (*compfunc)(const void *, const void *)" +.Fc +.Ft old_function_pointer +.Fo sk_set_cmp_func +.Fa "_STACK *stack" +.Fa "int (*compfunc)(const void *, const void *)" +.Fc +.Ft _STACK * +.Fo sk_dup +.Fa "_STACK *stack" +.Fc +.Ft void +.Fo sk_free +.Fa "_STACK *stack" +.Fc +.Ft void +.Fo sk_pop_free +.Fa "_STACK *stack" +.Fa "void (*freefunc)(void *)" +.Fc +.Ft int +.Fo sk_num +.Fa "const _STACK *stack" +.Fc +.Ft void * +.Fo sk_value +.Fa "const _STACK *stack" +.Fa "int index" +.Fc +.Ft int +.Fo sk_find +.Fa "_STACK *stack" +.Fa "void *wanted" +.Fc +.Ft void +.Fo sk_sort +.Fa "_STACK *stack" +.Fc +.Ft int +.Fo sk_is_sorted +.Fa "const _STACK *stack" +.Fc +.Ft int +.Fo sk_push +.Fa "_STACK *stack" +.Fa "void *new_item" +.Fc +.Ft int +.Fo sk_unshift +.Fa "_STACK *stack" +.Fa "void *new_item" +.Fc +.Ft int +.Fo sk_insert +.Fa "_STACK *stack" +.Fa "void *new_item" +.Fa "int index" +.Fc +.Ft void * +.Fo sk_set +.Fa "_STACK *stack" +.Fa "int index" +.Fa "void *new_item" +.Fc +.Ft void * +.Fo sk_pop +.Fa "_STACK *stack" +.Fc +.Ft void * +.Fo sk_shift +.Fa "_STACK *stack" +.Fc +.Ft void * +.Fo sk_delete +.Fa "_STACK *stack" +.Fa "int index" +.Fc +.Ft void * +.Fo sk_delete_ptr +.Fa "_STACK *stack" +.Fa "void *wanted" +.Fc +.Ft void +.Fo sk_zero +.Fa "_STACK *stack" +.Fc +.Sh DESCRIPTION +OpenSSL introduced an idiosyncratic concept of variable sized arrays +of pointers and somewhat misleadingly called such an array a +.Dq stack . +Intrinsically, and as documented in this manual page, OpenSSL stacks +are not type safe but only handle +.Vt void * +function arguments and return values. +.Pp +OpenSSL also provides a fragile, unusually complicated system of +macro-generated wrappers that offers superficial type safety at the +expense of extensive obfuscation, implemented using large amounts +of autogenerated code involving exceedingly ugly, nested +.Xr cpp 1 +macros; see the +.Xr STACK_OF 3 +manual page for details. +.Pp +The fundamental data type is the +.Vt _STACK +structure. +It stores a variable number of void pointers +and remembers the number of pointers currently stored. +It can optionally hold a pointer to a comparison function. +As long as no comparison function is installed, the order of pointers +is meaningful; as soon as a comparison function is installed, it +becomes ill-defined. +.Pp +.Fn sk_new_null +allocates and initializes a new, empty stack. +.Fn sk_new +is identical except that it also installs +.Fa compfunc +as the comparison function for the new stack object. +.Fn sk_set_cmp_func +installs +.Fa compfunc +for the existing +.Fa stack . +The +.Fa compfunc +is allowed to be +.Dv NULL , +but the +.Fa stack +is not. +.Pp +.Fn sk_dup +creates a shallow copy of the given +.Fa stack , +which must not be a +.Dv NULL +pointer. +It neither copies the objects pointed to from the stack nor +increases their reference counts, but merely copies the pointers. +Extreme care must be taken in order to avoid freeing the memory twice, +for example by calling +.Fn sk_free +on one copy and only calling +.Fn sk_pop_free +on the other. +.Pp +.Fn sk_free +frees the given +.Fa stack . +It does not free any of the pointers stored on the stack. +Unless these pointers are merely copies of pointers owned by +other objects, they must be freed before calling +.Fn sk_free , +in order to avoid leaking memory. +If +.Fa stack +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn sk_pop_free +is severely misnamed. +It does not at all do what one would expect from a function called +.Dq pop . +Instead, it does the same as +.Fn sk_free , +except that it also calls the function +.Fa freefunc +on each of the pointers contained in the +.Fa stack . +If the calls to +.Fa freefunc +are intended to free the memory in use by the objects on the stack, +ensure that no other pointers to the same objects remain elsewhere. +.Pp +.Fn sk_find +searches the +.Fa stack +for the +.Fa wanted +pointer. +If the +.Fa stack +contains more than one copy of the +.Fa wanted +pointer, only the first match is found. +If a comparison function is installed for the stack, the stack is +first sorted with +.Fn sk_sort , +and instead of comparing pointers, two pointers are considered to match +if the comparison function returns 0. +.Pp +.Fn sk_sort +sorts the +.Fa stack +using +.Xr qsort 3 +and the installed comparison function. +If +.Fa stack +is a +.Dv NULL +pointer or already considered sorted, no action occurs. +This function can only be called if a comparison function is installed. +.Pp +.Fn sk_is_sorted +reports whether the +.Fa stack +is considered sorted. +Calling +.Fn sk_new_null +or +.Fn sk_new , +successfully calling +.Fn sk_push , +.Fn sk_unshift , +.Fn sk_insert , +or +.Fn sk_set , +or changing the comparison function sets the state to unsorted. +If a comparison function is installed, calling +.Fn sk_sort , +or +.Fn sk_find +sets the state to sorted. +.Pp +.Fn sk_push +pushes +.Fa new_item +onto the end of the +.Fa stack , +increasing the number of pointers by 1. +If +.Fa stack +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn sk_unshift +inserts +.Fa new_item +at the beginning of the +.Fa stack , +such that it gets the index 0. +The number of pointers increases by 1. +If +.Fa stack +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn sk_insert +inserts the +.Fa new_item +into the +.Fa stack +such that it gets the given +.Fa index . +If +.Fa index +is less than 0 or greater than or equal to +.Fn sk_num stack , +the effect is the same as for +.Fn sk_push . +If +.Fa stack +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn sk_set +replaces the pointer with the given +.Fa index +on the +.Fa stack +with the +.Fa new_item . +The old pointer is not freed, +which may leak memory if no copy of it exists elsewhere. +If +.Fa stack +is a +.Dv NULL +pointer or if +.Fa index +is less than 0 or greater than or equal to +.Fn sk_num stack , +no action occurs. +.Pp +.Fn sk_pop +and +.Fn sk_shift +remove the pointer with the highest or lowest index from the +.Fa stack , +respectively, reducing the number of pointers by 1. +If +.Fa stack +is a +.Dv NULL +pointer or if it is empty, no action occurs. +.Pp +.Fn sk_delete +removes the pointer with the given +.Fa index +from the +.Fa stack , +reducing the number of pointers by 1. +If +.Fa stack +is a +.Dv NULL +pointer or the +.Fa index +is less than 0 or greater than or equal to +.Fn sk_num stack , +no action occurs. +.Pp +.Fn sk_delete_ptr +removes the +.Fa wanted +pointer from the +.Fa stack , +reducing the number of pointers by 1 if it is found. +It never uses a comparison function +but only compares pointers themselves. +The +.Fa stack +pointer must not be +.Dv NULL . +.Pp +.Fn sk_zero +removes all pointers from the +.Fa stack . +It does not free any of the pointers. +Unless these pointers are merely copies of pointers owned by other +objects, they must be freed before calling +.Fn sk_zero , +in order to avoid leaking memory. +If +.Fa stack +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn sk_new_null , +.Fn sk_new , +and +.Fn sk_dup +return a pointer to the newly allocated stack object or +.Dv NULL +if insufficient memory is available. +.Pp +.Fn sk_set_cmp_func +returns a pointer to the comparison function +that was previously installed for the +.Fa stack +or +.Dv NULL +if none was installed. +.Pp +.Fn sk_num +returns the number of pointers currently stored on the +.Fa stack , +or \-1 if +.Fa stack +is a +.Dv NULL +pointer. +.Pp +.Fn sk_value +returns the pointer with the given +.Fa index +from the +.Fa stack , +or +.Dv NULL +if +.Fa stack +is a +.Dv NULL +pointer or if the +.Fa index +is less than 0 or greater than or equal to +.Fn sk_num stack . +.Pp +.Fn sk_find +returns the lowest index considered to match or \-1 if +.Fa stack +is a +.Dv NULL +pointer or if no match is found. +.Pp +.Fn sk_is_sorted +returns 1 if the +.Fa stack +is considered sorted or if it is a +.Dv NULL +pointer, or 0 otherwise. +.Pp +.Fn sk_push , +.Fn sk_unshift , +and +.Fn sk_insert +return the new number of pointers on the +.Fa stack +or 0 if +.Fa stack +is a +.Dv NULL +pointer or if memory allocation fails. +.Pp +.Fn sk_set +returns +.Fa new_item +or +.Dv NULL +if +.Fa stack +is a +.Dv NULL +pointer or if the +.Fa index +is less than 0 or greater than or equal to +.Fn sk_num stack . +.Pp +.Fn sk_pop +and +.Fn sk_shift +return the deleted pointer or +.Dv NULL +if +.Fa stack +is a +.Dv NULL +pointer or if it is empty. +.Pp +.Fn sk_delete +returns the deleted pointer or +.Dv NULL +if +.Fa stack +is a +.Dv NULL +pointer or if the +.Fa index +is less than 0 or greater than or equal to +.Fn sk_num stack . +.Pp +.Fn sk_delete_ptr +returns +.Fa wanted +or +.Dv NULL +if it is not found. +.Sh SEE ALSO +.Xr STACK_OF 3 +.Sh HISTORY +.Fn sk_new_null , +.Fn sk_new , +.Fn sk_free , +.Fn sk_pop_free , +.Fn sk_num , +.Fn sk_value , +.Fn sk_find , +.Fn sk_push , +.Fn sk_unshift , +.Fn sk_insert , +.Fn sk_pop , +.Fn sk_shift , +.Fn sk_delete , +and +.Fn sk_delete_ptr +first appeared in SSLeay 0.5.1. +.Fn sk_set_cmp_func , +.Fn sk_dup , +and +.Fn sk_zero +first appeared in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn sk_set +first appeared in OpenSSL 0.9.3. +.Fn sk_sort +first appeared in OpenSSL 0.9.4. +Both functions have been available since +.Ox 2.6 . +.Pp +.Fn sk_is_sorted +first appeared in OpenSSL 0.9.7e and has been available since +.Ox 3.8 . +.Sh BUGS +Even if a comparison function is installed, empty stacks and +stacks containing a single pointer are sometimes considered +sorted and sometimes considered unsorted. +.Pp +If a comparison function is installed, the concept of +.Dq first match +in +.Fn sk_find +is ill-defined because +.Xr qsort 3 +is not a stable sorting function. +It is probably best to only assume that they return an arbitrary match. diff --git a/static/openbsd/man3/OpenSSL_add_all_algorithms.3 b/static/openbsd/man3/OpenSSL_add_all_algorithms.3 new file mode 100644 index 00000000..68d8799b --- /dev/null +++ b/static/openbsd/man3/OpenSSL_add_all_algorithms.3 @@ -0,0 +1,169 @@ +.\" $OpenBSD: OpenSSL_add_all_algorithms.3,v 1.19 2025/06/12 15:59:30 schwarze Exp $ +.\" full merge up to: OpenSSL b3696a55 Sep 2 09:35:50 2017 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2019, 2023, 2025 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2000, 2003, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 12 2025 $ +.Dt OPENSSL_ADD_ALL_ALGORITHMS 3 +.Os +.Sh NAME +.Nm OpenSSL_add_all_algorithms , +.Nm OpenSSL_add_all_ciphers , +.Nm OpenSSL_add_all_digests , +.Nm EVP_cleanup , +.Nm SSLeay_add_all_algorithms +.\" .Nm OPENSSL_add_all_algorithms_conf , +.\" .Nm OPENSSL_add_all_algorithms_noconf , +.\" .Nm SSLeay_add_all_ciphers , and +.\" .Nm SSLeay_add_all_digests are intentionally undocumented +.\" because they are unused aliases. +.Nd add algorithms to internal table +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft void +.Fn OpenSSL_add_all_algorithms void +.Ft void +.Fn OpenSSL_add_all_ciphers void +.Ft void +.Fn OpenSSL_add_all_digests void +.Ft void +.Fn EVP_cleanup void +.Ft void +.Fn SSLeay_add_all_algorithms void +.Sh DESCRIPTION +These functions are deprecated. +It is never useful for any application program +to call any of them explicitly. +Most of them have no effect except that they may or may not call +.Xr OPENSSL_init_crypto 3 . +.Pp +The library contains internal tables of digest algorithms and ciphers. +It uses these tables to look up digests and ciphers via +.Xr EVP_get_digestbyname 3 +and +.Xr EVP_get_cipherbyname 3 , +respectively. +In LibreSSL, these tables are static constants and do not require +initialization. +.Pp +.Fn OpenSSL_add_all_algorithms +used to add all digests and ciphers to the tables. +If an application is compiled with the preprocessor symbol +.Dv OPENSSL_LOAD_CONF +defined, it also calls +.Xr OPENSSL_config 3 +with a +.Dv NULL +argument, loading the default configuration file. +Relying on this behaviour is not recommended. +If loading a configuration file is desired, call +.Xr OPENSSL_config 3 +or +.Xr CONF_modules_load_file 3 +directly. +.Pp +.Fn OpenSSL_add_all_digests +used to add all digest algorithms to the table. +.Pp +.Fn OpenSSL_add_all_ciphers +used to add all encryption algorithms to the table. +.Pp +.Fn EVP_cleanup +has no effect; it used to remove various kinds of application-supplied +data that is no longer supported in the first place. +.Pp +.Fn SSLeay_add_all_algorithms +is a deprecated alias for +.Fn OpenSSL_add_all_algorithms . +.Pp +.Fn OpenSSL_add_all_algorithms +and +.Fn SSLeay_add_all_algorithms +are implemented as macros. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_EncryptInit 3 , +.Xr OPENSSL_config 3 +.Sh HISTORY +.Fn EVP_cleanup , +.Fn SSLeay_add_all_algorithms , +and precursor functions +.Fn SSLeay_add_all_ciphers +and +.Fn SSLeay_add_all_digests +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn OpenSSL_add_all_algorithms , +.Fn OpenSSL_add_all_ciphers , +and +.Fn OpenSSL_add_all_digests +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Sh BUGS +Although the functions do not return error codes, it is possible for them +to fail. diff --git a/static/openbsd/man3/PEM_ASN1_read.3 b/static/openbsd/man3/PEM_ASN1_read.3 new file mode 100644 index 00000000..016007d4 --- /dev/null +++ b/static/openbsd/man3/PEM_ASN1_read.3 @@ -0,0 +1,173 @@ +.\" $OpenBSD: PEM_ASN1_read.3,v 1.4 2025/07/16 17:59:10 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: July 16 2025 $ +.Dt PEM_ASN1_READ 3 +.Os +.Sh NAME +.Nm d2i_of_void , +.Nm PEM_ASN1_read , +.Nm PEM_ASN1_read_bio +.Nd PEM and DER decode an arbitrary ASN.1 value +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pem.h +.Ft typedef void * +.Fo d2i_of_void +.Fa "void **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft void * +.Fo PEM_ASN1_read +.Fa "d2i_of_void *d2i" +.Fa "const char *name" +.Fa "FILE *in_fp" +.Fa "void **val_out" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft void * +.Fo PEM_ASN1_read_bio +.Fa "d2i_of_void *d2i" +.Fa "const char *name" +.Fa "BIO *in_bp" +.Fa "void **val_out" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Sh DESCRIPTION +These functions read one object from +.Fa in_fp +or +.Fa in_bp +and perform both PEM and DER decoding. +They are needed when more specific decoding functions +like those documented in +.Xr PEM_read_bio_PrivateKey 3 +and +.Xr PEM_read_SSL_SESSION 3 +are inadequate for the type +.Fa name . +.Pp +For PEM decoding, +.Xr PEM_bytes_read_bio 3 +is called internally. +Consequently, the first object of type +.Fa name +is returned and preceding objects of other types are discarded. +If necessary, data is decrypted, using +.Fa cb +and/or +.Fa u +if they are not +.Dv NULL , +as described in the +.Xr pem_password_cb 3 +manual page. +.Pp +For subsequent DER decoding, pass a +.Fa d2i +callback function that is adequate for the type +.Fa name , +typically returning a pointer of a type more specific than +.Ft void * . +For example, +.Xr d2i_ASN1_TYPE 3 +can always be used and its manual page describes the required +behaviour of the callback function to be passed. +Normally, passing a more specific function is more useful; +candidate functions can be found with +.Ql man -k Nm~^d2i_ . +.Pp +For the +.Fa name +argument, the +.Dv PEM_STRING_* +string constants defined in +.In openssl/pem.h +can be used. +.Pp +The +.Fa val_out +argument is useless and its many dangers are described in detail in the +.Xr d2i_ASN1_TYPE 3 +manual page. +To reduce the risk of bugs, always passing +.Dv NULL +is recommended. +.Sh RETURN VALUES +These functions return a pointer to the decoded object or +.Dv NULL +if an error occurs. +They fail if +.Xr PEM_bytes_read_bio 3 +fails, for example because of invalid syntax in the input, an unknown +encryption, or an invalid passphrase entered by the user. +They also fail if +.Fa d2i +returns +.Dv NULL , +for example due to DER decoding errors. +.Pp +.Fn PEM_ASN1_read +may also fail if memory is exhausted. +.Sh EXAMPLES +Typical usage of +.Fn PEM_ASN1_read +is demonstrated by the implementation of the more specific function +to PEM and DER decode an X.509 certificate: +.Bd -literal -offset 2n +X509 * +PEM_read_X509(FILE *fp, X509 **val_out, pem_password_cb *cb, void *u) +{ + return PEM_ASN1_read((d2i_of_void *)d2i_X509, PEM_STRING_X509, + fp, (void **)val_out, cb, u); +} +.Ed +.Sh ERRORS +Diagnostics that can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 +include: +.Bl -tag -width Ds +.It Dv ERR_R_BUF_LIB Qq "BUF lib" +.Fn PEM_ASN1_read +failed to set up a temporary BIO, +for example because memory was exhausted. +.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib" +.Fa d2i +returned +.Dv NULL , +for example due to a DER syntax error. +.El +.Pp +Additional types of errors can result from +.Xr PEM_bytes_read_bio 3 . +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr d2i_ASN1_TYPE 3 , +.Xr PEM_bytes_read_bio 3 , +.Xr PEM_read 3 , +.Xr PEM_read_bio_PrivateKey 3 , +.Xr PEM_read_SSL_SESSION 3 , +.Xr PEM_X509_INFO_read_bio 3 +.Sh HISTORY +These functions first appeared in SSLeay 0.5.1 +and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/PEM_X509_INFO_read_bio.3 b/static/openbsd/man3/PEM_X509_INFO_read_bio.3 new file mode 100644 index 00000000..7d34951d --- /dev/null +++ b/static/openbsd/man3/PEM_X509_INFO_read_bio.3 @@ -0,0 +1,173 @@ +.\" $OpenBSD: PEM_X509_INFO_read_bio.3,v 1.1 2025/07/17 10:31:50 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: July 17 2025 $ +.Dt PEM_X509_INFO_READ_BIO 3 +.Os +.Sh NAME +.Nm PEM_X509_INFO_read_bio +.Nd PEM and DER decode X.509 certificates, private keys, and revocation lists +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pem.h +.Ft STACK_OF(X509_INFO) * +.Fo PEM_X509_INFO_read_bio +.Fa "BIO *in_bp" +.Fa "STACK_OF(X509_INFO) *sk" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Sh DESCRIPTION +This function reads zero or more objects +related to X.509 certificates from +.Fa in_bp , +performs both PEM and DER decoding, +and wraps the resulting objects in newly allocated +.Vt X509_INFO +containers. +.Pp +Setting +.Fa sk +to +.Dv NULL +is recommended, in which case +a new stack is allocated, populated, and returned. +If an existing +.Fa sk +is passed in, the created +.Vt X509_INFO +objects are pushed onto that stack. +.Pp +For PEM decoding, +.Xr PEM_read_bio 3 +is used internally, implying that any non-PEM data +before, between, and after the objects is silently discarded. +.Pp +For subsequent DER decoding, +the decoding function and the field of the +.Vt X509_INFO +structure to store the new object in +are selected according to the PEM type name: +.Bl -column "TRUSTED CERTIFICATE" "d2i_PrivateKey()" "revocation list" +.It PEM type name Ta decoder Ta Vt X509_INFO No field +.It CERTIFICATE Ta Xr d2i_X509 3 Ta certificate +.It X509 CERTIFICATE Ta Xr d2i_X509 3 Ta certificate +.It TRUSTED CERTIFICATE Ta Xr d2i_X509_AUX 3 Ta certificate +.It X509 CRL Ta Xr d2i_X509_CRL 3 Ta revocation list +.It RSA PRIVATE KEY Ta Xr d2i_PrivateKey 3 Ta private key +.It DSA PRIVATE KEY Ta Xr d2i_PrivateKey 3 Ta private key +.It EC PRIVATE KEY Ta Xr d2i_PrivateKey 3 Ta private key +.El +.Pp +Whenever the selected field is already occupied, another new +.Vt X509_INFO +container is allocated and pushed onto the stack. +Depending on the sequence of objects in the input, this can result +in several partially populated +.Vt X509_INFO +containers being pushed onto the stack. +.Pp +PEM objects of types not listed in the above table are silently skipped. +.Pp +Encrypted certificates and revocation lists are decrypted by calling +.Xr PEM_do_header 3 +internally, passing through the optional arguments +.Fa cb +and +.Fa u . +Encrypted private keys are not decrypted. +Instead, the encrypted form is stored as read. +All the same, +.Xr PEM_get_EVP_CIPHER_INFO 3 +is called internally to check that PEM headers, if there are any, +are valid and specify an encryption the library is prepared to handle. +.Pp +If any error occurs, objects that had already been read +during the same call are deleted again and +.Fa sk +is left unchanged. +.Sh RETURN VALUES +This function returns a pointer to the stack +the objects read were pushed onto or +.Dv NULL +if an error occurs. +It fails if +.Xr PEM_read_bio 3 , +.Xr PEM_get_EVP_CIPHER_INFO 3 , +.Xr PEM_do_header 3 , +or DER decoding fails or if memory is exhausted. +.Sh ERRORS +Diagnostics that can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 +include: +.Bl -tag -width Ds +.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib" +DER decoding of a PEM object failed. +.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" +.Fn PEM_X509_INFO_read_bio +failed to allocate a new +.Vt X509_INFO , +.Vt STACK_OF(X509_INFO) , +or +.Vt X509_PKEY +object. +.El +.Pp +Additional types of errors can result from +.Xr PEM_read_bio 3 , +.Xr PEM_get_EVP_CIPHER_INFO 3 , +and +.Xr PEM_do_header 3 . +.Pp +After this function failed due to memory exhaustion, +.Xr ERR_get_error 3 +may sometimes return 0 anyway. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr d2i_PrivateKey 3 , +.Xr d2i_X509 3 , +.Xr d2i_X509_CRL 3 , +.Xr EVP_PKEY_new 3 , +.Xr PEM_read 3 , +.Xr PEM_read_bio_PrivateKey 3 , +.Xr STACK_OF 3 , +.Xr X509_CRL_new 3 , +.Xr X509_INFO_new 3 , +.Xr X509_LOOKUP_new 3 , +.Xr X509_new 3 +.Sh HISTORY +.Fn PEM_X509_INFO_read_bio +first appeared in SSLeay 0.6.0 and has been available since +.Ox 2.4 . +.Sh CAVEATS +It is not an error +if the input does not contain any objects of the desired types. +In that case, nothing is added to +.Fa sk , +or if +.Fa sk +is +.Dv NULL , +a newly allocated, empty stack is returned. +The only way to detect this situation is by comparing +the number of objects on the stack before and after the call. +.Sh BUGS +When reaching the end of the input, this function calls +.Xr ERR_clear_error 3 , +which may hide errors that occurred before calling it. diff --git a/static/openbsd/man3/PEM_bytes_read_bio.3 b/static/openbsd/man3/PEM_bytes_read_bio.3 new file mode 100644 index 00000000..69cb26ce --- /dev/null +++ b/static/openbsd/man3/PEM_bytes_read_bio.3 @@ -0,0 +1,185 @@ +.\" $OpenBSD: PEM_bytes_read_bio.3,v 1.8 2025/07/16 17:59:10 schwarze Exp $ +.\" selective merge up to: +.\" OpenSSL PEM_bytes_read_bio.pod 7671342e Feb 29 15:47:12 2016 -0600 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" Copyright (c) 2020 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. +.\" +.\" The original file was written by Benjamin Kaduk . +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: July 16 2025 $ +.Dt PEM_BYTES_READ_BIO 3 +.Os +.Sh NAME +.Nm PEM_bytes_read_bio +.Nd read a PEM-encoded data structure from a BIO +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pem.h +.Ft int +.Fo PEM_bytes_read_bio +.Fa "unsigned char **pdata" +.Fa "long *plen" +.Fa "char **pnm" +.Fa "const char *name" +.Fa "BIO *in_bp" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Sh DESCRIPTION +.Fn PEM_bytes_read_bio +reads and PEM decodes the first object of type +.Fa name +.Pq e.g. RSA PRIVATE KEY, CERTIFICATE, etc.\& +from +.Fa in_bp . +If multiple PEM-encoded data structures are present in the same stream, +it skips non-matching data types and continues reading. +Before reading each PEM object, lines not starting with +.Qq "-----BEGIN " +are also skipped; see +.Xr PEM_read_bio 3 +for details of PEM parsing. +.Pp +The PEM header may indicate that the following data is encrypted; if so, +the data is decrypted, optionally using +.Fa cb +and +.Fa u , +as described in +.Xr pem_password_cb 3 . +.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 +.Em *pnm +if +.Fa pnm +is +.Pf non- Dv NULL . +The caller must free the storage pointed to by +.Em *pnm . +.Pp +The returned data is the DER-encoded form of the requested type, in +.Em *pdata +with length +.Em *plen . +The caller must free the storage pointed to by +.Em *pdata . +.Sh RETURN VALUES +.Fn PEM_bytes_read_bio +returns 1 for success or 0 for failure. +.Sh ERRORS +Diagnostics that can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 +include: +.Bl -tag -width Ds +.It Dv PEM_R_NO_START_LINE Qq no start line +No more PEM objects were found in the input. +This can happen when the input contains no PEM objects at all, +or only objects that do not match the type +.Fa name . +.It Dv PEM_R_NOT_PROC_TYPE Qq not proc type +The first PEM header does not start with +.Qq "Proc-Type: " . +.It Dv PEM_R_NOT_ENCRYPTED Qq not encrypted +The Proc-Type header differs from +.Qq 4,ENCRYPTED . +.It Dv PEM_R_SHORT_HEADER Qq short header +The Proc-Type header is the last header line. +.It Dv PEM_R_NOT_DEK_INFO Qq not dek info +The second PEM header does not start with +.Qq "DEK-Info: " . +.It Dv PEM_R_UNSUPPORTED_ENCRYPTION Qq unsupported encryption +The cipher name given in the DEK-Info header is unknown to +.Xr EVP_get_cipherbyname 3 . +.It Dv PEM_R_BAD_IV_CHARS Qq "bad iv chars" +The word following the cipher name in the DEK-Info header +contains bytes that are not hexadecimal digits. +This also happens when the initialization vector is missing or too short. +.It Dv PEM_R_BAD_PASSWORD_READ Qq bad password read +.Fa cb +reported failure. +This may for example happen when the user mistypes the password. +.It Dv PEM_R_BAD_DECRYPT Qq bad decrypt +.Xr EVP_DecryptInit_ex 3 , +.Xr EVP_DecryptUpdate 3 , +or +.Xr EVP_DecryptFinal_ex 3 +failed. +.El +.Pp +Additional types of errors can result from +.Xr PEM_read_bio 3 . +.Sh SEE ALSO +.Xr PEM_ASN1_read 3 , +.Xr PEM_read 3 , +.Xr PEM_read_bio_PrivateKey 3 , +.Xr PEM_X509_INFO_read_bio 3 +.Sh STANDARDS +RFC 1421: Privacy Enhancement for Internet Electronic Mail (PEM), Part I +.Sh HISTORY +.Fn PEM_bytes_read_bio +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/PEM_read.3 b/static/openbsd/man3/PEM_read.3 new file mode 100644 index 00000000..de93b3e9 --- /dev/null +++ b/static/openbsd/man3/PEM_read.3 @@ -0,0 +1,417 @@ +.\" $OpenBSD: PEM_read.3,v 1.17 2025/07/16 17:59:10 schwarze Exp $ +.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2020 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. +.\" +.\" The original file was written by Viktor Dukhovni +.\" and by Rich Salz . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: July 16 2025 $ +.Dt PEM_READ 3 +.Os +.Sh NAME +.Nm PEM_write , +.Nm PEM_write_bio , +.Nm PEM_read , +.Nm PEM_read_bio , +.Nm PEM_get_EVP_CIPHER_INFO , +.Nm PEM_do_header , +.Nm PEM_def_callback , +.Nm pem_password_cb +.Nd PEM encoding routines +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pem.h +.Ft int +.Fo PEM_write +.Fa "FILE *fp" +.Fa "const char *name" +.Fa "const char *header" +.Fa "const unsigned char *data" +.Fa "long len" +.Fc +.Ft int +.Fo PEM_write_bio +.Fa "BIO *bp" +.Fa "const char *name" +.Fa "const char *header" +.Fa "const unsigned char *data" +.Fa "long len" +.Fc +.Ft int +.Fo PEM_read +.Fa "FILE *fp" +.Fa "char **name" +.Fa "char **header" +.Fa "unsigned char **data" +.Fa "long *len" +.Fc +.Ft int +.Fo PEM_read_bio +.Fa "BIO *bp" +.Fa "char **name" +.Fa "char **header" +.Fa "unsigned char **data" +.Fa "long *len" +.Fc +.Ft int +.Fo PEM_get_EVP_CIPHER_INFO +.Fa "char *header" +.Fa "EVP_CIPHER_INFO *cinfo" +.Fc +.Ft int +.Fo PEM_do_header +.Fa "EVP_CIPHER_INFO *cinfo" +.Fa "unsigned char *data" +.Fa "long *len" +.Fa "pem_password_cb *cb" +.Fa "void *userdata" +.Fc +.Ft int +.Fo PEM_def_callback +.Fa "char *password" +.Fa "int size" +.Fa "int verify" +.Fa "void *userdata" +.Fc +.Ft typedef int +.Fo pem_password_cb +.Fa "char *password" +.Fa "int size" +.Fa "int verify" +.Fa "void *userdata" +.Fc +.Sh DESCRIPTION +These functions read and write PEM-encoded objects, using the PEM type +.Fa name , +any additional +.Fa header +information, and the raw +.Fa data +of length +.Fa len . +.Pp +PEM is the 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: +.Bd -literal -offset indent +-----BEGIN PRIVATE KEY----- +MIICdg.... +\&... bhTQ== +-----END PRIVATE KEY----- +.Ed +.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 +.Fn PEM_write +writes to the file +.Fa fp , +while +.Fn PEM_write_bio +writes to the BIO +.Fa bp . +The +.Fa name +is the name to use in the marker, the +.Fa header +is the header value or +.Dv NULL , +and +.Fa data +and +.Fa len +specify the data and its length. +.Pp +The final +.Fa data +buffer is typically an ASN.1 object which can be decoded with the +.Fn d2i_* +function appropriate to the type +.Fa name ; +see +.Xr d2i_X509 3 +for examples. +.Pp +.Fn PEM_read +reads from the file +.Fa fp , +while +.Fn PEM_read_bio +reads from the BIO +.Fa bp . +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 +.Fa name +argument, any encapsulation headers are returned in +.Fa header , +and the base64-decoded content and its length are returned via +.Fa data +and +.Fa len , +respectively. +The +.Fa name , +.Fa header , +and +.Fa data +pointers should be freed by the caller when no longer needed. +.Pp +The remaining functions are deprecated 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 +.Xr PEM_write_PrivateKey 3 +and +.Xr d2i_PKCS8PrivateKey_bio 3 . +.Pp +.Fn PEM_get_EVP_CIPHER_INFO +can be used to determine the +.Fa data +returned by +.Fn PEM_read +or +.Fn PEM_read_bio +is encrypted and to retrieve the associated cipher and IV. +The caller passes a pointer to a structure of type +.Vt EVP_CIPHER_INFO +via the +.Fa cinfo +argument and the +.Fa header +returned via +.Fn PEM_read +or +.Fn PEM_read_bio . +If the call is successful, 1 is returned and the cipher and IV are +stored at the address pointed to by +.Fa cinfo . +When the header is malformed or not supported or when the cipher is +unknown or some internal error happens, 0 is returned. +.Pp +.Fn PEM_do_header +can then be used to decrypt the data if the header indicates encryption. +The +.Fa cinfo +argument is a pointer to the structure initialized by a preceding call +to +.Fn PEM_get_EVP_CIPHER_INFO . +If that structure indicates the absence of encryption, +.Fn PEM_do_header +returns successfully without taking any action. +The +.Fa data +and +.Fa len +arguments are used both to pass in the encrypted data that was +returned in the same arguments from the preceding call to +.Fn PEM_read +or +.Fn PEM_read_bio +and to pass out the decrypted data. +.Pp +The callback function +.Fa cb +is used to obtain the encryption +.Fa password ; +if +.Fa cb +is +.Dv NULL , +.Fn PEM_def_callback +is used instead. +The +.Fa password +buffer needs to be at least +.Fa size +bytes long. +Unless +.Fa userdata +is +.Dv NULL , +.Fn PEM_def_callback +ignores the +.Fa verify +argument and copies the NUL-terminated byte string +.Fa userdata +to +.Fa password +without a terminating NUL byte, silently truncating the copy to at most +.Fa size +bytes. +If +.Fa userdata +is +.Dv NULL , +.Fn PEM_def_callback +instead prompts the user for the password with echoing turned off +by calling +.Xr EVP_read_pw_string_min 3 +internally. +In this case, the +.Fa size +is silently reduced to at most +.Dv BUFSIZ +and at most +.Fa size No \- 1 +bytes are accepted from the user and copied into the byte string buffer +.Fa password . +A callback function +.Fa cb +supplied by the application may use +.Fa userdata +for a different purpose than +.Fn PEM_def_callback +does, e.g., as auxiliary data to use while acquiring the password. +For example, a GUI application might pass a window handle. +If the +.Fa verify +flag is non-zero, the user is prompted twice for the password to +make typos less likely and it is checked that both inputs agree. +This flag is not set by +.Fn PEM_do_header +nor by other read functions, but it is typically set by write functions. +.Pp +If the data is a priori known to not be encrypted, then neither +.Fn PEM_get_EVP_CIPHER_INFO +nor +.Fn PEM_do_header +need to be called. +.Sh RETURN VALUES +.Fn PEM_read +and +.Fn PEM_read_bio +return 1 on success or 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 +.Dv PEM_R_NO_START_LINE , +which indicates that no more PEM objects were found. +See +.Xr ERR_peek_last_error 3 +and +.Xr ERR_GET_REASON 3 . +.Pp +.Fn PEM_get_EVP_CIPHER_INFO +and +.Fn PEM_do_header +return 1 on success or 0 on failure. +The +.Fa data +is likely meaningless if these functions fail. +.Pp +.Fn PEM_def_callback +returns the number of bytes stored into +.Fa buf +or a negative value on failure, and +.Fa cb +is expected to behave in the same way. +If +.Fa userdata +is +.Dv NULL , +.Fn PEM_def_callback +fails if +.Fa num +is less than 5 +or if an error occurs trying to prompt the user for the password. +Otherwise, it fails when +.Fa num +is negative. +The details of the circumstances that cause +.Fa cb +to fail may differ. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_PKCS8PrivateKey_bio 3 , +.Xr PEM_ASN1_read 3 , +.Xr PEM_bytes_read_bio 3 , +.Xr PEM_read_bio_PrivateKey 3 , +.Xr PEM_read_SSL_SESSION 3 , +.Xr PEM_write_bio_CMS_stream 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +.Xr PEM_X509_INFO_read_bio 3 +.Sh HISTORY +.Fn PEM_write , +.Fn PEM_read , +and +.Fn PEM_do_header +appeared in SSLeay 0.4 or earlier. +.Fn PEM_get_EVP_CIPHER_INFO +first appeared in SSLeay 0.5.1. +.Fn PEM_write_bio +and +.Fn PEM_read_bio +first appeared in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn PEM_def_callback +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/PEM_read_SSL_SESSION.3 b/static/openbsd/man3/PEM_read_SSL_SESSION.3 new file mode 100644 index 00000000..93bd0b8e --- /dev/null +++ b/static/openbsd/man3/PEM_read_SSL_SESSION.3 @@ -0,0 +1,148 @@ +.\" $OpenBSD: PEM_read_SSL_SESSION.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL doc/man3/PEM_read_CMS.pod b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Rich Salz . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PEM_READ_SSL_SESSION 3 +.Os +.Sh NAME +.Nm PEM_read_SSL_SESSION , +.Nm PEM_read_bio_SSL_SESSION , +.Nm PEM_write_SSL_SESSION , +.Nm PEM_write_bio_SSL_SESSION +.Nd encode and decode SSL session objects in PEM format +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft SSL_SESSION * +.Fo PEM_read_SSL_SESSION +.Fa "FILE *fp" +.Fa "SSL_SESSION **a" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft SSL_SESSION * +.Fo PEM_read_bio_SSL_SESSION +.Fa "BIO *bp" +.Fa "SSL_SESSION **a" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_SSL_SESSION +.Fa "FILE *fp" +.Fa "const SSL_SESSION *a" +.Fc +.Ft int +.Fo PEM_write_bio_SSL_SESSION +.Fa "BIO *bp" +.Fa "const SSL_SESSION *a" +.Fc +.Sh DESCRIPTION +These routines convert between local instances of ASN.1 +.Vt SSL_SESSION +objects and the PEM encoding. +.Pp +.Fn PEM_read_SSL_SESSION +reads a PEM-encoded +.Vt SSL_SESSION +object from the file +.Fa fp +and returns it. +The +.Fa cb +and +.Fa u +parameters are as described in +.Xr PEM_read_bio_PrivateKey 3 . +.Pp +.Fn PEM_read_bio_SSL_SESSION +is similar to +.Fn PEM_read_SSL_SESSION +but reads from the BIO +.Fa bp . +.Pp +.Fn PEM_write_SSL_SESSION +writes the PEM encoding of the object +.Fa a +to the file +.Fa fp . +.Pp +.Fn PEM_write_bio_SSL_SESSION +similarly writes to the BIO +.Fa bp . +.Sh RETURN VALUES +.Fn PEM_read_SSL_SESSION +and +.Fn PEM_read_bio_SSL_SESSION +return a pointer to an allocated object, which should be released by +calling +.Xr SSL_SESSION_free 3 , +or +.Dv NULL +on error. +.Pp +.Fn PEM_write_SSL_SESSION +and +.Fn PEM_write_bio_SSL_SESSION +return the number of bytes written or 0 on error. +.Sh SEE ALSO +.Xr PEM_read 3 , +.Xr ssl 3 +.Sh HISTORY +.Fn PEM_read_SSL_SESSION +and +.Fn PEM_write_SSL_SESSION +first appeared in SSLeay 0.5.2. +.Fn PEM_read_bio_SSL_SESSION +and +.Fn PEM_write_bio_SSL_SESSION +first appeared in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/PEM_read_bio_PrivateKey.3 b/static/openbsd/man3/PEM_read_bio_PrivateKey.3 new file mode 100644 index 00000000..9ef136de --- /dev/null +++ b/static/openbsd/man3/PEM_read_bio_PrivateKey.3 @@ -0,0 +1,1336 @@ +.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.25 2025/07/16 17:59:10 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL man3/PEM_read_bio_PrivateKey.pod 18bad535 Apr 9 15:13:55 2019 +0100 +.\" OpenSSL man3/PEM_read_CMS.pod 83cf7abf May 29 13:07:08 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2001-2004, 2009, 2013-2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: July 16 2025 $ +.Dt PEM_READ_BIO_PRIVATEKEY 3 +.Os +.Sh NAME +.Nm PEM_read_bio_PrivateKey , +.Nm PEM_read_PrivateKey , +.Nm PEM_write_bio_PrivateKey , +.Nm PEM_write_PrivateKey , +.Nm PEM_write_bio_PKCS8PrivateKey , +.Nm PEM_write_PKCS8PrivateKey , +.Nm PEM_write_bio_PKCS8PrivateKey_nid , +.Nm PEM_write_PKCS8PrivateKey_nid , +.Nm PEM_read_bio_PKCS8 , +.Nm PEM_read_PKCS8 , +.Nm PEM_write_bio_PKCS8 , +.Nm PEM_write_PKCS8 , +.Nm PEM_read_bio_PKCS8_PRIV_KEY_INFO , +.Nm PEM_read_PKCS8_PRIV_KEY_INFO , +.Nm PEM_write_bio_PKCS8_PRIV_KEY_INFO , +.Nm PEM_write_PKCS8_PRIV_KEY_INFO , +.Nm PEM_read_bio_PUBKEY , +.Nm PEM_read_PUBKEY , +.Nm PEM_write_bio_PUBKEY , +.Nm PEM_write_PUBKEY , +.Nm PEM_read_bio_RSAPrivateKey , +.Nm PEM_read_RSAPrivateKey , +.Nm PEM_write_bio_RSAPrivateKey , +.Nm PEM_write_RSAPrivateKey , +.Nm PEM_read_bio_RSAPublicKey , +.Nm PEM_read_RSAPublicKey , +.Nm PEM_write_bio_RSAPublicKey , +.Nm PEM_write_RSAPublicKey , +.Nm PEM_read_bio_RSA_PUBKEY , +.Nm PEM_read_RSA_PUBKEY , +.Nm PEM_write_bio_RSA_PUBKEY , +.Nm PEM_write_RSA_PUBKEY , +.Nm PEM_read_bio_DSAPrivateKey , +.Nm PEM_read_DSAPrivateKey , +.Nm PEM_write_bio_DSAPrivateKey , +.Nm PEM_write_DSAPrivateKey , +.Nm PEM_read_bio_DSA_PUBKEY , +.Nm PEM_read_DSA_PUBKEY , +.Nm PEM_write_bio_DSA_PUBKEY , +.Nm PEM_write_DSA_PUBKEY , +.Nm PEM_read_bio_DSAparams , +.Nm PEM_read_DSAparams , +.Nm PEM_write_bio_DSAparams , +.Nm PEM_write_DSAparams , +.Nm PEM_read_bio_DHparams , +.Nm PEM_read_DHparams , +.Nm PEM_write_bio_DHparams , +.Nm PEM_write_DHparams , +.Nm PEM_read_bio_ECPKParameters , +.Nm PEM_read_ECPKParameters , +.Nm PEM_write_bio_ECPKParameters , +.Nm PEM_write_ECPKParameters , +.Nm PEM_read_bio_ECPrivateKey , +.Nm PEM_read_ECPrivateKey , +.Nm PEM_write_bio_ECPrivateKey , +.Nm PEM_write_ECPrivateKey , +.Nm PEM_read_bio_EC_PUBKEY , +.Nm PEM_read_EC_PUBKEY , +.Nm PEM_write_bio_EC_PUBKEY , +.Nm PEM_write_EC_PUBKEY , +.Nm PEM_read_bio_X509 , +.Nm PEM_read_X509 , +.Nm PEM_write_bio_X509 , +.Nm PEM_write_X509 , +.Nm PEM_read_bio_X509_AUX , +.Nm PEM_read_X509_AUX , +.Nm PEM_write_bio_X509_AUX , +.Nm PEM_write_X509_AUX , +.Nm PEM_read_bio_X509_REQ , +.Nm PEM_read_X509_REQ , +.Nm PEM_write_bio_X509_REQ , +.Nm PEM_write_X509_REQ , +.Nm PEM_write_bio_X509_REQ_NEW , +.Nm PEM_write_X509_REQ_NEW , +.Nm PEM_read_bio_X509_CRL , +.Nm PEM_read_X509_CRL , +.Nm PEM_write_bio_X509_CRL , +.Nm PEM_write_X509_CRL , +.Nm PEM_read_bio_PKCS7 , +.Nm PEM_read_PKCS7 , +.Nm PEM_write_bio_PKCS7 , +.Nm PEM_write_PKCS7 , +.Nm PEM_read_CMS , +.Nm PEM_read_bio_CMS , +.Nm PEM_write_CMS , +.Nm PEM_write_bio_CMS +.Nd PEM routines +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pem.h +.Ft EVP_PKEY * +.Fo PEM_read_bio_PrivateKey +.Fa "BIO *bp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EVP_PKEY * +.Fo PEM_read_PrivateKey +.Fa "FILE *fp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PrivateKey +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_PrivateKey +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PKCS8PrivateKey +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_PKCS8PrivateKey +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PKCS8PrivateKey_nid +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fa "int nid" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_PKCS8PrivateKey_nid +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fa "int nid" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft X509_SIG * +.Fo PEM_read_bio_PKCS8 +.Fa "BIO *bp" +.Fa "X509_SIG **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft X509_SIG * +.Fo PEM_read_PKCS8 +.Fa "FILE *fp" +.Fa "X509_SIG **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PKCS8 +.Fa "BIO *bp" +.Fa "X509_SIG *x" +.Fc +.Ft int +.Fo PEM_write_PKCS8 +.Fa "FILE *fp" +.Fa "X509_SIG *x" +.Fc +.Ft PKCS8_PRIV_KEY_INFO * +.Fo PEM_read_bio_PKCS8_PRIV_KEY_INFO +.Fa "BIO *bp" +.Fa "PKCS8_PRIV_KEY_INFO **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft PKCS8_PRIV_KEY_INFO * +.Fo PEM_read_PKCS8_PRIV_KEY_INFO +.Fa "FILE *fp" +.Fa "PKCS8_PRIV_KEY_INFO **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PKCS8_PRIV_KEY_INFO +.Fa "BIO *bp" +.Fa "PKCS8_PRIV_KEY_INFO *x" +.Fc +.Ft int +.Fo PEM_write_PKCS8_PRIV_KEY_INFO +.Fa "FILE *fp" +.Fa "PKCS8_PRIV_KEY_INFO *x" +.Fc +.Ft EVP_PKEY * +.Fo PEM_read_bio_PUBKEY +.Fa "BIO *bp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EVP_PKEY * +.Fo PEM_read_PUBKEY +.Fa "FILE *fp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PUBKEY +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fc +.Ft int +.Fo PEM_write_PUBKEY +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fc +.Ft RSA * +.Fo PEM_read_bio_RSAPrivateKey +.Fa "BIO *bp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft RSA * +.Fo PEM_read_RSAPrivateKey +.Fa "FILE *fp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_RSAPrivateKey +.Fa "BIO *bp" +.Fa "RSA *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_RSAPrivateKey +.Fa "FILE *fp" +.Fa "RSA *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft RSA * +.Fo PEM_read_bio_RSAPublicKey +.Fa "BIO *bp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft RSA * +.Fo PEM_read_RSAPublicKey +.Fa "FILE *fp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_RSAPublicKey +.Fa "BIO *bp" +.Fa "RSA *x" +.Fc +.Ft int +.Fo PEM_write_RSAPublicKey +.Fa "FILE *fp" +.Fa "RSA *x" +.Fc +.Ft RSA * +.Fo PEM_read_bio_RSA_PUBKEY +.Fa "BIO *bp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft RSA * +.Fo PEM_read_RSA_PUBKEY +.Fa "FILE *fp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_RSA_PUBKEY +.Fa "BIO *bp" +.Fa "RSA *x" +.Fc +.Ft int +.Fo PEM_write_RSA_PUBKEY +.Fa "FILE *fp" +.Fa "RSA *x" +.Fc +.Ft DSA * +.Fo PEM_read_bio_DSAPrivateKey +.Fa "BIO *bp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft DSA * +.Fo PEM_read_DSAPrivateKey +.Fa "FILE *fp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_DSAPrivateKey +.Fa "BIO *bp" +.Fa "DSA *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_DSAPrivateKey +.Fa "FILE *fp" +.Fa "DSA *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft DSA * +.Fo PEM_read_bio_DSA_PUBKEY +.Fa "BIO *bp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft DSA * +.Fo PEM_read_DSA_PUBKEY +.Fa "FILE *fp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_DSA_PUBKEY +.Fa "BIO *bp" +.Fa "DSA *x" +.Fc +.Ft int +.Fo PEM_write_DSA_PUBKEY +.Fa "FILE *fp" +.Fa "DSA *x" +.Fc +.Ft DSA * +.Fo PEM_read_bio_DSAparams +.Fa "BIO *bp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft DSA * +.Fo PEM_read_DSAparams +.Fa "FILE *fp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_DSAparams +.Fa "BIO *bp" +.Fa "DSA *x" +.Fc +.Ft int +.Fo PEM_write_DSAparams +.Fa "FILE *fp" +.Fa "DSA *x" +.Fc +.Ft DH * +.Fo PEM_read_bio_DHparams +.Fa "BIO *bp" +.Fa "DH **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft DH * +.Fo PEM_read_DHparams +.Fa "FILE *fp" +.Fa "DH **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_DHparams +.Fa "BIO *bp" +.Fa "DH *x" +.Fc +.Ft int +.Fo PEM_write_DHparams +.Fa "FILE *fp" +.Fa "DH *x" +.Fc +.Ft EC_GROUP * +.Fo PEM_read_bio_ECPKParameters +.Fa "BIO *bp" +.Fa "EC_GROUP **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EC_GROUP * +.Fo PEM_read_ECPKParameters +.Fa "FILE *fp" +.Fa "EC_GROUP **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_ECPKParameters +.Fa "BIO *bp" +.Fa "const EC_GROUP *x" +.Fc +.Ft int +.Fo PEM_write_ECPKParameters +.Fa "FILE *fp" +.Fa "const EC_GROUP *x" +.Fc +.Ft EC_KEY * +.Fo PEM_read_bio_ECPrivateKey +.Fa "BIO *bp" +.Fa "EC_KEY **key" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EC_KEY * +.Fo PEM_read_ECPrivateKey +.Fa "FILE *fp" +.Fa "EC_KEY **eckey" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_ECPrivateKey +.Fa "BIO *bp" +.Fa "EC_KEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_ECPrivateKey +.Fa "FILE *fp" +.Fa "EC_KEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EC_KEY * +.Fo PEM_read_bio_EC_PUBKEY +.Fa "BIO *bp" +.Fa "EC_KEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EC_KEY * +.Fo PEM_read_EC_PUBKEY +.Fa "FILE *fp" +.Fa "EC_KEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_EC_PUBKEY +.Fa "BIO *bp" +.Fa "EC_KEY *x" +.Fc +.Ft int +.Fo PEM_write_EC_PUBKEY +.Fa "FILE *fp" +.Fa "EC_KEY *x" +.Fc +.Ft X509 * +.Fo PEM_read_bio_X509 +.Fa "BIO *bp" +.Fa "X509 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft X509 * +.Fo PEM_read_X509 +.Fa "FILE *fp" +.Fa "X509 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_X509 +.Fa "BIO *bp" +.Fa "X509 *x" +.Fc +.Ft int +.Fo PEM_write_X509 +.Fa "FILE *fp" +.Fa "X509 *x" +.Fc +.Ft X509 * +.Fo PEM_read_bio_X509_AUX +.Fa "BIO *bp" +.Fa "X509 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft X509 * +.Fo PEM_read_X509_AUX +.Fa "FILE *fp" +.Fa "X509 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_X509_AUX +.Fa "BIO *bp" +.Fa "X509 *x" +.Fc +.Ft int +.Fo PEM_write_X509_AUX +.Fa "FILE *fp" +.Fa "X509 *x" +.Fc +.Ft X509_REQ * +.Fo PEM_read_bio_X509_REQ +.Fa "BIO *bp" +.Fa "X509_REQ **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft X509_REQ * +.Fo PEM_read_X509_REQ +.Fa "FILE *fp" +.Fa "X509_REQ **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_X509_REQ +.Fa "BIO *bp" +.Fa "X509_REQ *x" +.Fc +.Ft int +.Fo PEM_write_X509_REQ +.Fa "FILE *fp" +.Fa "X509_REQ *x" +.Fc +.Ft int +.Fo PEM_write_bio_X509_REQ_NEW +.Fa "BIO *bp" +.Fa "X509_REQ *x" +.Fc +.Ft int +.Fo PEM_write_X509_REQ_NEW +.Fa "FILE *fp" +.Fa "X509_REQ *x" +.Fc +.Ft X509_CRL * +.Fo PEM_read_bio_X509_CRL +.Fa "BIO *bp" +.Fa "X509_CRL **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft X509_CRL * +.Fo PEM_read_X509_CRL +.Fa "FILE *fp" +.Fa "X509_CRL **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_X509_CRL +.Fa "BIO *bp" +.Fa "X509_CRL *x" +.Fc +.Ft int +.Fo PEM_write_X509_CRL +.Fa "FILE *fp" +.Fa "X509_CRL *x" +.Fc +.Ft PKCS7 * +.Fo PEM_read_bio_PKCS7 +.Fa "BIO *bp" +.Fa "PKCS7 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft PKCS7 * +.Fo PEM_read_PKCS7 +.Fa "FILE *fp" +.Fa "PKCS7 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PKCS7 +.Fa "BIO *bp" +.Fa "PKCS7 *x" +.Fc +.Ft int +.Fo PEM_write_PKCS7 +.Fa "FILE *fp" +.Fa "PKCS7 *x" +.Fc +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo PEM_read_CMS +.Fa "FILE *fp" +.Fa "CMS_ContentInfo **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft CMS_ContentInfo * +.Fo PEM_read_bio_CMS +.Fa "BIO *bp" +.Fa "CMS_ContentInfo **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_CMS +.Fa "FILE *fp" +.Fa "const CMS_ContentInfo *x" +.Fc +.Ft int +.Fo PEM_write_bio_CMS +.Fa "BIO *bp" +.Fa "const CMS_ContentInfo *x" +.Fc +.Sh DESCRIPTION +The PEM functions read or write structures in PEM format. +In this sense PEM format is simply base64-encoded data surrounded by +header lines; see +.Xr PEM_read 3 +for more details. +.Pp +For more details about the meaning of arguments see the +.Sx PEM function arguments +section. +.Pp +Each operation has four functions associated with it. +For brevity the term +.Dq Ar TYPE No functions +will be used to collectively refer to the +.Fn PEM_read_bio_TYPE , +.Fn PEM_read_TYPE , +.Fn PEM_write_bio_TYPE , +and +.Fn PEM_write_TYPE +functions. +If no set of specific functions exists for a given type, +.Xr PEM_ASN1_read 3 +can be used instead. +.Pp +The +.Sy PrivateKey +functions read or write a private key in PEM format using an +.Vt EVP_PKEY +structure. +The write routines use "traditional" private key format and can handle +both RSA and DSA private keys. +The read functions can additionally transparently handle PKCS#8 format +encrypted and unencrypted keys too. +.Pp +.Fn PEM_write_bio_PKCS8PrivateKey +and +.Fn PEM_write_PKCS8PrivateKey +write a private key in an +.Vt EVP_PKEY +structure in PKCS#8 +.Vt EncryptedPrivateKeyInfo +format using PKCS#5 v2.0 password based encryption algorithms. +The +.Fa enc +argument specifies the encryption algorithm to use: unlike all other PEM +routines, the encryption is applied at the PKCS#8 level and not in the +PEM headers. +If +.Fa enc +is +.Dv NULL , +then no encryption is used and a PKCS#8 +.Vt PrivateKeyInfo +structure is used instead. +.Pp +.Fn PEM_write_bio_PKCS8PrivateKey_nid +and +.Fn PEM_write_PKCS8PrivateKey_nid +also write out a private key as a PKCS#8 +.Vt EncryptedPrivateKeyInfo . +However they use PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. +The algorithm to use is specified in the +.Fa nid +parameter and should be the NID of the corresponding OBJECT IDENTIFIER. +.Pp +The +.Sy PKCS8 +functions process an encrypted private key using an +.Vt X509_SIG +structure and the +.Xr d2i_X509_SIG 3 +function. +.Pp +The +.Sy PKCS8_PRIV_KEY_INFO +functions process a private key using a +.Vt PKCS8_PRIV_KEY_INFO +structure. +.Pp +The +.Sy PUBKEY +functions process a public key using an +.Vt EVP_PKEY +structure. +The public key is encoded as an ASN.1 +.Vt SubjectPublicKeyInfo +structure. +.Pp +The +.Sy RSAPrivateKey +functions process an RSA private key using an +.Vt RSA +structure. +They handle the same formats as the +.Sy PrivateKey +functions, but an error occurs if the private key is not RSA. +.Pp +The +.Sy RSAPublicKey +functions process an RSA public key using an +.Vt RSA +structure. +The public key is encoded using a PKCS#1 +.Vt RSAPublicKey +structure. +.Pp +The +.Sy RSA_PUBKEY +functions also process an RSA public key using an +.Vt RSA +structure. +However the public key is encoded using an ASN.1 +.Vt SubjectPublicKeyInfo +structure and an error occurs if the public key is not RSA. +.Pp +The +.Sy DSAPrivateKey +functions process a DSA private key using a +.Vt DSA +structure. +They handle the same formats as the +.Sy PrivateKey +functions but an error occurs if the private key is not DSA. +.Pp +The +.Sy DSA_PUBKEY +functions process a DSA public key using a +.Vt DSA +structure. +The public key is encoded using an ASN.1 +.Vt SubjectPublicKeyInfo +structure and an error occurs if the public key is not DSA. +.Pp +The +.Sy DSAparams +functions process DSA parameters using a +.Vt DSA +structure. +The parameters are encoded using a Dss-Parms structure as defined in RFC 2459. +.Pp +The +.Sy DHparams +functions process DH parameters using a +.Vt DH +structure. +The parameters are encoded using a PKCS#3 DHparameter structure. +.Pp +The +.Sy ECPKParameters +functions process EC parameters using an +.Vt EC_GROUP +structure and the +.Xr d2i_ECPKParameters 3 +function. +.Pp +The +.Sy ECPrivateKey +functions process an EC private key using an +.Vt EC_KEY +structure. +.Pp +The +.Sy EC_PUBKEY +functions process an EC public key using an +.Vt EC_KEY +structure. +.Pp +The +.Sy X509 +functions process an X509 certificate using an +.Vt X509 +structure. +They will also process a trusted X509 certificate but any trust settings +are discarded. +.Pp +The +.Sy X509_AUX +functions process a trusted X509 certificate using an +.Vt X509 +structure. +.Pp +The +.Sy X509_REQ +and +.Sy X509_REQ_NEW +functions process a PKCS#10 certificate request using an +.Vt X509_REQ +structure. +The +.Sy X509_REQ +write functions use CERTIFICATE REQUEST in the header whereas the +.Sy X509_REQ_NEW +functions use NEW CERTIFICATE REQUEST (as required by some CAs). +The +.Sy X509_REQ +read functions will handle either form so there are no +.Sy X509_REQ_NEW +read functions. +.Pp +The +.Sy X509_CRL +functions process an X509 CRL using an +.Vt X509_CRL +structure. +.Pp +The +.Sy PKCS7 +functions process a PKCS#7 +.Vt ContentInfo +using a +.Vt PKCS7 +structure. +.Pp +The +.Sy CMS +functions process a +.Vt CMS_ContentInfo +structure. +.Pp +The old +.Sy PrivateKey +write routines are retained for compatibility. +New applications should write private keys using the +.Fn PEM_write_bio_PKCS8PrivateKey +or +.Fn PEM_write_PKCS8PrivateKey +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 +.Sy PrivateKey +read routines can be used in all applications because they handle all +formats transparently. +.Ss PEM function arguments +The PEM functions have many common arguments. +.Pp +The +.Fa bp +parameter specifies the +.Vt BIO +to read from or write to. +.Pp +The +.Fa fp +parameter specifies the +.Vt FILE +pointer to read from or write to. +.Pp +The PEM read functions all take a pointer to pointer argument +.Fa x +and return a pointer of the same type. +If +.Fa x +is +.Dv NULL , +then the parameter is ignored. +If +.Fa x +is not +.Dv NULL +but +.Pf * Fa x +is +.Dv NULL , +then the structure returned will be written to +.Pf * Fa x . +If neither +.Fa x +nor +.Pf * Fa x +are +.Dv NULL , +then an attempt is made to reuse the structure at +.Pf * Fa x , +but see the +.Sx BUGS +and +.Sx EXAMPLES +sections. +Irrespective of the value of +.Fa x , +a pointer to the structure is always returned, or +.Dv NULL +if an error occurred. +.Pp +The PEM functions which write private keys take an +.Fa enc +parameter, which specifies the encryption algorithm to use. +Encryption is done at the PEM level. +If this parameter is set to +.Dv NULL , +then the private key is written in unencrypted form. +.Pp +The optional arguments +.Fa u +and +.Fa cb +are a passphrase used for encrypting a PEM structure +or a callback to obtain the passphrase; see +.Xr pem_password_cb 3 +for details. +.Pp +For the PEM write routines, if the +.Fa kstr +parameter is not +.Dv NULL , +then +.Fa klen +bytes at +.Fa kstr +are used as the passphrase and +.Fa cb +is ignored. +.Ss PEM encryption format +These old +.Sy PrivateKey +routines use a non-standard technique for encryption. +.Pp +The private key (or other data) takes the following form: +.Bd -literal -offset indent +-----BEGIN RSA PRIVATE KEY----- +Proc-Type: 4,ENCRYPTED +DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 + +\&...base64 encoded data... +-----END RSA PRIVATE KEY----- +.Ed +.Pp +The line beginning with +.Dq DEK-Info +contains two comma separated pieces of information: +the encryption algorithm name as used by +.Xr EVP_get_cipherbyname 3 +and an 8-byte salt encoded as a set of hexadecimal digits. +.Pp +After this is the base64-encoded encrypted data. +.Pp +The encryption key is determined using +.Xr EVP_BytesToKey 3 , +using the salt and an iteration count of 1. +The IV used is the value of the salt and *not* the IV returned by +.Xr EVP_BytesToKey 3 . +.Sh RETURN VALUES +The read routines return either a pointer to the structure read or +.Dv NULL +if an error occurred. +.Pp +The write routines return 1 for success or 0 for failure. +.Sh EXAMPLES +Although the PEM routines take several arguments, in almost all +applications most of them are set to 0 or +.Dv NULL . +.Pp +Read a certificate in PEM format from a +.Vt BIO : +.Bd -literal -offset indent +X509 *x; +x = PEM_read_bio_X509(bp, NULL, 0, NULL); +if (x == NULL) { + /* Error */ +} +.Ed +.Pp +Alternative method: +.Bd -literal -offset indent +X509 *x = NULL; +if (!PEM_read_bio_X509(bp, &x, 0, NULL)) { + /* Error */ +} +.Ed +.Pp +Write a certificate to a +.Vt BIO : +.Bd -literal -offset indent +if (!PEM_write_bio_X509(bp, x)) { + /* Error */ +} +.Ed +.Pp +Write an unencrypted private key to a +.Vt FILE : +.Bd -literal -offset indent +if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) { + /* Error */ +} +.Ed +.Pp +Write a private key (using traditional format) to a +.Vt BIO +using triple DES encryption; the pass phrase is prompted for: +.Bd -literal -offset indent +if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), + NULL, 0, 0, NULL)) { + /* Error */ +} +.Ed +.Pp +Write a private key (using PKCS#8 format) to a +.Vt BIO +using triple DES encryption, using the pass phrase "hello": +.Bd -literal -offset indent +if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), + NULL, 0, 0, "hello")) { + /* Error */ +} +.Ed +.Pp +Read a private key from a +.Vt BIO +using the pass phrase "hello": +.Bd -literal -offset indent +key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); +if (key == NULL) { + /* Error */ +} +.Ed +.Pp +Read a private key from a +.Vt BIO +using a pass phrase callback: +.Bd -literal -offset indent +key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); +if (key == NULL) { + /* Error */ +} +.Ed +.Pp +Skeleton pass phrase callback: +.Bd -literal -offset indent +int +pass_cb(char *buf, int size, int rwflag, void *u) +{ + char *tmp; + size_t len; + + /* We'd probably do something else if 'rwflag' is 1 */ + printf("Enter pass phrase for \e"%s\e"\en", u); + + /* + * Instead of the following line, get the passphrase + * from the user in some way. + */ + tmp = "hello"; + if (tmp == NULL) /* An error occurred. */ + return -1; + + len = strlen(tmp); + if (len == 0) /* Treat an empty passphrase as an error, too. */ + return -1; + + /* if too long, truncate */ + if (len > size) + len = size; + memcpy(buf, tmp, len); + return len; +} +.Ed +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr DSA_new 3 , +.Xr PEM_ASN1_read 3 , +.Xr PEM_bytes_read_bio 3 , +.Xr PEM_read 3 , +.Xr PEM_read_SSL_SESSION 3 , +.Xr PEM_write_bio_CMS_stream 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +.Xr PEM_X509_INFO_read_bio 3 , +.Xr RSA_new 3 , +.Xr X509_CRL_new 3 , +.Xr X509_REQ_new 3 , +.Xr X509_SIG_new 3 +.Sh HISTORY +.Fn PEM_read_X509 +and +.Fn PEM_write_X509 +appeared in SSLeay 0.4 or earlier. +.Fn PEM_read_X509_REQ , +.Fn PEM_write_X509_REQ , +.Fn PEM_read_X509_CRL , +and +.Fn PEM_write_X509_CRL +first appeared in SSLeay 0.4.4. +.Fn PEM_read_RSAPrivateKey , +.Fn PEM_write_RSAPrivateKey , +.Fn PEM_read_DHparams , +.Fn PEM_write_DHparams , +.Fn PEM_read_PKCS7 , +and +.Fn PEM_write_PKCS7 +first appeared in SSLeay 0.5.1. +.Fn PEM_read_bio_PrivateKey , +.Fn PEM_read_PrivateKey , +.Fn PEM_read_bio_RSAPrivateKey , +.Fn PEM_write_bio_RSAPrivateKey , +.Fn PEM_read_bio_DSAPrivateKey , +.Fn PEM_read_DSAPrivateKey , +.Fn PEM_write_bio_DSAPrivateKey , +.Fn PEM_write_DSAPrivateKey , +.Fn PEM_read_bio_DHparams , +.Fn PEM_write_bio_DHparams , +.Fn PEM_read_bio_X509 , +.Fn PEM_write_bio_X509 , +.Fn PEM_read_bio_X509_REQ , +.Fn PEM_write_bio_X509_REQ , +.Fn PEM_read_bio_X509_CRL , +.Fn PEM_write_bio_X509_CRL , +.Fn PEM_read_bio_PKCS7 , +and +.Fn PEM_write_bio_PKCS7 +first appeared in SSLeay 0.6.0. +.Fn PEM_write_bio_PrivateKey , +.Fn PEM_write_PrivateKey , +.Fn PEM_read_bio_DSAparams , +.Fn PEM_read_DSAparams , +.Fn PEM_write_bio_DSAparams , +and +.Fn PEM_write_DSAparams +first appeared in SSLeay 0.8.0. +.Fn PEM_read_bio_RSAPublicKey , +.Fn PEM_read_RSAPublicKey , +.Fn PEM_write_bio_RSAPublicKey , +and +.Fn PEM_write_RSAPublicKey +first appeared in SSLeay 0.8.1. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn PEM_write_bio_PKCS8PrivateKey , +.Fn PEM_write_PKCS8PrivateKey , +.Fn PEM_read_bio_PKCS8 , +.Fn PEM_read_PKCS8 , +.Fn PEM_write_bio_PKCS8 , +.Fn PEM_write_PKCS8 , +.Fn PEM_read_bio_PKCS8_PRIV_KEY_INFO , +.Fn PEM_read_PKCS8_PRIV_KEY_INFO , +.Fn PEM_write_bio_PKCS8_PRIV_KEY_INFO , +.Fn PEM_write_PKCS8_PRIV_KEY_INFO , +.Pp +.Fn PEM_write_bio_PKCS8PrivateKey_nid , +.Fn PEM_write_PKCS8PrivateKey_nid , +.Fn PEM_read_bio_PUBKEY , +.Fn PEM_read_PUBKEY , +.Fn PEM_write_bio_PUBKEY , +.Fn PEM_write_PUBKEY , +.Fn PEM_read_bio_RSA_PUBKEY , +.Fn PEM_read_RSA_PUBKEY , +.Fn PEM_write_bio_RSA_PUBKEY , +.Fn PEM_write_RSA_PUBKEY , +.Fn PEM_read_bio_DSA_PUBKEY , +.Fn PEM_read_DSA_PUBKEY , +.Fn PEM_write_bio_DSA_PUBKEY , +.Fn PEM_write_DSA_PUBKEY , +.Fn PEM_write_bio_X509_REQ_NEW , +.Fn PEM_write_X509_REQ_NEW , +.Fn PEM_read_bio_X509_AUX , +.Fn PEM_read_X509_AUX , +.Fn PEM_write_bio_X509_AUX , +and +.Fn PEM_write_X509_AUX +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn PEM_read_bio_ECPKParameters , +.Fn PEM_read_ECPKParameters , +.Fn PEM_write_bio_ECPKParameters , +.Fn PEM_write_ECPKParameters , +.Fn PEM_read_bio_ECPrivateKey , +.Fn PEM_read_ECPrivateKey , +.Fn PEM_write_bio_ECPrivateKey , +.Fn PEM_write_ECPrivateKey , +.Fn PEM_read_bio_EC_PUBKEY , +.Fn PEM_read_EC_PUBKEY , +.Fn PEM_write_bio_EC_PUBKEY , +and +.Fn PEM_write_EC_PUBKEY +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn PEM_read_CMS , +.Fn PEM_read_bio_CMS , +.Fn PEM_write_CMS , +and +.Fn PEM_write_bio_CMS +first appeared in OpenSSL 0.9.8h and have been available since +.Ox 6.7 . +.Sh CAVEATS +A frequent cause of problems is attempting to use the PEM routines like +this: +.Bd -literal -offset indent +X509 *x; +PEM_read_bio_X509(bp, &x, 0, NULL); +.Ed +.Pp +This is a bug because an attempt will be made to reuse the data at +.Fa x , +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 BUGS +The PEM read routines in some versions of OpenSSL will not correctly +reuse an existing structure. +Therefore +.Pp +.Dl PEM_read_bio_X509(bp, &x, 0, NULL); +.Pp +where +.Fa x +already contains a valid certificate may not work, whereas +.Bd -literal -offset indent +X509_free(x); +x = PEM_read_bio_X509(bp, NULL, 0, NULL); +.Ed +.Pp +is guaranteed to work. diff --git a/static/openbsd/man3/PEM_write_bio_CMS_stream.3 b/static/openbsd/man3/PEM_write_bio_CMS_stream.3 new file mode 100644 index 00000000..a858874b --- /dev/null +++ b/static/openbsd/man3/PEM_write_bio_CMS_stream.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: PEM_write_bio_CMS_stream.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PEM_WRITE_BIO_CMS_STREAM 3 +.Os +.Sh NAME +.Nm PEM_write_bio_CMS_stream +.Nd output CMS_ContentInfo structure in PEM format +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft int +.Fo PEM_write_bio_CMS_stream +.Fa "BIO *out" +.Fa "CMS_ContentInfo *cms" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PEM_write_bio_CMS_stream +outputs a +.Vt CMS_ContentInfo +structure in PEM format. +.Pp +It is otherwise identical to the function +.Xr SMIME_write_CMS 3 . +.Pp +This function is effectively a version of +.Xr PEM_write_bio_CMS 3 +supporting streaming. +.Sh RETURN VALUES +.Fn PEM_write_bio_CMS_stream +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_decrypt 3 , +.Xr CMS_encrypt 3 , +.Xr CMS_sign 3 , +.Xr CMS_verify 3 , +.Xr ERR_get_error 3 , +.Xr i2d_CMS_bio_stream 3 , +.Xr PEM_write 3 , +.Xr SMIME_write_CMS 3 +.Sh HISTORY +.Fn PEM_write_bio_CMS_stream +first appeared in OpenSSL 1.0.0 +and has been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/PEM_write_bio_PKCS7_stream.3 b/static/openbsd/man3/PEM_write_bio_PKCS7_stream.3 new file mode 100644 index 00000000..a7317670 --- /dev/null +++ b/static/openbsd/man3/PEM_write_bio_PKCS7_stream.3 @@ -0,0 +1,91 @@ +.\" $OpenBSD: PEM_write_bio_PKCS7_stream.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2007, 2009, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PEM_WRITE_BIO_PKCS7_STREAM 3 +.Os +.Sh NAME +.Nm PEM_write_bio_PKCS7_stream +.Nd output PKCS7 structure in PEM format +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft int +.Fo PEM_write_bio_PKCS7_stream +.Fa "BIO *out" +.Fa "PKCS7 *p7" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PEM_write_bio_PKCS7_stream +outputs a PKCS7 structure in PEM format. +.Pp +It is otherwise identical to the function +.Xr SMIME_write_PKCS7 3 . +.Pp +This function is effectively a version of +.Xr PEM_write_bio_PKCS7 3 +supporting streaming. +.Sh RETURN VALUES +Upon successful completion, 1 is returned; +otherwise 0 is returned and an error code can be retrieved with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr i2d_PKCS7_bio_stream 3 , +.Xr PEM_write_PKCS7 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_new 3 , +.Xr SMIME_write_PKCS7 3 +.Sh HISTORY +.Fn PEM_write_bio_PKCS7_stream +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/PKCS12_SAFEBAG_new.3 b/static/openbsd/man3/PKCS12_SAFEBAG_new.3 new file mode 100644 index 00000000..45bdc20b --- /dev/null +++ b/static/openbsd/man3/PKCS12_SAFEBAG_new.3 @@ -0,0 +1,105 @@ +.\" $OpenBSD: PKCS12_SAFEBAG_new.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt PKCS12_SAFEBAG_NEW 3 +.Os +.Sh NAME +.Nm PKCS12_SAFEBAG_new , +.Nm PKCS12_SAFEBAG_free , +.Nm PKCS12_BAGS_new , +.Nm PKCS12_BAGS_free +.Nd PKCS#12 container for one piece of information +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs12.h +.Ft PKCS12_SAFEBAG * +.Fn PKCS12_SAFEBAG_new void +.Ft void +.Fn PKCS12_SAFEBAG_free "PKCS12_SAFEBAG *safebag" +.Ft PKCS12_BAGS * +.Fn PKCS12_BAGS_new void +.Ft void +.Fn PKCS12_BAGS_free "PKCS12_BAGS *bag" +.Sh DESCRIPTION +.Fn PKCS12_SAFEBAG_new +allocates and initializes an empty +.Vt PKCS12_SAFEBAG +object, representing an ASN.1 +.Vt SafeBag +structure defined in RFC 7292 section 4.2. +It can hold a pointer to a +.Vt PKCS12_BAGS +object together with a type identifier and optional attributes. +.Fn PKCS12_SAFEBAG_free +frees +.Fa safebag . +.Pp +.Fn PKCS12_BAGS_new +allocates and initializes an empty +.Vt PKCS12_BAGS +object, representing the bagValue field of an ASN.1 +.Vt SafeBag +structure. +It is used in +.Vt PKCS12_SAFEBAG +and can hold a DER-encoded X.509 certificate, +a base64-encoded SDSI certificate, +a DER-encoded X.509 CRL, +or other user-defined information. +.Pp +If an instance of +.Vt PKCS12_SAFEBAG +contains +.Vt PKCS8_PRIV_KEY_INFO , +.Vt X509_SIG , +or nested +.Vt PKCS12_SAFEBAG +objects, the respective pointers are stored directly in the +.Vt PKCS12_SAFEBAG +object rather than in the contained +.Vt PKCS12_BAGS +object as required by RFC 7292. +.Sh RETURN VALUES +.Fn PKCS12_SAFEBAG_new +and +.Fn PKCS12_BAGS_new +return the new +.Vt PKCS12_SAFEBAG +or +.Vt PKCS12_BAGS +object, respectively, or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr PKCS12_create 3 , +.Xr PKCS12_new 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 , +.Xr X509_ATTRIBUTE_new 3 , +.Xr X509_CRL_new 3 , +.Xr X509_new 3 , +.Xr X509_SIG_new 3 +.Sh STANDARDS +RFC 7292: PKCS #12: Personal Information Exchange Syntax, +section 4.2: The SafeBag Type +.Sh HISTORY +.Fn PKCS12_SAFEBAG_new , +.Fn PKCS12_SAFEBAG_free , +.Fn PKCS12_BAGS_new , +and +.Fn PKCS12_BAGS_free +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/PKCS12_create.3 b/static/openbsd/man3/PKCS12_create.3 new file mode 100644 index 00000000..80471ca8 --- /dev/null +++ b/static/openbsd/man3/PKCS12_create.3 @@ -0,0 +1,189 @@ +.\" $OpenBSD: PKCS12_create.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 05ea606a May 20 20:52:46 2016 -0400 +.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PKCS12_CREATE 3 +.Os +.Sh NAME +.Nm PKCS12_create +.Nd create a PKCS#12 structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs12.h +.Ft PKCS12 * +.Fo PKCS12_create +.Fa "const char *pass" +.Fa "const char *name" +.Fa "EVP_PKEY *pkey" +.Fa "X509 *cert" +.Fa "STACK_OF(X509) *ca" +.Fa "int nid_key" +.Fa "int nid_cert" +.Fa "int iter" +.Fa "int mac_iter" +.Fa "int keytype" +.Fc +.Sh DESCRIPTION +.Fn PKCS12_create +creates a PKCS#12 structure. +.Pp +.Fa pass +is the passphrase to use. +.Fa name +is the +.Sy friendlyName +to use for the supplied certificate and key. +.Fa pkey +is the private key to include in the structure and +.Fa cert +its corresponding certificates. +.Fa ca +is an optional set of certificates to also include in the structure. +.Fa pkey , +.Fa cert , +or both can be +.Dv NULL +to indicate that no key or certificate is required. +.Pp +.Fa nid_key +and +.Fa nid_cert +are the encryption algorithms that should be used for the key and +certificate, respectively. +If either +.Fa nid_key +or +.Fa nid_cert +is set to -1, no encryption will be used. +.Pp +.Fa iter +is the encryption algorithm iteration count to use and +.Fa mac_iter +is the MAC iteration count to use. +If +.Fa mac_iter +is set to -1, the MAC will be omitted entirely. +.Pp +.Fa keytype +is the type of key. +.Pp +The parameters +.Fa nid_key , +.Fa nid_cert , +.Fa iter , +.Fa mac_iter , +and +.Fa keytype +can all be set to zero and sensible defaults will be used. +.Pp +These defaults are: 40-bit RC2 encryption for certificates, triple DES +encryption for private keys, a key iteration count of +PKCS12_DEFAULT_ITER (currently 2048) and a MAC iteration count of 1. +.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 +.Fa mac_iter +should be set to PKCS12_DEFAULT_ITER. +.Pp +.Fa keytype +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 +.Dv KEY_SIG , +the key can be used for signing only; and if set to +.Dv KEY_EX , +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 a certificate contains an +.Sy alias +or +.Sy keyid +then this will be used for the corresponding +.Sy friendlyName +or +.Sy localKeyID +in the PKCS12 structure. +.Sh RETURN VALUES +.Fn PKCS12_create +returns a valid +.Vt PKCS12 +structure or +.Dv NULL +if an error occurred. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_PKCS12 3 , +.Xr PKCS12_new 3 , +.Xr PKCS12_newpass 3 , +.Xr PKCS12_parse 3 , +.Xr PKCS12_SAFEBAG_new 3 , +.Xr X509_keyid_set1 3 +.Sh HISTORY +.Fn PKCS12_create +first appeared in OpenSSL 0.9.3 and has been available since +.Ox 2.6 . +.Pp +Before OpenSSL 0.9.8, neither +.Fa pkey +nor +.Fa cert +were allowed to be +.Dv NULL , +and a value of -1 was not allowed for +.Fa nid_key , +.Fa nid_cert , +and +.Fa mac_iter . diff --git a/static/openbsd/man3/PKCS12_new.3 b/static/openbsd/man3/PKCS12_new.3 new file mode 100644 index 00000000..1506eaad --- /dev/null +++ b/static/openbsd/man3/PKCS12_new.3 @@ -0,0 +1,100 @@ +.\" $OpenBSD: PKCS12_new.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt PKCS12_NEW 3 +.Os +.Sh NAME +.Nm PKCS12_new , +.Nm PKCS12_free , +.Nm PKCS12_MAC_DATA_new , +.Nm PKCS12_MAC_DATA_free +.Nd PKCS#12 personal information exchange (PFX) +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs12.h +.Ft PKCS12 * +.Fn PKCS12_new void +.Ft void +.Fn PKCS12_free "PKCS12 *pfx" +.Ft PKCS12_MAC_DATA * +.Fn PKCS12_MAC_DATA_new void +.Ft void +.Fn PKCS12_MAC_DATA_free "PKCS12_MAC_DATA *mac_data" +.Sh DESCRIPTION +.Fn PKCS12_new +allocates and initializes an empty +.Vt PKCS12 +object, representing an ASN.1 +.Vt PFX +.Pq personal information exchange +structure defined in RFC 7292 section 4. +It can hold a pointer to a +.Vt PKCS7 +object described in +.Xr PKCS7_new 3 +and optionally an instance of +.Vt PKCS12_MAC_DATA +described below. +.Fn PKCS12_free +frees +.Fa pfx . +.Pp +.Fn PKCS12_MAC_DATA_new +allocates and initializes an empty +.Vt PKCS12_MAC_DATA +object, representing an ASN.1 +.Vt MacData +structure defined in RFC 7292 section 4. +It is used inside +.Vt PKCS12 +and can hold a pointer to an +.Vt X509_SIG +object described in +.Xr X509_SIG_new 3 +together with a salt value and an iteration count. +.Fn PKCS12_MAC_DATA_free +frees +.Fa mac_data . +.Sh RETURN VALUES +.Fn PKCS12_new +and +.Fn PKCS12_MAC_DATA_new +return the new +.Vt PKCS12 +or +.Vt PKCS12_MAC_DATA +object, respectively, or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_PKCS12 3 , +.Xr PKCS12_create 3 , +.Xr PKCS12_newpass 3 , +.Xr PKCS12_parse 3 , +.Xr PKCS12_SAFEBAG_new 3 , +.Xr PKCS7_new 3 , +.Xr X509_SIG_new 3 +.Sh STANDARDS +RFC 7292: PKCS #12: Personal Information Exchange Syntax +.Sh HISTORY +.Fn PKCS12_new , +.Fn PKCS12_free , +.Fn PKCS12_MAC_DATA_new , +and +.Fn PKCS12_MAC_DATA_free +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/PKCS12_newpass.3 b/static/openbsd/man3/PKCS12_newpass.3 new file mode 100644 index 00000000..b4d088e0 --- /dev/null +++ b/static/openbsd/man3/PKCS12_newpass.3 @@ -0,0 +1,156 @@ +.\" $OpenBSD: PKCS12_newpass.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL c95a8b4e May 5 14:26:26 2016 +0100 +.\" +.\" This file was written by Jeffrey Walton . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PKCS12_NEWPASS 3 +.Os +.Sh NAME +.Nm PKCS12_newpass +.Nd change the password of a PKCS#12 structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs12.h +.Ft int +.Fo PKCS12_newpass +.Fa "PKCS12 *p12" +.Fa "const char *oldpass" +.Fa "const char *newpass" +.Fc +.Sh DESCRIPTION +.Fn PKCS12_newpass +changes the password of a PKCS#12 structure. +.Pp +.Fa p12 +is a pointer to a PKCS#12 structure. +.Fa oldpass +is the existing password and +.Fa newpass +is the new password. +.Pp +If the PKCS#12 structure does not have a password, use the empty +string +.Qq \& +for +.Fa oldpass . +Passing +.Dv NULL +for +.Fa oldpass +results in a +.Fn PKCS12_newpass +failure. +.Pp +If the wrong password is used for +.Fa oldpass , +the function will fail with a MAC verification error. +In rare cases, the PKCS#12 structure does not contain a MAC: +in this case it will usually fail with a decryption padding error. +.Sh RETURN VALUES +Upon successful completion, 1 is returned; +otherwise 0 is returned and an error code can be retrieved with +.Xr ERR_get_error 3 . +.Sh EXAMPLES +This example loads a PKCS#12 file, changes its password, +and writes out the result to a new file. +.Bd -literal +#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; +} +.Ed +.Sh SEE ALSO +.Xr PKCS12_create 3 , +.Xr PKCS12_new 3 +.Sh HISTORY +.Fn PKCS12_newpass +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Sh BUGS +The password format is a NUL terminated ASCII string which is +converted to Unicode form internally. +As a result, some passwords cannot be supplied to this function. diff --git a/static/openbsd/man3/PKCS12_parse.3 b/static/openbsd/man3/PKCS12_parse.3 new file mode 100644 index 00000000..333d86b6 --- /dev/null +++ b/static/openbsd/man3/PKCS12_parse.3 @@ -0,0 +1,146 @@ +.\" $OpenBSD: PKCS12_parse.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2009 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PKCS12_PARSE 3 +.Os +.Sh NAME +.Nm PKCS12_parse +.Nd parse a PKCS#12 structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs12.h +.Ft int +.Fo PKCS12_parse +.Fa "PKCS12 *p12" +.Fa "const char *pass" +.Fa "EVP_PKEY **pkey" +.Fa "X509 **cert" +.Fa "STACK_OF(X509) **ca" +.Fc +.Sh DESCRIPTION +.Fn PKCS12_parse +parses a PKCS12 structure. +.Pp +.Fa p12 +is the +.Vt PKCS12 +structure to parse. +.Fa pass +is the passphrase to use. +If successful, the private key will be written to +.Pf * Fa pkey , +the corresponding certificate to +.Pf * Fa cert , +and any additional certificates to +.Pf * Fa ca . +.Pp +The parameters +.Fa pkey +and +.Fa cert +cannot be +.Dv NULL . +.Fa ca +can be +.Dv NULL , +in which case additional certificates will be discarded. +.Pf * Fa ca +can also be a valid STACK, in which case additional certificates are +appended to +.Pf * Fa ca . +If +.Pf * Fa ca +is +.Dv NULL , +a new STACK will be allocated. +.Pp +The +.Sy friendlyName +and +.Sy localKeyID +attributes (if present) of each certificate will be stored in the +.Fa alias +and +.Fa keyid +attributes of the +.Vt X509 +structure. +.Sh RETURN VALUES +.Fn PKCS12_parse +returns 1 for success and 0 if an error occurred. +.Pp +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr d2i_PKCS12 3 , +.Xr PKCS12_create 3 , +.Xr PKCS12_new 3 , +.Xr X509_keyid_set1 3 +.Sh HISTORY +.Fn PKCS12_parse +first appeared in OpenSSL 0.9.3 and has been available since +.Ox 2.6 . +.Sh 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 +.Sy friendlyName +and +.Sy localKeyID +attributes are currently stored in certificates. +Other attributes are discarded. +.Pp +Attributes currently cannot be stored in the private key +.Vt EVP_PKEY +structure. diff --git a/static/openbsd/man3/PKCS5_PBKDF2_HMAC.3 b/static/openbsd/man3/PKCS5_PBKDF2_HMAC.3 new file mode 100644 index 00000000..7c113029 --- /dev/null +++ b/static/openbsd/man3/PKCS5_PBKDF2_HMAC.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: PKCS5_PBKDF2_HMAC.3,v 1.10 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Jeffrey Walton . +.\" Copyright (c) 2014, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PKCS5_PBKDF2_HMAC 3 +.Os +.Sh NAME +.Nm PKCS5_PBKDF2_HMAC , +.Nm PKCS5_PBKDF2_HMAC_SHA1 +.Nd password based derivation routines with salt and iteration count +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo PKCS5_PBKDF2_HMAC +.Fa "const char *pass" +.Fa "int passlen" +.Fa "const unsigned char *salt" +.Fa "int saltlen" +.Fa "int iter" +.Fa "const EVP_MD *digest" +.Fa "int keylen" +.Fa "unsigned char *out" +.Fc +.Ft int +.Fo PKCS5_PBKDF2_HMAC_SHA1 +.Fa "const char *pass" +.Fa "int passlen" +.Fa "const unsigned char *salt" +.Fa "int saltlen" +.Fa "int iter" +.Fa "int keylen" +.Fa "unsigned char *out" +.Fc +.Sh DESCRIPTION +.Fn PKCS5_PBKDF2_HMAC +derives a key from a password using a salt and iteration count as +specified in RFC 2898. +.Pp +.Fa pass +is the password used in the derivation of length +.Fa passlen . +.Fa pass +is an optional parameter and can be +.Dv NULL . +If +.Fa passlen +is -1, then the function will calculate the length of +.Fa pass +using +.Xr strlen 3 . +.Pp +.Fa salt +is the salt used in the derivation of length +.Fa saltlen . +If the +.Fa salt +is +.Dv NULL , +then +.Fa saltlen +must be 0. +The function will not attempt to calculate the length of the +.Fa salt +because it is not assumed to be NUL terminated. +.Pp +.Fa iter +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 +.Fa iter +less than 1 is treated as a single iteration. +.Pp +.Fa digest +is the message digest function used in the derivation. +Values include any of the EVP_* message digests. +.Fn PKCS5_PBKDF2_HMAC_SHA1 +calls +.Fn PKCS5_PBKDF2_HMAC +with +.Xr EVP_sha1 3 . +.Pp +The derived key will be written to +.Fa out . +The size of the +.Fa out +buffer is specified via +.Fa keylen . +.Pp +A typical application of this function is to derive keying material for +an encryption algorithm from a password in the +.Fa pass , +a salt in +.Fa salt , +and an iteration count. +.Pp +Increasing the +.Fa iter +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 +.Fn PKCS5_PBKDF2_HMAC +and +.Fn PBKCS5_PBKDF2_HMAC_SHA1 +return 1 on success or 0 on error. +.Sh SEE ALSO +.Xr EVP_BytesToKey 3 , +.Xr EVP_DigestInit 3 +.Sh HISTORY +.Fn PKCS5_PBKDF2_HMAC_SHA1 +first appeared in OpenSSL 0.9.4 and has been available since +.Ox 2.6 . +.Pp +.Fn PKCS5_PBKDF2_HMAC +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/PKCS7_add_attribute.3 b/static/openbsd/man3/PKCS7_add_attribute.3 new file mode 100644 index 00000000..e7c8c734 --- /dev/null +++ b/static/openbsd/man3/PKCS7_add_attribute.3 @@ -0,0 +1,370 @@ +.\" $OpenBSD: PKCS7_add_attribute.3,v 1.6 2025/07/27 19:31:20 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: July 27 2025 $ +.Dt PKCS7_ADD_ATTRIBUTE 3 +.Os +.Sh NAME +.Nm PKCS7_add_attribute , +.Nm PKCS7_set_attributes , +.Nm PKCS7_get_attribute , +.Nm PKCS7_add_signed_attribute , +.Nm PKCS7_set_signed_attributes , +.Nm PKCS7_get_signed_attribute , +.Nm PKCS7_add_attrib_content_type , +.Nm PKCS7_add1_attrib_digest , +.Nm PKCS7_add0_attrib_signing_time , +.Nm PKCS7_add_attrib_smimecap +.Nd attributes of SignerInfo objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_add_attribute +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "int nid" +.Fa "int attrtype" +.Fa "void *value" +.Fc +.Ft int +.Fo PKCS7_set_attributes +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "STACK_OF(X509_ATTRIBUTE) *sk" +.Fc +.Ft ASN1_TYPE * +.Fo PKCS7_get_attribute +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "int nid" +.Fc +.Ft int +.Fo PKCS7_add_signed_attribute +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "int nid" +.Fa "int attrtype" +.Fa "void *value" +.Fc +.Ft int +.Fo PKCS7_set_signed_attributes +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "STACK_OF(X509_ATTRIBUTE) *sk" +.Fc +.Ft ASN1_TYPE * +.Fo PKCS7_get_signed_attribute +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "int nid" +.Fc +.Ft int +.Fo PKCS7_add_attrib_content_type +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "ASN1_OBJECT *coid" +.Fc +.Ft int +.Fo PKCS7_add1_attrib_digest +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "const unsigned char *md" +.Fa "int mdlen" +.Fc +.Ft int +.Fo PKCS7_add0_attrib_signing_time +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "ASN1_TIME *t" +.Fc +.Ft int +.Fo PKCS7_add_attrib_smimecap +.Fa "PKCS7_SIGNER_INFO *si" +.Fa "STACK_OF(X509_ALGOR) *cap" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_add_attribute +appends a new attribute of type +.Fa nid +to the +.Fa unauthenticatedAttributes +list of +.Fa si , +and it adds a new ASN.1 ANY object of type +.Fa attrtype +with the given +.Fa value +to the new attribute. +Ownership of the +.Fa value +is transferred into the new attribute object, so the calling code +must not +.Xr free 3 +the +.Fa value . +If the list already contains an unauthenticated attribute of type +.Fa nid +before the call, the new attribute replaces the old one +instead of being appended to the end of the list. +.Pp +.Fn PKCS7_set_attributes +frees the +.Fa unauthenticatedAttributes +list of +.Fa si +and all the attributes contained in it and replaces it with a deep copy of +.Fa sk . +.Pp +.Fn PKCS7_get_attribute +retrieves the first ASN.1 ANY member of the attribute of type +.Fa nid +from the +.Fa unauthenticatedAttributes +list of +.Fa si . +.Pp +The behaviour of +.Fn PKCS7_add_signed_attribute , +.Fn PKCS7_set_signed_attributes , +and +.Fn PKCS7_get_signed_attribute +is identical except that they operate on the list of +.Fa authenticatedAttributes . +.Pp +The normal way to use +.Fn PKCS7_add_signed_attribute +is to first create a +.Vt SignedInfo +object with +.Xr PKCS7_sign 3 +using the +.Dv PKCS7_PARTIAL +or +.Dv PKCS7_STREAM +flag, retrieve the +.Vt PKCS7_SIGNER_INFO +object with +.Xr PKCS7_get_signer_info 3 +or add an additional one with +.Xr PKCS7_sign_add_signer 3 , +call +.Fn PKCS7_add_signed_attribute +for each desired additional attribute, then do the signing with +.Xr PKCS7_final 3 +or with another finalizing function. +.Pp +The four remaining functions are wrappers around +.Fn PKCS7_add_signed_attribute . +.Pp +.Fn PKCS7_add_attrib_content_type +sets the +.Dv NID_pkcs9_contentType +attribute to +.Fa coid , +which specifies the content type of the +.Vt ContentInfo +value to be signed. +This attribute is mandatory and automatically added by +.Xr PKCS7_sign 3 +and +.Xr PKCS7_sign_add_signer 3 +unless the +.Dv PKCS7_NOATTR +flag is present. +Objects suitable as +.Fa coid +arguments can for example be obtained with +.Xr OBJ_nid2obj 3 . +If +.Fa coid +is +.Dv NULL , +the content type defaults to +.Dv NID_pkcs7_data . +.Pp +.Fn PKCS7_add1_attrib_digest +sets or replaces the +.Dv NID_pkcs9_messageDigest +attribute, which is the message digest of the contents octets +of the DER-encoding of the content field of the +.Vt ContentInfo +value being signed, to a copy of +.Fa md , +which is assumed to be +.Fa mdlen +bytes long. +If +.Fa mdlen +is -1, then +.Fn strlen md +is used instead of +.Fa mdlen . +This attribute is mandatory and automatically added by +.Xr PKCS7_dataFinal 3 +and +.Xr PKCS7_final 3 . +.Pp +.Fn PKCS7_add0_attrib_signing_time +sets or replaces the optional +.Dv NID_pkcs9_signingTime +attribute to +.Fa t , +specifying the time at which the signer performed the signing process. +Ownership of +.Fa t +is transferred into the new attribute object, so the calling code +must not +.Xr free 3 +.Fa t . +If +.Fa t +is +.Dv NULL , +a new +.Vt ASN1_TIME +structure is allocated. +This attribute is automatically added by +.Xr PKCS7_dataFinal 3 +and +.Xr PKCS7_final 3 . +.Pp +.Fn PKCS7_add_attrib_smimecap +sets or replaces the optional +.Dv NID_SMIMECapabilities +attribute, indicating algorithms the sender is prepared to handle. +The +.Fa cap +pointer is not stored in the new attribute object and can be passed to +.Fn sk_X509_ALGOR_pop_free +after the call. +This attribute is automatically added by +.Xr PKCS7_sign 3 +and +.Xr PKCS7_sign_add_signer 3 +unless the +.Dv PKCS7_NOATTR +or +.Dv PKCS7_NOSMIMECAP +flag is present. +.Sh RETURN VALUES +.Fn PKCS7_add_attribute , +.Fn PKCS7_set_attributes , +.Fn PKCS7_add_signed_attribute , +.Fn PKCS7_set_signed_attributes , +.Fn PKCS7_add_attrib_content_type , +.Fn PKCS7_add1_attrib_digest , +.Fn PKCS7_add0_attrib_signing_time , +and +.Fn PKCS7_add_attrib_smimecap +return 1 on success or 0 on failure. +The most common reason for failure is lack of memory. +.Fn PKCS7_add_attribute +and +.Fn PKCS7_add_signed_attribute +also fail if +.Fa nid +is invalid, and +.Fn PKCS7_add_attrib_content_type +if +.Fa si +already contains an authenticated attribute of type +.Dv NID_pkcs9_contentType . +.Pp +.Fn PKCS7_get_attribute +and +.Fn PKCS7_get_signed_attribute +return an internal pointer to an ASN.1 ANY object or +.Dv NULL +on failure. +They fail if +.Fa nid +is invalid, if the respective list in +.Fa si +contains no attribute of the requested type, or if an invalid element +is found in the list before finding the attribute of the requested type. +.Sh SEE ALSO +.Xr ASN1_TIME_new 3 , +.Xr ASN1_TYPE_new 3 , +.Xr OBJ_nid2obj 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_get_signer_info 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_sign 3 , +.Xr PKCS7_sign_add_signer 3 , +.Xr STACK_OF 3 , +.Xr X509_ALGOR_new 3 , +.Xr X509_ATTRIBUTE_new 3 +.Sh STANDARDS +RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5, +section 9.2: SignerInfo type +.Pp +RFC 2985: PKCS #9: Selected Object Classes and Attribute Types Version 2.0, +section 5.3: Attribute types for use in PKCS #7 data +and section 5.6: Attributes defined in S/MIME +.Pp +RFC 5652: Cryptographic Message Syntax (CMS), +section 5.3: SignerInfo Type +and section 11: Useful Attributes +.Pp +RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME) +Version 4.0 Message Specification, +section 2.5.2: SMIMECapabilities Attribute +.Sh HISTORY +.Fn PKCS7_add_attribute , +.Fn PKCS7_set_attributes , +.Fn PKCS7_get_attribute , +.Fn PKCS7_add_signed_attribute , +.Fn PKCS7_set_signed_attributes , +and +.Fn PKCS7_get_signed_attribute +first appeared in OpenSSL 0.9.1 and have been available since +.Ox 2.6 . +.Pp +.Fn PKCS7_add_attrib_smimecap +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn PKCS7_add_attrib_content_type , +.Fn PKCS7_add1_attrib_digest , +and +.Fn PKCS7_add0_attrib_signing_time +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Sh CAVEATS +.Fn PKCS7_set_signed_attributes +does not validate that +.Fa sk +contains the PKCS #9 content type and message digest attributes +required by RFC 2315. +It succeeds even when +.Fa sk +is empty, leaving +.Fa si +in a state that violates the standard. +.Pp +.Fn PKCS7_add0_attrib_signing_time +does not validate +.Fa t +beyond checking that it is well-formed per RFC 5652, section 11.3. +In particular, it may set the signing time to the future +or to the remote past. +.Sh BUGS +A function to remove individual attributes from these lists +does not appear to exist. +A program desiring to do that might have to manually iterate the fields +.Fa auth_attr +and +.Fa unauth_attr +of +.Fa si , +which are both of type +.Vt STACK_OF(X509_ATTRIBUTE) , +using the facilities described in +.Xr STACK_OF 3 +and +.Xr OPENSSL_sk_new 3 . diff --git a/static/openbsd/man3/PKCS7_dataFinal.3 b/static/openbsd/man3/PKCS7_dataFinal.3 new file mode 100644 index 00000000..fdc9da7f --- /dev/null +++ b/static/openbsd/man3/PKCS7_dataFinal.3 @@ -0,0 +1,159 @@ +.\" $OpenBSD: PKCS7_dataFinal.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: June 8 2025 $ +.Dt PKCS7_DATAFINAL 3 +.Os +.Sh NAME +.Nm PKCS7_dataFinal +.Nd move data from a BIO chain to a ContentInfo object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_dataFinal +.Fa "PKCS7 *p7" +.Fa "BIO *chain" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_dataFinal +transfers the data from the memory BIO at the end of the given +.Fa chain +into the appropriate content field of +.Fa p7 +itself or of its appropriate substructure. +It is typically used as the final step of populating +.Fa p7 , +after creating the +.Fa chain +with +.Xr PKCS7_dataInit 3 +and after writing the data into it. +.Pp +After calling +.Fn PKCS7_dataFinal , +the program can call +.Xr BIO_free_all 3 +on the +.Fa chain +because such chains are not designed for reuse. +.Pp +Depending on the +.Fa contentType +of +.Fa p7 , +.Fn PKCS7_dataFinal +sets the following fields: +.Bl -tag -width Ds +.It for Vt SignedData No or Vt DigestedData : +in substructures of the +.Fa content +field of +.Fa p7 : +the +.Fa content +field in the +.Vt ContentInfo +structure (unless +.Fa p7 +is configured to store a detached signature) and the +.Fa encryptedDigest +fields in all the +.Vt SignerInfo +structures +.It for Vt EnvelopedData No or Vt SignedAndEnvelopedData : +the +.Fa encryptedContent +field in the +.Vt EncryptedContentInfo +structure contained in the +.Fa content +field of +.Fa p7 +.It for arbitrary data : +the +.Fa content +field of +.Fa p7 +itself +.El +.Sh RETURN VALUES +.Fn PKCS7_dataFinal +returns 1 on success or 0 on failure. +.Pp +Possible reasons for failure include: +.Pp +.Bl -dash -compact -offset 2n -width 1n +.It +.Fa p7 +is +.Dv NULL . +.It +The +.Fa content +field of +.Fa p7 +is empty. +.It +The +.Fa contentType +of +.Fa p7 +is unsupported. +.It +The +.Fa chain +does not contain the expected memory BIO. +.It +Signing or digesting is requested and +.Fa p7 +is not configured to store a detached signature, +but does not contain the required field to store the content either. +.It +At least one signer lacks a usable digest algorithm. +.It +Signing or digesting fails. +.It +Memory allocation fails. +.El +.Pp +Signers lacking private keys do not cause failure +but are silently skipped. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr PKCS7_dataInit 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_sign 3 +.Sh HISTORY +.Fn PKCS7_dataFinal +first appeared in SSLeay 0.9.1 and has been available since +.Ox 2.6 . +.Sh CAVEATS +This function does not support +.Vt EncryptedData . +.Pp +Even though this function is typically used after +.Xr PKCS7_dataInit 3 +and even though +.Xr PKCS7_dataInit 3 +also supports reading from +.Vt ContentInfo +structures that are already fully populated, do not use +.Fn PKCS7_dataFinal +on fully populated structures. +It is only intended for putting data into new structures +and it is neither needed nor suitable for reading. diff --git a/static/openbsd/man3/PKCS7_dataInit.3 b/static/openbsd/man3/PKCS7_dataInit.3 new file mode 100644 index 00000000..320a2274 --- /dev/null +++ b/static/openbsd/man3/PKCS7_dataInit.3 @@ -0,0 +1,227 @@ +.\" $OpenBSD: PKCS7_dataInit.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: June 8 2025 $ +.Dt PKCS7_DATAINIT 3 +.Os +.Sh NAME +.Nm PKCS7_dataInit +.Nd construct a BIO chain for adding or retrieving content +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft BIO * +.Fo PKCS7_dataInit +.Fa "PKCS7 *p7" +.Fa "BIO *indata" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_dataInit +constructs a BIO chain in preparation for putting data into +or retrieving data out of +.Fa p7 . +Depending on the +.Fa contentType +of +.Fa p7 , +the created chain starts with: +.Bl -tag -width Ds +.It for Vt SignedData : +one or more +.Xr BIO_f_md 3 +message digest filters +.It for Vt EnvelopedData : +one +.Xr BIO_f_cipher 3 +encryption filter +.It for Vt SignedAndEnvelopedData : +one or more +.Xr BIO_f_md 3 +message digest filters followed by one +.Xr BIO_f_cipher 3 +encryption filter +.It for Vt DigestedData : +one +.Xr BIO_f_md 3 +message digest filter +.It for arbitrary data : +no filter BIO +.El +.Pp +One additional BIO is appended to the end of the chain, +depending on the first condition that holds in the following list: +.Bl -tag -width Ds +.It Fa indata +if the +.Fa indata +argument is not +.Dv NULL . +This only makes sense while verifying a detached signature, in which case +.Fa indata +is expected to supply the content associated with the detached signature. +.It Xr BIO_s_null 3 +if the +.Fa contentType +of +.Fa p7 +is +.Vt SignedData +and it is configured to contain a detached signature. +This only makes sense while creating the detached signature. +.It Xr BIO_new_mem_buf 3 +when reading from a +.Vt SignedData +or +.Vt DigestedData +object. +.Fn PKCS7_dataInit +attaches the end of the chain to the nested content of +.Fa p7 . +.It Xr BIO_s_mem 3 +otherwise. +This is the most common case while writing data to +.Fa p7 . +.Xr PKCS7_dataFinal 3 +can later be used to transfer the data from the memory BIO into +.Fa p7 . +.El +.Ss Adding content +Before calling +.Fn PKCS7_dataInit +in order to add content, +.Xr PKCS7_new 3 , +.Xr PKCS7_set_type 3 , +and +.Xr PKCS7_content_new 3 +are typically required to create +.Fa p7 , +to choose its desired type, and to allocate the nested +.Vt ContentInfo +structure. +Alternatively, for +.Vt SignedData , +.Xr PKCS7_sign 3 +can be used with the +.Dv PKCS7_PARTIAL +or +.Dv PKCS7_STREAM +.Fa flags +or for +.Vt EnvelopedData , +.Xr PKCS7_encrypt 3 +with the +.Dv PKCS7_STREAM +flag. +.Pp +After calling +.Fn PKCS7_dataInit , +the desired data can be written into the returned +.Vt BIO , +.Xr BIO_flush 3 +can be called on it, +.Xr PKCS7_dataFinal 3 +can be used to transfer the processed data +from the returned memory BIO to the +.Fa p7 +structure, and the chain can finally be destroyed with +.Xr BIO_free_all 3 . +.Pp +While +.Fn PKCS7_dataInit +does support the +.Vt EnvelopedData +and +.Vt SignedAndEnvelopedData +types, using it for these types is awkward and error prone +except when using +.Xr PKCS7_encrypt 3 +for the setup because +.Xr PKCS7_content_new 3 +does not support these two types. +So in addition to creating +.Fa p7 +itself and setting its type, the nested +.Fa ContentInfo +structure also needs to be constructed with +.Xr PKCS7_new 3 +and +.Xr PKCS7_set_type 3 +and manually inserted into the correct field +of the respective sub-structure of +.Fa p7 . +.Ss Retrieving content +.Fn PKCS7_dataInit +can also be called on a fully populated object of type +.Vt SignedData +or +.Vt DigestedData . +After that, +.Xr BIO_read 3 +can be used to retrieve data from it. +In this use case, do not call +.Xr PKCS7_dataFinal 3 ; +simply proceed directly to +.Xr BIO_free_all 3 +after reading the data. +.Sh RETURN VALUES +.Fn PKCS7_dataInit +returns a BIO chain on success or +.Dv NULL +on failure. +It fails if +.Fa p7 +is +.Dv NULL , +if the +.Fa content +field of +.Fa p7 +is empty, if the +.Fa contentType +of +.Fa p7 +is unsupported, if a cipher is required but none is configured, or +if any required operation fails, for example due to lack of memory +or for various other reasons. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr BIO_read 3 , +.Xr PKCS7_content_new 3 , +.Xr PKCS7_dataFinal 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_set_type 3 , +.Xr PKCS7_sign 3 +.Sh HISTORY +.Fn PKCS7_dataInit +first appeared in SSLeay 0.8.1 and has been available since +.Ox 2.4 . +.Sh CAVEATS +This function does not support +.Vt EncryptedData . +.Sh BUGS +If +.Fa p7 +is a fully populated structure containing +.Vt EnvelopedData , +.Vt SignedAndEnvelopedData , +or arbitrary data, +.Fn PKCS7_dataInit +returns a BIO chain that ultimately reads from an empty memory BIO, +so reading from it will instantly return an end-of-file indication +rather than reading the actual data contained in +.Fa p7 . diff --git a/static/openbsd/man3/PKCS7_decrypt.3 b/static/openbsd/man3/PKCS7_decrypt.3 new file mode 100644 index 00000000..857777bc --- /dev/null +++ b/static/openbsd/man3/PKCS7_decrypt.3 @@ -0,0 +1,119 @@ +.\" $OpenBSD: PKCS7_decrypt.3,v 1.11 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2006 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PKCS7_DECRYPT 3 +.Os +.Sh NAME +.Nm PKCS7_decrypt +.Nd decrypt content from a PKCS#7 envelopedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_decrypt +.Fa "PKCS7 *p7" +.Fa "EVP_PKEY *pkey" +.Fa "X509 *cert" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_decrypt +extracts and decrypts the content from a PKCS#7 envelopedData structure. +.Fa pkey +is the private key of the recipient, +.Fa cert +is the recipient's certificate, +.Fa data +is a +.Vt BIO +to write the content to and +.Fa flags +is an optional set of flags. +.Pp +Although the recipient's certificate is not needed to decrypt the data, +it is needed to locate the appropriate recipients +in the PKCS#7 structure. +.Pp +If the +.Dv PKCS7_TEXT +.Fa flag +is set, MIME headers for type +.Sy text/plain +are deleted from the content. +If the content is not of type +.Sy text/plain , +an error is returned. +.Sh RETURN VALUES +.Fn PKCS7_decrypt +returns 1 for success or 0 for failure. +.Pp +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_verify 3 +.Sh HISTORY +.Fn PKCS7_decrypt +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Sh BUGS +.Fn PKCS7_decrypt +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 +.Xr PKCS7_sign 3 +also applies to +.Fn PKCS7_decrypt . diff --git a/static/openbsd/man3/PKCS7_encrypt.3 b/static/openbsd/man3/PKCS7_encrypt.3 new file mode 100644 index 00000000..3e728383 --- /dev/null +++ b/static/openbsd/man3/PKCS7_encrypt.3 @@ -0,0 +1,170 @@ +.\" $OpenBSD: PKCS7_encrypt.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2006, 2007, 2008, 2009 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PKCS7_ENCRYPT 3 +.Os +.Sh NAME +.Nm PKCS7_encrypt +.Nd create a PKCS#7 envelopedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft PKCS7 * +.Fo PKCS7_encrypt +.Fa "STACK_OF(X509) *certs" +.Fa "BIO *in" +.Fa "const EVP_CIPHER *cipher" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_encrypt +creates and returns a PKCS#7 envelopedData structure. +.Fa certs +is a list of recipient certificates. +.Fa in +is the content to be encrypted. +.Fa cipher +is the symmetric cipher to use. +.Fa flags +is an optional set of flags. +.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 +The algorithm passed in the +.Fa cipher +parameter must support ASN.1 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 +.Vt BIO +and passing it to +.Fn PKCS7_encrypt . +.Pp +The following flags can be passed in the +.Fa flags +parameter. +.Pp +If the +.Dv PKCS7_TEXT +flag is set, MIME headers for type +.Sy text/plain +are prepended to the data. +.Pp +Normally the supplied content is translated into MIME canonical format +(as required by the S/MIME specifications). +If +.Dv PKCS7_BINARY +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 +.Dv PKCS7_BINARY +is set, then +.Dv PKCS7_TEXT +is ignored. +.Pp +If the +.Dv PKCS7_STREAM +flag is set, a partial +.Vt PKCS7 +structure is output suitable for streaming I/O: no data is read from +.Fa in . +.Pp +If the flag +.Dv PKCS7_STREAM +is set, the returned +.Vt PKCS7 +structure is +.Sy not +complete and outputting its contents via a function that does not +properly finalize the +.Vt PKCS7 +structure will give unpredictable results. +.Pp +Several functions including +.Xr PKCS7_final 3 , +.Xr SMIME_write_PKCS7 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +and +.Xr i2d_PKCS7_bio_stream 3 +finalize the structure. +Alternatively finalization can be performed by obtaining the streaming +ASN.1 +.Vt BIO +directly using +.Fn BIO_new_PKCS7 . +.Sh RETURN VALUES +.Fn PKCS7_encrypt +returns either a +.Vt PKCS7 +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr PKCS7_decrypt 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_sign 3 +.Sh HISTORY +.Fn PKCS7_encrypt +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +The +.Dv PKCS7_STREAM +flag was first supported in OpenSSL 1.0.0. diff --git a/static/openbsd/man3/PKCS7_final.3 b/static/openbsd/man3/PKCS7_final.3 new file mode 100644 index 00000000..5c2063b1 --- /dev/null +++ b/static/openbsd/man3/PKCS7_final.3 @@ -0,0 +1,203 @@ +.\" $OpenBSD: PKCS7_final.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: June 8 2025 $ +.Dt PKCS7_FINAL 3 +.Os +.Sh NAME +.Nm PKCS7_final +.Nd read data from a BIO into a ContentInfo object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_final +.Fa "PKCS7 *p7" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_final +reads +.Fa data +and puts it into the appropriate content field of +.Fa p7 +itself or of its appropriate substructure, which can be of type +.Vt SignedData , +.Vt EnvelopedData , +.Vt SignedAndEnvelopedData , +.Vt DigestedData , +or arbitrary data. +The +.Xr PKCS7_dataFinal 3 +manual explains which field exactly the data is put into. +.Pp +The following +.Fa flags +are recognized: +.Bl -tag -width PKCS7_BINARY +.It Dv PKCS7_BINARY +Copy the data verbatim without changing any bytes. +By default, line endings are replaced with two-byte +.Qq \er\en +sequences (ASCII CR+LF). +If this flag is set, +.Dv PKCS7_TEXT +is ignored. +.It Dv PKCS7_TEXT +Prepend +.Qq Content-Type: text/plain +followed by a blank line to the data. +This flag is ignored if +.Dv PKCS7_BINARY +is also set. +.El +.Pp +If any other bits are set in +.Fa flags , +for example +.Dv PKCS7_STREAM +or +.Dv PKCS7_PARTIAL , +they are ignored, allowing to pass the same +.Fa flags +argument that was already passed to +.Xr PKCS7_sign 3 +or +.Xr PKCS7_encrypt 3 . +.Pp +.Fn PKCS7_final +is most commonly used to finalize a +.Fa p7 +object returned from a call to +.Xr PKCS7_sign 3 +that used +.Fa flags +including +.Dv PKCS7_PARTIAL +or +.Dv PKCS7_STREAM . +With these flags, +.Xr PKCS7_sign 3 +ignores its +.Fa data +argument. +The partial +.Fa p7 +object returned can then be customized, for example setting up +multiple signers or non-default digest algorithms with +.Xr PKCS7_sign_add_signer 3 , +before calling +.Fn PKCS7_final . +.Pp +Similarly, +.Fn PKCS7_final +can be used to finalize a +.Fa p7 +object returned from a call to +.Xr PKCS7_encrypt 3 +that used +.Fa flags +including +.Dv PKCS7_STREAM . +.Pp +Since +.Fn PKCS7_final +starts by calling +.Xr PKCS7_dataInit 3 +internally, using it to finalize a +.Fa p7 +object containing +.Vt SignedAndEnvelopedData , +.Vt DigestedData , +or arbitrary data requires the setup described in the +.Xr PKCS7_dataInit 3 +manual. +For +.Vt SignedData +and +.Vt EnvelopedData , +such manual setup is also feasible, but it is more easily performed with +.Xr PKCS7_sign 3 +or +.Xr PKCS7_encrypt 3 , +respectively. +.Pp +.Fn PKCS7_final +is only one among several functions that can be used to finalize +.Fa p7 ; +alternatives include +.Xr SMIME_write_PKCS7 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +and +.Xr i2d_PKCS7_bio_stream 3 . +.Sh RETURN VALUES +.Fn PKCS7_final +returns 1 on success or 0 on failure. +.Pp +Possible reasons for failure include: +.Pp +.Bl -dash -compact -offset 2n -width 1n +.It +.Fa p7 +is +.Dv NULL . +.It +The +.Fa content +field of +.Fa p7 +is empty. +.It +The +.Fa contentType +of +.Fa p7 +is unsupported. +.It +Signing or digesting is requested and +.Fa p7 +is not configured to store a detached signature, but does not contain +the required field to store the content either. +.It +At least one signer lacks a usable digest algorithm. +.It +A cipher is required but none is configured. +.It +Any required operation fails, for example signing or digesting. +.It +Memory allocation fails. +.El +.Pp +Signers lacking private keys do not cause failure but are silently skipped. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr i2d_PKCS7_bio_stream 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +.Xr PKCS7_add_attribute 3 , +.Xr PKCS7_dataFinal 3 , +.Xr PKCS7_dataInit 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_sign 3 , +.Xr SMIME_write_PKCS7 3 +.Sh HISTORY +.Fn PKCS7_final +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Sh CAVEATS +This function does not support +.Vt EncryptedData . diff --git a/static/openbsd/man3/PKCS7_get_signer_info.3 b/static/openbsd/man3/PKCS7_get_signer_info.3 new file mode 100644 index 00000000..9edf4c63 --- /dev/null +++ b/static/openbsd/man3/PKCS7_get_signer_info.3 @@ -0,0 +1,63 @@ +.\" $OpenBSD: PKCS7_get_signer_info.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: June 8 2025 $ +.Dt PKCS7_GET_SIGNER_INFO 3 +.Os +.Sh NAME +.Nm PKCS7_get_signer_info +.Nd retrieve signerInfos from a SignedData object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft STACK_OF(PKCS7_SIGNER_INFO) * +.Fn PKCS7_get_signer_info "PKCS7 *p7" +.Sh DESCRIPTION +This function retrieves the set of +.Vt SignerInfo +structures from the +.Fa signerInfos +field of +.Fa p7 . +.Pp +These can subsequently be manipulated with the functions documented in +.Xr PKCS7_add_attribute 3 . +.Sh RETURN VALUES +.Fn PKCS7_get_signer_info +returns an internal pointer to a +.Vt STACK_OF(PKCS7_SIGNER_INFO) +object or +.Dv NULL +on failure. +It fails if +.Fa p7 +is +.Dv NULL , +if it has no content, +or if it is of a type other than +.Vt SignedData +or +.Vt SignedAndEnvelopedData . +.Sh SEE ALSO +.Xr PKCS7_add_attribute 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_sign 3 , +.Xr PKCS7_sign_add_signer 3 +.Sh HISTORY +.Fn PKCS7_get_signer_info +first appeared in SSLeay 0.8.1 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/PKCS7_new.3 b/static/openbsd/man3/PKCS7_new.3 new file mode 100644 index 00000000..19f6f1ac --- /dev/null +++ b/static/openbsd/man3/PKCS7_new.3 @@ -0,0 +1,270 @@ +.\" $OpenBSD: PKCS7_new.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt PKCS7_NEW 3 +.Os +.Sh NAME +.Nm PKCS7_new , +.Nm PKCS7_free , +.Nm PKCS7_SIGNED_new , +.Nm PKCS7_SIGNED_free , +.Nm PKCS7_ENVELOPE_new , +.Nm PKCS7_ENVELOPE_free , +.Nm PKCS7_SIGN_ENVELOPE_new , +.Nm PKCS7_SIGN_ENVELOPE_free , +.Nm PKCS7_DIGEST_new , +.Nm PKCS7_DIGEST_free , +.Nm PKCS7_ENCRYPT_new , +.Nm PKCS7_ENCRYPT_free , +.Nm PKCS7_ENC_CONTENT_new , +.Nm PKCS7_ENC_CONTENT_free , +.Nm PKCS7_SIGNER_INFO_new , +.Nm PKCS7_SIGNER_INFO_free , +.Nm PKCS7_RECIP_INFO_new , +.Nm PKCS7_RECIP_INFO_free , +.Nm PKCS7_ISSUER_AND_SERIAL_new , +.Nm PKCS7_ISSUER_AND_SERIAL_free +.Nd PKCS#7 data structures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft PKCS7 * +.Fn PKCS7_new void +.Ft void +.Fn PKCS7_free "PKCS7 *p7" +.Ft PKCS7_SIGNED * +.Fn PKCS7_SIGNED_new void +.Ft void +.Fn PKCS7_SIGNED_free "PKCS7_SIGNED *signed" +.Ft PKCS7_ENVELOPE * +.Fn PKCS7_ENVELOPE_new void +.Ft void +.Fn PKCS7_ENVELOPE_free "PKCS7_ENVELOPE *envelope" +.Ft PKCS7_SIGN_ENVELOPE * +.Fn PKCS7_SIGN_ENVELOPE_new void +.Ft void +.Fn PKCS7_SIGN_ENVELOPE_free "PKCS7_SIGN_ENVELOPE *signed_envelope" +.Ft PKCS7_DIGEST * +.Fn PKCS7_DIGEST_new void +.Ft void +.Fn PKCS7_DIGEST_free "PKCS7_DIGEST *digested" +.Ft PKCS7_ENCRYPT * +.Fn PKCS7_ENCRYPT_new void +.Ft void +.Fn PKCS7_ENCRYPT_free "PKCS7_ENCRYPT *encrypted" +.Ft PKCS7_ENC_CONTENT * +.Fn PKCS7_ENC_CONTENT_new void +.Ft void +.Fn PKCS7_ENC_CONTENT_free "PKCS7_ENC_CONTENT *content" +.Ft PKCS7_SIGNER_INFO * +.Fn PKCS7_SIGNER_INFO_new void +.Ft void +.Fn PKCS7_SIGNER_INFO_free "PKCS7_SIGNER_INFO *signer" +.Ft PKCS7_RECIP_INFO * +.Fn PKCS7_RECIP_INFO_new void +.Ft void +.Fn PKCS7_RECIP_INFO_free "PKCS7_RECIP_INFO *recip" +.Ft PKCS7_ISSUER_AND_SERIAL * +.Fn PKCS7_ISSUER_AND_SERIAL_new void +.Ft void +.Fn PKCS7_ISSUER_AND_SERIAL_free "PKCS7_ISSUER_AND_SERIAL *cert" +.Sh DESCRIPTION +PKCS#7 is an ASN.1-based format for transmitting data that has +cryptography applied to it, in particular signed and encrypted data. +.Pp +.Fn PKCS7_new +allocates and initializes an empty +.Vt PKCS7 +object, representing an ASN.1 +.Vt ContentInfo +structure defined in RFC 2315 section 7. +It is the top-level data structure able to hold any kind of content +that can be transmitted using PKCS#7. +It can be used recursively in +.Vt PKCS7_SIGNED +and +.Vt PKCS7_DIGEST +objects. +.Fn PKCS7_free +frees +.Fa p7 . +.Pp +.Fn PKCS7_SIGNED_new +allocates and initializes an empty +.Vt PKCS7_SIGNED +object, representing an ASN.1 +.Vt SignedData +structure defined in RFC 2315 section 9. +It can be used inside +.Vt PKCS7 +objects and holds any kind of content together with signatures by +zero or more signers and information about the signing algorithm +and certificates used. +.Fn PKCS7_SIGNED_free +frees +.Fa signed . +.Pp +.Fn PKCS7_ENVELOPE_new +allocates and initializes an empty +.Vt PKCS7_ENVELOPE +object, representing an ASN.1 +.Vt EnvelopedData +structure defined in RFC 2315 section 10. +It can be used inside +.Vt PKCS7 +objects and holds any kind of encrypted content together with +content-encryption keys for one or more recipients. +.Fn PKCS7_ENVELOPE_free +frees +.Fa envelope . +.Pp +.Fn PKCS7_SIGN_ENVELOPE_new +allocates and initializes an empty +.Vt PKCS7_SIGN_ENVELOPE +object, representing an ASN.1 +.Vt SignedAndEnvelopedData +structure defined in RFC 2315 section 11. +It can be used inside +.Vt PKCS7 +objects and holds any kind of encrypted content together with +signatures by one or more signers, information about the signing +algorithm and certificates used, and content-encryption keys for +one or more recipients. +.Fn PKCS7_SIGN_ENVELOPE_free +frees +.Fa signed_envelope . +.Pp +.Fn PKCS7_DIGEST_new +allocates and initializes an empty +.Vt PKCS7_DIGEST +object, representing an ASN.1 +.Vt DigestedData +structure defined in RFC 2315 section 12. +It can be used inside +.Vt PKCS7 +objects and holds any kind of content together with a message digest +for checking its integrity and information about the algorithm used. +.Fn PKCS7_DIGEST_free +frees +.Fa digested . +.Pp +.Fn PKCS7_ENCRYPT_new +allocates and initializes an empty +.Vt PKCS7_ENCRYPT +object, representing an ASN.1 +.Vt EncryptedData +structure defined in RFC 2315 section 13. +It can be used inside +.Vt PKCS7 +objects and holds any kind of encrypted content. +Keys are not included and need to be communicated separately. +.Fn PKCS7_ENCRYPT_free +frees +.Fa encrypted . +.Pp +.Fn PKCS7_ENC_CONTENT_new +allocates and initializes an empty +.Vt PKCS7_ENC_CONTENT +object, representing an ASN.1 +.Vt EncryptedContentInfo +structure defined in RFC 2315 section 10.1. +It can be used inside +.Vt PKCS7_ENVELOPE , +.Vt PKCS7_SIGN_ENVELOPE , +and +.Vt PKCS7_ENCRYPT +objects and holds encrypted content together with information about +the encryption algorithm used. +.Fn PKCS7_ENC_CONTENT_free +frees +.Fa content . +.Pp +.Fn PKCS7_SIGNER_INFO_new +allocates and initializes an empty +.Vt PKCS7_SIGNER_INFO +object, representing an ASN.1 +.Vt SignerInfo +structure defined in RFC 2315 section 9.2. +It can be used inside +.Vt PKCS7_SIGNED +and +.Vt PKCS7_SIGN_ENVELOPE +objects and holds a signature together with information about the +signer and the algorithms used. +.Fn PKCS7_SIGNER_INFO_free +frees +.Fa signer . +.Pp +.Fn PKCS7_RECIP_INFO_new +allocates and initializes an empty +.Vt PKCS7_RECIP_INFO +object, representing an ASN.1 +.Vt RecipientInfo +structure defined in RFC 2315 section 10.2. +It can be used inside +.Vt PKCS7_ENVELOPE +and +.Vt PKCS7_SIGN_ENVELOPE +objects and holds a content-encryption key together with information +about the intended recipient and the key encryption algorithm used. +.Fn PKCS7_RECIP_INFO_free +frees +.Fa recip . +.Pp +.Fn PKCS7_ISSUER_AND_SERIAL_new +allocates and initializes an empty +.Vt PKCS7_ISSUER_AND_SERIAL +object, representing an ASN.1 +.Vt IssuerAndSerialNumber +structure defined in RFC 2315 section 6.7. +It can be used inside +.Vt PKCS7_SIGNER_INFO +and +.Vt PKCS7_RECIP_INFO +objects and identifies a certificate by holding the distinguished +name of the certificate issuer and an issuer-specific certificate +serial number. +.Fn PKCS7_ISSUER_AND_SERIAL_free +frees +.Fa cert . +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_PKCS7 3 , +.Xr i2d_PKCS7_bio_stream 3 , +.Xr PEM_read_PKCS7 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +.Xr PKCS7_add_attribute 3 , +.Xr PKCS7_dataFinal 3 , +.Xr PKCS7_dataInit 3 , +.Xr PKCS7_decrypt 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_get_signer_info 3 , +.Xr PKCS7_ISSUER_AND_SERIAL_digest 3 , +.Xr PKCS7_set_content 3 , +.Xr PKCS7_set_type 3 , +.Xr PKCS7_sign 3 , +.Xr PKCS7_sign_add_signer 3 , +.Xr PKCS7_verify 3 , +.Xr SMIME_read_PKCS7 3 , +.Xr SMIME_write_PKCS7 3 +.Sh STANDARDS +RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5 +.Sh HISTORY +These functions first appeared in SSLeay 0.5.1 +and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/PKCS7_set_content.3 b/static/openbsd/man3/PKCS7_set_content.3 new file mode 100644 index 00000000..bf0eb767 --- /dev/null +++ b/static/openbsd/man3/PKCS7_set_content.3 @@ -0,0 +1,121 @@ +.\" $OpenBSD: PKCS7_set_content.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: June 8 2025 $ +.Dt PKCS7_SET_CONTENT 3 +.Os +.Sh NAME +.Nm PKCS7_set_content , +.Nm PKCS7_content_new +.Nd set the nested contentInfo in a PKCS#7 structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_set_content +.Fa "PKCS7 *outer" +.Fa "PKCS7 *inner" +.Fc +.Ft int +.Fo PKCS7_content_new +.Fa "PKCS7 *outer" +.Fa "int inner_type" +.Fc +.Sh DESCRIPTION +If the +.Fa contentType +of the +.Fa outer +PKCS7 structure is +.Vt SignedData +or +.Vt DigestedData , +.Fn PKCS7_set_content +sets the +.Fa contentInfo +field of the +.Fa content +field of +.Fa outer +to +.Fa inner , +without copying +.Fa inner . +If there was previous +.Fa contentInfo , +it is freed rather than overwritten. +The rest of the internal state of +.Fa outer +and of its +.Fa content +remains unchanged. +.Pp +.Fn PKCS7_content_new +is similar except that it first allocates and initializes a new, empty +.Fa inner +object of the given +.Fa inner_type +using +.Xr PKCS7_new 3 +and +.Xr PKCS7_set_type 3 . +The +.Fa inner_type +can be any of the NIDs listed in the +.Xr PKCS7_set_type 3 +manual. +.Sh RETURN VALUES +These functions return 1 on success or 0 on failure. +They fail if the +.Fa contentType +of +.Fa outer +is unsupported. +.Fn PKCS7_content_new +can also fail when memory is exhausted. +In case of failure, +.Fa outer +remains unchanged. +.Sh SEE ALSO +.Xr PKCS7_dataInit 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_set_type 3 , +.Xr PKCS7_sign 3 +.Sh STANDARDS +RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5 +.Bl -bullet -compact -offset 1n -width 1n +.It +Section 7. General syntax +.It +Section 9. Signed-data content type +.It +Section 12.\& Digested-data content type +.El +.Sh HISTORY +These functions first appeared in SSLeay 0.8.1 +and have been available since +.Ox 2.4 . +.Sh CAVEATS +Despite the function names, these functions do not set the +.Fa content +field of +.Fa outer , +but only the +.Fa contentInfo +field inside it. +The rest of the +.Fa content +remains unchanged. diff --git a/static/openbsd/man3/PKCS7_set_type.3 b/static/openbsd/man3/PKCS7_set_type.3 new file mode 100644 index 00000000..23eefff9 --- /dev/null +++ b/static/openbsd/man3/PKCS7_set_type.3 @@ -0,0 +1,120 @@ +.\" $OpenBSD: PKCS7_set_type.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: June 8 2025 $ +.Dt PKCS7_SET_TYPE 3 +.Os +.Sh NAME +.Nm PKCS7_set_type , +.Nm PKCS7_set0_type_other +.Nd initialize type of PKCS#7 ContentInfo +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_set_type +.Fa "PKCS7 *p7" +.Fa "int type" +.Fc +.Ft int +.Fo PKCS7_set0_type_other +.Fa "PKCS7 *p7" +.Fa "int type" +.Fa "ASN1_TYPE *content" +.Fc +.Sh DESCRIPTION +These functions set the +.Fa type +of an unused +.Vt ContentInfo +structure +.Fa p7 . +.Pp +The function +.Fn PKCS7_set_type +also allocates and initializes an empty child object in +.Fa p7 . +The +.Fa type +argument can be any of these NIDs, +creating a child object of the indicated data type: +.Pp +.Bl -column NID_pkcs7_signedAndEnveloped PKCS7_SIGN_ENVELOPE n.a. -compact +.It Fa type No argument Ta data type of child Ta version +.It Dv NID_pkcs7_data Ta Vt ASN1_OCTET_STRING Ta n.a. +.It Dv NID_pkcs7_digest Ta Vt PKCS7_DIGEST Ta 0 +.It Dv NID_pkcs7_encrypted Ta Vt PKCS7_ENCRYPT Ta 0 +.It Dv NID_pkcs7_enveloped Ta Vt PKCS7_ENVELOPE Ta 0 +.It Dv NID_pkcs7_signed Ta Vt PKCS7_SIGNED Ta 1 +.It Dv NID_pkcs7_signedAndEnveloped Ta Vt PKCS7_SIGN_ENVELOPE Ta 1 +.El +.Pp +If the provided +.Fa type +is invalid, +.Fa p7 +remains unchanged and +.Fn PKCS7_set_type +fails. +.Pp +If memory allocation fails, +.Fn PKCS7_set_type +fails and +.Fa p7 +may remain in an inconsistent state. +.Pp +The function +.Fn PKCS7_set0_type_other +accepts an arbitrary NID as the +.Fa type +and also sets the +.Fa content , +neither checking it in any way nor copying it. +.Pp +For both functions, the rest of the internal state of +.Fa p7 +remains unchanged. +.Sh RETURN VALUES +The function +.Fn PKCS7_set_type +returns 1 on success or 0 on failure. +.Pp +The function +.Fn PKCS7_set0_type_other +does no error handling at all and always returns 1. +.Sh SEE ALSO +.Xr ASN1_OCTET_STRING_new 3 , +.Xr ASN1_TYPE_new 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_set_content 3 , +.Xr PKCS7_sign 3 +.Sh HISTORY +The function +.Fn PKCS7_set_type +first appeared in SSLeay 0.8.1 and +.Fn PKCS7_set0_type_other +in OpenSSL 0.9.8. +Both have been available since +.Ox 2.4 . +.Sh CAVEATS +If +.Fa p7 +has already been in use before being passed to one of these functions, +it will report success even though it leaks memory. +Later on, if other functions try to use +.Fa p7 +in its former role, they are likely to misbehave. diff --git a/static/openbsd/man3/PKCS7_sign.3 b/static/openbsd/man3/PKCS7_sign.3 new file mode 100644 index 00000000..174b3851 --- /dev/null +++ b/static/openbsd/man3/PKCS7_sign.3 @@ -0,0 +1,252 @@ +.\" $OpenBSD: PKCS7_sign.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2003, 2006-2009, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PKCS7_SIGN 3 +.Os +.Sh NAME +.Nm PKCS7_sign +.Nd create a PKCS#7 signedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft PKCS7 * +.Fo PKCS7_sign +.Fa "X509 *signcert" +.Fa "EVP_PKEY *pkey" +.Fa "STACK_OF(X509) *certs" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_sign +creates and returns a PKCS#7 signedData structure. +.Fa signcert +is the certificate to sign with, +.Fa pkey +is the corresponding private key. +.Fa certs +is an optional additional set of certificates to include in the PKCS#7 +structure (for example any intermediate CAs in the chain). +.Pp +The data to be signed is read from +.Vt BIO +.Fa data . +.Pp +.Fa flags +is an optional set of flags. +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter. +.Pp +Many S/MIME clients expect the signed content to include valid MIME +headers. +If the +.Dv PKCS7_TEXT +flag is set, MIME headers for type +.Sy text/plain +are prepended to the data. +.Pp +If +.Dv PKCS7_NOCERTS +is set, the signer's certificate will not be included in the PKCS7 +structure, though the signer's certificate must still be supplied in the +.Fa signcert +parameter. +This can reduce the size of the signature if the signer's certificate can +be obtained by other means: for example a previously signed message. +.Pp +The data being signed is included in the +.Vt PKCS7 +structure, unless +.Dv PKCS7_DETACHED +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 +.Dv PKCS7_BINARY +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 +.Dv PKCS7_NOATTR +is set, then no authenticatedAttributes will be used. +If +.Dv PKCS7_NOSMIMECAP +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 +.Dv PKCS7_STREAM +is set, then the returned +.Vt PKCS7 +structure is just initialized ready to perform the signing operation. +The signing is however +.Sy not +performed and the data to be signed is not read from the +.Fa data +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 +.Dv PKCS7_PARTIAL +flag is set, a partial +.Vt PKCS7 +structure is output to which additional signers and capabilities can be +added before finalization. +.Pp +If the flag +.Dv PKCS7_STREAM +is set, the returned +.Vt PKCS7 +structure is +.Sy not +complete and outputting its contents via a function that does not +properly finalize the +.Vt PKCS7 +structure will give unpredictable results. +.Pp +Several functions including +.Xr PKCS7_final 3 , +.Xr SMIME_write_PKCS7 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +and +.Xr i2d_PKCS7_bio_stream 3 +finalize the structure. +Alternatively finalization can be performed by obtaining the streaming +ASN.1 +.Vt BIO +directly using +.Fn BIO_new_PKCS7 . +.Pp +If a signer is specified, it will use the default digest for the +signing algorithm. +This is +.Sy SHA1 +for both RSA and DSA keys. +.Pp +In OpenSSL 1.0.0, the +.Fa certs , +.Fa signcert , +and +.Fa pkey +parameters can all be +.Dv NULL +if the +.Dv PKCS7_PARTIAL +flag is set. +One or more signers can be added using the function +.Xr PKCS7_sign_add_signer 3 +and attributes can be added using the functions described in +.Xr PKCS7_add_attribute 3 . +.Xr PKCS7_final 3 +must also be called to finalize the structure if streaming is not +enabled. +Alternative signing digests can also be specified using this method. +.Pp +In OpenSSL 1.0.0, if +.Fa signcert +and +.Fa pkey +are +.Dv NULL , +then a certificate-only PKCS#7 structure is output. +.Pp +In versions of OpenSSL before 1.0.0 the +.Fa signcert +and +.Fa pkey +parameters must +.Sy NOT +be +.Dv NULL . +.Sh RETURN VALUES +.Fn PKCS7_sign +returns either a valid +.Vt PKCS7 +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr PKCS7_add_attribute 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_get_signer_info 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_sign_add_signer 3 , +.Xr PKCS7_verify 3 +.Sh HISTORY +.Fn PKCS7_sign +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +The +.Dv PKCS7_PARTIAL +and +.Dv PKCS7_STREAM +flags were added in OpenSSL 1.0.0. +.Sh BUGS +Some advanced attributes such as counter signatures are not supported. diff --git a/static/openbsd/man3/PKCS7_sign_add_signer.3 b/static/openbsd/man3/PKCS7_sign_add_signer.3 new file mode 100644 index 00000000..4b88ff72 --- /dev/null +++ b/static/openbsd/man3/PKCS7_sign_add_signer.3 @@ -0,0 +1,188 @@ +.\" $OpenBSD: PKCS7_sign_add_signer.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2007, 2008, 2009, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt PKCS7_SIGN_ADD_SIGNER 3 +.Os +.Sh NAME +.Nm PKCS7_sign_add_signer +.Nd add a signer to a SignedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft PKCS7_SIGNER_INFO * +.Fo PKCS7_sign_add_signer +.Fa "PKCS7 *p7" +.Fa "X509 *signcert" +.Fa "EVP_PKEY *pkey" +.Fa "const EVP_MD *md" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_sign_add_signer +adds a signer with certificate +.Fa signcert +and private key +.Fa pkey +using message digest +.Fa md +to a +.Vt PKCS7 +signed data structure +.Fa p7 . +.Pp +The +.Vt PKCS7 +structure should be obtained from an initial call to +.Xr PKCS7_sign 3 +with the flag +.Dv PKCS7_PARTIAL +set or, in the case or re-signing, a valid +.Vt PKCS7 +signed data structure. +.Pp +If the +.Fa md +parameter is +.Dv NULL , +then the default digest for the public key algorithm will be used. +.Pp +Unless the +.Dv PKCS7_REUSE_DIGEST +flag is set, the returned +.Dv PKCS7 +structure is not complete and must be +finalized either by streaming (if applicable) or by a call to +.Xr PKCS7_final 3 . +.Pp +The main purpose of this function is to provide finer control over a +PKCS#7 signed data structure where the simpler +.Xr PKCS7_sign 3 +function defaults are not appropriate, for example if multiple +signers or non default digest algorithms are needed. +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter. +.Pp +If +.Dv PKCS7_REUSE_DIGEST +is set, then an attempt is made to copy the content digest value from the +.Vt PKCS7 +structure: to add a signer to an existing structure. +An error occurs if a matching digest value cannot be found to copy. +The returned +.Vt PKCS7 +structure will be valid and finalized when this flag is set. +.Pp +If +.Dv PKCS7_PARTIAL +is set in addition to +.Dv PKCS7_REUSE_DIGEST , +then the +.Dv PKCS7_SIGNER_INO +structure will not be finalized, so additional attributes can be added. +In this case an explicit call to +.Fn PKCS7_SIGNER_INFO_sign +is needed to finalize it. +.Pp +If +.Dv PKCS7_NOCERTS +is set, the signer's certificate will not be included in the +.Vt PKCS7 +structure, though the signer's certificate must still be supplied in the +.Fa signcert +parameter. +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 +.Dv PKCS7_NOATTR +is set, then no authenticatedAttributes will be used. +If +.Dv PKCS7_NOSMIMECAP +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 +.Fn PKCS7_sign_add_signer +returns an internal pointer to the +.Vt PKCS7_SIGNER_INFO +structure just added, which can be used to set additional attributes +with the functions described in +.Xr PKCS7_add_attribute 3 +before it is finalized. +.Sh RETURN VALUES +.Fn PKCS7_sign_add_signer +returns an internal pointer to the +.Vt PKCS7_SIGNER_INFO +structure just added or +.Dv NULL +if an error occurs. +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr EVP_DigestInit 3 , +.Xr PKCS7_add_attribute 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_get_signer_info 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_sign 3 +.Sh HISTORY +.Fn PKCS7_sign_add_signer +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/PKCS7_verify.3 b/static/openbsd/man3/PKCS7_verify.3 new file mode 100644 index 00000000..53b32f73 --- /dev/null +++ b/static/openbsd/man3/PKCS7_verify.3 @@ -0,0 +1,262 @@ +.\" $OpenBSD: PKCS7_verify.3,v 1.13 2025/12/20 07:22:43 tb Exp $ +.\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2006, 2013, 2014, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: December 20 2025 $ +.Dt PKCS7_VERIFY 3 +.Os +.Sh NAME +.Nm PKCS7_verify , +.Nm PKCS7_get0_signers +.Nd verify a PKCS#7 signedData structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_verify +.Fa "PKCS7 *p7" +.Fa "STACK_OF(X509) *certs" +.Fa "X509_STORE *store" +.Fa "BIO *indata" +.Fa "BIO *out" +.Fa "int flags" +.Fc +.Ft STACK_OF(X509) * +.Fo PKCS7_get0_signers +.Fa "PKCS7 *p7" +.Fa "STACK_OF(X509) *certs" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_verify +verifies a PKCS#7 signedData structure. +.Fa p7 +is the +.Vt PKCS7 +structure to verify. +.Fa certs +is a set of certificates in which to search for the signer's +certificate. +.Fa store +is a trusted certificate store (used for chain verification). +.Fa indata +is the signed data if the content is not present in +.Fa p7 , +that is if it is detached. +The content is written to +.Fa out +if it is not +.Dv NULL . +.Pp +.Fa flags +is an optional set of flags, which can be used to modify the verify +operation. +.Pp +.Fn PKCS7_get0_signers +retrieves the signer's certificates from +.Fa p7 . +The signers must be freed with +.Fn sk_X509_free . +It does +.Sy not +check their validity or whether any signatures are valid. +The +.Fa certs +and +.Fa flags +parameters have the same meanings as in +.Fn PKCS7_verify . +.Pp +Normally the verify process proceeds as follows. +.Pp +Initially some sanity checks are performed on +.Fa p7 . +The type of +.Fa p7 +must be signedData. +There must be at least one signature on the data and if the content +is detached, +.Fa indata +cannot be +.Dv NULL . +If the content is not detached and +.Fa indata +is not +.Fa NULL , +then the structure has both embedded and external content. +To treat this as an error, use the flag +.Dv PKCS7_NO_DUAL_CONTENT . +The default behavior allows this, for compatibility with other +implementations. +.Pp +An attempt is made to locate all the signer's certificates, first +looking in the +.Fa certs +parameter (if it is not +.Dv NULL ) +and then looking in any certificates contained in the +.Fa p7 +structure itself. +If any signer's certificates cannot be located, the operation fails. +.Pp +Each signer's certificate is chain verified using the +.Sy smimesign +purpose and the supplied trusted certificate store. +Any internal certificates in the message are used as untrusted CAs. +If any chain verify fails, an error code is returned. +.Pp +Finally, the signed content is read (and written to +.Fa out +if it is not +.Dv NULL ) +and the signature's checked. +.Pp +If all signature's verify correctly then the function is successful. +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter to change the default verify behaviour. +Only the flag +.Dv PKCS7_NOINTERN +is meaningful to +.Fn PKCS7_get0_signers . +.Pp +If +.Dv PKCS7_NOINTERN +is set, the certificates in the message itself are not searched when +locating the signer's certificate. +This means that all the signer's certificates must be in the +.Fa certs +parameter. +.Pp +If the +.Dv PKCS7_TEXT +flag is set, MIME headers for type +.Sy text/plain +are deleted from the content. +If the content is not of type +.Sy text/plain , +then an error is returned. +.Pp +If +.Dv PKCS7_NOVERIFY +is set, the signer's certificates are not chain verified. +.Pp +If +.Dv PKCS7_NOCHAIN +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's +certificate) must be contained in the trusted store. +.Pp +If +.Dv PKCS7_NOSIGS +is set, then the signatures on the data are not checked. +.Pp +One application of +.Dv PKCS7_NOINTERN +is to only accept messages signed by a small number of certificates. +The acceptable certificates would be passed in the +.Fa certs +parameter. +In this case, if the signer is not one of the certificates supplied in +.Fa certs , +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 +.Dv PKCS7_NOVERIFY | PKCS7_NOSIGS +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 +.Fa out +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 +.Fn PKCS7_verify +returns 1 for a successful verification and 0 or a negative value if +an error occurs. +.Pp +.Fn PKCS7_get0_signers +returns all signers or +.Dv NULL +if an error occurred. +The signers must be freed with +.Fn sk_X509_free . +.Pp +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr PKCS7_decrypt 3 , +.Xr PKCS7_new 3 , +.Xr PKCS7_sign 3 , +.Xr X509_STORE_new 3 +.Sh HISTORY +.Fn PKCS7_verify +and +.Fn PKCS7_get0_signers +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Sh BUGS +The trusted certificate store is not searched for the signer's +certificate. +This is primarily due to the inadequacies of the current +.Vt X509_STORE +functionality. +.Pp +The lack of single pass processing and the need to hold all data +in memory as mentioned in +.Xr PKCS7_sign 3 +also applies to +.Fn PKCS7_verify . diff --git a/static/openbsd/man3/PKCS8_PRIV_KEY_INFO_new.3 b/static/openbsd/man3/PKCS8_PRIV_KEY_INFO_new.3 new file mode 100644 index 00000000..55eb464a --- /dev/null +++ b/static/openbsd/man3/PKCS8_PRIV_KEY_INFO_new.3 @@ -0,0 +1,66 @@ +.\" $OpenBSD: PKCS8_PRIV_KEY_INFO_new.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt PKCS8_PRIV_KEY_INFO_NEW 3 +.Os +.Sh NAME +.Nm PKCS8_PRIV_KEY_INFO_new , +.Nm PKCS8_PRIV_KEY_INFO_free +.Nd PKCS#8 private key information +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft PKCS8_PRIV_KEY_INFO * +.Fn PKCS8_PRIV_KEY_INFO_new void +.Ft void +.Fn PKCS8_PRIV_KEY_INFO_free "PKCS8_PRIV_KEY_INFO *key" +.Sh DESCRIPTION +.Fn PKCS8_PRIV_KEY_INFO_new +allocates and initializes an empty +.Vt PKCS8_PRIV_KEY_INFO +object, representing an ASN.1 +.Vt PrivateKeyInfo +structure defined in RFC 5208 section 5. +It can hold a private key together with information about the +algorithm to be used with it and optional attributes. +.Pp +.Fn PKCS8_PRIV_KEY_INFO_free +frees +.Fa key . +.Sh RETURN VALUES +.Fn PKCS8_PRIV_KEY_INFO_new +returns the new +.Vt PKCS8_PRIV_KEY_INFO +object or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_PKCS8_PRIV_KEY_INFO 3 , +.Xr d2i_PKCS8PrivateKey_bio 3 , +.Xr EVP_PKCS82PKEY 3 , +.Xr PEM_read_PKCS8_PRIV_KEY_INFO 3 , +.Xr PKCS12_parse 3 , +.Xr PKCS8_pkey_set0 3 , +.Xr X509_ATTRIBUTE_new 3 +.Sh STANDARDS +RFC 5208: PKCS#8: Private-Key Information Syntax Specification +.Sh HISTORY +.Fn PKCS8_PRIV_KEY_INFO_new +and +.Fn PKCS8_PRIV_KEY_INFO_free +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/PKCS8_pkey_set0.3 b/static/openbsd/man3/PKCS8_pkey_set0.3 new file mode 100644 index 00000000..a8a160d5 --- /dev/null +++ b/static/openbsd/man3/PKCS8_pkey_set0.3 @@ -0,0 +1,160 @@ +.\" $OpenBSD: PKCS8_pkey_set0.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt PKCS8_PKEY_SET0 3 +.Os +.Sh NAME +.Nm PKCS8_pkey_set0 , +.Nm PKCS8_pkey_get0 , +.Nm PKCS8_pkey_add1_attr_by_NID , +.Nm PKCS8_pkey_get0_attrs +.Nd change and inspect PKCS#8 PrivateKeyInfo objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo PKCS8_pkey_set0 +.Fa "PKCS8_PRIV_KEY_INFO *keyinfo" +.Fa "ASN1_OBJECT *aobj" +.Fa "int version" +.Fa "int ptype" +.Fa "void *pval" +.Fa "unsigned char *data" +.Fa "int len" +.Fc +.Ft int +.Fo PKCS8_pkey_get0 +.Fa "const ASN1_OBJECT **paobj" +.Fa "const unsigned char **pdata" +.Fa "int *plen" +.Fa "const X509_ALGOR **palgor" +.Fa "const PKCS8_PRIV_KEY_INFO *keyinfo" +.Fc +.Ft int +.Fo PKCS8_pkey_add1_attr_by_NID +.Fa "PKCS8_PRIV_KEY_INFO *keyinfo" +.Fa "int nid" +.Fa "int type" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft const STACK_OF(X509_ATTRIBUTE) * +.Fo PKCS8_pkey_get0_attrs +.Fa "const PKCS8_PRIV_KEY_INFO *keyinfo" +.Fc +.Sh DESCRIPTION +.Fn PKCS8_pkey_set0 +initializes the +.Fa keyinfo +object. +The algorithm is set to +.Fa aobj +with the associated parameter type +.Fa ptype +and parameter value +.Fa pval +using +.Xr X509_ALGOR_set0 3 , +replacing any previous information about the algorithm. +Unless +.Fa data +is +.Dv NULL , +the encoded private key is set to the +.Fa len +bytes starting at +.Fa data +using +.Xr ASN1_STRING_set0 3 , +not performing any validation. +If +.Fa data +is +.Dv NULL , +the key data remains unchanged. +If the +.Fa version +argument is greater than or equal to 0, it replaces any existing version; +otherwise, the version remains unchanged. +If +.Fa keyinfo +contains any attributes, they remain unchanged. +.Pp +.Fn PKCS8_pkey_get0 +retrieves some information from the +.Fa keyinfo +object. +Internal pointers to the algorithm OID, the +.Vt AlgorithmIdentifier , +and the encoded private key are stored in +.Pf * Fa paobj , +.Pf * Fa palgor , +and +.Pf * Fa pdata , +respectively. +.Dv NULL +pointers can be passed for any of these three arguments if the respective +information is not needed. +Unless +.Fa pdata +is +.Dv NULL , +.Pf * Fa plen +is set to the number of bytes in +.Pf * Fa pdata . +.Pp +.Fn PKCS8_pkey_add1_attr_by_NID +creates a new X.501 Attribute object using +.Xr X509_ATTRIBUTE_create_by_NID 3 +and appends it to the attributes of +.Fa keyinfo . +.Sh RETURN VALUES +.Fn PKCS8_pkey_set0 +and +.Fn PKCS8_pkey_add1_attr_by_NID +return 1 for success or 0 for failure. +.Pp +.Fn PKCS8_pkey_get0 +always returns 1. +.Pp +.Fn PKCS8_pkey_get0_attrs +returns an internal pointer to the array of attributes associated with +.Fa keyinfo +or +.Dv NULL +if no attributes are set. +.Sh SEE ALSO +.Xr ASN1_STRING_set0 3 , +.Xr EVP_PKCS82PKEY 3 , +.Xr OBJ_nid2obj 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 , +.Xr STACK_OF 3 , +.Xr X509_ALGOR_new 3 , +.Xr X509_ATTRIBUTE_create_by_NID 3 , +.Xr X509_ATTRIBUTE_new 3 +.Sh HISTORY +.Fn PKCS8_pkey_set0 +and +.Fn PKCS8_pkey_get0 +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +.Fn PKCS8_pkey_add1_attr_by_NID +and +.Fn PKCS8_pkey_get0_attrs +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.4 . diff --git a/static/openbsd/man3/PKEY_USAGE_PERIOD_new.3 b/static/openbsd/man3/PKEY_USAGE_PERIOD_new.3 new file mode 100644 index 00000000..2d4f010b --- /dev/null +++ b/static/openbsd/man3/PKEY_USAGE_PERIOD_new.3 @@ -0,0 +1,75 @@ +.\" $OpenBSD: PKEY_USAGE_PERIOD_new.3,v 1.6 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt PKEY_USAGE_PERIOD_NEW 3 +.Os +.Sh NAME +.Nm PKEY_USAGE_PERIOD_new , +.Nm PKEY_USAGE_PERIOD_free +.Nd X.509 certificate private key usage period extension +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft PKEY_USAGE_PERIOD * +.Fn PKEY_USAGE_PERIOD_new void +.Ft void +.Fn PKEY_USAGE_PERIOD_free "PKEY_USAGE_PERIOD *period" +.Sh DESCRIPTION +.Fn PKEY_USAGE_PERIOD_new +allocates and initializes an empty +.Vt PKEY_USAGE_PERIOD +object, representing an ASN.1 +.Vt PrivateKeyUsagePeriod +structure defined in RFC 3280 section 4.2.1.4. +It could be used in +.Vt X509 +certificates to specify a validity period for the private key +that differed from the validity period of the certificate. +.Pp +.Fn PKEY_USAGE_PERIOD_free +frees +.Fa period . +.Sh RETURN VALUES +.Fn PKEY_USAGE_PERIOD_new +returns the new +.Vt PKEY_USAGE_PERIOD +object or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_PKEY_USAGE_PERIOD 3 , +.Xr EXTENDED_KEY_USAGE_new 3 , +.Xr X509_CINF_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 3280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 4.2.1.4: Private Key Usage Period +.Pp +RFC 3280 was obsoleted by RFC 5280, which says: "Section 4.2.1.4 +in RFC 3280, which specified the +.Vt PrivateKeyUsagePeriod +certificate extension but deprecated its use, was removed. +Use of this ISO standard extension is neither deprecated +nor recommended for use in the Internet PKI." +.Sh HISTORY +.Fn PKEY_USAGE_PERIOD_new +and +.Fn PKEY_USAGE_PERIOD_free +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/POLICYINFO_new.3 b/static/openbsd/man3/POLICYINFO_new.3 new file mode 100644 index 00000000..aad2ad3c --- /dev/null +++ b/static/openbsd/man3/POLICYINFO_new.3 @@ -0,0 +1,219 @@ +.\" $OpenBSD: POLICYINFO_new.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt POLICYINFO_NEW 3 +.Os +.Sh NAME +.Nm POLICYINFO_new , +.Nm POLICYINFO_free , +.Nm CERTIFICATEPOLICIES_new , +.Nm CERTIFICATEPOLICIES_free , +.Nm POLICYQUALINFO_new , +.Nm POLICYQUALINFO_free , +.Nm USERNOTICE_new , +.Nm USERNOTICE_free , +.Nm NOTICEREF_new , +.Nm NOTICEREF_free , +.Nm POLICY_MAPPING_new , +.Nm POLICY_MAPPING_free , +.Nm POLICY_CONSTRAINTS_new , +.Nm POLICY_CONSTRAINTS_free +.Nd X.509 certificate policies +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft POLICYINFO * +.Fn POLICYINFO_new void +.Ft void +.Fn POLICYINFO_free "POLICYINFO *pi" +.Ft CERTIFICATEPOLICIES * +.Fn CERTIFICATEPOLICIES_new void +.Ft void +.Fn CERTIFICATEPOLICIES_free "CERTIFICATEPOLICIES *pis" +.Ft POLICYQUALINFO * +.Fn POLICYQUALINFO_new void +.Ft void +.Fn POLICYQUALINFO_free "POLICYQUALINFO *pqi" +.Ft USERNOTICE * +.Fn USERNOTICE_new void +.Ft void +.Fn USERNOTICE_free "USERNOTICE *usernotice" +.Ft NOTICEREF * +.Fn NOTICEREF_new void +.Ft void +.Fn NOTICEREF_free "NOTICEREF *noticeref" +.Ft POLICY_MAPPING * +.Fn POLICY_MAPPING_new void +.Ft void +.Fn POLICY_MAPPING_free "POLICY_MAPPING *pm" +.Ft POLICY_CONSTRAINTS * +.Fn POLICY_CONSTRAINTS_new void +.Ft void +.Fn POLICY_CONSTRAINTS_free "POLICY_CONSTRAINTS *pc" +.Sh DESCRIPTION +X.509 CA and end entity certificates can optionally indicate +restrictions on their intended use. +.Pp +.Fn POLICYINFO_new +allocates and initializes an empty +.Vt POLICYINFO +object, representing an ASN.1 +.Vt PolicyInformation +structure defined in RFC 5280 section 4.2.1.4. +It can hold a policy identifier and optional advisory qualifiers. +.Fn POLICYINFO_free +frees +.Fa pi . +.Pp +.Fn CERTIFICATEPOLICIES_new +allocates and initializes an empty +.Vt CERTIFICATEPOLICIES +object, which is a +.Vt STACK_OF(POLICYINFO) +and represents an ASN.1 +.Vt CertificatePolicies +structure defined in RFC 5280 section 4.2.1.4. +It can be used by +.Vt X509 +objects, both by CA certificates and end entity certificates. +.Fn CERTIFICATEPOLICIES_free +frees +.Fa pis . +.Pp +.Fn POLICYQUALINFO_new +allocates and initializes an empty +.Vt POLICYQUALINFO +object, representing an ASN.1 +.Vt PolicyQualifierInfo +structure defined in RFC 5280 section 4.2.1.4. +It can be used in +.Vt POLICYINFO +and it can hold either a uniform resource identifier of a certification +practice statement published by the CA, or a pointer to a +.Vt USERNOTICE +object, or arbitrary other information. +.Fn POLICYQUALINFO_free +frees +.Fa pqi . +.Pp +.Fn USERNOTICE_new +allocates and initializes an empty +.Vt USERNOTICE +object, representing an ASN.1 +.Vt UserNotice +structure defined in RFC 5280 section 4.2.1.4. +It can be used in +.Vt POLICYQUALINFO +and it can hold either an +.Vt ASN1_STRING +intended for display to the user or a pointer to a +.Vt NOTICEREF +object. +.Fn NOTICEREF_free +frees +.Fa usernotice . +.Pp +.Fn NOTICEREF_new +allocates and initializes an empty +.Vt NOTICEREF +object, representing an ASN.1 +.Vt NoticeReference +structure defined in RFC 5280 section 4.2.1.4. +It can be used in +.Vt USERNOTICE +and can hold an organization name and a stack of notice numbers. +.Fn NOTICEREF_free +frees +.Fa noticeref . +.Pp +.Fn POLICY_MAPPING_new +allocates and initializes an empty +.Vt POLICY_MAPPING +object, representing an ASN.1 +.Vt PolicyMappings +structure defined in RFC 5280 section 4.2.1.5. +It can be used in +.Vt X509 +CA certificates and can hold a list of pairs of policy identifiers, +declaring one of the policies in each pair as equivalent to the +other. +.Fn POLICY_MAPPING_free +frees +.Fa pm . +.Pp +.Fn POLICY_CONSTRAINTS_new +allocates and initializes an empty +.Vt POLICY_CONSTRAINTS +object, representing an ASN.1 +.Vt PolicyConstraints +structure defined in RFC 5280 section 4.2.1.11. +It can be used in +.Vt X509 +CA certificates to restrict policy mapping and/or to require explicit +certificate policies in subsequent intermediate certificates in the +certification path. +.Fn POLICY_CONSTRAINTS_free +frees +.Fa pc . +.Sh RETURN VALUES +The constructor functions return a new object of the respective +type or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr BASIC_CONSTRAINTS_new 3 , +.Xr d2i_POLICYINFO 3 , +.Xr NAME_CONSTRAINTS_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_get_extension_flags 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile: +.Bl -dash -compact +.It +section 4.2.1.4: Certificate Policies +.It +section 4.2.1.5: Policy Mappings +.It +section 4.2.1.11: Policy Constraints +.El +.Sh HISTORY +.Fn POLICYINFO_new , +.Fn POLICYINFO_free , +.Fn CERTIFICATEPOLICIES_new , +.Fn CERTIFICATEPOLICIES_free , +.Fn POLICYQUALINFO_new , +.Fn POLICYQUALINFO_free , +.Fn USERNOTICE_new , +.Fn USERNOTICE_free , +.Fn NOTICEREF_new , +and +.Fn NOTICEREF_free +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . +.Pp +.Fn POLICY_MAPPING_new , +.Fn POLICY_MAPPING_free , +.Fn POLICY_CONSTRAINTS_new , +and +.Fn POLICY_CONSTRAINTS_free +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Sh BUGS +This is a lot of nested data structures, but most of them are +designed to have almost no effect. diff --git a/static/openbsd/man3/RAND_add.3 b/static/openbsd/man3/RAND_add.3 new file mode 100644 index 00000000..b56707a3 --- /dev/null +++ b/static/openbsd/man3/RAND_add.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: RAND_add.3,v 1.11 2025/06/08 22:40:30 schwarze Exp $ +.\" content checked up to: OpenSSL c16de9d8 Aug 31 23:16:22 2017 +0200 +.\" +.\" Copyright (c) 2014 Miod Vallat +.\" +.\" 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: June 8 2025 $ +.Dt RAND_ADD 3 +.Os +.Sh NAME +.Nm RAND_add , +.Nm RAND_cleanup , +.Nm RAND_poll , +.Nm RAND_seed , +.Nm RAND_status +.Nd manipulate the PRNG state +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rand.h +.Ft void +.Fo RAND_add +.Fa "const void *buf" +.Fa "int num" +.Fa "double entropy" +.Fc +.Ft void +.Fn RAND_cleanup void +.Ft int +.Fn RAND_poll void +.Ft void +.Fo RAND_seed +.Fa "const void *buf" +.Fa "int num" +.Fc +.Ft int +.Fn RAND_status void +.Sh DESCRIPTION +These functions used to allow for the state of the random number +generator to be controlled by external sources. +.Pp +They are kept for ABI compatibility but are no longer functional, and +should not be used in new programs. +.Sh RETURN VALUES +.Fn RAND_poll +and +.Fn RAND_status +always return 1. +.Sh HISTORY +.Fn RAND_cleanup +and +.Fn RAND_seed +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn RAND_add +and +.Fn RAND_status +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn RAND_poll +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . diff --git a/static/openbsd/man3/RAND_bytes.3 b/static/openbsd/man3/RAND_bytes.3 new file mode 100644 index 00000000..ce0773f4 --- /dev/null +++ b/static/openbsd/man3/RAND_bytes.3 @@ -0,0 +1,109 @@ +.\" $OpenBSD: RAND_bytes.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RAND_BYTES 3 +.Os +.Sh NAME +.Nm RAND_bytes , +.Nm RAND_pseudo_bytes +.Nd generate random data +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rand.h +.Ft int +.Fo RAND_bytes +.Fa "unsigned char *buf" +.Fa "int num" +.Fc +.Ft int +.Fo RAND_pseudo_bytes +.Fa "unsigned char *buf" +.Fa "int num" +.Fc +.Sh DESCRIPTION +These functions are deprecated and only retained for compatibility +with legacy application programs. +Use +.Xr arc4random_buf 3 +instead. +.Pp +.Fn RAND_bytes +puts +.Fa num +cryptographically strong pseudo-random bytes into +.Fa buf . +.Pp +.Fn RAND_pseudo_bytes +puts +.Fa num +pseudo-random bytes into +.Fa buf . +Pseudo-random byte sequences generated by +.Fn RAND_pseudo_bytes +will be unique if they are of sufficient length, but are not necessarily +unpredictable. +They can be used for non-cryptographic purposes and for certain purposes +in cryptographic protocols, but usually not for key generation etc. +.Sh RETURN VALUES +.Fn RAND_bytes +returns 1. +.Fn RAND_pseudo_bytes +returns 1. +.Sh HISTORY +.Fn RAND_bytes +first appeared in SSLeay 0.5.1 and has been available since +.Ox 2.4 . +It has a return value since OpenSSL 0.9.5 and +.Ox 2.7 . +.Pp +.Fn RAND_pseudo_bytes +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/RAND_load_file.3 b/static/openbsd/man3/RAND_load_file.3 new file mode 100644 index 00000000..1c6f7a27 --- /dev/null +++ b/static/openbsd/man3/RAND_load_file.3 @@ -0,0 +1,120 @@ +.\" $OpenBSD: RAND_load_file.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RAND_LOAD_FILE 3 +.Os +.Sh NAME +.Nm RAND_file_name , +.Nm RAND_load_file , +.Nm RAND_write_file +.Nd PRNG seed file +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rand.h +.Ft const char * +.Fo RAND_file_name +.Fa "char *buf" +.Fa "size_t num" +.Fc +.Ft int +.Fo RAND_load_file +.Fa "const char *filename" +.Fa "long max_bytes" +.Fc +.Ft int +.Fo RAND_write_file +.Fa "const char *filename" +.Fc +.Sh DESCRIPTION +.Fn RAND_file_name +returns a default path for the random seed file. +.Fa buf +points to a buffer of size +.Fa num +in which to store the filename. +If +.Fa num +is too small for the path name, an error occurs. +.Pp +.Fn RAND_load_file +used to allow for the state of the random number generator to be +controlled by external sources. +It is kept for ABI compatibility but is no longer functional, and should +not be used in new programs. +.Pp +.Fn RAND_write_file +writes a number of random bytes (currently 1024) to file +.Fa filename . +.Sh RETURN VALUES +.Fn RAND_load_file +returns +.Fa max_bytes , +or a bogus positive value if +.Fa max_bytes +is -1. +.Pp +.Fn RAND_write_file +returns the number of bytes written, or a number less than or equal +to 1 if an error occurs. +.Pp +.Fn RAND_file_name +returns a pointer to +.Fa buf +on success or +.Dv NULL +on error. +.Sh HISTORY +.Fn RAND_load_file , +.Fn RAND_write_file , +and +.Fn RAND_file_name +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/RAND_set_rand_method.3 b/static/openbsd/man3/RAND_set_rand_method.3 new file mode 100644 index 00000000..2756099c --- /dev/null +++ b/static/openbsd/man3/RAND_set_rand_method.3 @@ -0,0 +1,56 @@ +.\" $OpenBSD: RAND_set_rand_method.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Miod Vallat +.\" +.\" 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: June 8 2025 $ +.Dt RAND_SET_RAND_METHOD 3 +.Os +.Sh NAME +.Nm RAND_set_rand_method , +.Nm RAND_get_rand_method , +.Nm RAND_SSLeay +.Nd select RAND method +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rand.h +.Ft int +.Fo RAND_set_rand_method +.Fa "const RAND_METHOD *meth" +.Fc +.Ft const RAND_METHOD * +.Fn RAND_get_rand_method void +.Ft RAND_METHOD * +.Fn RAND_SSLeay void +.Sh DESCRIPTION +These functions used to allow for the random number generator functions +to be replaced by arbitrary code. +.Pp +They are kept for ABI compatibility but are no longer functional, and +should not be used in new programs. +.Sh RETURN VALUES +.Fn RAND_set_rand_method +always returns 1. +.Fn RAND_get_rand_method +and +.Fn RAND_SSLeay +always return +.Dv NULL . +.Sh HISTORY +.Fn RAND_set_rand_method , +.Fn RAND_get_rand_method , +and +.Fn RAND_SSLeay +first appeared in SSLeay 0.9.1 and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/RC2_encrypt.3 b/static/openbsd/man3/RC2_encrypt.3 new file mode 100644 index 00000000..735c10cb --- /dev/null +++ b/static/openbsd/man3/RC2_encrypt.3 @@ -0,0 +1,196 @@ +.\" $OpenBSD: RC2_encrypt.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2024 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 $Mdocdate: June 8 2025 $ +.Dt RC2_ENCRYPT 3 +.Os +.Sh NAME +.Nm RC2_set_key , +.Nm RC2_encrypt , +.Nm RC2_decrypt , +.Nm RC2_cbc_encrypt , +.Nm RC2_ecb_encrypt , +.Nm RC2_cfb64_encrypt , +.Nm RC2_ofb64_encrypt +.Nd low-level functions for Rivest Cipher 2 +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rc2.h +.Ft void +.Fo RC2_set_key +.Fa "RC2_KEY *expanded_key" +.Fa "int len" +.Fa "const unsigned char *user_key" +.Fa "int effective_bits" +.Fc +.Ft void +.Fo RC2_encrypt +.Fa "unsigned long *data" +.Fa "RC2_KEY *expanded_key" +.Fc +.Ft void +.Fo RC2_decrypt +.Fa "unsigned long *data" +.Fa "RC2_KEY *expanded_key" +.Fc +.Ft void +.Fo RC2_cbc_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "RC2_KEY *expanded_key" +.Fa "unsigned char *iv" +.Fa "int encrypt" +.Fc +.Ft void +.Fo RC2_ecb_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "RC2_KEY *expanded_key" +.Fa "int encrypt" +.Fc +.Ft void +.Fo RC2_cfb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "RC2_KEY *expanded_key" +.Fa "unsigned char *iv" +.Fa "int *num" +.Fa "int encrypt" +.Fc +.Ft void +.Fo RC2_ofb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "RC2_KEY *expanded_key" +.Fa "unsigned char *iv" +.Fa "int *num" +.Fc +.Sh DESCRIPTION +RC2 is a block cipher operating on blocks of +.Dv RC2_BLOCK No = 8 +bytes, equivalent to 64 bits, using a variable key length +with an additional parameter called +.Dq effective key bits +or +.Dq effective key length . +The maximum effective key length is 1024 bits. +.Pp +If using RC2 cannot be avoided, it is recommended that application +programs use the +.Xr EVP_rc2_cbc 3 +family of functions instead of the functions documented in the present +manual page, to ease later migration to less outdated encryption algorithms. +.Pp +.Fn RC2_set_key +expands the first +.Fa len +bytes of +.Fa user_key +into the +.Vt RC2_KEY +structure +.Pf * Fa expanded_key . +The storage for the expanded key has to be provided by the calling code. +If the +.Fa len +argument exceeds 128, only the first 128 bytes are used. +.Pp +Optionally, if the +.Fa effective_bits +argument is positive and less than 1024, the effective key length of +.Pf * Fa expanded_key +is reduced to +.Fa effective_bits . +Reducing the effective key length is not cryptographically useful. +This option was originally designed to conform to US export regulations +valid at the time, which were designed to allow the US government +to spy on foreign encrypted communications. +Unless interoperability requires otherwise, setting +.Fa effective_bits +to 1024 is recommended. +.Pp +.Fn RC2_encrypt +and +.Fn RC2_decrypt +interpret +.Fa data +as an array of two 32 bit integers and encrypt or decrypt +that single block in place, respectively, using the +.Fa expanded_key . +.Pp +The remaining functions encode or decode +.Fa length +bytes starting at +.Fa in +to +.Fa length +bytes starting at +.Fa out +in various modes of operation using the +.Fa expanded_key . +Both arrays need to be long enough to hold +.Fa length +bytes rounded up to the next multiple of 8. +The +.Fa iv +argument points to an array of 8 bytes used as the initialization vector. +If the +.Fa encrypt +argument is +.Dv RC2_ENCRYPT +or another non-zero value, encryption is performed; +if it is +.Dv RC2_DECRYPT No = 0 , +decryption is performed. +.Pp +.Fn RC2_cbc_encrypt +operates in cipher block chaining mode. +.Pp +.Fn RC2_ecb_encrypt +encodes or decodes eight bytes at +.Fa in +to +eight bytes at +.Fa out +in electronic codebook mode. +.Pp +.Fn RC2_cfb64_encrypt +and +.Fn RC2_ofb64_encrypt +operate in cipher feedback mode and output feedback mode, respectively, +with 64 bit blocks. +The number of bytes used from the last 8 byte block is kept track of in +.Pf * Fa num . +.Sh SEE ALSO +.Xr crypto 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_rc2_cbc 3 +.Sh HISTORY +.Fn RC2_set_key , +.Fn RC2_encrypt , +.Fn RC2_cbc_encrypt , +.Fn RC2_ecb_encrypt , +.Fn RC2_cfb64_encrypt , +and +.Fn RC2_ofb64_encrypt +first appeared in SSLeay 0.5.2. +.Fn RC2_decrypt +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/RC4.3 b/static/openbsd/man3/RC4.3 new file mode 100644 index 00000000..ff92cffc --- /dev/null +++ b/static/openbsd/man3/RC4.3 @@ -0,0 +1,127 @@ +.\" $OpenBSD: RC4.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RC4 3 +.Os +.Sh NAME +.Nm RC4_set_key , +.Nm RC4 +.Nd RC4 encryption +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rc4.h +.Ft void +.Fo RC4_set_key +.Fa "RC4_KEY *key" +.Fa "int len" +.Fa "const unsigned char *data" +.Fc +.Ft void +.Fo RC4 +.Fa "RC4_KEY *key" +.Fa "unsigned long len" +.Fa "const unsigned char *indata" +.Fa "unsigned char *outdata" +.Fc +.Sh DESCRIPTION +This library implements the alleged RC4 cipher, which is described for +example in +.Qq Applied Cryptography . +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 +.Fn RC4_set_key +sets up the +.Vt RC4_KEY +.Fa key +using the +.Fa len +bytes long key at +.Fa data . +.Pp +.Fn RC4 +encrypts or decrypts the +.Fa len +bytes of data at +.Fa indata +using +.Fa key +and places the result at +.Fa outdata . +Repeated +.Fn RC4 +calls with the same +.Fa key +yield a continuous key stream. +.Pp +Since RC4 is a stream cipher (the input is XOR'ed with a pseudo-random +key stream to produce the output), decryption uses the same function +calls as encryption. +.Sh SEE ALSO +.Xr blowfish 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_rc4 3 +.Sh HISTORY +.Fn RC4_set_key +and +.Fn RC4 +appeared in SSLeay 0.4 or earlier and have been available since +.Ox 2.4 . +.Sh BUGS +This cipher is broken and should no longer be used. diff --git a/static/openbsd/man3/RIPEMD160.3 b/static/openbsd/man3/RIPEMD160.3 new file mode 100644 index 00000000..e22f4ed8 --- /dev/null +++ b/static/openbsd/man3/RIPEMD160.3 @@ -0,0 +1,155 @@ +.\" $OpenBSD: RIPEMD160.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 72a7a702 Feb 26 14:05:09 2019 +0000 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2006, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RIPEMD160 3 +.Os +.Sh NAME +.Nm RIPEMD160 , +.Nm RIPEMD160_Init , +.Nm RIPEMD160_Update , +.Nm RIPEMD160_Final +.Nd RIPEMD-160 hash function +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ripemd.h +.Ft unsigned char * +.Fo RIPEMD160 +.Fa "const unsigned char *d" +.Fa "unsigned long n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo RIPEMD160_Init +.Fa "RIPEMD160_CTX *c" +.Fc +.Ft int +.Fo RIPEMD160_Update +.Fa "RIPEMD160_CTX *c" +.Fa "const void *data" +.Fa "unsigned long len" +.Fc +.Ft int +.Fo RIPEMD160_Final +.Fa "unsigned char *md" +.Fa "RIPEMD160_CTX *c" +.Fc +.Sh DESCRIPTION +RIPEMD-160 is a cryptographic hash function with a 160-bit output. +.Pp +.Fn RIPEMD160 +computes the RIPEMD-160 message digest of the +.Fa n +bytes at +.Fa d +and places it in +.Fa md , +which must have space for +.Dv RIPEMD160_DIGEST_LENGTH +== 20 bytes of output. +.Pp +The following functions may be used if the message is not completely +stored in memory: +.Pp +.Fn RIPEMD160_Init +initializes a +.Vt RIPEMD160_CTX +structure. +.Pp +.Fn RIPEMD160_Update +can be called repeatedly with chunks of the message to be hashed +.Pq Fa len No bytes at Fa data . +.Pp +.Fn RIPEMD160_Final +places the message digest in +.Fa md , +which must have space for +.Dv RIPEMD160_DIGEST_LENGTH +== 20 bytes of output, +and erases the +.Vt RIPEMD160_CTX . +.Pp +Applications should use the higher level functions +.Xr EVP_DigestInit 3 +etc. instead of calling the hash functions directly. +.Sh RETURN VALUES +.Fn RIPEMD160 +returns a pointer to the hash value. +.Pp +.Fn RIPEMD160_Init , +.Fn RIPEMD160_Update , +and +.Fn RIPEMD160_Final +return 1 for success or 0 otherwise. +.Sh SEE ALSO +.Xr EVP_DigestInit 3 , +.Xr HMAC 3 +.Sh STANDARDS +.Bd -unfilled +ISO/IEC 10118-3:2004/Cor 1:2011 +Hash-functions \(em Part 3: Dedicated hash-functions +Clause 7: RIPEMD-160 +.Ed +.Sh HISTORY +.Fn RIPEMD160 , +.Fn RIPEMD160_Init , +.Fn RIPEMD160_Update , +and +.Fn RIPEMD160_Final +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . +.Sh CAVEATS +Other implementations allow +.Fa md +in +.Fn RIPEMD160 +to be +.Dv NULL +and return a static array, which is not thread safe. diff --git a/static/openbsd/man3/RMD160Init.3 b/static/openbsd/man3/RMD160Init.3 new file mode 100644 index 00000000..f923d685 --- /dev/null +++ b/static/openbsd/man3/RMD160Init.3 @@ -0,0 +1,236 @@ +.\" $OpenBSD: RMD160Init.3,v 1.4 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 1997, 2004 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. +.\" +.\" See http://www.esat.kuleuven.ac.be/~bosselae/ripemd160.html +.\" for detailed information about RIPEMD-160. +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt RMD160INIT 3 +.Os +.Sh NAME +.Nm RMD160Init , +.Nm RMD160Update , +.Nm RMD160Pad , +.Nm RMD160Final , +.Nm RMD160Transform , +.Nm RMD160End , +.Nm RMD160File , +.Nm RMD160FileChunk , +.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_int8_t *data" "size_t nbytes" +.Ft void +.Fn RMD160Pad "RMD160_CTX *context" +.Ft void +.Fn RMD160Final "u_int8_t digest[RMD160_DIGEST_LENGTH]" "RMD160_CTX *context" +.Ft void +.Fn RMD160Transform "u_int32_t state[5]" "const u_int8_t block[RMD160_BLOCK_LENGTH]" +.Ft char * +.Fn RMD160End "RMD160_CTX *context" "char *buf" +.Ft char * +.Fn RMD160File "const char *filename" "char *buf" +.Ft char * +.Fn RMD160FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft char * +.Fn RMD160Data "const u_int8_t *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 +MD5 +functions and at least as secure as the +SHA1 +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. +.Pp +The +.Fn RMD160Pad +function can be used to apply padding to the message digest as in +.Fn RMD160Final , +but 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 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 +.Fn RMD160FileChunk +behaves like +.Fn RMD160File +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 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 +.Dq abc +which is +.Dq 0x8eb208f7e05d987a9b044a8e98c6b087f15a0bfc . +.Bd -literal -offset indent +RMD160_CTX rmd; +u_int8_t results[RMD160_DIGEST_LENGTH]; +char *buf; +int n; + +buf = "abc"; +n = strlen(buf); +RMD160Init(&rmd); +RMD160Update(&rmd, (u_int8_t *)buf, n); +RMD160Final(results, &rmd); + +/* Print the digest as one long hex value */ +printf("0x"); +for (n = 0; n < RMD160_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 +RMD160_CTX rmd; +u_int8_t output[RMD160_DIGEST_STRING_LENGTH]; +char *buf = "abc"; + +printf("0x%s\en", RMD160Data(buf, strlen(buf), output)); +.Ed +.Sh SEE ALSO +.Xr cksum 1 , +.Xr MD5Init 3 , +.Xr SHA1Init 3 , +.Xr SHA256Init 3 +.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 +.An -nosplit +This implementation of RMD-160 was written by +.An Markus Friedl . +.Pp +The +.Fn RMD160End , +.Fn RMD160File , +.Fn RMD160FileChunk , +and +.Fn RMD160Data +helper functions are derived from code written by +.An Poul-Henning Kamp . diff --git a/static/openbsd/man3/RSA_PSS_PARAMS_new.3 b/static/openbsd/man3/RSA_PSS_PARAMS_new.3 new file mode 100644 index 00000000..6532028a --- /dev/null +++ b/static/openbsd/man3/RSA_PSS_PARAMS_new.3 @@ -0,0 +1,61 @@ +.\" $OpenBSD: RSA_PSS_PARAMS_new.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt RSA_PSS_PARAMS_NEW 3 +.Os +.Sh NAME +.Nm RSA_PSS_PARAMS_new , +.Nm RSA_PSS_PARAMS_free +.Nd probabilistic signature scheme with RSA hashing +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft RSA_PSS_PARAMS * +.Fn RSA_PSS_PARAMS_new void +.Ft void +.Fn RSA_PSS_PARAMS_free "RSA_PSS_PARAMS *params" +.Sh DESCRIPTION +.Fn RSA_PSS_PARAMS_new +allocates and initializes an empty +.Vt RSA_PSS_PARAMS +object, representing an ASN.1 +.Vt RSASSA-PSS-params +structure defined in RFC 8017 appendix A.2.3. +It references the hash function and the mask generation function +and stores the length of the salt and the trailer field number. +.Fn RSA_PSS_PARAMS_free +frees +.Fa params . +.Sh RETURN VALUES +.Fn RSA_PSS_PARAMS_new +returns the new +.Vt RSA_PSS_PARAMS +object or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr RSA_new 3 , +.Xr RSA_padding_add_PKCS1_type_1 3 , +.Xr X509_sign 3 +.Sh STANDARDS +RFC 8017: PKCS#1: RSA Cryptography Specifications Version 2.2 +.Sh HISTORY +.Fn RSA_PSS_PARAMS_new +and +.Fn RSA_PSS_PARAMS_free +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/RSA_blinding_on.3 b/static/openbsd/man3/RSA_blinding_on.3 new file mode 100644 index 00000000..0dfebf37 --- /dev/null +++ b/static/openbsd/man3/RSA_blinding_on.3 @@ -0,0 +1,98 @@ +.\" $OpenBSD: RSA_blinding_on.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_BLINDING_ON 3 +.Os +.Sh NAME +.Nm RSA_blinding_on , +.Nm RSA_blinding_off +.Nd protect the RSA operation from timing attacks +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_blinding_on +.Fa "RSA *rsa" +.Fa "BN_CTX *ctx" +.Fc +.Ft void +.Fo RSA_blinding_off +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +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 +.Fn RSA_blinding_on +turns blinding on for key +.Fa rsa +and generates a random blinding factor. +.Fa ctx +is +.Dv NULL +or a pre-allocated and initialized +.Vt BN_CTX . +.Pp +.Fn RSA_blinding_off +turns blinding off and frees the memory used for the blinding factor. +.Sh RETURN VALUES +.Fn RSA_blinding_on +returns 1 on success, and 0 if an error occurred. +.Sh SEE ALSO +.Xr RSA_new 3 +.Sh HISTORY +.Fn RSA_blinding_on +and +.Fn RSA_blinding_off +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/RSA_check_key.3 b/static/openbsd/man3/RSA_check_key.3 new file mode 100644 index 00000000..b6c9bc20 --- /dev/null +++ b/static/openbsd/man3/RSA_check_key.3 @@ -0,0 +1,131 @@ +.\" $OpenBSD: RSA_check_key.3,v 1.11 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 6859cf74 Sep 25 13:33:28 2002 +0000 +.\" +.\" This file was written by Ulf Moeller and +.\" Geoff Thorpe . +.\" Copyright (c) 2000, 2002 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_CHECK_KEY 3 +.Os +.Sh NAME +.Nm RSA_check_key +.Nd validate private RSA keys +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_check_key +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +This function validates RSA keys. +It checks that +.Fa rsa->p +and +.Fa rsa->q +are in fact prime, and that +.Fa rsa->n +satisfies n = p*q. +.Pp +It also checks that +.Fa rsa->d +and +.Fa rsa->e +satisfy d*e = 1 mod ((p-1)*(q-1)), +and that +.Fa rsa->dmp1 , +.Fa rsa->dmq1 , +and +.Fa resa->iqmp +are set correctly or are +.Dv NULL . +.Pp +This function does not work on RSA public keys that have only the +modulus and public exponent elements populated. +It performs integrity checks on all the RSA key material, so the +.Vt RSA +key structure must contain all the private key data too. +Therefore, it cannot be used with any arbitrary +.Vt RSA +key object, even if it is otherwise fit for regular RSA operation. +.Sh RETURN VALUES +.Fn RSA_check_key +returns 1 if +.Fa rsa +is a valid RSA key, and 0 otherwise. +-1 is returned 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 +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_is_prime_ex 3 , +.Xr RSA_get0_key 3 , +.Xr RSA_new 3 +.Sh HISTORY +.Fn RSA_check_key +first appeared in OpenSSL 0.9.4 and has been available since +.Ox 2.6 . +.Sh BUGS +A method of verifying the RSA key using opaque RSA API functions might +need to be considered. +Right now +.Fn RSA_check_key +simply uses the +.Vt RSA +structure elements directly, bypassing the +.Vt RSA_METHOD +table altogether (and completely violating encapsulation and +object-orientation in the process). +The best fix will probably be to introduce a +.Fn check_key +handler +to the +.Vt RSA_METHOD +function table so that alternative implementations can also provide +their own verifiers. diff --git a/static/openbsd/man3/RSA_generate_key.3 b/static/openbsd/man3/RSA_generate_key.3 new file mode 100644 index 00000000..a72168de --- /dev/null +++ b/static/openbsd/man3/RSA_generate_key.3 @@ -0,0 +1,165 @@ +.\" $OpenBSD: RSA_generate_key.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL RSA_generate_key.pod bb6c5e7f Feb 5 10:29:22 2017 -0500 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2002, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_GENERATE_KEY 3 +.Os +.Sh NAME +.Nm RSA_generate_key_ex , +.Nm RSA_generate_key +.Nd generate RSA key pair +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_generate_key_ex +.Fa "RSA *rsa" +.Fa "int bits" +.Fa "BIGNUM *e" +.Fa "BN_GENCB *cb" +.Fc +.Pp +Deprecated: +.Pp +.Ft RSA * +.Fo RSA_generate_key +.Fa "int num" +.Fa "unsigned long e" +.Fa "void (*callback)(int, int, void *)" +.Fa "void *cb_arg" +.Fc +.Sh DESCRIPTION +.Fn RSA_generate_key_ex +generates a key pair and stores it in +.Fa rsa . +.Pp +The modulus size will be of length +.Fa bits , +and the public exponent will be +.Fa e . +Key sizes with +.Fa num +< 1024 should be considered insecure. +The exponent is an odd number, typically 3, 17 or 65537. +.Pp +A callback function may be used to provide feedback about the progress +of the key generation. +If +.Fa cb +is not +.Dv NULL , +it will be called as follows using the +.Xr BN_GENCB_call 3 +function: +.Bl -bullet +.It +While a random prime number is generated, it is called as described in +.Xr BN_generate_prime 3 . +.It +When the +.Fa n Ns -th +randomly generated prime is rejected as not suitable for +the key, +.Fn BN_GENCB_call cb 2 n +is called. +.It +When a random p has been found with p-1 relatively prime to +.Fa e , +it is called as +.Fn BN_GENCB_call cb 3 0 . +.El +.Pp +The process is then repeated for prime q with +.Fn BN_GENCB_call cb 3 1 . +.Pp +.Fn RSA_generate_key +is deprecated. +New applications should use +.Fn RSA_generate_key_ex +instead. +.Fn RSA_generate_key +works in the same way as +.Fn RSA_generate_key_ex +except it uses "old style" call backs. +See +.Xr BN_generate_prime 3 +for further details. +.Sh RETURN VALUES +.Fn RSA_generate_key_ex +returns 1 on success or 0 on error. +.Fn RSA_generate_key +returns the key on success or +.Dv NULL +on error. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_generate_prime 3 , +.Xr RSA_get0_key 3 , +.Xr RSA_meth_set_keygen 3 , +.Xr RSA_new 3 +.Sh HISTORY +.Fn RSA_generate_key +appeared in SSLeay 0.4 or earlier and had its +.Fa cb_arg +argument added in SSLeay 0.9.0. +It has been available since +.Ox 2.4 . +.Pp +.Fn RSA_generate_key_ex +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Sh BUGS +.Fn BN_GENCB_call cb 2 x +is used with two different meanings. +.Pp +.Fn RSA_generate_key +goes into an infinite loop for illegal input values. diff --git a/static/openbsd/man3/RSA_get0_key.3 b/static/openbsd/man3/RSA_get0_key.3 new file mode 100644 index 00000000..cf82b21c --- /dev/null +++ b/static/openbsd/man3/RSA_get0_key.3 @@ -0,0 +1,461 @@ +.\" $OpenBSD: RSA_get0_key.3,v 1.10 2025/06/13 18:34:00 schwarze Exp $ +.\" selective merge up to: OpenSSL 665d899f Aug 2 02:19:43 2017 +0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 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. +.\" +.\" The original file was written by Richard Levitte +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt RSA_GET0_KEY 3 +.Os +.Sh NAME +.Nm RSA_get0_key , +.Nm RSA_get0_n , +.Nm RSA_get0_e , +.Nm RSA_get0_d , +.Nm RSA_set0_key , +.Nm RSA_get0_factors , +.Nm RSA_get0_p , +.Nm RSA_get0_q , +.Nm RSA_set0_factors , +.Nm RSA_get0_crt_params , +.Nm RSA_get0_dmp1 , +.Nm RSA_get0_dmq1 , +.Nm RSA_get0_iqmp , +.Nm RSA_set0_crt_params , +.Nm RSA_clear_flags , +.Nm RSA_test_flags , +.Nm RSA_set_flags +.Nd get and set data in an RSA object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft void +.Fo RSA_get0_key +.Fa "const RSA *r" +.Fa "const BIGNUM **n" +.Fa "const BIGNUM **e" +.Fa "const BIGNUM **d" +.Fc +.Ft const BIGNUM * +.Fo RSA_get0_n +.Fa "const RSA *r" +.Fc +.Ft const BIGNUM * +.Fo RSA_get0_e +.Fa "const RSA *r" +.Fc +.Ft const BIGNUM * +.Fo RSA_get0_d +.Fa "const RSA *r" +.Fc +.Ft int +.Fo RSA_set0_key +.Fa "RSA *r" +.Fa "BIGNUM *n" +.Fa "BIGNUM *e" +.Fa "BIGNUM *d" +.Fc +.Ft void +.Fo RSA_get0_factors +.Fa "const RSA *r" +.Fa "const BIGNUM **p" +.Fa "const BIGNUM **q" +.Fc +.Ft const BIGNUM * +.Fo RSA_get0_p +.Fa "const RSA *r" +.Fc +.Ft const BIGNUM * +.Fo RSA_get0_q +.Fa "const RSA *r" +.Fc +.Ft int +.Fo RSA_set0_factors +.Fa "RSA *r" +.Fa "BIGNUM *p" +.Fa "BIGNUM *q" +.Fc +.Ft void +.Fo RSA_get0_crt_params +.Fa "const RSA *r" +.Fa "const BIGNUM **dmp1" +.Fa "const BIGNUM **dmq1" +.Fa "const BIGNUM **iqmp" +.Fc +.Ft const BIGNUM * +.Fo RSA_get0_dmp1 +.Fa "const RSA *r" +.Fc +.Ft const BIGNUM * +.Fo RSA_get0_dmq1 +.Fa "const RSA *r" +.Fc +.Ft const BIGNUM * +.Fo RSA_get0_iqmp +.Fa "const RSA *r" +.Fc +.Ft int +.Fo RSA_set0_crt_params +.Fa "RSA *r" +.Fa "BIGNUM *dmp1" +.Fa "BIGNUM *dmq1" +.Fa "BIGNUM *iqmp" +.Fc +.Ft void +.Fo RSA_clear_flags +.Fa "RSA *r" +.Fa "int flags" +.Fc +.Ft int +.Fo RSA_test_flags +.Fa "const RSA *r" +.Fa "int flags" +.Fc +.Ft void +.Fo RSA_set_flags +.Fa "RSA *r" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +An +.Vt RSA +object contains the components for the public and private key. +.Fa n +is the modulus common to both public and private key, +.Fa e +is the public exponent and +.Fa d +is the private exponent. +.Fa p , +.Fa q , +.Fa dmp1 , +.Fa dmq1 , +and +.Fa iqmp +are the factors for the second representation of a private key +(see PKCS#1 section 3 Key Types), where +.Fa p +and +.Fa q +are the first and second factor of +.Fa n . +.Fa dmp1 , +.Fa dmq1 , +and +.Fa iqmp +are the exponents and coefficient +for Chinese Remainder Theorem (CRT) calculations. +.Pp +The +.Fa n , +.Fa e , +and +.Fa d +parameters can be obtained by calling +.Fn RSA_get0_key . +If they have not been set yet, then +.Pf * Fa n , +.Pf * Fa e , +and +.Pf * Fa d +are set to +.Dv NULL . +Otherwise, they are set to pointers to the internal representations +of the values that should not be freed by the caller. +.Pp +The +.Fa n , +.Fa e , +and +.Fa d +parameter values can be set by calling +.Fn RSA_set0_key . +The values +.Fa n +and +.Fa e +must be +.Pf non- Dv NULL +the first time this function is called on a given +.Vt RSA +object. +The value +.Fa d +may be +.Dv NULL . +On subsequent calls, any of these values may be +.Dv NULL , +which means that the corresponding field is left untouched. +Calling this function transfers the memory management of the values to +the RSA object. +Therefore, the values that have been passed in +should not be freed by the caller. +.Pp +In a similar fashion, the +.Fa p +and +.Fa q +parameters can be obtained and set with +.Fn RSA_get0_factors +and +.Fn RSA_set0_factors , +and the +.Fa dmp1 , +.Fa dmq1 , +and +.Fa iqmp +parameters can be obtained and set with +.Fn RSA_get0_crt_params +and +.Fn RSA_set0_crt_params . +.Pp +For +.Fn RSA_get0_key , +.Fn RSA_get0_factors , +and +.Fn RSA_get0_crt_params , +.Dv NULL +value +.Vt BIGNUM ** +output arguments are permitted. +The functions +ignore +.Dv NULL +arguments but return values for other, +.Pf non- Dv NULL , +arguments. +.Pp +Values retrieved with +.Fn RSA_get0_key , +.Fn RSA_get0_factors , +and +.Fn RSA_get0_crt_params +are owned by the +.Vt RSA +object used in the call and may therefore +.Em not +be passed to +.Fn RSA_set0_key , +.Fn RSA_set0_factors , +or +.Fn RSA_set0_crt_params . +If needed, duplicate the received value using +.Xr BN_dup 3 +and pass the duplicate. +.Pp +Any of the values +.Fa n , +.Fa e , +.Fa d , +.Fa p , +.Fa q , +.Fa dmp1 , +.Fa dmq1 , +and +.Fa iqmp +can also be retrieved separately by the corresponding functions +.Fn RSA_get0_n , +.Fn RSA_get0_e , +.Fn RSA_get0_d , +.Fn RSA_get0_p , +.Fn RSA_get0_q , +.Fn RSA_get0_dmp1 , +.Fn RSA_get0_dmq1 , +and +.Fn RSA_get0_iqmp , +respectively. +The pointers are owned by the +.Vt RSA +object. +.Pp +.Fn RSA_clear_flags +clears the specified +.Fa flags +in +.Fa r . +.Fn RSA_test_flags +tests the +.Fa flags +in +.Fa r . +.Fn RSA_set_flags +sets the +.Fa flags +in +.Fa r ; +any flags already set remain set. +For all three functions, multiple flags can be passed in one call, +OR'ed together bitwise. +.Pp +The following flags are supported: +.Bl -tag -width Ds +.It Dv RSA_FLAG_CACHE_PRIVATE No and Dv RSA_FLAG_CACHE_PUBLIC +Precompute information needed for Montgomery multiplication +from the private and public key, respectively, and cache it in +.Fa r +for repeated use. +These two flags are set by default for the default RSA implementation, +.Xr RSA_PKCS1_SSLeay 3 . +.It Dv RSA_FLAG_EXT_PKEY +The function set with +.Xr RSA_meth_set_mod_exp 3 +is used for private key operations even if +.Fa p , +.Fa q , +.Fa dmp1 , +.Fa dmq1 , +and +.Fa iqmp +are all +.Dv NULL . +This flag may be useful with RSA implementations that do not use the +private key components stored in the standard fields, for example +because they store the private key in external hardware. +If this flag is unset, the function set with +.Xr RSA_meth_set_bn_mod_exp 3 +is used with +.Fa n +and +.Fa d +instead. +.It Dv RSA_FLAG_NO_BLINDING +Turn off blinding during private key encryption and decryption. +This flag is set by +.Xr RSA_blinding_off 3 . +.It Dv RSA_FLAG_SIGN_VER +This flag has no effect. +It is provided only for backward compatibility with legacy applications. +.El +.Pp +The flags +.Dv RSA_FLAG_BLINDING , +.Dv RSA_FLAG_CHECKED , +.Dv RSA_FLAG_FIPS_METHOD , +.Dv RSA_FLAG_NON_FIPS_ALLOW , +and +.Dv RSA_FLAG_THREAD_SAFE +are defined for compatibility with existing code but have no effect. +.Sh RETURN VALUES +.Fn RSA_get0_n , +.Fn RSA_get0_e , +.Fn RSA_get0_d , +.Fn RSA_get0_p , +.Fn RSA_get0_q , +.Fn RSA_get0_dmp1 , +.Fn RSA_get0_dmq1 , +and +.Fn RSA_get0_iqmp +return a pointer owned by the +.Vt RSA +object if the corresponding value has been set, +otherwise they return +.Dv NULL . +.Pp +.Fn RSA_set0_key , +.Fn RSA_set0_factors , +and +.Fn RSA_set0_crt_params +return 1 on success or 0 on failure. +.Pp +.Fn RSA_test_flags +returns those of the given +.Fa flags +currently set in +.Fa r +or 0 if none of the given +.Fa flags +are set. +.Sh SEE ALSO +.Xr RSA_check_key 3 , +.Xr RSA_generate_key 3 , +.Xr RSA_new 3 , +.Xr RSA_print 3 , +.Xr RSA_size 3 +.Sh HISTORY +.Fn RSA_get0_key , +.Fn RSA_set0_key , +.Fn RSA_get0_factors , +.Fn RSA_set0_factors , +.Fn RSA_get0_crt_params , +.Fn RSA_set0_crt_params , +.Fn RSA_clear_flags , +.Fn RSA_test_flags , +and +.Fn RSA_set_flags +first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 6.3 . +.Pp +.Fn RSA_get0_n , +.Fn RSA_get0_e , +.Fn RSA_get0_d , +.Fn RSA_get0_p , +.Fn RSA_get0_q , +.Fn RSA_get0_dmp1 , +.Fn RSA_get0_dmq1 , +and +.Fn RSA_get0_iqmp +first appeared in OpenSSL 1.1.1 +and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/RSA_get_ex_new_index.3 b/static/openbsd/man3/RSA_get_ex_new_index.3 new file mode 100644 index 00000000..1b7096fa --- /dev/null +++ b/static/openbsd/man3/RSA_get_ex_new_index.3 @@ -0,0 +1,383 @@ +.\" $OpenBSD: RSA_get_ex_new_index.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2023 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 $Mdocdate: June 8 2025 $ +.Dt RSA_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm RSA_get_ex_new_index , +.Nm RSA_set_ex_data , +.Nm RSA_get_ex_data +.Nd add application specific data to RSA objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo RSA_set_ex_data +.Fa "RSA *rsa" +.Fa "int idx" +.Fa "void *data" +.Fc +.Ft void * +.Fo RSA_get_ex_data +.Fa "RSA *rsa" +.Fa "int idx" +.Fc +.Sh DESCRIPTION +The following parent objects can have application specific data called +.Dq ex_data +attached to them: +.Vt BIO , DH , DSA , EC_KEY , RSA , +.Vt SSL , SSL_CTX , SSL_SESSION , UI , X509 , X509_STORE , +and +.Vt X509_STORE_CTX . +.\" CRYPTO_EX_INDEX_APP and CRYPTO_EX_INDEX_UI_METHOD are unused. +The present manual page documents the related API functions taking the +.Vt RSA +object type as an example. +The functions for the other object types work in exactly the same way: +just replace the string +.Qq RSA +with the name of the respective object type +throughout the rest of this manual page. +.Pp +By default, each individual +.Vt RSA +object can store one +.Vt void * +pointing to application specific data. +That specific pointer is identified by an +.Fa idx +argument of 0. +.Pp +.Fn RSA_get_ex_new_index +reserves the next consecutive +.Fa idx +argument, enabling storage of one additional +.Vt void * +per +.Vt RSA +object. +It is typically called at program startup. +It can be called more than once if some +.Vt RSA +objects need to store more than two application specific pointers. +Reserving an additional index for one parent object type, for example for +.Vt RSA , +does not change the numbers of indices that can be used +with any other parent object type. +.Pp +It is strongly recommended to always pass three +.Dv NULL +pointers for the arguments +.Fa new_func , +.Fa dup_func , +and +.Fa free_func . +When following this recommendation, the arguments +.Fa argl +and +.Fa argp +are ignored; conventionally, passing 0 and +.Dv NULL +is recommended. +Because using them is discouraged, the three function callback types +are only documented in the low-level +.Xr CRYPTO_EX_new 3 +manual page. +.Pp +.Fn RSA_set_ex_data +stores the +.Fa data +pointer as application specific data at the given +.Fa idx +in the given +.Fa rsa +object. +The meaning of the data pointed to is up to the application. +The caller retains ownership of the +.Fa data +and is responsible for freeing it when neither the caller nor the +.Fa rsa +object need it any longer. +Any other pointer that was previously stored at the same +.Fa idx +in the same +.Fa rsa +object is silently overwritten. +Passing a +.Dv NULL +pointer for the +.Fa data +argument is valid and indicates that no application specific data +currently needs to be stored at the given +.Fa idx . +.Pp +.Fn RSA_get_ex_data +retrieves the last pointer that was stored using +.Fn RSA_set_ex_data +at the given +.Fa idx +in the given +.Fa rsa +object. +.Sh RETURN VALUES +.Fn RSA_get_ex_new_index +returns a new index equal to or greater than 1 +or \-1 if memory allocation fails. +.Pp +.Fn RSA_set_ex_data +returns 1 on success or 0 if memory allocation fails. +.Pp +.Fn RSA_get_ex_data +returns the application specific data or +.Dv NULL +if +.Fa rsa +does not contain application specific data at the given +.Fa idx . +.Sh ERRORS +After failure of +.Fn RSA_get_ex_new_index +or +.Fn RSA_set_ex_data , +the following diagnostic can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" +Memory allocation failed. +.El +.Pp +In a few unusual failure cases, +.Xr ERR_get_error 3 +may report different errors caused by +.Xr OPENSSL_init_crypto 3 +or even none at all. +.Pp +.Fn RSA_get_ex_data +does not distinguish success from failure. +Consequently, after +.Fn RSA_get_ex_data +returns +.Dv NULL , +.Xr ERR_get_error 3 +returns 0 unless there is still an earlier error in the queue. +.Sh SEE ALSO +.Xr BIO_set_ex_data 3 , +.Xr CRYPTO_set_ex_data 3 , +.Xr DH_set_ex_data 3 , +.Xr DSA_set_ex_data 3 , +.Xr RSA_new 3 , +.Xr SSL_CTX_set_ex_data 3 , +.Xr SSL_SESSION_set_ex_data 3 , +.Xr SSL_set_ex_data 3 , +.Xr X509_STORE_CTX_set_ex_data 3 , +.Xr X509_STORE_set_ex_data 3 +.Sh HISTORY +These functions first appeared in SSLeay 0.9.0 +and have been available since +.Ox 2.4 . +.Sh CAVEATS +A relatively small minority of application programs +attempt to change the API contract such that +.Fn RSA_set_ex_data +transfers ownership of the +.Fa data +to the +.Fa rsa +object. +They do this by providing a +.Fa free_func +that calls +.Xr free 3 +or higher-level +.Fn *_free +functions on the +.Fa data +and sometimes also attempt additional cleanup work as a side effect. +.Pp +This practice is discouraged for several reasons: +.Bl -enum +.It +Due to a massive design mistake in the low-level API function +.Xr CRYPTO_free_ex_data 3 , +this practice creates a possibility that +.Xr RSA_free 3 +may fail due to memory allocation failure, consequently leaking the +memory containing the application specific data and silently skipping +any additional cleanup work the +.Fa free_func +was supposed to do, leaving the application in an undetectably +inconsistent state. +Arguably, leaking additional memory while trying to free some +is most unfortunate especially when the program +is already starved for memory. +.It +This practice introduces a risk of use-after-free and double-free +bugs in case the +.Fa rsa +object gets destructed while a caller of +.Fn RSA_set_ex_data +or +.Fn RSA_get_ex_data +still holds a +.Fa data +pointer. +No such risk exists when no +.Fa free_func +is installed. +.It +Attempting additional cleanup work in +.Fa free_func +is an even worse idea because +.Fa free_func +is unable to report any issues it might detect while doing that work. +Instead, if any additional cleanup work is needed, it is recommended +that the calling code takes care of that before calling +.Xr RSA_free 3 . +.El +.Pp +Even fewer application programs install a +.Fa new_func +that allocates memory and stores a pointer to it in the +.Fa rsa +object by calling +.Xr CRYPTO_set_ex_data 3 . +That is useless because +.Fa new_func +does not have access to any useful information it could store in such memory +and because the default return value of +.Dv NULL +from +.Fn RSA_get_ex_data +is sufficient to indicate +that no application specific data has been stored yet. +In addition, allocating memory in +.Fa new_func +is also inadvisable because it introduces an additional responsibility +for callers of +.Fn RSA_set_ex_data +to always call +.Fn RSA_get_ex_data +first, even when it is the first time the application wants to set +application specific data in a particular +.Fa rsa +object, and to either modify whatever +.Fn RSA_get_ex_data +returns or to free it before calling +.Fn RSA_set_ex_data . +If that is forgotten, a memory leak results. +.Pp +Consequently, allocating any required memory +is better left to the application code that calls +.Fn RSA_set_ex_data . +.Pp +Installing a +.Fa dup_func +is often seen in combination with installing a +.Fa free_func , +for obvious reasons. +It is rarely useful because for most parent object types +that support ex_data, including for +.Vt RSA , +the library does not provide a copying API function in the first place, and +even where copying functions exist, they tend to be fragile and error-prone. +When a new object is needed, it is usually advisable to construct it from +scratch whenever possible, rather than attempting a copy operation. +.Pp +On top of that, if +.Fa dup_func +fails, for example because of a memory allocation failure, the +failure is neither reported nor detectable in any way, leaving the +new parent object with incomplete data and potentially in an +inconsistent state. +.Sh BUGS +If +.Fn RSA_set_ex_data +fails, recovery is very difficult. +In particular, calling +.Xr RSA_free 3 +on the parent +.Fa rsa +object right afterwards is likely to also hit a memory allocation +failure, leaking all memory internally allocated by all earlier calls of +.Fn RSA_set_ex_data +on +.Fa rsa +rather than freeing that memory. +In order to recover, the application program +would have to free a sufficient amount of +.Em other +memory before calling +.Xr RSA_free 3 , +which will rarely be feasible. +Consequently, after a failure of +.Fn RSA_set_ex_data , +terminating the program is likely the only reasonable option. +.Pp +If +.Fn RSA_set_ex_data +is called with an +.Fa idx +argument greater than the last one previously returned from +.Fn RSA_get_ex_new_index , +it may still succeed, and though that is not guaranteed by the API, +retrieving the +.Fa data +from such a bogus +.Fa idx +may even be possible with +.Fn RSA_get_ex_data , +hiding the bug in the application program that caused passing the bogus +.Fa idx +to +.Fn RSA_set_ex_data +in the first place. +.Pp +If the bogus +.Fa idx +argument is large, +.Fn RSA_set_ex_data +may uselessly allocate a large amount of memory. +Calling +.Xr RSA_free 3 +on the parent +.Fa rsa +object is the only way to recover that memory. +.Pp +If the bogus +.Fa idx +argument is very large, +.Fn RSA_set_ex_data +is likely to cause a significant delay before eventually failing +due to memory exhaustion. +It is likely to return without releasing the memory already +allocated, causing any subsequent attempt to allocate memory +for other purposes to fail, too. +In this situation, what was said above about failure of +.Fn RSA_set_ex_data +applies, so terminating the program is likely the only reasonable option. diff --git a/static/openbsd/man3/RSA_meth_new.3 b/static/openbsd/man3/RSA_meth_new.3 new file mode 100644 index 00000000..9626f113 --- /dev/null +++ b/static/openbsd/man3/RSA_meth_new.3 @@ -0,0 +1,607 @@ +.\" $OpenBSD: RSA_meth_new.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL a970b14f Jul 31 18:58:40 2017 -0400 +.\" selective merge up to: OpenSSL 24907560 Sep 17 07:47:42 2018 +1000 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2019 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. +.\" +.\" The original file was written by Richard Levitte . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_METH_NEW 3 +.Os +.Sh NAME +.Nm RSA_meth_new , +.Nm RSA_meth_dup , +.Nm RSA_meth_free , +.Nm RSA_meth_get0_name , +.Nm RSA_meth_set1_name , +.Nm RSA_meth_get_flags , +.Nm RSA_meth_set_flags , +.Nm RSA_meth_get0_app_data , +.Nm RSA_meth_set0_app_data , +.Nm RSA_meth_get_init , +.Nm RSA_meth_set_init , +.Nm RSA_meth_get_finish , +.Nm RSA_meth_set_finish , +.Nm RSA_meth_get_pub_enc , +.Nm RSA_meth_set_pub_enc , +.Nm RSA_meth_get_pub_dec , +.Nm RSA_meth_set_pub_dec , +.Nm RSA_meth_get_priv_enc , +.Nm RSA_meth_set_priv_enc , +.Nm RSA_meth_get_priv_dec , +.Nm RSA_meth_set_priv_dec , +.Nm RSA_meth_get_sign , +.Nm RSA_meth_set_sign , +.Nm RSA_meth_get_verify , +.Nm RSA_meth_set_verify , +.Nm RSA_meth_get_mod_exp , +.Nm RSA_meth_set_mod_exp , +.Nm RSA_meth_get_bn_mod_exp , +.Nm RSA_meth_set_bn_mod_exp , +.Nm RSA_meth_get_keygen , +.Nm RSA_meth_set_keygen +.Nd build up RSA methods +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft RSA_METHOD * +.Fo RSA_meth_new +.Fa "const char *name" +.Fa "int flags" +.Fc +.Ft RSA_METHOD * +.Fo RSA_meth_dup +.Fa "const RSA_METHOD *meth" +.Fc +.Ft void +.Fo RSA_meth_free +.Fa "RSA_METHOD *meth" +.Fc +.Ft const char * +.Fo RSA_meth_get0_name +.Fa "const RSA_METHOD *meth" +.Fc +.Ft int +.Fo RSA_meth_set1_name +.Fa "RSA_METHOD *meth" +.Fa "const char *name" +.Fc +.Ft int +.Fo RSA_meth_get_flags +.Fa "const RSA_METHOD *meth" +.Fc +.Ft int +.Fo RSA_meth_set_flags +.Fa "RSA_METHOD *meth" +.Fa "int flags" +.Fc +.Ft void * +.Fo RSA_meth_get0_app_data +.Fa "const RSA_METHOD *meth" +.Fc +.Ft int +.Fo RSA_meth_set0_app_data +.Fa "RSA_METHOD *meth" +.Fa "void *app_data" +.Fc +.Ft int +.Fo "(*RSA_meth_get_init(const RSA_METHOD *meth))" +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo "RSA_meth_set_init" +.Fa "RSA_METHOD *meth" +.Fa "int (*init)(RSA *rsa)" +.Fc +.Ft int +.Fo "(*RSA_meth_get_finish(const RSA_METHOD *meth))" +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_meth_set_finish +.Fa "RSA_METHOD *meth" +.Fa "int (*finish)(RSA *rsa)" +.Fc +.Ft int +.Fo "(*RSA_meth_get_pub_enc(const RSA_METHOD *meth))" +.Fa "int flen" +.Fa "const unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_meth_set_pub_enc +.Fa "RSA_METHOD *meth" +.Fa "int (*pub_enc)(int flen, const unsigned char *from,\ + unsigned char *to, RSA *rsa, int padding)" +.Fc +.Ft int +.Fo "(*RSA_meth_get_pub_dec(const RSA_METHOD *meth))" +.Fa "int flen" +.Fa "const unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_meth_set_pub_dec +.Fa "RSA_METHOD *meth" +.Fa "int (*pub_dec)(int flen, const unsigned char *from,\ + unsigned char *to, RSA *rsa, int padding)" +.Fc +.Ft int +.Fo "(*RSA_meth_get_priv_enc(const RSA_METHOD *meth))" +.Fa "int flen" +.Fa "const unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_meth_set_priv_enc +.Fa "RSA_METHOD *meth" +.Fa "int (*priv_enc)(int flen, const unsigned char *from,\ + unsigned char *to, RSA *rsa, int padding)" +.Fc +.Ft int +.Fo "(*RSA_meth_get_priv_dec(const RSA_METHOD *meth))" +.Fa "int flen" +.Fa "const unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_meth_set_priv_dec +.Fa "RSA_METHOD *meth" +.Fa "int (*priv_dec)(int flen, const unsigned char *from,\ + unsigned char *to, RSA *rsa, int padding)" +.Fc +.Ft int +.Fo "(*RSA_meth_get_sign(const RSA_METHOD *meth))" +.Fa "int type" +.Fa "const unsigned char *m" +.Fa "unsigned int m_length" +.Fa "unsigned char *sigret" +.Fa "unsigned int *siglen" +.Fa "const RSA *rsa" +.Fc +.Ft int +.Fo RSA_meth_set_sign +.Fa "RSA_METHOD *rsa" +.Fa "int (*sign)(int type, const unsigned char *m, unsigned int m_length,\ + unsigned char *sigret, unsigned int *siglen, const RSA *rsa)" +.Fc +.Ft int +.Fo "(*RSA_meth_get_verify(const RSA_METHOD *meth))" +.Fa "int dtype" +.Fa "const unsigned char *m" +.Fa "unsigned int m_length" +.Fa "const unsigned char *sigbuf" +.Fa "unsigned int siglen" +.Fa "const RSA *rsa" +.Fc +.Ft int +.Fo RSA_meth_set_verify +.Fa "RSA_METHOD *rsa" +.Fa "int (*verify)(int dtype, const unsigned char *m,\ + unsigned int m_length, const unsigned char *sigbuf,\ + unsigned int siglen, const RSA *rsa)" +.Fc +.Ft int +.Fo "(*RSA_meth_get_mod_exp(const RSA_METHOD *meth))" +.Fa "BIGNUM *r0" +.Fa "const BIGNUM *i" +.Fa "RSA *rsa" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo RSA_meth_set_mod_exp +.Fa "RSA_METHOD *meth" +.Fa "int (*mod_exp)(BIGNUM *r0, const BIGNUM *i, RSA *rsa, BN_CTX *ctx)" +.Fc +.Ft int +.Fo "(*RSA_meth_get_bn_mod_exp(const RSA_METHOD *meth))" +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fa "BN_MONT_CTX *m_ctx" +.Fc +.Ft int +.Fo RSA_meth_set_bn_mod_exp +.Fa "RSA_METHOD *meth" +.Fa "int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,\ + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx)" +.Fc +.Ft int +.Fo "(*RSA_meth_get_keygen(const RSA_METHOD *meth))" +.Fa "RSA *rsa" +.Fa "int bits" +.Fa "BIGNUM *e" +.Fa "BN_GENCB *cb" +.Fc +.Ft int +.Fo RSA_meth_set_keygen +.Fa "RSA_METHOD *meth" +.Fa "int (*keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb)" +.Fc +.Sh DESCRIPTION +The +.Vt RSA_METHOD +structure holds function pointers for custom RSA implementations. +.Pp +.Fn RSA_meth_new +creates a new +.Vt RSA_METHOD +structure. +A copy of the NUL-terminated +.Fa name +is stored in the new +.Vt RSA_METHOD +object. +Any new +.Vt RSA +object constructed from this +.Vt RSA_METHOD +will have the given +.Fa flags +set by default, as if they were set with +.Xr RSA_set_flags 3 . +.Pp +.Fn RSA_meth_dup +creates a deep copy of +.Fa meth , +except that a pointer stored into it with +.Fn RSA_meth_set0_app_data +is copied as a pointer without creating a copy of its content. +This might be useful for creating a new +.Vt RSA_METHOD +based on an existing one, but with some differences. +.Pp +.Fn RSA_meth_free +destroys +.Fa meth +and frees any memory associated with it, +except that memory pointed to by a pointer set with +.Fn RSA_meth_set0_app_data +is not freed. +If +.Fa meth +is +.Dv NULL , +no action occurs. +.Pp +.Fn RSA_meth_get0_name +returns an internal pointer to the name of +.Fa meth . +.Fn RSA_meth_set1_name +stores a copy of the NUL-terminated +.Fa name +in the +.Vt RSA_METHOD +object after freeing the previously stored name. +Method names are ignored by the default RSA implementation +but can be used by alternative implementations +and by the application program. +.Pp +.Fn RSA_meth_get_flags +retrieves the flags from +.Fa meth . +Flags are documented in +.Xr RSA_test_flags 3 . +.Fn RSA_meth_set_flags +overwrites all flags in +.Fa meth . +Unlike +.Xr RSA_set_flags 3 , +it does not preserve any flags that were set before the call. +.Pp +.Fn RSA_meth_get0_app_data +and +.Fn RSA_meth_set0_app_data +get and set a pointer to implementation-specific data. +The function +.Fn RSA_meth_free +does not +.Xr free 3 +the memory pointed to by +.Fa app_data . +The default RSA implementation does not use +.Fa app_data . +.Pp +.Fn RSA_meth_get_init +and +.Fn RSA_meth_set_init +get and set an optional function used when creating a new +.Vt RSA +object. +Unless +.Fa init +is +.Dv NULL , +it will be called at the end of +.Xr RSA_new 3 , +.Xr RSA_new_method 3 , +and +.Xr RSA_set_method 3 , +passing a pointer to the newly allocated or reset +.Vt RSA +object as an argument. +The default RSA implementation, +.Xr RSA_PKCS1_SSLeay 3 , +contains an +.Fa init +function equivalent to calling +.Xr RSA_set_flags 3 +with an argument of +.Dv RSA_FLAG_CACHE_PUBLIC | RSA_FLAG_CACHE_PRIVATE . +.Pp +.Fn RSA_meth_get_finish +and +.Fn RSA_meth_set_finish +get and set an optional function for destroying an +.Vt RSA +object. +Unless +.Fa finish +is +.Dv NULL , +it will be called from +.Xr RSA_set_method 3 +and from +.Xr RSA_free 3 . +It takes the same argument as +.Xr RSA_free 3 +and is intended to do RSA implementation specific cleanup. +The memory used by the +.Vt RSA +object itself should not be freed by the +.Fa finish +function. +The default RSA implementation contains a +.Fa finish +function freeing the memory used by the +.Dv RSA_FLAG_CACHE_PUBLIC +and +.Dv RSA_FLAG_CACHE_PRIVATE +caches. +.Pp +.Fn RSA_meth_get_pub_enc , +.Fn RSA_meth_set_pub_enc , +.Fn RSA_meth_get_pub_dec , +.Fn RSA_meth_set_pub_dec , +.Fn RSA_meth_get_priv_enc , +.Fn RSA_meth_set_priv_enc , +.Fn RSA_meth_get_priv_dec , +and +.Fn RSA_meth_set_priv_dec +get and set the mandatory functions +used for public and private key encryption and decryption. +These functions will be called from +.Xr RSA_public_encrypt 3 , +.Xr RSA_public_decrypt 3 , +.Xr RSA_private_encrypt 3 , +and +.Xr RSA_private_decrypt 3 , +respectively, and take the same parameters as those. +.Pp +.Fn RSA_meth_get_sign , +.Fn RSA_meth_set_sign , +.Fn RSA_meth_get_verify , +and +.Fn RSA_meth_set_verify +get and set the optional functions +used for creating and verifying an RSA signature. +.Pp +.Fn RSA_meth_get_mod_exp +and +.Fn RSA_meth_set_mod_exp +get and set the function +used for Chinese Remainder Theorem (CRT) computations involving the +.Fa p , +.Fa q , +.Fa dmp1 , +.Fa dmq1 , +and +.Fa iqmp +fields of an +.Vt RSA +object. +It is used by the default RSA implementation during +.Xr RSA_private_encrypt 3 +and +.Xr RSA_private_decrypt 3 +when the required components of the private key are available +or when the +.Dv RSA_FLAG_EXT_PKEY +flag is set. +.Pp +.Fn RSA_meth_get_bn_mod_exp +and +.Fn RSA_meth_set_bn_mod_exp +get and set the function used for CRT computations, +specifically the value r = +.Fa a +\(ha +.Fa p +mod +.Fa m . +It is used by the default RSA implementation during +.Xr RSA_public_encrypt 3 +and +.Xr RSA_public_decrypt 3 +and as a fallback during +.Xr RSA_private_encrypt 3 +and +.Xr RSA_private_decrypt 3 . +.Pp +.Fn RSA_meth_get_keygen +and +.Fn RSA_meth_set_keygen +get and set the optional function used for generating a new RSA key pair. +Unless +.Fa keygen +is +.Dv NULL , +it will be called from +.Xr RSA_generate_key_ex 3 +and takes the same parameters. +Otherwise, a builtin default implementation is used. +.Sh RETURN VALUES +.Fn RSA_meth_new +and +.Fn RSA_meth_dup +return the newly allocated +.Vt RSA_METHOD +object or +.Dv NULL +on failure. +.Pp +.Fn RSA_meth_get0_name +returns an internal pointer which must not be freed by the caller. +.Pp +.Fn RSA_meth_get_flags +returns zero or more +.Dv RSA_FLAG_* +constants OR'ed together, or 0 if no flags are set in +.Fa meth . +.Pp +.Fn RSA_meth_get0_app_data +returns the pointer that was earlier passed to +.Fn RSA_meth_set0_app_data +or +.Dv NULL +otherwise. +.Pp +All other +.Fn RSA_meth_get_* +functions return the appropriate function pointer that has been set +with the corresponding +.Fn RSA_meth_set_* +function, or +.Dv NULL +if no such pointer has been set in +.Fa meth . +.Pp +All +.Fn RSA_meth_set* +functions return 1 on success or 0 on failure. +In the current implementation, only +.Fn RSA_meth_set1_name +can actually fail. +.Sh SEE ALSO +.Xr RSA_generate_key_ex 3 , +.Xr RSA_new 3 , +.Xr RSA_private_encrypt 3 , +.Xr RSA_public_encrypt 3 , +.Xr RSA_set_flags 3 , +.Xr RSA_set_method 3 , +.Xr RSA_sign 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0. +.Fn RSA_meth_new , +.Fn RSA_meth_dup , +.Fn RSA_meth_free , +.Fn RSA_meth_set_finish , +.Fn RSA_meth_set_priv_enc , +and +.Fn RSA_meth_set_priv_dec +have been available since +.Ox 6.3 , +.Fn RSA_meth_set1_name +and +.Fn RSA_meth_get_finish +since +.Ox 6.4 , +and +.Fn RSA_meth_get0_name , +.Fn RSA_meth_get_flags , +.Fn RSA_meth_set_flags , +.Fn RSA_meth_get0_app_data , +.Fn RSA_meth_set0_app_data , +.Fn RSA_meth_get_init , +.Fn RSA_meth_set_init , +.Fn RSA_meth_set_finish , +.Fn RSA_meth_get_pub_enc , +.Fn RSA_meth_set_pub_enc , +.Fn RSA_meth_get_pub_dec , +.Fn RSA_meth_set_pub_dec , +.Fn RSA_meth_get_priv_enc , +.Fn RSA_meth_get_priv_dec , +.Fn RSA_meth_get_sign , +.Fn RSA_meth_set_sign , +.Fn RSA_meth_get_verify , +.Fn RSA_meth_set_verify , +.Fn RSA_meth_get_mod_exp , +.Fn RSA_meth_set_mod_exp , +.Fn RSA_meth_get_bn_mod_exp , +.Fn RSA_meth_set_bn_mod_exp , +.Fn RSA_meth_get_keygen , +and +.Fn RSA_meth_set_keygen +since +.Ox 6.6 . diff --git a/static/openbsd/man3/RSA_new.3 b/static/openbsd/man3/RSA_new.3 new file mode 100644 index 00000000..9c69ce27 --- /dev/null +++ b/static/openbsd/man3/RSA_new.3 @@ -0,0 +1,249 @@ +.\" $OpenBSD: RSA_new.3,v 1.19 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL doc/man3/RSA_new.pod e9b77246 Jan 20 19:58:49 2017 +0100 +.\" OpenSSL doc/crypto/rsa.pod 35d2e327 Jun 3 16:19:49 2016 -0400 (final) +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2019 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. +.\" +.\" The original file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2002, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_NEW 3 +.Os +.Sh NAME +.Nm RSA_new , +.Nm RSAPrivateKey_dup , +.Nm RSAPublicKey_dup , +.Nm RSA_up_ref , +.Nm RSA_free +.Nd allocate and free RSA objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft RSA * +.Fn RSA_new void +.Ft RSA * +.Fo RSAPrivateKey_dup +.Fa "RSA *rsa" +.Fc +.Ft RSA * +.Fo RSAPublicKey_dup +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_up_ref +.Fa "RSA *rsa" +.Fc +.Ft void +.Fo RSA_free +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +The RSA functions implement RSA public key encryption and signatures +as defined in PKCS #1 v2.0 (RFC 2437). +.Pp +.Fn RSA_new +allocates and initializes an +.Vt RSA +structure, setting the reference count to 1. +It is equivalent to calling +.Xr RSA_new_method 3 +with a +.Dv NULL +argument. +.Pp +.Fn RSAPrivateKey_dup +calls +.Fn RSA_new +and copies the public and private key components from +.Fa rsa +into the new structure. +.Fn RSAPublicKey_dup +does the same except that it copies the public key components only. +.Pp +.Fn RSA_up_ref +increments the reference count by 1. +.Pp +.Fn RSA_free +decrements the reference count by 1. +If it reaches 0, it calls the optional +.Fa finish +function set up with +.Xr RSA_meth_set_finish 3 +and frees the +.Vt RSA +structure and its components. +The key is erased before the memory is returned to the system. +If +.Fa rsa +is a +.Dv NULL +pointer, no action occurs. +.Pp +The +.Vt RSA +structure consists of several +.Vt BIGNUM +components. +It can contain public as well as private RSA keys: +.Bd -literal +typedef 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; +.Ed +.Pp +In public keys, the private exponent +.Fa d +and the related secret values +.Fa p , q , dmp1 , dmp2 , +and +.Fa iqmp +are +.Dv NULL . +.Pp +.Fa p , +.Fa q , +.Fa dmp1 , +.Fa dmq1 , +and +.Fa iqmp +may be +.Dv NULL +in private keys, but the RSA operations are much faster when these +values are available. +.Pp +Note that RSA keys may use non-standard +.Vt RSA_METHOD +implementations. +In some cases, these +.Vt BIGNUM +values will not be used by the implementation or may be used for +alternative data storage. +For this reason, applications should generally avoid using +.Vt RSA +structure elements directly and instead use API functions to query +or modify keys. +.Sh RETURN VALUES +.Fn RSA_new , +.Fn RSAPrivateKey_dup , +and +.Fn RSAPublicKey_dup +return a pointer to the newly allocated structure, or +.Dv NULL +if an error occurs. +An error code can be obtained by +.Xr ERR_get_error 3 . +.Pp +.Fn RSA_up_ref +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr BN_new 3 , +.Xr crypto 3 , +.Xr d2i_RSAPublicKey 3 , +.Xr DH_new 3 , +.Xr DSA_new 3 , +.Xr EVP_PKEY_set1_RSA 3 , +.Xr RSA_blinding_on 3 , +.Xr RSA_check_key 3 , +.Xr RSA_generate_key 3 , +.Xr RSA_get0_key 3 , +.Xr RSA_get_ex_new_index 3 , +.Xr RSA_meth_new 3 , +.Xr RSA_padding_add_PKCS1_type_1 3 , +.Xr RSA_pkey_ctx_ctrl 3 , +.Xr RSA_print 3 , +.Xr RSA_private_encrypt 3 , +.Xr RSA_PSS_PARAMS_new 3 , +.Xr RSA_public_encrypt 3 , +.Xr RSA_security_bits 3 , +.Xr RSA_set_method 3 , +.Xr RSA_sign 3 , +.Xr RSA_sign_ASN1_OCTET_STRING 3 , +.Xr RSA_size 3 +.Sh STANDARDS +SSL, PKCS #1 v2.0 +.Pp +RSA was covered by a US patent which expired in September 2000. +.Sh HISTORY +.Fn RSA_new +and +.Fn RSA_free +appeared in SSLeay 0.4 or earlier. +.Fn RSAPrivateKey_dup +first appeared in SSLeay 0.5.1 and +.Fn RSAPublicKey_dup +in SSLeay 0.5.2. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn RSA_up_ref +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/RSA_padding_add_PKCS1_type_1.3 b/static/openbsd/man3/RSA_padding_add_PKCS1_type_1.3 new file mode 100644 index 00000000..d8a142f3 --- /dev/null +++ b/static/openbsd/man3/RSA_padding_add_PKCS1_type_1.3 @@ -0,0 +1,237 @@ +.\" $OpenBSD: RSA_padding_add_PKCS1_type_1.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 1e3f62a3 Jul 17 16:47:13 2017 +0200 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_PADDING_ADD_PKCS1_TYPE_1 3 +.Os +.Sh NAME +.Nm RSA_padding_add_PKCS1_type_1 , +.Nm RSA_padding_check_PKCS1_type_1 , +.Nm RSA_padding_add_PKCS1_type_2 , +.Nm RSA_padding_check_PKCS1_type_2 , +.Nm RSA_padding_add_PKCS1_OAEP , +.Nm RSA_padding_check_PKCS1_OAEP , +.Nm RSA_padding_add_none , +.Nm RSA_padding_check_none +.Nd asymmetric encryption padding +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_padding_add_PKCS1_type_1 +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fc +.Ft int +.Fo RSA_padding_check_PKCS1_type_1 +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "int rsa_len" +.Fc +.Ft int +.Fo RSA_padding_add_PKCS1_type_2 +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fc +.Ft int +.Fo RSA_padding_check_PKCS1_type_2 +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "int rsa_len" +.Fc +.Ft int +.Fo RSA_padding_add_PKCS1_OAEP +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "unsigned char *p" +.Fa "int pl" +.Fc +.Ft int +.Fo RSA_padding_check_PKCS1_OAEP +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "int rsa_len" +.Fa "unsigned char *p" +.Fa "int pl" +.Fc +.Ft int +.Fo RSA_padding_add_none +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fc +.Ft int +.Fo RSA_padding_check_none +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "int rsa_len" +.Fc +.Sh DESCRIPTION +These 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. +.Fn RSA_padding_add_PKCS1_OAEP +and +.Fn RSA_padding_check_PKCS1_OAEP +may be used in an application combined with +.Dv RSA_NO_PADDING +in order to implement OAEP with an encoding parameter. +.Pp +.Fn RSA_padding_add_* +encodes +.Fa fl +bytes from +.Fa f +so as to fit into +.Fa tlen +bytes and stores the result at +.Fa to . +An error occurs if +.Fa fl +does not meet the size requirements of the encoding method. +.Pp +The following encoding methods are implemented: +.Pp +.Bl -tag -width PKCS1_type_2 -compact +.It PKCS1_type_1 +PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); +used for signatures +.It PKCS1_type_2 +PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) +.It PKCS1_OAEP +PKCS #1 v2.0 EME-OAEP +.It none +simply copy the data +.El +.Pp +.Fn RSA_padding_check_* +verifies that the +.Fa fl +bytes at +.Fa f +contain a valid encoding for a +.Fa rsa_len +byte RSA key in the respective encoding method and stores the recovered +data of at most +.Fa tlen +bytes (for +.Dv RSA_NO_PADDING : +of size +.Fa tlen ) +at +.Fa to . +.Pp +For +.Fn RSA_padding_*_OAEP , +.Fa p +points to the encoding parameter of length +.Fa pl . +.Fa p +may be +.Dv NULL +if +.Fa pl +is 0. +.Sh RETURN VALUES +The +.Fn RSA_padding_add_* +functions return 1 on success or 0 on error. +The +.Fn RSA_padding_check_* +functions return the length of the recovered data or -1 on error. +Error codes can be obtained by calling +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr RSA_new 3 , +.Xr RSA_private_decrypt 3 , +.Xr RSA_public_encrypt 3 , +.Xr RSA_sign 3 , +.Xr RSA_verify 3 +.Sh HISTORY +.Fn RSA_padding_add_PKCS1_type_1 , +.Fn RSA_padding_check_PKCS1_type_1 , +.Fn RSA_padding_add_PKCS1_type_2 , +.Fn RSA_padding_check_PKCS1_type_2 , +.Fn RSA_padding_add_none , +and +.Fn RSA_padding_check_none +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . +.Pp +.Fn RSA_padding_add_PKCS1_OAEP +and +.Fn RSA_padding_check_PKCS1_OAEP +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . +.Sh BUGS +The +.Fn RSA_padding_check_PKCS1_type_2 +padding check leaks timing 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 PKCS1_OAEP padding. diff --git a/static/openbsd/man3/RSA_pkey_ctx_ctrl.3 b/static/openbsd/man3/RSA_pkey_ctx_ctrl.3 new file mode 100644 index 00000000..ca805e51 --- /dev/null +++ b/static/openbsd/man3/RSA_pkey_ctx_ctrl.3 @@ -0,0 +1,403 @@ +.\" $OpenBSD: RSA_pkey_ctx_ctrl.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL man3/EVP_PKEY_CTX_ctrl.pod 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" OpenSSL man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod +.\" 87103969 Oct 1 14:11:57 2018 -0700 +.\" selective merge up to: +.\" OpenSSL man3/EVP_PKEY_CTX_ctrl.pod df75c2b f Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson +.\" and Antoine Salon . +.\" Copyright (c) 2006, 2009, 2013, 2014, 2015, 2017, 2018 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_PKEY_CTX_CTRL 3 +.Os +.Sh NAME +.Nm RSA_pkey_ctx_ctrl , +.Nm EVP_PKEY_CTX_set_rsa_padding , +.Nm EVP_PKEY_CTX_get_rsa_padding , +.Nm EVP_PKEY_CTX_set_rsa_keygen_bits , +.Nm EVP_PKEY_CTX_set_rsa_keygen_pubexp , +.Nm EVP_PKEY_CTX_set_rsa_mgf1_md , +.Nm EVP_PKEY_CTX_get_rsa_mgf1_md , +.Nm EVP_PKEY_CTX_set_rsa_oaep_md , +.Nm EVP_PKEY_CTX_get_rsa_oaep_md , +.Nm EVP_PKEY_CTX_set0_rsa_oaep_label , +.Nm EVP_PKEY_CTX_get0_rsa_oaep_label , +.Nm EVP_PKEY_CTX_set_rsa_pss_saltlen , +.Nm EVP_PKEY_CTX_get_rsa_pss_saltlen , +.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_md , +.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md , +.Nm EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen +.Nd RSA private key control operations +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_pkey_ctx_ctrl +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int optype" +.Fa "int cmd" +.Fa "int p1" +.Fa "void *p2" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_padding +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int pad" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_rsa_padding +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int *ppad" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_keygen_bits +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int mbits" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_keygen_pubexp +.Fa "EVP_PKEY_CTX *ctx" +.Fa "BIGNUM *pubexp" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_mgf1_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_rsa_mgf1_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD **pmd" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_oaep_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_rsa_oaep_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD **pmd" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set0_rsa_oaep_label +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *label" +.Fa "int len" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get0_rsa_oaep_label +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char **plabel" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_pss_saltlen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int len" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_rsa_pss_saltlen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int *plen" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_md +.Fa "EVP_PKEY_CTX *pctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md +.Fa "EVP_PKEY_CTX *pctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen +.Fa "EVP_PKEY_CTX *pctx" +.Fa "int saltlen" +.Fc +.Sh DESCRIPTION +The function +.Fn RSA_pkey_ctx_ctrl +is a shallow wrapper around +.Xr EVP_PKEY_CTX_ctrl 3 +which only succeeds if +.Fa ctx +matches either +.Dv EVP_PKEY_RSA +or +.Dv EVP_PKEY_RSA_PSS . +.Pp +All the remaining "functions" are implemented as macros. +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_padding +macro sets the RSA padding mode for +.Fa ctx . +The +.Fa pad +parameter can take the value +.Dv RSA_PKCS1_PADDING +for PKCS#1 padding, +.Dv RSA_NO_PADDING +for no padding, +.Dv RSA_PKCS1_OAEP_PADDING +for OAEP padding (encrypt and decrypt only), +.Dv RSA_X931_PADDING +for X9.31 padding (signature operations only) and +.Dv RSA_PKCS1_PSS_PADDING +(sign and verify only). +Only the last one can be used with keys of the type +.Dv EVP_PKEY_RSA_PSS . +.Pp +Two RSA padding modes behave differently if +.Xr EVP_PKEY_CTX_set_signature_md 3 +is used. +If this macro is called for PKCS#1 padding, the plaintext buffer is an +actual digest value and is encapsulated in a +.Vt 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 +The +.Fn EVP_PKEY_CTX_get_rsa_padding +macro retrieves the RSA padding mode for +.Fa ctx . +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_keygen_bits +macro sets the RSA key length for RSA or RSA-PSS key generation to +.Fa mbits . +The smallest supported value is 512 bits. +If not specified, 1024 bits is used. +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp +macro sets the public exponent value for RSA or RSA-PSS key generation to +.Fa pubexp . +Currently, it should be an odd integer. +The +.Fa pubexp +pointer is used internally by this function, so it should not be modified +or freed after the call. +If this macro is not called, then 65537 is used. +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_mgf1_md +macro sets the MGF1 digest for RSA padding schemes to +.Fa md . +Unless explicitly specified, the signing digest is used. +The padding mode must have been set to +.Dv RSA_PKCS1_OAEP_PADDING +or +.Dv RSA_PKCS1_PSS_PADDING . +If the key is of the type +.Dv EVP_PKEY_RSA_PSS +and has usage restrictions, an error occurs if an attempt is made +to set the digest to anything other than the restricted value. +.Pp +The +.Fn EVP_PKEY_CTX_get_rsa_mgf1_md +macro retrieves the MGF1 digest for +.Fa ctx . +Unless explicitly specified, the signing digest is used. +The padding mode must have been set to +.Dv RSA_PKCS1_OAEP_PADDING +or +.Dv RSA_PKCS1_PSS_PADDING . +.Ss Optimal asymmetric encryption padding +The following macros require that the padding mode was set to +.Dv RSA_PKCS1_OAEP_PADDING . +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_oaep_md +macro sets the message digest type used in RSA OAEP to +.Fa md . +.Pp +The +.Fn EVP_PKEY_CTX_get_rsa_oaep_md +macro gets the message digest type used in RSA OAEP to +.Pf * Fa pmd . +.Pp +The +.Fn EVP_PKEY_CTX_set0_rsa_oaep_label +macro sets the RSA OAEP label to +.Fa label +and its length to +.Fa len . +If +.Fa label +is +.Dv NULL +or +.Fa len +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 +.Fa label . +.Pp +The +.Fn EVP_PKEY_CTX_get0_rsa_oaep_label +macro gets the RSA OAEP label to +.Pf * Fa plabel . +The return value is the label length. +The resulting pointer is owned by the library and should not be +freed by the caller. +.Ss Probabilistic signature scheme +The following macros require that the padding mode was set to +.Dv RSA_PKCS1_PSS_PADDING . +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen +macro sets the RSA PSS salt length to +.Fa len . +Three special values are supported: +.Dv RSA_PSS_SALTLEN_DIGEST +sets the salt length to the digest length. +.Dv RSA_PSS_SALTLEN_MAX +sets the salt length to the maximum permissible value. +When signing, +.Dv RSA_PSS_SALTLEN_AUTO +sets the salt length to the maximum permissible value. +When verifying, +.Dv RSA_PSS_SALTLEN_AUTO +causes the salt length to be automatically determined based on the +PSS block structure. +If this macro is not called, a salt length value of +.Dv RSA_PSS_SALTLEN_AUTO +is used by default. +.Pp +If the key has usage restrictions and an attempt is made to set the +salt length below the minimum value, an error occurs. +Also, if the key has usage restrictions, +.Dv RSA_PSS_SALTLEN_AUTO +is not supported for verification. +.Pp +The +.Fn EVP_PKEY_CTX_get_rsa_pss_saltlen +macro retrieves the RSA PSS salt length for +.Fa ctx . +.Pp +Optional parameter restrictions can be specified when generating a PSS +key. +If any restrictions are set using the macros described below, +then all 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 +.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_md +restricts the digest algorithm the generated key can use to +.Fa md . +.Pp +.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md +restricts the MGF1 algorithm the generated key can use to +.Fa md . +.Pp +.Fn EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen +restricts the minimum salt length to +.Fa saltlen . +.Sh RETURN VALUES +These functions return a positive value for success or 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 +.Xr EVP_DigestInit 3 , +.Xr EVP_PKEY_CTX_ctrl 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_get_default_digest_nid 3 , +.Xr EVP_PKEY_keygen 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +The functions +.Fn EVP_PKEY_CTX_set_rsa_padding , +.Fn EVP_PKEY_CTX_set_rsa_keygen_bits , +.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp , +and +.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +The functions +.Fn EVP_PKEY_CTX_get_rsa_padding , +.Fn EVP_PKEY_CTX_set_rsa_mgf1_md , +.Fn EVP_PKEY_CTX_get_rsa_mgf1_md , +and +.Fn EVP_PKEY_CTX_get_rsa_pss_saltlen +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . +.Pp +The functions +.Fn EVP_PKEY_CTX_set_rsa_oaep_md , +.Fn EVP_PKEY_CTX_get_rsa_oaep_md , +.Fn EVP_PKEY_CTX_set0_rsa_oaep_label , +and +.Fn EVP_PKEY_CTX_get0_rsa_oaep_label +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 6.7 . +.Pp +The function +.Fn RSA_pkey_ctx_ctrl +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/RSA_print.3 b/static/openbsd/man3/RSA_print.3 new file mode 100644 index 00000000..3f5d927b --- /dev/null +++ b/static/openbsd/man3/RSA_print.3 @@ -0,0 +1,145 @@ +.\" $OpenBSD: RSA_print.3,v 1.10 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2002, 2003 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_PRINT 3 +.Os +.Sh NAME +.Nm RSA_print , +.Nm RSA_print_fp , +.Nm DSAparams_print , +.Nm DSAparams_print_fp , +.Nm DSA_print , +.Nm DSA_print_fp , +.Nm DHparams_print , +.Nm DHparams_print_fp +.Nd print cryptographic parameters +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_print +.Fa "BIO *bp" +.Fa "RSA *x" +.Fa "int offset" +.Fc +.Ft int +.Fo RSA_print_fp +.Fa "FILE *fp" +.Fa "RSA *x" +.Fa "int offset" +.Fc +.In openssl/dsa.h +.Ft int +.Fo DSAparams_print +.Fa "BIO *bp" +.Fa "DSA *x" +.Fc +.Ft int +.Fo DSAparams_print_fp +.Fa "FILE *fp" +.Fa "DSA *x" +.Fc +.Ft int +.Fo DSA_print +.Fa "BIO *bp" +.Fa "DSA *x" +.Fa "int offset" +.Fc +.Ft int +.Fo DSA_print_fp +.Fa "FILE *fp" +.Fa "DSA *x" +.Fa "int offset" +.Fc +.In openssl/dh.h +.Ft int +.Fo DHparams_print +.Fa "BIO *bp" +.Fa "DH *x" +.Fc +.Ft int +.Fo DHparams_print_fp +.Fa "FILE *fp" +.Fa "DH *x" +.Fc +.Sh DESCRIPTION +A human-readable hexadecimal output of the components of the RSA key, +DSA parameters or key or DH parameters is printed to +.Fa bp +or +.Fa fp . +.Pp +The output lines are indented by +.Fa offset +spaces. +.Sh RETURN VALUES +These functions return 1 on success or 0 on error. +.Sh SEE ALSO +.Xr BN_bn2bin 3 , +.Xr DH_get0_pqg 3 , +.Xr DH_new 3 , +.Xr DSA_get0_pqg 3 , +.Xr RSA_get0_key 3 , +.Xr RSA_new 3 +.Sh HISTORY +.Fn RSA_print +and +.Fn DHparams_print +first appeared in SSLeay 0.5.1. +.Fn RSA_print_fp , +.Fn DSA_print , +and +.Fn DHparams_print_fp +first appeared in SSLeay 0.6.0. +.Fn DSA_print_fp +first appeared in SSLeay 0.8.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/RSA_private_encrypt.3 b/static/openbsd/man3/RSA_private_encrypt.3 new file mode 100644 index 00000000..43e94b1f --- /dev/null +++ b/static/openbsd/man3/RSA_private_encrypt.3 @@ -0,0 +1,151 @@ +.\" $OpenBSD: RSA_private_encrypt.3,v 1.11 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL RSA_private_encrypt.pod b41f6b64 Mar 10 15:49:04 2017 +0000 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_PRIVATE_ENCRYPT 3 +.Os +.Sh NAME +.Nm RSA_private_encrypt , +.Nm RSA_public_decrypt +.Nd low level signature operations +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_private_encrypt +.Fa "int flen" +.Fa "const unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_public_decrypt +.Fa "int flen" +.Fa "const unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Sh DESCRIPTION +These functions handle RSA signatures at a low level. +.Pp +.Fn RSA_private_encrypt +signs the +.Fa flen +bytes at +.Fa from +(usually a message digest with an algorithm identifier) using the +private key +.Fa rsa +and stores the signature in +.Fa to . +.Fa to +must point to +.Fn RSA_size rsa +bytes of memory. +.Pp +.Fa padding +denotes one of the following modes: +.Bl -tag -width Ds +.It Dv RSA_PKCS1_PADDING +PKCS #1 v1.5 padding. +This function does not handle the +.Sy algorithmIdentifier +specified in PKCS #1. +When generating or verifying PKCS #1 signatures, +.Xr RSA_sign 3 +and +.Xr RSA_verify 3 +should be used. +.It Dv RSA_NO_PADDING +Raw RSA signature. +This mode should only be used to implement cryptographically sound +padding modes in the application code. +Signing user data directly with RSA is insecure. +.El +.Pp +.Fn RSA_public_decrypt +recovers the message digest from the +.Fa flen +bytes long signature at +.Fa from +using the signer's public key +.Fa rsa . +.Fa to +must point to a memory section large enough to hold the message digest +(which is smaller than +.Fn RSA_size rsa +- 11). +.Fa padding +is the padding mode that was used to sign the data. +.Sh RETURN VALUES +.Fn RSA_private_encrypt +returns the size of the signature (i.e.\& +.Fn RSA_size rsa ) . +.Fn RSA_public_decrypt +returns the size of the recovered message digest. +.Pp +On error, -1 is returned; the error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr RSA_meth_set_priv_enc 3 , +.Xr RSA_new 3 , +.Xr RSA_sign 3 , +.Xr RSA_verify 3 +.Sh HISTORY +.Fn RSA_private_encrypt +and +.Fn RSA_public_decrypt +appeared in SSLeay 0.4 or earlier and have been available since +.Ox 2.4 . +.Pp +.Dv RSA_NO_PADDING +is available since SSLeay 0.9.0. diff --git a/static/openbsd/man3/RSA_public_encrypt.3 b/static/openbsd/man3/RSA_public_encrypt.3 new file mode 100644 index 00000000..f4011884 --- /dev/null +++ b/static/openbsd/man3/RSA_public_encrypt.3 @@ -0,0 +1,248 @@ +.\" $OpenBSD: RSA_public_encrypt.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL RSA_public_encrypt.pod 1e3f62a3 Jul 17 16:47:13 2017 +0200 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2004 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_PUBLIC_ENCRYPT 3 +.Os +.Sh NAME +.Nm RSA_public_encrypt , +.Nm RSA_private_decrypt , +.Nm EVP_PKEY_encrypt_old , +.Nm EVP_PKEY_decrypt_old +.Nd RSA public key cryptography +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_public_encrypt +.Fa "int flen" +.Fa "const unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_private_decrypt +.Fa "int flen" +.Fa "const unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_encrypt_old +.Fa "unsigned char *to" +.Fa "const unsigned char *from" +.Fa "int flen" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_decrypt_old +.Fa "unsigned char *to" +.Fa "const unsigned char *from" +.Fa "int flen" +.Fa "EVP_PKEY *pkey" +.Fc +.Sh DESCRIPTION +.Fn RSA_public_encrypt +encrypts the +.Fa flen +bytes at +.Fa from +(usually a session key) using the public key +.Fa rsa +and stores the ciphertext in +.Fa to . +.Fa to +must point to +.Fn RSA_size rsa +bytes of memory. +.Pp +.Fa padding +denotes one of the following modes: +.Bl -tag -width Ds +.It Dv RSA_PKCS1_PADDING +PKCS #1 v1.5 padding. +This currently is the most widely used mode. +.It Dv 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. +.It Dv RSA_NO_PADDING +Raw RSA encryption. +This mode should only be used to implement cryptographically sound +padding modes in the application code. +Encrypting user data directly with RSA is insecure. +.El +.Pp +.Fa flen +must be less than +.Fn RSA_size rsa +- 11 for the PKCS #1 v1.5 based padding modes, less than +.Fn RSA_size rsa +- 41 for +.Dv RSA_PKCS1_OAEP_PADDING +and exactly +.Fn RSA_size rsa +for +.Dv RSA_NO_PADDING . +.Pp +.Fn RSA_private_decrypt +decrypts the +.Fa flen +bytes at +.Fa from +using the private key +.Fa rsa +and stores the plaintext in +.Fa to . +.Fa to +must point to a memory section large enough to hold the decrypted data +(which is smaller than +.Fn RSA_size rsa ) . +.Fa padding +is the padding mode that was used to encrypt the data. +.Pp +.Fn EVP_PKEY_encrypt_old +is a deprecated wrapper around +.Fn RSA_public_encrypt +that uses the +.Vt RSA +public key stored in +.Fa pkey +and +.Dv RSA_PKCS1_PADDING . +.Pp +.Fn EVP_PKEY_decrypt_old +is a deprecated wrapper around +.Fn RSA_private_decrypt +that uses the +.Vt RSA +private key stored in +.Fa pkey +and +.Dv RSA_PKCS1_PADDING . +.Sh RETURN VALUES +.Fn RSA_public_encrypt +and +.Fn EVP_PKEY_encrypt_old +return the size of the encrypted data (i.e.\& +.Fn RSA_size rsa ) . +.Fn RSA_private_decrypt +and +.Fn EVP_PKEY_decrypt_old +returns the size of the recovered plaintext. +On error, \-1 is returned; the error codes can be obtained by +.Xr ERR_get_error 3 . +.Pp +In addition to the return values documented above, +.Fn EVP_PKEY_encrypt_old +may return 0 if the +.Xr EVP_PKEY_id 3 +of +.Fa pkey +is not +.Dv EVP_PKEY_RSA . +.Sh SEE ALSO +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr RSA_meth_set_priv_dec 3 , +.Xr RSA_new 3 , +.Xr RSA_size 3 +.Sh STANDARDS +SSL, PKCS #1 v2.0 +.Sh HISTORY +.Fn RSA_public_encrypt +and +.Fn RSA_private_decrypt +appeared in SSLeay 0.4 or earlier and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_PKEY_encrypt +and +.Fn EVP_PKEY_decrypt +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . +There were renamed to +.Fn EVP_PKEY_encrypt_old +and +.Fn EVP_PKEY_decrypt_old +in OpenSSL 1.0.0 and +.Ox 4.9 . +.Pp +.Dv RSA_NO_PADDING +is available since SSLeay 0.9.0. +OAEP was added in OpenSSL 0.9.2b. +.Sh BUGS +Decryption failures in the +.Dv 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 +.Dv RSA_PKCS1_OAEP_PADDING . diff --git a/static/openbsd/man3/RSA_security_bits.3 b/static/openbsd/man3/RSA_security_bits.3 new file mode 100644 index 00000000..0766ce61 --- /dev/null +++ b/static/openbsd/man3/RSA_security_bits.3 @@ -0,0 +1,138 @@ +.\" $OpenBSD: RSA_security_bits.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2022 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 $Mdocdate: June 8 2025 $ +.Dt RSA_SECURITY_BITS 3 +.Os +.Sh NAME +.Nm RSA_security_bits , +.Nm DSA_security_bits , +.Nm DH_security_bits , +.Nm BN_security_bits +.Nd get security strength +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fn RSA_security_bits "const RSA *rsa" +.In openssl/dsa.h +.Ft int +.Fn DSA_security_bits "const DSA *dsa" +.In openssl/dh.h +.Ft int +.Fn DH_security_bits "const DH *dh" +.In openssl/bn.h +.Ft int +.Fo BN_security_bits +.Fa "int pubbits" +.Fa "int privbits" +.Fc +.Sh DESCRIPTION +These functions return the security strength of some specific types of +cryptographic keys, measured in bits. +It is approximately the binary logarithm of the number of operations +an attacker has to perform in order to break the key. +.Pp +.Fn RSA_security_bits +uses only the number of significant bits in the public modulus of +.Fa rsa +as returned by +.Xr RSA_bits 3 . +It returns +.Bl -column 256 for 15360 last_column -offset indent +.It 256 Ta for Ta 15360 Ta or more significant bits +.It 192 Ta Ta 7680 Ta +.It 128 Ta Ta 3072 Ta +.It 112 Ta Ta 2048 Ta +.It 80 Ta Ta 1024 Ta +.El +.Pp +or 0 otherwise. +.Pp +.Fn DSA_security_bits +uses the number of significant bits in the public domain parameter +.Fa p +contained in the +.Fa dsa +object, which is equal to the size of the public key, in the same way as +.Fn RSA_security_bits . +In addition, the public domain parameter +.Fa q +contained in the +.Fa dsa +object, which is equal to the size of the private key, is inspected. +The return value is either the security strength according to the above table +or half the size of the private key, whichever is smaller. +If the return value would be smaller than 80, 0 is returned instead. +.Pp +.Fn DH_security_bits +uses the number of significant bits in the shared secret contained in the +.Fa dh +object as returned by +.Xr DH_bits 3 +in the same way as +.Fn RSA_security_bits . +If +.Fa dh +contains the domain parameter +.Fa q , +its number of significant bits is used in the same way as for +.Fn DSA_security_bits +to limit the return value. +Otherwise, if +.Fa dh +contains the length of the secret exponent in bits, +that number is used. +If neither is available, only the above table is used +without calculating a minimum. +.Pp +.Fn BN_security_bits +is a combined function. +If \-1 is passed for the +.Fa privbits +argument, it behaves like +.Fn RSA_security_bits . +Otherwise, it behaves like +.Fn DSA_security_bits . +.Sh RETURN VALUES +All these functions return numbers in the range from 0 to 256 inclusive. +.Pp +.Fn DSA_security_bits +fails and returns \-1 unless both of the +.Fa p +and +.Fa q +domain parameters are present. +.Sh SEE ALSO +.Xr BN_num_bits 3 , +.Xr DH_bits 3 , +.Xr DH_get0_pqg 3 , +.Xr DSA_get0_pqg 3 , +.Xr RSA_bits 3 , +.Xr SSL_CTX_set_security_level 3 +.Rs +.%A Elaine Barker +.%T Recommendation for Key Management +.%I U.S. National Institute of Standards and Technology +.%R NIST Special Publication 800-57 Part 1 Revision 5 +.%U https://doi.org/10.6028/NIST.SP.800-57pt1r5 +.%C Gaithersburg, MD +.%D May 2020 +.Re +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 7.2 . diff --git a/static/openbsd/man3/RSA_set_method.3 b/static/openbsd/man3/RSA_set_method.3 new file mode 100644 index 00000000..127dc62c --- /dev/null +++ b/static/openbsd/man3/RSA_set_method.3 @@ -0,0 +1,253 @@ +.\" $OpenBSD: RSA_set_method.3,v 1.19 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Ulf Moeller +.\" and Geoff Thorpe . +.\" Copyright (c) 2000, 2002, 2007, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_SET_METHOD 3 +.Os +.Sh NAME +.Nm RSA_set_default_method , +.Nm RSA_get_default_method , +.Nm RSA_set_method , +.Nm RSA_get_method , +.Nm RSA_PKCS1_SSLeay , +.Nm RSA_flags , +.Nm RSA_new_method +.Nd select RSA method +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft void +.Fo RSA_set_default_method +.Fa "const RSA_METHOD *meth" +.Fc +.Ft const RSA_METHOD * +.Fn RSA_get_default_method void +.Ft int +.Fo RSA_set_method +.Fa "RSA *rsa" +.Fa "const RSA_METHOD *meth" +.Fc +.Ft const RSA_METHOD * +.Fo RSA_get_method +.Fa "const RSA *rsa" +.Fc +.Ft const RSA_METHOD * +.Fn RSA_PKCS1_SSLeay void +.Ft int +.Fo RSA_flags +.Fa "const RSA *rsa" +.Fc +.Ft RSA * +.Fo RSA_new_method +.Fa "ENGINE *engine" +.Fc +.Sh DESCRIPTION +An +.Vt RSA_METHOD +object contains pointers to the functions used for RSA operations. +By default, the internal implementation returned by +.Fn RSA_PKCS1_SSLeay +is used. +By selecting another method, alternative implementations +such as hardware accelerators may be used. +.Pp +.Fn RSA_set_default_method +selects +.Fa meth +as the default method for all +.Vt RSA +structures created later. +.Pp +.Fn RSA_get_default_method +returns a pointer to the current default method. +.Pp +.Fn RSA_set_method +selects +.Fa meth +to perform all operations using the key +.Fa rsa . +This replaces the previous +.Vt RSA_METHOD +used by the RSA key, calling the +.Fa finish +function set up with +.Xr RSA_meth_set_finish 3 +if any. +If +.Fa meth +contains an +.Fa init +function set up with +.Xr RSA_meth_set_init 3 , +that function is called just before returning from +.Fn RSA_set_method . +.Pp +It is possible to have RSA keys that only work with certain +.Vt RSA_METHOD +implementations, +and in such cases attempting to change the +.Vt RSA_METHOD +for the key can have unexpected results. +.Pp +.Fn RSA_get_method +returns a pointer to the +.Vt RSA_METHOD +being used by +.Fa rsa . +.Pp +The misleadingly named function +.Fn RSA_flags +returns the flags that are set for the current +.Vt RSA_METHOD +of +.Fa rsa . +The flags used by +.Fa rsa +itself can instead be tested with +.Xr RSA_test_flags 3 . +See the +.Sx BUGS +section for more details. +.Pp +.Fn RSA_new_method +allocates and initializes an +.Vt RSA +structure. +The +.Fa engine +argument is ignored and +the default method controlled by +.Fn RSA_set_default_method +is used. +.Pp +The initial +.Fa flags +are copied from the +.Vt RSA_METHOD +object used and will not be affected by later changes to that object, +but may be modified by the optional +.Fa init +function which may have been set up with +.Xr RSA_meth_set_init 3 +and which is called just before returning from +.Fn RSA_new_method . +.Sh RETURN VALUES +.Fn RSA_PKCS1_SSLeay , +.Fn RSA_get_default_method , +and +.Fn RSA_get_method +return pointers to the respective +.Vt RSA_METHOD . +.Pp +.Fn RSA_set_method +returns 1 on success or 0 on failure. +Currently, it cannot fail. +.Pp +.Fn RSA_new_method +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 +if the allocation fails. +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr RSA_meth_new 3 , +.Xr RSA_new 3 +.Sh HISTORY +.Fn RSA_set_default_method , +.Fn RSA_PKCS1_SSLeay , +and +.Fn RSA_new_method +first appeared in SSLeay 0.8.0. +.Fn RSA_flags +first appeared in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn RSA_get_default_method , +.Fn RSA_set_method , +and +.Fn RSA_get_method +as well as the +.Fa rsa_sign +and +.Fa rsa_verify +components of +.Vt RSA_METHOD +first appeared in OpenSSL 0.9.4 and have been available since +.Ox 2.6 . +.Sh BUGS +The behaviour of +.Fn RSA_flags +is a misfeature that is left as-is for now to avoid creating +compatibility problems. +RSA functionality, such as the encryption functions, are controlled by +the +.Fa flags +value in the +.Vt RSA +key itself, not by the +.Fa flags +value in the +.Vt RSA_METHOD +attached to the RSA key (which is what this function returns). +If the flags element of an +.Vt RSA +key is changed, the changes will be honoured by RSA functionality +but will not be reflected in the return value of the +.Fn RSA_flags +function - in effect +.Fn RSA_flags +behaves more like an +.Fn RSA_default_flags +function, which does not +currently exist. diff --git a/static/openbsd/man3/RSA_sign.3 b/static/openbsd/man3/RSA_sign.3 new file mode 100644 index 00000000..d2a45123 --- /dev/null +++ b/static/openbsd/man3/RSA_sign.3 @@ -0,0 +1,148 @@ +.\" $OpenBSD: RSA_sign.3,v 1.10 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL aa90ca11 Aug 20 15:48:56 2016 -0400 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2005, 2014, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_SIGN 3 +.Os +.Sh NAME +.Nm RSA_sign , +.Nm RSA_verify +.Nd RSA signatures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_sign +.Fa "int type" +.Fa "const unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigret" +.Fa "unsigned int *siglen" +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_verify +.Fa "int type" +.Fa "const unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigbuf" +.Fa "unsigned int siglen" +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +.Fn RSA_sign +signs the message digest +.Fa m +of size +.Fa m_len +using the private key +.Fa rsa +using RSASSA-PKCS1-v1_5 as specified in RFC 3447. +It stores the signature in +.Fa sigret +and the signature size in +.Fa siglen . +.Fa sigret +must point to +.Fn RSA_size rsa +bytes of memory. +Note that PKCS #1 adds meta-data, placing limits on the size of the key +that can be used. +See +.Xr RSA_private_encrypt 3 +for lower-level operations. +.Pp +.Fa type +denotes the message digest algorithm that was used to generate +.Fa m . +If +.Fa type +is +.Sy NID_md5_sha1 , +an SSL signature (MD5 and SHA-1 message digests with PKCS #1 padding and +no algorithm identifier) is created. +.Pp +.Fn RSA_verify +verifies that the signature +.Fa sigbuf +of size +.Fa siglen +matches a given message digest +.Fa m +of size +.Fa m_len . +.Fa type +denotes the message digest algorithm that was used to generate the +signature. +.Fa rsa +is the signer's public key. +.Sh RETURN VALUES +.Fn RSA_sign +returns 1 on success. +.Fn RSA_verify +returns 1 on successful verification. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr RSA_meth_set_sign 3 , +.Xr RSA_new 3 , +.Xr RSA_private_encrypt 3 , +.Xr RSA_public_decrypt 3 +.Sh STANDARDS +SSL, PKCS #1 v2.0 +.Sh HISTORY +.Fn RSA_sign +first appeared in SSLeay 0.4.4. +.Fn RSA_verify +first appeared in SSLeay 0.6.0. +Both functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/RSA_sign_ASN1_OCTET_STRING.3 b/static/openbsd/man3/RSA_sign_ASN1_OCTET_STRING.3 new file mode 100644 index 00000000..bd11a060 --- /dev/null +++ b/static/openbsd/man3/RSA_sign_ASN1_OCTET_STRING.3 @@ -0,0 +1,132 @@ +.\" $OpenBSD: RSA_sign_ASN1_OCTET_STRING.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_SIGN_ASN1_OCTET_STRING 3 +.Os +.Sh NAME +.Nm RSA_sign_ASN1_OCTET_STRING , +.Nm RSA_verify_ASN1_OCTET_STRING +.Nd RSA signatures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_sign_ASN1_OCTET_STRING +.Fa "int dummy" +.Fa "unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigret" +.Fa "unsigned int *siglen" +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_verify_ASN1_OCTET_STRING +.Fa "int dummy" +.Fa "unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigbuf" +.Fa "unsigned int siglen" +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +.Fn RSA_sign_ASN1_OCTET_STRING +signs the octet string +.Fa m +of size +.Fa m_len +using the private key +.Fa rsa +represented in DER using PKCS #1 padding. +It stores the signature in +.Fa sigret +and the signature size in +.Fa siglen . +.Fa sigret +must point to +.Fn RSA_size rsa +bytes of memory. +.Pp +.Fa dummy +is ignored. +.Pp +.Fn RSA_verify_ASN1_OCTET_STRING +verifies that the signature +.Fa sigbuf +of size +.Fa siglen +is the DER representation of a given octet string +.Fa m +of size +.Fa m_len . +.Fa dummy +is ignored. +.Fa rsa +is the signer's public key. +.Sh RETURN VALUES +.Fn RSA_sign_ASN1_OCTET_STRING +returns 1 on success or 0 otherwise. +.Fn RSA_verify_ASN1_OCTET_STRING +returns 1 on successful verification or 0 otherwise. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr RSA_new 3 , +.Xr RSA_sign 3 , +.Xr RSA_verify 3 +.Sh HISTORY +.Fn RSA_sign_ASN1_OCTET_STRING +and +.Fn RSA_verify_ASN1_OCTET_STRING +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Sh BUGS +These functions serve no recognizable purpose. diff --git a/static/openbsd/man3/RSA_size.3 b/static/openbsd/man3/RSA_size.3 new file mode 100644 index 00000000..9988903d --- /dev/null +++ b/static/openbsd/man3/RSA_size.3 @@ -0,0 +1,98 @@ +.\" $OpenBSD: RSA_size.3,v 1.11 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Ulf Moeller and +.\" Kurt Roeckx . +.\" Copyright (c) 2000, 2002, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt RSA_SIZE 3 +.Os +.Sh NAME +.Nm RSA_size , +.Nm RSA_bits +.Nd get the RSA modulus size +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft int +.Fo RSA_size +.Fa "const RSA *rsa" +.Fc +.Ft int +.Fo RSA_bits +.Fa "const RSA *rsa" +.Fc +.Sh DESCRIPTION +.Fn RSA_size +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 +.Fn RSA_bits +returns the number of significant bits. +.Pp +.Fa rsa +and +.Fa rsa->n +must not be +.Dv NULL . +.Sh RETURN VALUES +The size. +.Sh SEE ALSO +.Xr BN_num_bits 3 , +.Xr RSA_get0_key 3 , +.Xr RSA_new 3 , +.Xr RSA_security_bits 3 +.Sh HISTORY +.Fn RSA_size +first appeared in SSLeay 0.4.4 and has been available since +.Ox 2.4 . +.Pp +.Fn RSA_bits +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SHA1.3 b/static/openbsd/man3/SHA1.3 new file mode 100644 index 00000000..74fd388c --- /dev/null +++ b/static/openbsd/man3/SHA1.3 @@ -0,0 +1,286 @@ +.\" $OpenBSD: SHA1.3,v 1.10 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Ulf Moeller and +.\" Matt Caswell . +.\" Copyright (c) 2000, 2006, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SHA1 3 +.Os +.Sh NAME +.Nm SHA1 , +.Nm SHA1_Init , +.Nm SHA1_Update , +.Nm SHA1_Final , +.Nm SHA224 , +.Nm SHA224_Init , +.Nm SHA224_Update , +.Nm SHA224_Final , +.Nm SHA256 , +.Nm SHA256_Init , +.Nm SHA256_Update , +.Nm SHA256_Final , +.Nm SHA384 , +.Nm SHA384_Init , +.Nm SHA384_Update , +.Nm SHA384_Final , +.Nm SHA512 , +.Nm SHA512_Init , +.Nm SHA512_Update , +.Nm SHA512_Final +.Nd Secure Hash Algorithm +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/sha.h +.Ft unsigned char * +.Fo SHA1 +.Fa "const unsigned char *d" +.Fa "size_t n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo SHA1_Init +.Fa "SHA_CTX *c" +.Fc +.Ft int +.Fo SHA1_Update +.Fa "SHA_CTX *c" +.Fa "const void *data" +.Fa "size_t len" +.Fc +.Ft int +.Fo SHA1_Final +.Fa "unsigned char *md" +.Fa "SHA_CTX *c" +.Fc +.Ft unsigned char * +.Fo SHA224 +.Fa "const unsigned char *d" +.Fa "size_t n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo SHA224_Init +.Fa "SHA256_CTX *c" +.Fc +.Ft int +.Fo SHA224_Update +.Fa "SHA256_CTX *c" +.Fa "const void *data" +.Fa "size_t len" +.Fc +.Ft int +.Fo SHA224_Final +.Fa "unsigned char *md" +.Fa "SHA256_CTX *c" +.Fc +.Ft unsigned char * +.Fo SHA256 +.Fa "const unsigned char *d" +.Fa "size_t n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo SHA256_Init +.Fa "SHA256_CTX *c" +.Fc +.Ft int +.Fo SHA256_Update +.Fa "SHA256_CTX *c" +.Fa "const void *data" +.Fa "size_t len" +.Fc +.Ft int +.Fo SHA256_Final +.Fa "unsigned char *md" +.Fa "SHA256_CTX *c" +.Fc +.Ft unsigned char * +.Fo SHA384 +.Fa "const unsigned char *d" +.Fa "size_t n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo SHA384_Init +.Fa "SHA512_CTX *c" +.Fc +.Ft int +.Fo SHA384_Update +.Fa "SHA512_CTX *c" +.Fa "const void *data" +.Fa "size_t len" +.Fc +.Ft int +.Fo SHA384_Final +.Fa "unsigned char *md" +.Fa "SHA512_CTX *c" +.Fc +.Ft unsigned char * +.Fo SHA512 +.Fa "const unsigned char *d" +.Fa "size_t n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo SHA512_Init +.Fa "SHA512_CTX *c" +.Fc +.Ft int +.Fo SHA512_Update +.Fa "SHA512_CTX *c" +.Fa "const void *data" +.Fa "size_t len" +.Fc +.Ft int +.Fo SHA512_Final +.Fa "unsigned char *md" +.Fa "SHA512_CTX *c" +.Fc +.Sh DESCRIPTION +SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a +160-bit output. +.Pp +.Fn SHA1 +computes the SHA-1 message digest of the +.Fa n +bytes at +.Fa d +and places it in +.Fa md , +which must have space for +.Dv SHA_DIGEST_LENGTH +== 20 bytes of output. +.Pp +The following functions may be used if the message is not completely +stored in memory: +.Pp +.Fn SHA1_Init +initializes a +.Vt SHA_CTX +structure. +.Pp +.Fn SHA1_Update +can be called repeatedly with chunks of the message to be hashed +.Pq Fa len No bytes at Fa data . +.Pp +.Fn SHA1_Final +places the message digest in +.Fa md , +which must have space for +.Dv SHA_DIGEST_LENGTH +== 20 bytes of output, and erases the +.Vt SHA_CTX . +.Pp +The SHA224, SHA256, SHA384, and SHA512 families of functions operate +in the same way as the SHA1 functions. +Note that SHA224 and SHA256 use a +.Vt SHA256_CTX +object instead of +.Vt SHA_CTX , +and SHA384 and SHA512 use +.Vt SHA512_CTX . +The buffer +.Fa md +must have space for the output from the SHA variant being used: +.Dv SHA224_DIGEST_LENGTH , +.Dv SHA256_DIGEST_LENGTH , +.Dv SHA384_DIGEST_LENGTH , +or +.Dv SHA512_DIGEST_LENGTH +bytes. +.Pp +Applications should use the higher level functions +.Xr EVP_DigestInit 3 +etc. instead of calling the hash functions directly. +.Sh RETURN VALUES +.Fn SHA1 , +.Fn SHA224 , +.Fn SHA256 , +.Fn SHA384 , +and +.Fn SHA512 +return a pointer to the hash value. +The other functions return 1 for success or 0 otherwise. +.Sh SEE ALSO +.Xr EVP_DigestInit 3 , +.Xr HMAC 3 , +.Xr RIPEMD160 3 +.Sh STANDARDS +.Rs +.%T Secure Hash Standard (SHS) +.%R NIST FIPS Publication +.%N 180-4 +.%U https://doi.org/10.6028/NIST.FIPS.180-4 +.%D 2015 +.Re +.Sh HISTORY +.Fn SHA1 , +.Fn SHA1_Init , +.Fn SHA1_Update , +and +.Fn SHA1_Final +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +The other functions first appeared in OpenSSL 0.9.8 +and have been available since +.Ox 4.5 . +.Sh CAVEATS +Other implementations allow +.Fa md +in +.Fn SHA1 , +.Fn SHA224 , +.Fn SHA256 , +.Fn SHA384 , +and +.Fn SHA512 +to be +.Dv NULL +and return a static array, which is not thread safe. diff --git a/static/openbsd/man3/SHA1Init.3 b/static/openbsd/man3/SHA1Init.3 new file mode 100644 index 00000000..6f7c6ea7 --- /dev/null +++ b/static/openbsd/man3/SHA1Init.3 @@ -0,0 +1,239 @@ +.\" $OpenBSD: SHA1Init.3,v 1.4 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 1997, 2004 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. +.\" +.\" See http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.txt +.\" for the detailed standard +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt SHA1INIT 3 +.Os +.Sh NAME +.Nm SHA1Init , +.Nm SHA1Update , +.Nm SHA1Pad , +.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 u_int8_t *data" "size_t len" +.Ft void +.Fn SHA1Pad "SHA1_CTX *context" +.Ft void +.Fn SHA1Final "u_int8_t digest[SHA1_DIGEST_LENGTH]" "SHA1_CTX *context" +.Ft void +.Fn SHA1Transform "u_int32_t state[5]" "const u_int8_t buffer[SHA1_BLOCK_LENGTH]" +.Ft char * +.Fn SHA1End "SHA1_CTX *context" "char *buf" +.Ft char * +.Fn SHA1File "const char *filename" "char *buf" +.Ft char * +.Fn SHA1FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft char * +.Fn SHA1Data "const u_int8_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 +SHA-1 has been broken; it should only be used where necessary for +backward compatibility. +The attack on SHA-1 is in the nature of finding +.Dq collisions +\(em that is, multiple inputs which hash to the same value. +It is still unlikely for an attacker to be able to determine the exact +original input given a hash value. +.Pp +The +.Fn SHA1Init +function initializes a SHA1_CTX +.Fa context +for use with +.Fn SHA1Update , +and +.Fn SHA1Final . +The +.Fn SHA1Update +function adds +.Fa data +of length +.Fa len +to the SHA1_CTX specified by +.Fa context . +.Fn SHA1Final +is called when all data has been added via +.Fn SHA1Update +and stores a message digest in the +.Fa digest +parameter. +.Pp +The +.Fn SHA1Pad +function can be used to apply padding to the message digest as in +.Fn SHA1Final , +but 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 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 +.Dv 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 +.Fa 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 following code fragment will calculate the digest for +the string +.Qq abc +which is +.Dq 0xa9993e364706816aba3e25717850c26c9cd0d89d . +.Bd -literal -offset indent +SHA1_CTX sha; +u_int8_t results[SHA1_DIGEST_LENGTH]; +char *buf; +int n; + +buf = "abc"; +n = strlen(buf); +SHA1Init(&sha); +SHA1Update(&sha, (u_int8_t *)buf, n); +SHA1Final(results, &sha); + +/* Print the digest as one long hex value */ +printf("0x"); +for (n = 0; n < SHA1_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 +u_int8_t output[SHA1_DIGEST_STRING_LENGTH]; +char *buf = "abc"; + +printf("0x%s\en", SHA1Data(buf, strlen(buf), output)); +.Ed +.Sh SEE ALSO +.Xr cksum 1 , +.Xr sha1 1 , +.Xr MD5Init 3 , +.Xr RMD160Init 3 , +.Xr SHA256Init 3 +.Sh STANDARDS +.Rs +.%A J. Burrows +.%R FIPS PUB 180-1 +.%T The Secure Hash Standard +.Re +.Pp +.Rs +.%A D. Eastlake +.%A P. Jones +.%D September 2001 +.%R RFC 3174 +.%T US Secure Hash Algorithm 1 (SHA1) +.Re +.Sh HISTORY +The SHA-1 functions appeared in +.Ox 2.0 . +.Sh AUTHORS +.An -nosplit +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 +.An Poul-Henning Kamp . diff --git a/static/openbsd/man3/SHA256Init.3 b/static/openbsd/man3/SHA256Init.3 new file mode 100644 index 00000000..f3621b0d --- /dev/null +++ b/static/openbsd/man3/SHA256Init.3 @@ -0,0 +1,349 @@ +.\" $OpenBSD: SHA256Init.3,v 1.4 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2003, 2004 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. +.\" +.\" See http://www.nist.gov/sha/ for the detailed standard +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt SHA256INIT 3 +.Os +.Sh NAME +.Nm SHA224Init , +.Nm SHA224Update , +.Nm SHA224Pad , +.Nm SHA224Final , +.Nm SHA224Transform , +.Nm SHA224End , +.Nm SHA224File , +.Nm SHA224FileChunk , +.Nm SHA224Data , +.Nm SHA256Init , +.Nm SHA256Update , +.Nm SHA256Pad , +.Nm SHA256Final , +.Nm SHA256Transform , +.Nm SHA256End , +.Nm SHA256File , +.Nm SHA256FileChunk , +.Nm SHA256Data , +.Nm SHA384Init , +.Nm SHA384Update , +.Nm SHA384Pad , +.Nm SHA384Final , +.Nm SHA384Transform , +.Nm SHA384End , +.Nm SHA384File , +.Nm SHA384FileChunk , +.Nm SHA384Data , +.Nm SHA512Init , +.Nm SHA512Update , +.Nm SHA512Pad , +.Nm SHA512Final , +.Nm SHA512Transform , +.Nm SHA512End , +.Nm SHA512File , +.Nm SHA512FileChunk , +.Nm SHA512Data , +.Nm SHA512_256Init , +.Nm SHA512_256Update , +.Nm SHA512_256Pad , +.Nm SHA512_256Final , +.Nm SHA512_256Transform , +.Nm SHA512_256End , +.Nm SHA512_256File , +.Nm SHA512_256FileChunk , +.Nm SHA512_256Data +.Nd calculate the NIST Secure Hash Standard (version 2) +.Sh SYNOPSIS +.In sys/types.h +.In sha2.h +.Ft void +.Fn SHA224Init "SHA2_CTX *context" +.Ft void +.Fn SHA224Update "SHA2_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn SHA224Pad "SHA2_CTX *context" +.Ft void +.Fn SHA224Final "u_int8_t digest[SHA224_DIGEST_LENGTH]" "SHA2_CTX *context" +.Ft void +.Fn SHA224Transform "u_int32_t state[8]" "const u_int8_t buffer[SHA224_BLOCK_LENGTH]" +.Ft char * +.Fn SHA224End "SHA2_CTX *context" "char *buf" +.Ft char * +.Fn SHA224File "const char *filename" "char *buf" +.Ft char * +.Fn SHA224FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft char * +.Fn SHA224Data "const u_int8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA256Init "SHA2_CTX *context" +.Ft void +.Fn SHA256Update "SHA2_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn SHA256Pad "SHA2_CTX *context" +.Ft void +.Fn SHA256Final "u_int8_t digest[SHA256_DIGEST_LENGTH]" "SHA2_CTX *context" +.Ft void +.Fn SHA256Transform "u_int32_t state[8]" "const u_int8_t buffer[SHA256_BLOCK_LENGTH]" +.Ft char * +.Fn SHA256End "SHA2_CTX *context" "char *buf" +.Ft char * +.Fn SHA256File "const char *filename" "char *buf" +.Ft char * +.Fn SHA256FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft char * +.Fn SHA256Data "const u_int8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA384Init "SHA2_CTX *context" +.Ft void +.Fn SHA384Update "SHA2_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn SHA384Pad "SHA2_CTX *context" +.Ft void +.Fn SHA384Final "u_int8_t digest[SHA384_DIGEST_LENGTH]" "SHA2_CTX *context" +.Ft void +.Fn SHA384Transform "u_int64_t state[8]" "const u_int8_t buffer[SHA384_BLOCK_LENGTH]" +.Ft char * +.Fn SHA384End "SHA2_CTX *context" "char *buf" +.Ft char * +.Fn SHA384File "const char *filename" "char *buf" +.Ft char * +.Fn SHA384FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft char * +.Fn SHA384Data "const u_int8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA512Init "SHA2_CTX *context" +.Ft void +.Fn SHA512Update "SHA2_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn SHA512Pad "SHA2_CTX *context" +.Ft void +.Fn SHA512Final "u_int8_t digest[SHA512_DIGEST_LENGTH]" "SHA2_CTX *context" +.Ft void +.Fn SHA512Transform "u_int64_t state[8]" "const u_int8_t buffer[SHA512_BLOCK_LENGTH]" +.Ft char * +.Fn SHA512End "SHA2_CTX *context" "char *buf" +.Ft char * +.Fn SHA512File "const char *filename" "char *buf" +.Ft char * +.Fn SHA512FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft char * +.Fn SHA512Data "const u_int8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA512_256Init "SHA2_CTX *context" +.Ft void +.Fn SHA512_256Update "SHA2_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn SHA512_256Pad "SHA2_CTX *context" +.Ft void +.Fn SHA512_256Final "u_int8_t digest[SHA512_256_DIGEST_LENGTH]" "SHA2_CTX *context" +.Ft void +.Fn SHA512_256Transform "u_int64_t state[8]" "const u_int8_t buffer[SHA512_256_BLOCK_LENGTH]" +.Ft char * +.Fn SHA512_256End "SHA2_CTX *context" "char *buf" +.Ft char * +.Fn SHA512_256File "const char *filename" "char *buf" +.Ft char * +.Fn SHA512_256FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft char * +.Fn SHA512_256Data "const u_int8_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 SHA1 functions, +with which they share a similar interface. +The 224, 256, 384, and 512-bit versions of SHA2 share the same interface. +SHA512/256, a truncated version of SHA512, is also supported. +For brevity, only the 256-bit variants are described below. +.Pp +The +.Fn SHA256Init +function initializes a SHA2_CTX +.Fa context +for use with +.Fn SHA256Update +and +.Fn SHA256Final . +The +.Fn SHA256Update +function adds +.Fa data +of length +.Fa len +to the SHA2_CTX specified by +.Fa context . +.Fn SHA256Final +is called when all data has been added via +.Fn SHA256Update +and stores a message digest in the +.Fa digest +parameter. +.Pp +The +.Fn SHA256Pad +function can be used to apply padding to the message digest as in +.Fn SHA256Final , +but the current context can still be used with +.Fn SHA256Update . +.Pp +The +.Fn SHA256Transform +function is used by +.Fn SHA256Update +to hash 512-bit blocks and forms the core of the algorithm. +Most programs should use the interface provided by +.Fn SHA256Init , +.Fn SHA256Update , +and +.Fn SHA256Final +instead of calling +.Fn SHA256Transform +directly. +.Pp +The +.Fn SHA256End +function is a front end for +.Fn SHA256Final +which converts the digest into an ASCII representation +of the digest in hexadecimal. +.Pp +The +.Fn SHA256File +function calculates the digest for a file and returns the result via +.Fn SHA256End . +If +.Fn SHA256File +is unable to open the file, a +.Dv NULL +pointer is returned. +.Pp +.Fn SHA256FileChunk +behaves like +.Fn SHA256File +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 SHA256Data +function +calculates the digest of an arbitrary string and returns the result via +.Fn SHA256End . +.Pp +For each of the +.Fn SHA256End , +.Fn SHA256File , +.Fn SHA256FileChunk , +and +.Fn SHA256Data +functions the +.Fa buf +parameter should either be a string large enough to hold the resulting digest +(e.g.\& +.Dv SHA224_DIGEST_STRING_LENGTH , +.Dv SHA256_DIGEST_STRING_LENGTH , +.Dv SHA384_DIGEST_STRING_LENGTH , +.Dv SHA512_DIGEST_STRING_LENGTH , +or +.Dv SHA512_256_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 +SHA2_CTX ctx; +u_int8_t results[SHA256_DIGEST_LENGTH]; +char *buf; +int n; + +buf = "abc"; +n = strlen(buf); +SHA256Init(&ctx); +SHA256Update(&ctx, (u_int8_t *)buf, n); +SHA256Final(results, &ctx); + +/* Print the digest as one long hex value */ +printf("0x"); +for (n = 0; n \*(Lt 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 +u_int8_t output[SHA256_DIGEST_STRING_LENGTH]; +char *buf = "abc"; + +printf("0x%s\en", SHA256Data(buf, strlen(buf), output)); +.Ed +.Sh SEE ALSO +.Xr cksum 1 , +.Xr sha256 1 , +.Xr MD5Init 3 , +.Xr RMD160Init 3 , +.Xr SHA1Init 3 +.Rs +.%T Secure Hash Standard +.%O FIPS PUB 180-2 +.Re +.Sh HISTORY +The SHA2 functions appeared in +.Ox 3.4 . +.Sh AUTHORS +.An -nosplit +This implementation of the SHA functions was written by +.An Aaron D. Gifford . +.Pp +The +.Fn SHA256End , +.Fn SHA256File , +.Fn SHA256FileChunk , +and +.Fn SHA256Data +helper functions are derived from code written by +.An Poul-Henning Kamp . diff --git a/static/openbsd/man3/SMIME_crlf_copy.3 b/static/openbsd/man3/SMIME_crlf_copy.3 new file mode 100644 index 00000000..0991d207 --- /dev/null +++ b/static/openbsd/man3/SMIME_crlf_copy.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: SMIME_crlf_copy.3,v 1.5 2025/06/11 13:48:54 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 11 2025 $ +.Dt SMIME_CRLF_COPY 3 +.Os +.Sh NAME +.Nm SMIME_crlf_copy +.Nd buffered copy between BIOs +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo SMIME_crlf_copy +.Fa "BIO *in_bio" +.Fa "BIO *out_bio" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn SMIME_crlf_copy +copies data from +.Fa in_bio +to +.Fa out_bio . +To avoid many small write operations on +.Fa out_bio , +a buffering BIO created with +.Xr BIO_f_buffer 3 +is temporarily prepended to it. +.Pp +If the bit +.Dv SMIME_BINARY +is set in the +.Fa flags +argument, all the data is copied verbatim using +.Xr BIO_read 3 +and +.Xr BIO_write 3 . +.Pp +Otherwise, the data is read as text. +All trailing carriage return and newline characters are discarded +from every input line and a single pair of carriage return and +newline characters is appended to mark the end of every output line, +except that the last output line will end without such a pair if +the last input line does not have a newline character at the end. +.Pp +If the bit +.Dv SMIME_TEXT +is set in the +.Fa flags +argument and the bit +.Dv SMIME_BINARY +is not set, the line +.Qq Content-Type: text/plain +is prepended to the output +with two pairs of carriage return and newline characters after it. +.Pp +In any case, +.Xr BIO_flush 3 +is called on the output at the end of the function. +.Sh RETURN VALUES +.Fn SMIME_crlf_copy +is intended to return 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr BIO_f_buffer 3 , +.Xr BIO_flush 3 , +.Xr BIO_new 3 , +.Xr BIO_push 3 , +.Xr BIO_read 3 , +.Xr SMIME_text 3 , +.Xr SMIME_write_CMS 3 , +.Xr SMIME_write_PKCS7 3 +.Sh HISTORY +.Fn SMIME_crlf_copy +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Sh BUGS +.Fn SMIME_crlf_copy +silently ignores most errors and may return 1 +even if it lost part or all of the data in transit. +.Pp +Only blocking BIOs are supported. +If any of the +.Vt BIO +arguments is non-blocking, part or all of the data is likely +to be silently lost in transit. diff --git a/static/openbsd/man3/SMIME_read_CMS.3 b/static/openbsd/man3/SMIME_read_CMS.3 new file mode 100644 index 00000000..d37769e5 --- /dev/null +++ b/static/openbsd/man3/SMIME_read_CMS.3 @@ -0,0 +1,136 @@ +.\" $OpenBSD: SMIME_read_CMS.3,v 1.9 2025/06/11 13:41:03 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 11 2025 $ +.Dt SMIME_READ_CMS 3 +.Os +.Sh NAME +.Nm SMIME_read_CMS +.Nd extract CMS ContentInfo from an S/MIME message +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo SMIME_read_CMS +.Fa "BIO *in" +.Fa "BIO **bcont" +.Fc +.Sh DESCRIPTION +.Fn SMIME_read_CMS +parses a message in S/MIME format from +.Fa in . +.Pp +If the message uses cleartext signing, the content is saved in a memory BIO +which is written to +.Pf * Fa bcont +and which can then be passed to +.Xr CMS_verify 3 +with the +.Dv CMS_DETACHED +flag set. +Otherwise, +.Pf * Fa bcont +is set to +.Dv NULL +and the type of the returned structure can be determined using +.Xr CMS_get0_type 3 . +.Pp +To support future functionality if +.Fa bcont +is not +.Dv NULL , +.Pf * Fa bcont +should be initialized to +.Dv NULL , +for example: +.Bd -literal -offset indent +BIO *cont = NULL; +CMS_ContentInfo *cms = SMIME_read_CMS(in, &cont); +.Ed +.Sh RETURN VALUES +.Fn SMIME_read_CMS +returns a valid +.Vt CMS_ContentInfo +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BIO_f_base64 3 , +.Xr BIO_new 3 , +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_decrypt 3 , +.Xr CMS_get0_type 3 , +.Xr CMS_verify 3 , +.Xr d2i_CMS_ContentInfo 3 , +.Xr SMIME_read_PKCS7 3 , +.Xr SMIME_text 3 , +.Xr SMIME_write_CMS 3 +.Sh HISTORY +.Fn SMIME_read_CMS +first appeared in OpenSSL 0.9.8h +and has been available since +.Ox 6.7 . +.Sh BUGS +The MIME parser used by +.Fn SMIME_read_CMS +is somewhat primitive. +While it will handle most S/MIME messages, more complex compound formats +may not work. +.Pp +The parser assumes that the +.Vt 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 +the message which can be processed due to memory restraints: a streaming +single pass option should be available. diff --git a/static/openbsd/man3/SMIME_read_PKCS7.3 b/static/openbsd/man3/SMIME_read_PKCS7.3 new file mode 100644 index 00000000..095115c0 --- /dev/null +++ b/static/openbsd/man3/SMIME_read_PKCS7.3 @@ -0,0 +1,154 @@ +.\" $OpenBSD: SMIME_read_PKCS7.3,v 1.10 2025/06/11 13:41:03 schwarze Exp $ +.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2006 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 11 2025 $ +.Dt SMIME_READ_PKCS7 3 +.Os +.Sh NAME +.Nm SMIME_read_PKCS7 +.Nd extract a PKCS#7 object from an S/MIME message +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft PKCS7 * +.Fo SMIME_read_PKCS7 +.Fa "BIO *in" +.Fa "BIO **bcont" +.Fc +.Sh DESCRIPTION +.Fn SMIME_read_PKCS7 +parses a message in S/MIME format. +.Pp +.Fa in +is a +.Vt BIO +to read the message from. +.Pp +If cleartext signing is used, then the content is saved in a memory +.Vt BIO +which is written to +.Pf * Fa bcont , +otherwise +.Pf * Fa bcont +is set to +.Dv NULL . +.Pp +The parsed PKCS#7 structure is returned, or +.Dv NULL +if an error occurred. +.Pp +If +.Pf * Fa bcont +is not +.Dv NULL , +then the message is clear text signed. +.Pf * Fa bcont +can then be passed to +.Xr PKCS7_verify 3 +with the +.Dv PKCS7_DETACHED +flag set. +.Pp +Otherwise the type of the returned structure can be determined using the +.Fn PKCS7_type_is_* +macros defined in +.In openssl/pkcs7.h . +.Pp +To support future functionality, if +.Fa bcont +is not +.Dv NULL , +.Pf * Fa bcont +should be initialized to +.Dv NULL . +For example: +.Bd -literal -offset indent +BIO *cont = NULL; +PKCS7 *p7; + +p7 = SMIME_read_PKCS7(in, &cont); +.Ed +.Sh RETURN VALUES +.Fn SMIME_read_PKCS7 +returns a valid +.Vt PKCS7 +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BIO_f_base64 3 , +.Xr BIO_new 3 , +.Xr PKCS7_new 3 , +.Xr SMIME_read_CMS 3 , +.Xr SMIME_text 3 , +.Xr SMIME_write_PKCS7 3 +.Sh HISTORY +.Fn SMIME_read_PKCS7 +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Sh BUGS +The MIME parser used by +.Fn SMIME_read_PKCS7 +is somewhat primitive. +While it will handle most S/MIME messages, more complex compound +formats may not work. +.Pp +The parser assumes that the +.Vt PKCS7 +structure is always base64 encoded, and it will not handle the case +where it is in binary format or uses quoted printable format. +.Pp +The use of a memory +.Vt BIO +to hold the signed content limits the size of the message which can +be processed due to memory restraints: a streaming single pass +option should be available. diff --git a/static/openbsd/man3/SMIME_text.3 b/static/openbsd/man3/SMIME_text.3 new file mode 100644 index 00000000..719b3d92 --- /dev/null +++ b/static/openbsd/man3/SMIME_text.3 @@ -0,0 +1,61 @@ +.\" $OpenBSD: SMIME_text.3,v 1.3 2025/06/11 13:48:54 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 11 2025 $ +.Dt SMIME_TEXT 3 +.Os +.Sh NAME +.Nm SMIME_text +.Nd remove text/plain MIME headers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo SMIME_text +.Fa "BIO *in_bio" +.Fa "BIO *out_bio" +.Fc +.Sh DESCRIPTION +.Fn SMIME_text +reads MIME headers from +.Fa in_bio , +checks that the content type is +.Dq text/plain , +discards the MIME headers, +and copies the text that follows the headers from +.Fa in_bio +to +.Fa out_bio . +.Sh RETURN VALUES +.Fn SMIME_text +returns 1 on success or 0 if memory allocation, reading the input, +or parsing the MIME headers fails, if there is no +.Dq content-type +header, or if the content type is not +.Dq text/plain . +.Sh SEE ALSO +.Xr SMIME_crlf_copy 3 , +.Xr SMIME_read_CMS 3 , +.Xr SMIME_read_PKCS7 3 , +.Xr SMIME_write_CMS 3 , +.Xr SMIME_write_PKCS7 3 +.Sh HISTORY +.Fn SMIME_text +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Sh CAVEATS +.Fn SMIME_text +does not support non-blocking BIOs. diff --git a/static/openbsd/man3/SMIME_write_CMS.3 b/static/openbsd/man3/SMIME_write_CMS.3 new file mode 100644 index 00000000..5f4c43bb --- /dev/null +++ b/static/openbsd/man3/SMIME_write_CMS.3 @@ -0,0 +1,223 @@ +.\" $OpenBSD: SMIME_write_CMS.3,v 1.9 2025/06/11 23:16:32 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021, 2025 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 11 2025 $ +.Dt SMIME_WRITE_CMS 3 +.Os +.Sh NAME +.Nm SMIME_write_CMS +.Nd convert CMS structure to S/MIME format +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft int +.Fo SMIME_write_CMS +.Fa "BIO *out" +.Fa "CMS_ContentInfo *cms" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn SMIME_write_CMS +generates an S/MIME message on +.Fa out +by writing MIME 1.0 headers +followed by a BER- and base64-encoded serialization of +.Fa cms . +The BER encoding uses the DER format except as described for +.Dv CMS_STREAM +below. +If streaming is enabled, the content must be supplied in the +.Fa data +argument. +.Pp +The +.Fa flags +can be the logical OR of zero or more of the following bits: +.Bl -tag -width Ds +.It Dv CMS_DETACHED +Use cleartext signing and generate a +.Qq multipart/signed +S/MIME message. +The content is read from +.Fa data . +If +.Fa data +is a +.Dv NULL +pointer, this flag is ignored. +.Pp +This flag is only supported if +.Fa cms +is of the type +.Vt SignedData +and +.Dv CMS_DETACHED +was also set when it was created with +.Xr CMS_sign 3 . +.Pp +If +.Dv CMS_STREAM +is not set, the data must be read twice: +once to compute the signature in +.Xr CMS_sign 3 +and once to output the S/MIME message. +.Pp +If +.Dv CMS_DETACHED +is ignored or not specified, the smime-type is chosen according to +.Xr CMS_get0_type 3 : +.Bl -tag -width Ds +.It Dv NID_pkcs7_enveloped +.Qq enveloped-data +.It Dv NID_pkcs7_signed +.Bl -tag -width Msigned-receiptM -compact +.It Qq signed-receipt +if +.Xr CMS_get0_eContentType 3 +is +.Dv NID_id_smime_ct_receipt +.It Qq signed-data +if +.Fa cms +specifies any digest algorithm +.It Qq certs-only +otherwise +.El +.It Dv NID_id_smime_ct_compressedData +.Qq compressed-data +.El +.It Dv CMS_REUSE_DIGEST +Skip the calls to +.Xr CMS_dataInit 3 +and +.Xr CMS_dataFinal 3 . +This flag has no effect unless +.Dv CMS_DETACHED +is also set. +.It Dv CMS_STREAM +Perform streaming by reading the content from +.Fa data . +This only works if +.Dv CMS_DETACHED +is not specified. +.Pp +This flag should only be set if +.Dv CMS_STREAM +was also passed to the function that created +.Fa cms . +.Pp +The content is output in BER format using indefinite length +constructed encoding except in the case of +.Vt SignedData +with detached content where the content is absent and DER format is +used. +.It Dv CMS_TEXT +Prepend the line +.Qq Content-Type: text/plain +to the content. +This only makes sense if +.Dv CMS_DETACHED +is also set. +It is ignored if the flag +.Dv SMIME_BINARY +is also set. +.It Dv SMIME_BINARY +If specified, this flag is passed through to +.Xr SMIME_crlf_copy 3 . +.It Dv SMIME_CRLFEOL +End MIME header lines with pairs of carriage return and newline characters. +By default, no carriage return characters are written +and header lines are ended with newline characters only. +.El +.Sh RETURN VALUES +.Fn SMIME_write_CMS +is intended to return 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr BIO_f_base64 3 , +.Xr BIO_new 3 , +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_encrypt 3 , +.Xr CMS_sign 3 , +.Xr d2i_CMS_ContentInfo 3 , +.Xr ERR_get_error 3 , +.Xr SMIME_crlf_copy 3 , +.Xr SMIME_read_CMS 3 , +.Xr SMIME_write_PKCS7 3 +.Sh HISTORY +.Fn SMIME_write_CMS +first appeared in OpenSSL 0.9.8h +and has been available since +.Ox 6.7 . +.Sh BUGS +.Fn SMIME_write_CMS +ignores most errors and is likely to return 1 +even after producing corrupt or incomplete output. +.Pp +.Fn SMIME_write_CMS +always base64 encodes CMS structures. +There should be an option to disable this. diff --git a/static/openbsd/man3/SMIME_write_PKCS7.3 b/static/openbsd/man3/SMIME_write_PKCS7.3 new file mode 100644 index 00000000..5e344d9c --- /dev/null +++ b/static/openbsd/man3/SMIME_write_PKCS7.3 @@ -0,0 +1,228 @@ +.\" $OpenBSD: SMIME_write_PKCS7.3,v 1.12 2025/06/11 23:16:32 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021, 2025 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2003, 2006, 2007, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 11 2025 $ +.Dt SMIME_WRITE_PKCS7 3 +.Os +.Sh NAME +.Nm SMIME_write_PKCS7 +.Nd convert PKCS#7 structure to S/MIME format +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft int +.Fo SMIME_write_PKCS7 +.Fa "BIO *out" +.Fa "PKCS7 *p7" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn SMIME_write_PKCS7 +generates an S/MIME message on +.Fa out +by writing MIME 1.0 headers +followed by a BER- and base64-encoded serialization of +.Fa p7 . +The BER encoding uses the DER format except as described for +.Dv PKCS7_STREAM +below. +If streaming is enabled, then the content must be supplied in the +.Fa data +argument. +.Pp +The +.Fa flags +can be the logical OR of zero or more of the following bits: +.Bl -tag -width Ds +.It Dv PKCS7_DETACHED +Use cleartext signing and generate a +.Qq multipart/signed +S/MIME message. +The content is read from +.Fa data . +If +.Fa data +is a +.Dv NULL +pointer, this flag is ignored. +.Pp +This flag is only supported for signedData where +.Dv PKCS7_DETACHED +is also set when +.Xr PKCS7_sign 3 +is called. +.Pp +If +.Dv PKCS7_STREAM +is not set, the data must be read twice: once to compute the +signature in +.Xr PKCS7_sign 3 +and once to output the S/MIME message. +.Pp +If +.Dv PKCS7_DETACHED +is ignored or not specified, the smime-type is chosen according to the type of +.Fa p7 : +.Bl -tag -width Ds +.It Dv NID_pkcs7_enveloped +.Qq enveloped-data +.It Dv NID_pkcs7_signed +.Bl -tag -width Msigned-dataM -compact +.It Qq signed-data +if +.Fa p7 +specifies any digest algorithm +.It Qq certs-only +otherwise +.El +.It Dv NID_id_smime_ct_compressedData +.Qq compressed-data +.El +.It Dv PKCS7_REUSE_DIGEST +Skip the calls to +.Xr PKCS7_dataInit 3 +and +.Xr PKCS7_dataFinal 3 . +This flag has no effect unless +.Dv PKCS7_DETACHED +is also set. +.It Dv PKCS7_STREAM +Perform streaming by reading the content from +.Fa data . +This only works if +.Dv PKCS7_DETACHED +is not specified. +.Pp +This flag should only be set if +.Dv PKCS7_STREAM +was also set in the previous call to +.Xr PKCS7_sign 3 +or +.Xr PKCS7_encrypt 3 . +.Pp +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. +.It Dv PKCS7_TEXT +Prepend the line +.Qq Content-Type: text/plain +to the content. +This only makes sense if +.Dv PKCS7_DETACHED +is also set. +It is ignored if the flag +.Dv SMIME_BINARY +is also set. +.It Dv SMIME_BINARY +If specified, this flag is passed through to +.Xr SMIME_crlf_copy 3 . +.It Dv SMIME_CRLFEOL +End MIME header lines with pairs of carriage return and newline characters. +By default, no carriage return characters are written +and header lines are ended with newline characters only. +.It Dv SMIME_OLDMIME +If this bit is set in the +.Fa flags +argument, +.Qq application/pkcs7-mime +or +.Qq application/pkcs7-signature +is used in Content-Type headers. +Otherwise, +.Qq application/x-pkcs7-mime +or +.Qq application/x-pkcs7-signature +is used. +.El +.Sh RETURN VALUES +.Fn SMIME_write_PKCS7 +is intended to return 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr BIO_f_base64 3 , +.Xr BIO_new 3 , +.Xr i2d_PKCS7_bio_stream 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +.Xr PEM_write_PKCS7 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_new 3 , +.Xr SMIME_crlf_copy 3 , +.Xr SMIME_read_PKCS7 3 , +.Xr SMIME_write_CMS 3 +.Sh HISTORY +.Fn SMIME_write_PKCS7 +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Sh BUGS +.Fn SMIME_write_PKCS7 +ignores most errors and is likely to return 1 +even after producing corrupt or incomplete output. +.Pp +.Fn SMIME_write_PKCS7 +always base64 encodes PKCS#7 structures. +There should be an option to disable this. diff --git a/static/openbsd/man3/SSL_CIPHER_get_name.3 b/static/openbsd/man3/SSL_CIPHER_get_name.3 new file mode 100644 index 00000000..fc92eb97 --- /dev/null +++ b/static/openbsd/man3/SSL_CIPHER_get_name.3 @@ -0,0 +1,399 @@ +.\" $OpenBSD: SSL_CIPHER_get_name.3,v 1.19 2025/06/13 18:34:00 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Lutz Jaenicke , +.\" Dr. Stephen Henson , Todd Short , +.\" and Paul Yang . +.\" Copyright (c) 2000, 2005, 2009, 2013, 2014, 2015, 2016, 2017 +.\" The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt SSL_CIPHER_GET_NAME 3 +.Os +.Sh NAME +.Nm SSL_CIPHER_get_name , +.Nm SSL_CIPHER_get_bits , +.Nm SSL_CIPHER_get_version , +.Nm SSL_CIPHER_get_cipher_nid , +.Nm SSL_CIPHER_get_digest_nid , +.Nm SSL_CIPHER_get_handshake_digest , +.Nm SSL_CIPHER_get_kx_nid , +.Nm SSL_CIPHER_get_auth_nid , +.Nm SSL_CIPHER_is_aead , +.Nm SSL_CIPHER_find , +.Nm SSL_CIPHER_get_id , +.Nm SSL_CIPHER_description +.Nd get SSL_CIPHER properties +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft const char * +.Fn SSL_CIPHER_get_name "const SSL_CIPHER *cipher" +.Ft int +.Fn SSL_CIPHER_get_bits "const SSL_CIPHER *cipher" "int *alg_bits" +.Ft const char * +.Fn SSL_CIPHER_get_version "const SSL_CIPHER *cipher" +.Ft int +.Fn SSL_CIPHER_get_cipher_nid "const SSL_CIPHER *cipher" +.Ft int +.Fn SSL_CIPHER_get_digest_nid "const SSL_CIPHER *cipher" +.Ft const EVP_MD * +.Fn SSL_CIPHER_get_handshake_digest "const SSL_CIPHER *cipher" +.Ft int +.Fn SSL_CIPHER_get_kx_nid "const SSL_CIPHER *cipher" +.Ft int +.Fn SSL_CIPHER_get_auth_nid "const SSL_CIPHER *cipher" +.Ft int +.Fn SSL_CIPHER_is_aead "const SSL_CIPHER *cipher" +.Ft const SSL_CIPHER * +.Fn SSL_CIPHER_find "SSL *ssl" "const unsigned char *ptr" +.Ft unsigned long +.Fn SSL_CIPHER_get_id "const SSL_CIPHER *cipher" +.Ft char * +.Fn SSL_CIPHER_description "const SSL_CIPHER *cipher" "char *buf" "int size" +.Sh DESCRIPTION +.Fn SSL_CIPHER_get_name +returns a pointer to the name of +.Fa cipher . +.Pp +.Fn SSL_CIPHER_get_bits +returns the number of secret bits used for +.Fa cipher . +If +.Fa alg_bits +is not +.Dv NULL , +the number of bits processed by the chosen algorithm is stored into it. +.Pp +.Fn SSL_CIPHER_get_version +returns a string which indicates the SSL/TLS protocol version that first +defined the cipher. +This is currently +.Qq TLSv1/SSLv3 . +In some cases it should possibly return +.Qq TLSv1.2 +but the function does not; use +.Fn SSL_CIPHER_description +instead. +.Pp +.Fn SSL_CIPHER_get_cipher_nid +returns the cipher NID corresponding to the +.Fa cipher . +If there is no cipher (e.g. for cipher suites with no encryption), then +.Dv NID_undef +is returned. +.Pp +.Fn SSL_CIPHER_get_digest_nid +returns the digest NID corresponding to the MAC used by the +.Fa cipher +during record encryption/decryption. +If there is no digest (e.g. for AEAD cipher suites), then +.Dv NID_undef +is returned. +.Pp +.Fn SSL_CIPHER_get_handshake_digest +returns the +.Vt EVP_MD +object representing the digest used during a TLS handshake with the cipher +.Fa c , +which may be different to the digest used in the message authentication code +for encrypted records. +.Pp +.Fn SSL_CIPHER_get_kx_nid +returns the key exchange NID corresponding to the method used by the +.Fa cipher . +If there is no key exchange, then +.Dv NID_undef +is returned. +Examples of possible return values include +.Dv NID_kx_rsa , +.Dv NID_kx_dhe , +and +.Dv NID_kx_ecdhe . +.Pp +.Fn SSL_CIPHER_get_auth_nid +returns the authentication NID corresponding to the method used by the +.Fa cipher . +If there is no authentication, +.Dv NID_undef +is returned. +Examples of possible return values include +.Dv NID_auth_rsa +and +.Dv NID_auth_ecdsa . +.Pp +.Fn SSL_CIPHER_is_aead +returns 1 if the +.Fa cipher +is AEAD (e.g. GCM or ChaCha20/Poly1305), or 0 if it is not AEAD. +.Pp +.Fn SSL_CIPHER_find +returns a pointer to a +.Vt SSL_CIPHER +structure which has the cipher ID specified in +.Fa ptr . +The +.Fa ptr +parameter is an array of length two which stores the two-byte +TLS cipher ID (as allocated by IANA) in network byte order. +.Fa SSL_CIPHER_find +returns +.Dv NULL +if an error occurs or the indicated cipher is not found. +.Pp +.Fn SSL_CIPHER_get_id +returns the ID of the given +.Fa cipher , +which must not be +.Dv NULL . +The ID here is an OpenSSL-specific concept, which stores a prefix +of 0x0300 in the higher two bytes and the IANA-specified cipher +suite ID in the lower two bytes. +For instance, TLS_RSA_WITH_NULL_MD5 has IANA ID "0x00, 0x01", so +.Fn SSL_CIPHER_get_id +returns 0x03000001. +.Pp +.Fn SSL_CIPHER_description +copies a textual description of +.Fa cipher +into the buffer +.Fa buf , +which must be at least +.Fa size +bytes long. +The +.Fa cipher +argument must not be a +.Dv NULL +pointer. +If +.Fa buf +is +.Dv NULL , +a buffer is allocated using +.Xr asprintf 3 ; +that buffer should be freed using the +.Xr free 3 +function. +If +.Fa len +is too small to hold the description, a pointer to the static string +.Qq Buffer too small +is returned. +If memory allocation fails, which can happen even if a +.Fa buf +of sufficient size is provided, a pointer to the static string +.Qq OPENSSL_malloc Error +is returned and the content of +.Fa buf +remains unchanged. +.Pp +The string returned by +.Fn SSL_CIPHER_description +consists of several fields separated by whitespace: +.Bl -tag -width Ds +.It Aq Ar ciphername +Textual representation of the cipher name. +.It Aq Ar protocol version +Protocol version: +.Sy SSLv3 , +.Sy TLSv1.2 , +or +.Sy TLSv1.3 . +The TLSv1.0 ciphers are flagged with SSLv3. +No new ciphers were added by TLSv1.1. +.It Kx= Ns Aq Ar key exchange +Key exchange method: +.Sy DH , +.Sy ECDH , +.Sy GOST , +.Sy RSA , +or +.Sy TLSv1.3 . +.It Au= Ns Aq Ar authentication +Authentication method: +.Sy ECDSA , +.Sy GOST01 , +.Sy RSA , +.Sy TLSv1.3 , +or +.Sy None . +.Sy None +is the representation of anonymous ciphers. +.It Enc= Ns Aq Ar symmetric encryption method +Encryption method with number of secret bits: +.Sy 3DES(168) , +.Sy RC4(128) , +.Sy AES(128) , +.Sy AES(256) , +.Sy AESGCM(128) , +.Sy AESGCM(256) , +.Sy Camellia(128) , +.Sy Camellia(256) , +.Sy ChaCha20-Poly1305 , +.Sy GOST-28178-89-CNT , +or +.Sy None . +.It Mac= Ns Aq Ar message authentication code +Message digest: +.Sy MD5 , +.Sy SHA1 , +.Sy SHA256 , +.Sy SHA384 , +.Sy AEAD , +.Sy GOST94 , +.Sy GOST89IMIT , +or +.Sy STREEBOG256 . +.El +.Sh RETURN VALUES +.Fn SSL_CIPHER_get_name +returns an internal pointer to a NUL-terminated string. +.Fn SSL_CIPHER_get_version +returns a pointer to a static NUL-terminated string. +If +.Fa cipher +is a +.Dv NULL +pointer, both functions return a pointer to the static string +.Qq Pq NONE . +.Pp +.Fn SSL_CIPHER_get_bits +returns a positive integer representing the number of secret bits +or 0 if +.Fa cipher +is a +.Dv NULL +pointer. +.Pp +.Fn SSL_CIPHER_get_cipher_nid , +.Fn SSL_CIPHER_get_digest_nid , +.Fn SSL_CIPHER_get_kx_nid , +and +.Fn SSL_CIPHER_get_auth_nid +return an NID constant or +.Dv NID_undef +if an error occurred. +.Fn SSL_CIPHER_get_handshake_digest +returns a valid +.Vt EVP_MD +object or +.Dv NULL +if an error occurred. +.Pp +.Fn SSL_CIPHER_is_aead +returns 1 if the +.Fa cipher +is AEAD or 0 otherwise. +.Pp +.Fn SSL_CIPHER_find +returns a pointer to a valid +.Vt SSL_CIPHER +structure or +.Dv NULL +if an error occurred. +.Pp +.Fn SSL_CIPHER_get_id +returns a 32-bit unsigned integer. +.Pp +.Fn SSL_CIPHER_description +returns +.Fa buf +or a newly allocated string on success or a pointer to a static +string on error. +.Sh EXAMPLES +An example for the output of +.Fn SSL_CIPHER_description : +.Bd -literal +ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD +.Ed +.Pp +A complete list can be retrieved by invoking the following command: +.Pp +.Dl $ openssl ciphers -v ALL:COMPLEMENTOFALL +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_get_ciphers 3 , +.Xr SSL_get_current_cipher 3 +.Sh HISTORY +.Fn SSL_CIPHER_description +first appeared in SSLeay 0.8.0. +.Fn SSL_CIPHER_get_name , +.Fn SSL_CIPHER_get_bits , +and +.Fn SSL_CIPHER_get_version +first appeared in SSLeay 0.8.1. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn SSL_CIPHER_get_id +first appeared in OpenSSL 1.0.1 and has been available since +.Ox 5.3 . +.Pp +.Fn SSL_CIPHER_get_cipher_nid , +.Fn SSL_CIPHER_get_digest_nid , +.Fn SSL_CIPHER_get_kx_nid , +.Fn SSL_CIPHER_get_auth_nid , +and +.Fn SSL_CIPHER_is_aead +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +.Fn SSL_CIPHER_find +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.0 . +.Fn SSL_CIPHER_get_handshake_digest +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 7.6 . +.Sh BUGS +If +.Fn SSL_CIPHER_description +cannot handle a built-in cipher, +the according description of the cipher property is +.Qq unknown . +This case should not occur. diff --git a/static/openbsd/man3/SSL_COMP_add_compression_method.3 b/static/openbsd/man3/SSL_COMP_add_compression_method.3 new file mode 100644 index 00000000..0b990ca8 --- /dev/null +++ b/static/openbsd/man3/SSL_COMP_add_compression_method.3 @@ -0,0 +1,43 @@ +.\" $OpenBSD: SSL_COMP_add_compression_method.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt SSL_COMP_ADD_COMPRESSION_METHOD 3 +.Os +.Sh NAME +.Nm SSL_COMP_get_compression_methods +.Nd handle SSL/TLS integrated compression methods +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft STACK_OF(SSL_COMP) * +.Fn SSL_COMP_get_compression_methods void +.Sh DESCRIPTION +This function is deprecated and has no effect. +It is provided purely for compatibility with legacy application code. +.Pp +.Fn SSL_COMP_get_compression_methods +used to return a stack of available compression methods. +.Sh RETURN VALUES +.Fn SSL_COMP_get_compression_methods +always returns +.Dv NULL . +.Sh SEE ALSO +.Xr ssl 3 +.Sh HISTORY +.Fn SSL_COMP_get_compression_methods +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/SSL_CTX_add1_chain_cert.3 b/static/openbsd/man3/SSL_CTX_add1_chain_cert.3 new file mode 100644 index 00000000..91c4c807 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_add1_chain_cert.3 @@ -0,0 +1,223 @@ +.\" $OpenBSD: SSL_CTX_add1_chain_cert.3,v 1.3 2025/06/08 22:52:00 schwarze Exp $ +.\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson +.\" and Rob Stradling . +.\" Copyright (c) 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_ADD1_CHAIN_CERT 3 +.Os +.Sh NAME +.Nm SSL_CTX_set0_chain , +.Nm SSL_CTX_set1_chain , +.Nm SSL_CTX_add0_chain_cert , +.Nm SSL_CTX_add1_chain_cert , +.Nm SSL_CTX_get0_chain_certs , +.Nm SSL_CTX_clear_chain_certs , +.Nm SSL_set0_chain , +.Nm SSL_set1_chain , +.Nm SSL_add0_chain_cert , +.Nm SSL_add1_chain_cert , +.Nm SSL_get0_chain_certs , +.Nm SSL_clear_chain_certs +.Nd extra chain certificate processing +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_set0_chain +.Fa "SSL_CTX *ctx" +.Fa "STACK_OF(X509) *chain" +.Fc +.Ft int +.Fo SSL_CTX_set1_chain +.Fa "SSL_CTX *ctx" +.Fa "STACK_OF(X509) *chain" +.Fc +.Ft int +.Fo SSL_CTX_add0_chain_cert +.Fa "SSL_CTX *ctx" +.Fa "X509 *cert" +.Fc +.Ft int +.Fo SSL_CTX_add1_chain_cert +.Fa "SSL_CTX *ctx" +.Fa "X509 *cert" +.Fc +.Ft int +.Fo SSL_CTX_get0_chain_certs +.Fa "SSL_CTX *ctx" +.Fa "STACK_OF(X509) **chain" +.Fc +.Ft int +.Fo SSL_CTX_clear_chain_certs +.Fa "SSL_CTX *ctx" +.Fc +.Ft int +.Fo SSL_set0_chain +.Fa "SSL *ssl" +.Fa "STACK_OF(X509) *chain" +.Fc +.Ft int +.Fo SSL_set1_chain +.Fa "SSL *ssl" +.Fa "STACK_OF(X509) *chain" +.Fc +.Ft int +.Fo SSL_add0_chain_cert +.Fa "SSL *ssl" +.Fa "X509 *cert" +.Fc +.Ft int +.Fo SSL_add1_chain_cert +.Fa "SSL *ssl" +.Fa "X509 *cert" +.Fc +.Ft int +.Fo SSL_get0_chain_certs +.Fa "SSL *ssl" +.Fa "STACK_OF(X509) **chain" +.Fc +.Ft int +.Fo SSL_clear_chain_certs +.Fa "SSL *ssl" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set0_chain +and +.Fn SSL_CTX_set1_chain +set the certificate chain associated with the current certificate of +.Fa ctx +to +.Fa chain . +The +.Fa chain +is not supposed to include the current certificate itself. +.Pp +.Fn SSL_CTX_add0_chain_cert +and +.Fn SSL_CTX_add1_chain_cert +append the single certificate +.Fa cert +to the chain associated with the current certificate of +.Fa ctx . +.Pp +.Fn SSL_CTX_get0_chain_certs +retrieves the chain associated with the current certificate of +.Fa ctx . +.Pp +.Fn SSL_CTX_clear_chain_certs +clears the existing chain associated with the current certificate of +.Fa ctx , +if any. +This is equivalent to calling +.Fn SSL_CTX_set0_chain +with +.Fa chain +set to +.Dv NULL . +.Pp +Each of these functions operates on the +.Em current +end entity (i.e. server or client) certificate. +This is the last certificate loaded or selected on the corresponding +.Fa ctx +structure, for example using +.Xr SSL_CTX_use_certificate 3 . +.Pp +.Fn SSL_set0_chain , +.Fn SSL_set1_chain , +.Fn SSL_add0_chain_cert , +.Fn SSL_add1_chain_cert , +.Fn SSL_get0_chain_certs , +and +.Fn SSL_clear_chain_certs +are similar except that they operate on the +.Fa ssl +connection. +.Pp +The functions containing a +.Sy 1 +in their name increment the reference count of the supplied certificate +or chain, so it must be freed at some point after the operation. +Those containing a +.Sy 0 +do not increment reference counts and the supplied certificate or chain +must not be freed after the operation. +.Pp +The chains associated with an +.Vt SSL_CTX +structure are copied to the new +.Vt SSL +structure when +.Xr SSL_new 3 +is called. +Existing +.Vt SSL +structures are not affected by any chains subsequently changed +in the parent +.Vt SSL_CTX . +.Pp +One chain can be set for each key type supported by a server. +So, for example, an RSA and an ECDSA certificate can have +different chains. +.Pp +If any certificates are added using these functions, no certificates +added using +.Xr SSL_CTX_add_extra_chain_cert 3 +will be used. +.Sh RETURN VALUES +These functions return 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_use_certificate 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.2 +and have been available since +.Ox 6.5 . diff --git a/static/openbsd/man3/SSL_CTX_add_extra_chain_cert.3 b/static/openbsd/man3/SSL_CTX_add_extra_chain_cert.3 new file mode 100644 index 00000000..891c22a4 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_add_extra_chain_cert.3 @@ -0,0 +1,161 @@ +.\" $OpenBSD: SSL_CTX_add_extra_chain_cert.3,v 1.9 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke and +.\" Dr. Stephen Henson . +.\" Copyright (c) 2000, 2002, 2013, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_ADD_EXTRA_CHAIN_CERT 3 +.Os +.Sh NAME +.Nm SSL_CTX_add_extra_chain_cert , +.Nm SSL_CTX_get_extra_chain_certs_only , +.Nm SSL_CTX_get_extra_chain_certs , +.Nm SSL_CTX_clear_extra_chain_certs +.Nd add, retrieve, and clear extra chain certificates +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_add_extra_chain_cert "SSL_CTX *ctx" "X509 *x509" +.Ft long +.Fn SSL_CTX_get_extra_chain_certs_only "SSL_CTX *ctx" "STACK_OF(X509) **certs" +.Ft long +.Fn SSL_CTX_get_extra_chain_certs "SSL_CTX *ctx" "STACK_OF(X509) **certs" +.Ft long +.Fn SSL_CTX_clear_extra_chain_certs "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_add_extra_chain_cert +adds the certificate +.Fa x509 +to the extra chain certificates associated with +.Fa ctx . +Several certificates can be added one after another. +.Pp +.Fn SSL_CTX_get_extra_chain_certs_only +retrieves an internal pointer to the stack of extra chain certificates +associated with +.Fa ctx , +or set +.Pf * Fa certs +to +.Dv NULL +if there are none. +.Pp +.Fn SSL_CTX_get_extra_chain_certs +does the same except that it retrieves an internal pointer +to the chain associated with the certificate +if there are no extra chain certificates. +.Pp +.Fn SSL_CTX_clear_extra_chain_certs +clears all extra chain certificates associated with +.Fa ctx . +.Pp +These functions are implemented as macros. +.Pp +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 +.Xr SSL_CTX_load_verify_locations 3 . +.Pp +The x509 certificate provided to +.Fn SSL_CTX_add_extra_chain_cert +will be freed by the library when the +.Vt SSL_CTX +is destroyed. +An application should not free the +.Fa x509 +object, nor the +.Pf * Fa certs +object retrieved by +.Fn SSL_CTX_get_extra_chain_certs . +.Sh RETURN VALUES +These functions return 1 on success or 0 for failure. +Check out the error stack to find out the reason for failure. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_add1_chain_cert 3 , +.Xr SSL_CTX_ctrl 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_client_cert_cb 3 , +.Xr SSL_CTX_use_certificate 3 +.Sh HISTORY +.Fn SSL_CTX_add_extra_chain_cert +first appeared in SSLeay 0.9.1 and has been available since +.Ox 2.6 . +.Pp +.Fn SSL_CTX_get_extra_chain_certs +and +.Fn SSL_CTX_clear_extra_chain_certs +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . +.Pp +.Fn SSL_CTX_get_extra_chain_certs_only +first appeared in OpenSSL 1.0.2 and has been available since +.Ox 6.7 . +.Sh CAVEATS +Certificates added with +.Fn SSL_CTX_add_extra_chain_cert +are ignored when certificates are also available that have been +added using the functions documented in +.Xr SSL_CTX_set1_chain 3 . +.Pp +Only one set of extra chain certificates can be specified per +.Vt SSL_CTX +structure using +.Fn SSL_CTX_add_extra_chain_cert . +Different chains for different certificates (for example if both +RSA and ECDSA certificates are specified by the same server) or +different SSL structures with the same parent +.Vt SSL_CTX +require using the functions documented in +.Xr SSL_CTX_set1_chain 3 +instead. diff --git a/static/openbsd/man3/SSL_CTX_add_session.3 b/static/openbsd/man3/SSL_CTX_add_session.3 new file mode 100644 index 00000000..df634bcd --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_add_session.3 @@ -0,0 +1,133 @@ +.\" $OpenBSD: SSL_CTX_add_session.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL SSL_CTX_add_session.pod 1722496f Jun 8 15:18:38 2017 -0400 +.\" +.\" This file was written by Lutz Jaenicke and +.\" Geoff Thorpe . +.\" Copyright (c) 2001, 2002, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_ADD_SESSION 3 +.Os +.Sh NAME +.Nm SSL_CTX_add_session , +.Nm SSL_CTX_remove_session +.Nd manipulate session cache +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_add_session "SSL_CTX *ctx" "SSL_SESSION *c" +.Ft int +.Fn SSL_CTX_remove_session "SSL_CTX *ctx" "SSL_SESSION *c" +.Sh DESCRIPTION +.Fn SSL_CTX_add_session +adds the session +.Fa c +to the context +.Fa ctx . +The reference count for session +.Fa c +is incremented by 1. +If a session with the same session id already exists, +the old session is removed by calling +.Xr SSL_SESSION_free 3 . +.Pp +.Fn SSL_CTX_remove_session +removes the session +.Fa c +from the context +.Fa ctx +and marks it as non-resumable. +.Xr SSL_SESSION_free 3 +is called once for +.Fa c . +.Pp +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 +.Vt SSL_SESSION +object, the old session is removed and replaced by the new session. +If the session is actually identical (the +.Vt SSL_SESSION +object is identical), +.Fn SSL_CTX_add_session +is a no-op, and the return value is 0. +.Pp +If a server +.Vt SSL_CTX +is configured with the +.Dv 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 +.Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP ) . +So the application can use +.Fn SSL_CTX_add_session +directly to have full control over the sessions that can be resumed if desired. +.Sh RETURN VALUES +The following values are returned by all functions: +.Bl -tag -width Ds +.It 0 +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. +.It 1 +The operation succeeded. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_SESSION_free 3 +.Sh HISTORY +.Fn SSL_CTX_add_session +and +.Fn SSL_CTX_remove_session +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_ctrl.3 b/static/openbsd/man3/SSL_CTX_ctrl.3 new file mode 100644 index 00000000..4d254d8f --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_ctrl.3 @@ -0,0 +1,123 @@ +.\" $OpenBSD: SSL_CTX_ctrl.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_CTRL 3 +.Os +.Sh NAME +.Nm SSL_CTX_ctrl , +.Nm SSL_CTX_callback_ctrl , +.Nm SSL_ctrl , +.Nm SSL_callback_ctrl +.Nd internal handling functions for SSL_CTX and SSL objects +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_ctrl "SSL_CTX *ctx" "int cmd" "long larg" "void *parg" +.Ft long +.Fn SSL_CTX_callback_ctrl "SSL_CTX *" "int cmd" "void (*fp)()" +.Ft long +.Fn SSL_ctrl "SSL *ssl" "int cmd" "long larg" "void *parg" +.Ft long +.Fn SSL_callback_ctrl "SSL *" "int cmd" "void (*fp)()" +.Sh DESCRIPTION +The +.Fn SSL_*_ctrl +family of functions is used to manipulate settings of +the +.Vt SSL_CTX +and +.Vt SSL +objects. +Depending on the command +.Fa cmd +the arguments +.Fa larg , +.Fa parg , +or +.Fa fp +are evaluated. +These functions should never be called directly. +All functionalities needed are made available via other functions or macros. +.Sh RETURN VALUES +The return values of the +.Fn SSL*_ctrl +functions depend on the command supplied via the +.Fn cmd +parameter. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_sess_number 3 , +.Xr SSL_CTX_sess_set_cache_size 3 , +.Xr SSL_CTX_set_max_cert_list 3 , +.Xr SSL_CTX_set_mode 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_CTX_set_tlsext_servername_callback 3 , +.Xr SSL_CTX_set_tlsext_status_cb 3 , +.Xr SSL_CTX_set_tlsext_ticket_key_cb 3 , +.Xr SSL_get_server_tmp_key 3 , +.Xr SSL_num_renegotiations 3 , +.Xr SSL_session_reused 3 , +.Xr SSL_set_max_send_fragment 3 +.Sh HISTORY +.Fn SSL_CTX_ctrl +and +.Fn SSL_ctrl +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn SSL_CTX_callback_ctrl +and +.Fn SSL_callback_ctrl +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/SSL_CTX_flush_sessions.3 b/static/openbsd/man3/SSL_CTX_flush_sessions.3 new file mode 100644 index 00000000..deabf520 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_flush_sessions.3 @@ -0,0 +1,101 @@ +.\" $OpenBSD: SSL_CTX_flush_sessions.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL SSL_CTX_flush_sessions.pod 1722496f Jun 8 15:18:38 2017 -0400 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_FLUSH_SESSIONS 3 +.Os +.Sh NAME +.Nm SSL_CTX_flush_sessions +.Nd remove expired sessions +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_flush_sessions "SSL_CTX *ctx" "long tm" +.Sh DESCRIPTION +.Fn SSL_CTX_flush_sessions +causes a run through the session cache of +.Fa ctx +to remove sessions expired at time +.Fa tm . +.Pp +If enabled, the internal session cache will collect all sessions established +up to the specified maximum number (see +.Xr SSL_CTX_sess_set_cache_size 3 ) . +As sessions will not be reused once 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 +.Xr SSL_CTX_set_session_cache_mode 3 ) +or manually by calling +.Fn SSL_CTX_flush_sessions . +.Pp +The parameter +.Fa tm +specifies the time which should be used for the +expiration test, in most cases the actual time given by +.Fn time 0 +will be used. +.Pp +.Fn SSL_CTX_flush_sessions +will only check sessions stored in the internal cache. +When a session is found and removed, the +.Va remove_session_cb +is however called to synchronize with the external cache (see +.Xr SSL_CTX_sess_set_get_cb 3 ) . +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_sess_set_get_cb 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_CTX_set_timeout 3 +.Sh HISTORY +.Fn SSL_CTX_flush_sessions +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_free.3 b/static/openbsd/man3/SSL_CTX_free.3 new file mode 100644 index 00000000..0afef7cd --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_free.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: SSL_CTX_free.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2003 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_FREE 3 +.Os +.Sh NAME +.Nm SSL_CTX_free +.Nd free an allocated SSL_CTX object +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_free "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_free +decrements the reference count of +.Fa ctx , +and removes the +.Vt SSL_CTX +object pointed to by +.Fa ctx +and frees up the allocated memory if the reference count has reached 0. +If +.Fa ctx +is a +.Dv NULL +pointer, no action occurs. +.Pp +It also calls the +.Xr free 3 Ns ing +procedures for indirectly affected items, if applicable: +the session cache, the list of ciphers, the list of Client CAs, +the certificates and keys. +.Sh WARNINGS +If a session-remove callback is set +.Pq Xr SSL_CTX_sess_set_remove_cb 3 , +this callback will be called for each session being freed from +.Fa ctx Ns 's +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 +.Fn SSL_CTX_sess_set_remove_cb ctx NULL +prior to calling +.Fn SSL_CTX_free . +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_sess_set_get_cb 3 +.Sh HISTORY +.Fn SSL_CTX_free +first appeared in SSLeay 0.5.1 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_get0_certificate.3 b/static/openbsd/man3/SSL_CTX_get0_certificate.3 new file mode 100644 index 00000000..226e6cd8 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_get0_certificate.3 @@ -0,0 +1,53 @@ +.\" $OpenBSD: SSL_CTX_get0_certificate.3,v 1.4 2025/06/08 22:47:20 schwarze Exp $ +.\" +.\" Copyright (c) 2018 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 $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_GET0_CERTIFICATE 3 +.Os +.Sh NAME +.Nm SSL_CTX_get0_certificate +.Nd get the active certificate from an SSL context +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft X509 * +.Fo SSL_CTX_get0_certificate +.Fa "const SSL_CTX *ctx" +.Fc +.Sh DESCRIPTION +The +.Fn SSL_CTX_get0_certificate +function returns an internal pointer +to the ASN.1 certificate currently active in +.Fa ctx +or +.Dv NULL +if none was installed with +.Xr SSL_CTX_use_certificate 3 +or similar functions. +.Pp +The returned pointer must not be freed by the caller. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_use_certificate 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_new 3 +.Sh HISTORY +.Fn SSL_CTX_get0_certificate +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_CTX_get_ex_new_index.3 b/static/openbsd/man3/SSL_CTX_get_ex_new_index.3 new file mode 100644 index 00000000..30a02cc3 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_get_ex_new_index.3 @@ -0,0 +1,125 @@ +.\" $OpenBSD: SSL_CTX_get_ex_new_index.3,v 1.4 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm SSL_CTX_get_ex_new_index , +.Nm SSL_CTX_set_ex_data , +.Nm SSL_CTX_get_ex_data +.Nd internal application specific data functions +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fn SSL_CTX_set_ex_data "SSL_CTX *ctx" "int idx" "void *arg" +.Ft void * +.Fn SSL_CTX_get_ex_data "const SSL_CTX *ctx" "int idx" +.Bd -literal + 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); +.Ed +.Sh 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 +.Fn SSL_CTX_get_ex_new_index +is used to register a new index for application specific data. +.Pp +.Fn SSL_CTX_set_ex_data +is used to store application data at +.Fa arg +for +.Fa idx +into the +.Fa ctx +object. +.Pp +.Fn SSL_CTX_get_ex_data +is used to retrieve the information for +.Fa idx +from +.Fa ctx . +.Pp +A detailed description for the +.Fn *_get_ex_new_index +functionality can be found in +.Xr RSA_get_ex_new_index 3 . +The +.Fn *_get_ex_data +and +.Fn *_set_ex_data +functionality is described in +.Xr CRYPTO_set_ex_data 3 . +.Sh SEE ALSO +.Xr CRYPTO_set_ex_data 3 , +.Xr RSA_get_ex_new_index 3 , +.Xr ssl 3 +.Sh HISTORY +.Fn SSL_CTX_get_ex_new_index , +.Fn SSL_CTX_set_ex_data , +and +.Fn SSL_CTX_get_ex_data +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_get_verify_mode.3 b/static/openbsd/man3/SSL_CTX_get_verify_mode.3 new file mode 100644 index 00000000..88187f7f --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_get_verify_mode.3 @@ -0,0 +1,132 @@ +.\" $OpenBSD: SSL_CTX_get_verify_mode.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_GET_VERIFY_MODE 3 +.Os +.Sh NAME +.Nm SSL_CTX_get_verify_mode , +.Nm SSL_get_verify_mode , +.Nm SSL_CTX_get_verify_depth , +.Nm SSL_get_verify_depth , +.Nm SSL_get_verify_callback , +.Nm SSL_CTX_get_verify_callback +.Nd get currently set verification parameters +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_get_verify_mode "const SSL_CTX *ctx" +.Ft int +.Fn SSL_get_verify_mode "const SSL *ssl" +.Ft int +.Fn SSL_CTX_get_verify_depth "const SSL_CTX *ctx" +.Ft int +.Fn SSL_get_verify_depth "const SSL *ssl" +.Ft int +.Fo "(*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))" +.Fa int "X509_STORE_CTX *" +.Fc +.Ft int +.Fo "(*SSL_get_verify_callback(const SSL *ssl))" +.Fa int "X509_STORE_CTX *" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_get_verify_mode +returns the verification mode currently set in +.Fa ctx . +.Pp +.Fn SSL_get_verify_mode +returns the verification mode currently set in +.Fa ssl . +.Pp +.Fn SSL_CTX_get_verify_depth +returns the verification depth limit currently set +in +.Fa ctx . +If no limit has been explicitly set, +\(mi1 is returned and the default value will be used. +.Pp +.Fn SSL_get_verify_depth +returns the verification depth limit currently set in +.Fa ssl . +If no limit has been explicitly set, +\(mi1 is returned and the default value will be used. +.Pp +.Fn SSL_CTX_get_verify_callback +returns a function pointer to the verification callback currently set in +.Fa ctx . +If no callback was explicitly set, the +.Dv NULL +pointer is returned and the default callback will be used. +.Pp +.Fn SSL_get_verify_callback +returns a function pointer to the verification callback currently set in +.Fa ssl . +If no callback was explicitly set, the +.Dv NULL +pointer is returned and the default callback will be used. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 +.Sh HISTORY +.Fn SSL_CTX_get_verify_mode , +.Fn SSL_get_verify_mode , +.Fn SSL_get_verify_callback , +and +.Fn SSL_CTX_get_verify_callback +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn SSL_CTX_get_verify_depth +and +.Fn SSL_get_verify_depth +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/SSL_CTX_load_verify_locations.3 b/static/openbsd/man3/SSL_CTX_load_verify_locations.3 new file mode 100644 index 00000000..0cc22f43 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_load_verify_locations.3 @@ -0,0 +1,239 @@ +.\" $OpenBSD: SSL_CTX_load_verify_locations.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_LOAD_VERIFY_LOCATIONS 3 +.Os +.Sh NAME +.Nm SSL_CTX_load_verify_locations , +.Nm SSL_CTX_set_default_verify_paths +.Nd set default locations for trusted CA certificates +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_load_verify_locations +.Fa "SSL_CTX *ctx" "const char *CAfile" "const char *CApath" +.Fc +.Ft int +.Fo SSL_CTX_set_default_verify_paths +.Fa "SSL_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_load_verify_locations +specifies the locations for +.Fa ctx , +at which CA certificates for verification purposes are located. +The certificates available via +.Fa CAfile +and +.Fa CApath +are trusted. +.Pp +.Fn SSL_CTX_set_default_verify_paths +specifies that the default locations from which CA certificates are +loaded should be used. +There is one default directory and one default file. +The default CA certificates directory is called +.Pa certs +in the default OpenSSL directory. +The default CA certificates file is called +.Pa cert.pem +in the default OpenSSL directory. +.Pp +If +.Fa CAfile +is not +.Dv NULL , +it points to a file of CA certificates in PEM format. +The file can contain several CA certificates identified by sequences of: +.Bd -literal + -----BEGIN CERTIFICATE----- + ... (CA certificate in base64 encoding) ... + -----END CERTIFICATE----- +.Ed +.Pp +Before, between, and after the certificates arbitrary text is allowed which can +be used, e.g., for descriptions of the certificates. +.Pp +The +.Fa CAfile +is processed on execution of the +.Fn SSL_CTX_load_verify_locations +function. +.Pp +If +.Fa CApath +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., +.Pa 9d66eef0.0 , +.Pa 9d66eef0.1 , +etc.). +The search is performed in the ordering of the extension number, +regardless of other properties of the certificates. +.Pp +The certificates in +.Fa CApath +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, the OpenSSL library will first search the +certificates in +.Fa CAfile , +then those in +.Fa CApath . +Certificate matching is done based on the subject name, the key identifier (if +present), and the serial number as taken from the certificate to be verified. +If these data do not match, the next certificate will be tried. +If a first certificate matching the parameters is found, +the verification process will be performed; +no other certificates for the same parameters will be searched in case of +failure. +.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 +.Fa CAfile +or +.Fa CApath +and must explicitly be set using the +.Xr SSL_CTX_set_client_CA_list 3 +family of functions. +.Pp +When building its own certificate chain, an OpenSSL client/server will try to +fill in missing certificates from +.Fa CAfile Ns / Fa CApath , +if the +certificate chain was not explicitly specified (see +.Xr SSL_CTX_add_extra_chain_cert 3 +and +.Xr SSL_CTX_use_certificate 3 ) . +.Sh RETURN VALUES +For +.Fn SSL_CTX_load_verify_locations , +the following return values can occur: +.Bl -tag -width Ds +.It 0 +The operation failed because +.Fa CAfile +and +.Fa CApath +are +.Dv NULL +or the processing at one of the locations specified failed. +Check the error stack to find out the reason. +.It 1 +The operation succeeded. +.El +.Pp +.Fn SSL_CTX_set_default_verify_paths +returns 1 on success or 0 on failure. +A missing default location is still treated as a success. +.Sh EXAMPLES +Generate a CA certificate file with descriptive text from the CA certificates +.Pa ca1.pem +.Pa ca2.pem +.Pa ca3.pem : +.Bd -literal +#!/bin/sh +rm CAfile.pem +for i in ca1.pem ca2.pem ca3.pem; do + openssl x509 -in $i -text >> CAfile.pem +done +.Ed +.Pp +Prepare the directory /some/where/certs containing several CA certificates +for use as +.Fa CApath : +.Bd -literal +$ cd /some/where/certs +$ rm -f *.[0-9]* *.r[0-9]* +$ for c in *.pem; do +> [ "$c" = "*.pem" ] && continue +> hash=$(openssl x509 -noout -hash -in "$c") +> if egrep -q -- '-BEGIN( X509 | TRUSTED | )CERTIFICATE-' "$c"; then +> suf=0 +> while [ -e $hash.$suf ]; do suf=$(( $suf + 1 )); done +> ln -s "$c" $hash.$suf +> fi +> if egrep -q -- '-BEGIN X509 CRL-' "$c"; then +> suf=0 +> while [ -e $hash.r$suf ]; do suf=$(( $suf + 1 )); done +> ln -s "$c" $hash.r$suf +> fi +> done +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_set_cert_store 3 , +.Xr SSL_CTX_set_client_CA_list 3 , +.Xr SSL_CTX_use_certificate 3 , +.Xr SSL_get_client_CA_list 3 +.Sh HISTORY +.Fn SSL_CTX_load_verify_locations +and +.Fn SSL_CTX_set_default_verify_paths +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Sh CAVEATS +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 +.Dq certificate expired +verification error occurs, no other certificate will be searched. +Make sure to not have expired certificates mixed with valid ones. diff --git a/static/openbsd/man3/SSL_CTX_new.3 b/static/openbsd/man3/SSL_CTX_new.3 new file mode 100644 index 00000000..2afad537 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_new.3 @@ -0,0 +1,346 @@ +.\" $OpenBSD: SSL_CTX_new.3,v 1.18 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 21cd6e00 Oct 21 14:40:15 2015 +0100 +.\" selective merge up to: OpenSSL 8f75443f May 24 14:04:26 2019 +0200 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2005, 2012, 2013, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_NEW 3 +.Os +.Sh NAME +.Nm SSL_CTX_new , +.Nm SSL_CTX_up_ref , +.Nm TLS_method , +.Nm TLS_server_method , +.Nm TLS_client_method , +.Nm SSLv23_method , +.Nm SSLv23_server_method , +.Nm SSLv23_client_method , +.Nm TLSv1_method , +.Nm TLSv1_server_method , +.Nm TLSv1_client_method , +.Nm TLSv1_1_method , +.Nm TLSv1_1_server_method , +.Nm TLSv1_1_client_method , +.Nm TLSv1_2_method , +.Nm TLSv1_2_server_method , +.Nm TLSv1_2_client_method , +.Nm DTLS_method , +.Nm DTLS_server_method , +.Nm DTLS_client_method , +.Nm DTLSv1_method , +.Nm DTLSv1_server_method , +.Nm DTLSv1_client_method , +.Nm DTLSv1_2_method , +.Nm DTLSv1_2_server_method , +.Nm DTLSv1_2_client_method +.Nd create a new SSL_CTX object as a framework for TLS enabled functions +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft SSL_CTX * +.Fn SSL_CTX_new "const SSL_METHOD *method" +.Ft int +.Fn SSL_CTX_up_ref "SSL_CTX *ctx" +.Ft const SSL_METHOD * +.Fn TLS_method void +.Ft const SSL_METHOD * +.Fn TLS_server_method void +.Ft const SSL_METHOD * +.Fn TLS_client_method void +.Ft const SSL_METHOD * +.Fn SSLv23_method void +.Ft const SSL_METHOD * +.Fn SSLv23_server_method void +.Ft const SSL_METHOD * +.Fn SSLv23_client_method void +.Ft const SSL_METHOD * +.Fn TLSv1_method void +.Ft const SSL_METHOD * +.Fn TLSv1_server_method void +.Ft const SSL_METHOD * +.Fn TLSv1_client_method void +.Ft const SSL_METHOD * +.Fn TLSv1_1_method void +.Ft const SSL_METHOD * +.Fn TLSv1_1_server_method void +.Ft const SSL_METHOD * +.Fn TLSv1_1_client_method void +.Ft const SSL_METHOD * +.Fn TLSv1_2_method void +.Ft const SSL_METHOD * +.Fn TLSv1_2_server_method void +.Ft const SSL_METHOD * +.Fn TLSv1_2_client_method void +.Ft const SSL_METHOD * +.Fn DTLS_method void +.Ft const SSL_METHOD * +.Fn DTLS_server_method void +.Ft const SSL_METHOD * +.Fn DTLS_client_method void +.Ft const SSL_METHOD * +.Fn DTLSv1_method void +.Ft const SSL_METHOD * +.Fn DTLSv1_server_method void +.Ft const SSL_METHOD * +.Fn DTLSv1_client_method void +.Ft const SSL_METHOD * +.Fn DTLSv1_2_method void +.Ft const SSL_METHOD * +.Fn DTLSv1_2_server_method void +.Ft const SSL_METHOD * +.Fn DTLSv1_2_client_method void +.Sh DESCRIPTION +.Fn SSL_CTX_new +creates a new +.Vt SSL_CTX +object as a framework to establish TLS or DTLS enabled connections. +It initializes the list of ciphers, the session cache setting, the +callbacks, the keys and certificates, the options, and the security +level to its default values. +.Pp +An +.Vt SSL_CTX +object is reference counted. +Creating a new +.Vt SSL_CTX +object sets its reference count to 1. +Calling +.Fn SSL_CTX_up_ref +on it increments the reference count by 1. +Calling +.Xr SSL_CTX_free 3 +on it decrements the reference count by 1. +When the reference count drops to zero, +any memory or resources allocated to the +.Vt SSL_CTX +object are freed. +.Pp +The +.Vt SSL_CTX +object uses +.Fa method +as its connection method, which can be: +.Bl -tag -width Ds +.It Fn TLS_method +The general-purpose version-flexible TLS method. +The protocol version used will be negotiated to the highest +version mutually supported by the client and the server. +The supported protocols are TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3. +.It Fn DTLS_method +The version-flexible DTLS method. +The currently supported protocols are DTLSv1 and DTLSv1.2. +.El +.Pp +The following +.Fa method +arguments are deprecated: +.Bl -tag -width Ds +.It Xo +.Fn TLS_server_method , +.Fn TLS_client_method , +.Fn SSLv23_method , +.Fn SSLv23_server_method , +.Fn SSLv23_client_method +.Xc +Deprecated aliases for +.Fn TLS_method . +.It Xo +.Fn DTLS_server_method , +.Fn DTLS_client_method +.Xc +Deprecated aliases for +.Fn DTLS_method . +.It Xo +.Fn TLSv1_method , +.Fn TLSv1_server_method , +.Fn TLSv1_client_method +.Xc +A connection established with these methods will only +understand the TLSv1 protocol. +.It Xo +.Fn TLSv1_1_method , +.Fn TLSv1_1_server_method , +.Fn TLSv1_1_client_method +.Xc +A connection established with these methods will only +understand the TLSv1.1 protocol. +.It Xo +.Fn TLSv1_2_method , +.Fn TLSv1_2_server_method , +.Fn TLSv1_2_client_method +.Xc +A connection established with these methods will only +understand the TLSv1.2 protocol. +.It Xo +.Fn DTLSv1_method , +.Fn DTLSv1_server_method , +.Fn DTLSv1_client_method +.Xc +These are the version-specific methods for DTLSv1. +.It Xo +.Fn DTLSv1_2_method , +.Fn DTLSv1_2_server_method , +.Fn DTLSv1_2_client_method +These are the version-specific methods for DTLSv1.2. +.Xc +.El +.Pp +In LibreSSL, the methods containing the substrings +.Dq _server +or +.Dq _client +in their names return the same objects +as the methods without these substrings. +.Pp +The list of protocols available can also be limited using the +.Dv SSL_OP_NO_TLSv1 , +.Dv SSL_OP_NO_TLSv1_1 , +and +.Dv SSL_OP_NO_TLSv1_2 +options of the +.Xr SSL_CTX_set_options 3 +or +.Xr SSL_set_options 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 +all previous protocol versions, the effect is to also disable all +subsequent protocol versions. +.Pp +DTLSv1 and DTLSv1.2 can be disabled with +.Xr SSL_CTX_set_options 3 +or +.Xr SSL_set_options 3 +using the +.Dv SSL_OP_NO_DTLSv1 +and +.Dv SSL_OP_NO_DTLSv1_2 +options, respectively. +.Sh RETURN VALUES +.Fn SSL_CTX_new +returns a pointer to the newly allocated object or +.Dv NULL +on failure. +Check the error stack to find out the reason for failure. +.Pp +.Fn SSL_CTX_up_ref +returns 1 for success or 0 for failure. +.Pp +.Fn TLS_method +and the other +.Fn *_method +functions return pointers to constant static objects. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_CTX_free 3 , +.Xr SSL_CTX_set_min_proto_version 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_CTX_set_security_level 3 , +.Xr SSL_set_connect_state 3 +.Sh HISTORY +.Fn SSL_CTX_new +first appeared in SSLeay 0.5.1. +.Fn SSLv23_method , +.Fn SSLv23_server_method , +and +.Fn SSLv23_client_method +first appeared in SSLeay 0.8.0. +.Fn TLSv1_method , +.Fn TLSv1_server_method , +and +.Fn TLSv1_client_method +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn DTLSv1_method , +.Fn DTLSv1_server_method , +and +.Fn DTLSv1_client_method +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn TLSv1_1_method , +.Fn TLSv1_1_server_method , +.Fn TLSv1_1_client_method , +.Fn TLSv1_2_method , +.Fn TLSv1_2_server_method , +and +.Fn TLSv1_2_client_method +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . +.Pp +.Fn DTLS_method , +.Fn DTLS_server_method , +and +.Fn DTLS_client_method +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 6.5 . +.Pp +.Fn TLS_method , +.Fn TLS_server_method , +and +.Fn TLS_client_method +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 5.8 . +.Pp +.Fn SSL_CTX_up_ref +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . +.Pp +.Fn DTLSv1_2_method , +.Fn DTLSv1_2_server_method , +and +.Fn DTLSv1_2_client_method +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.9 . diff --git a/static/openbsd/man3/SSL_CTX_sess_number.3 b/static/openbsd/man3/SSL_CTX_sess_number.3 new file mode 100644 index 00000000..854f6256 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_sess_number.3 @@ -0,0 +1,169 @@ +.\" $OpenBSD: SSL_CTX_sess_number.3,v 1.10 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL SSL_CTX_sess_number.pod 7bd27895 Mar 29 11:45:29 2017 +1000 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SESS_NUMBER 3 +.Os +.Sh NAME +.Nm SSL_CTX_sess_number , +.Nm SSL_CTX_sess_connect , +.Nm SSL_CTX_sess_connect_good , +.Nm SSL_CTX_sess_connect_renegotiate , +.Nm SSL_CTX_sess_accept , +.Nm SSL_CTX_sess_accept_good , +.Nm SSL_CTX_sess_accept_renegotiate , +.Nm SSL_CTX_sess_hits , +.Nm SSL_CTX_sess_cb_hits , +.Nm SSL_CTX_sess_misses , +.Nm SSL_CTX_sess_timeouts , +.Nm SSL_CTX_sess_cache_full +.Nd obtain session cache statistics +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_sess_number "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_connect "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_connect_good "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_connect_renegotiate "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_accept "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_accept_good "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_accept_renegotiate "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_hits "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_cb_hits "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_misses "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_timeouts "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_cache_full "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_sess_number +returns the current number of sessions in the internal session cache. +.Pp +.Fn SSL_CTX_sess_connect +returns the number of started SSL/TLS handshakes in client mode. +.Pp +.Fn SSL_CTX_sess_connect_good +returns the number of successfully established SSL/TLS sessions in client mode. +.Pp +.Fn SSL_CTX_sess_connect_renegotiate +returns the number of started renegotiations in client mode. +.Pp +.Fn SSL_CTX_sess_accept +returns the number of started SSL/TLS handshakes in server mode. +.Pp +.Fn SSL_CTX_sess_accept_good +returns the number of successfully established SSL/TLS sessions in server mode. +.Pp +.Fn SSL_CTX_sess_accept_renegotiate +returns the number of started renegotiations in server mode. +.Pp +.Fn SSL_CTX_sess_hits +returns the number of successfully reused sessions. +In client mode a session set with +.Xr SSL_set_session 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 +.Fn SSL_CTX_sess_cb_hits +returns the number of successfully retrieved sessions from the external session +cache in server mode. +.Pp +.Fn SSL_CTX_sess_misses +returns the number of sessions proposed by clients that were not found in the +internal session cache in server mode. +.Pp +.Fn SSL_CTX_sess_timeouts +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 +.Fn SSL_CTX_sess_hits +count. +.Pp +.Fn SSL_CTX_sess_cache_full +returns the number of sessions that were removed because the maximum session +cache size was exceeded. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_ctrl 3 , +.Xr SSL_CTX_sess_set_cache_size 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_set_session 3 +.Sh HISTORY +.Fn SSL_CTX_sess_number , +.Fn SSL_CTX_sess_connect , +.Fn SSL_CTX_sess_connect_good , +.Fn SSL_CTX_sess_accept , +.Fn SSL_CTX_sess_accept_good , +.Fn SSL_CTX_sess_hits , +.Fn SSL_CTX_sess_misses , +and +.Fn SSL_CTX_sess_timeouts +first appeared in SSLeay 0.5.2. +.Fn SSL_CTX_sess_cb_hits +first appeared in SSLeay 0.6.0. +.Fn SSL_CTX_sess_connect_renegotiate , +.Fn SSL_CTX_sess_accept_renegotiate , +and +.Fn SSL_CTX_sess_cache_full +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_sess_set_cache_size.3 b/static/openbsd/man3/SSL_CTX_sess_set_cache_size.3 new file mode 100644 index 00000000..e8bfe50a --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_sess_set_cache_size.3 @@ -0,0 +1,110 @@ +.\" $OpenBSD: SSL_CTX_sess_set_cache_size.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2002, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SESS_SET_CACHE_SIZE 3 +.Os +.Sh NAME +.Nm SSL_CTX_sess_set_cache_size , +.Nm SSL_CTX_sess_get_cache_size +.Nd manipulate session cache size +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_sess_set_cache_size "SSL_CTX *ctx" "long t" +.Ft long +.Fn SSL_CTX_sess_get_cache_size "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_sess_set_cache_size +sets the size of the internal session cache of context +.Fa ctx +to +.Fa t . +.Pp +.Fn SSL_CTX_sess_get_cache_size +returns the currently valid session cache size. +.Pp +The internal session cache size is +.Dv SSL_SESSION_CACHE_MAX_SIZE_DEFAULT , +currently 1024\(mu20, so that up to 20000 sessions can be held. +This size can be modified using the +.Fn SSL_CTX_sess_set_cache_size +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 +.Xr SSL_CTX_flush_sessions 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 the next time a session shall be added. +This removal is not synchronized with the expiration of sessions. +.Sh RETURN VALUES +.Fn SSL_CTX_sess_set_cache_size +returns the previously valid size. +.Pp +.Fn SSL_CTX_sess_get_cache_size +returns the currently valid size. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_ctrl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_sess_number 3 , +.Xr SSL_CTX_set_session_cache_mode 3 +.Sh HISTORY +.Fn SSL_CTX_sess_set_cache_size +and +.Fn SSL_CTX_sess_get_cache_size +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_sess_set_get_cb.3 b/static/openbsd/man3/SSL_CTX_sess_set_get_cb.3 new file mode 100644 index 00000000..62a66983 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_sess_set_get_cb.3 @@ -0,0 +1,222 @@ +.\" $OpenBSD: SSL_CTX_sess_set_get_cb.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2002, 2003, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SESS_SET_GET_CB 3 +.Os +.Sh NAME +.Nm SSL_CTX_sess_set_new_cb , +.Nm SSL_CTX_sess_set_remove_cb , +.Nm SSL_CTX_sess_set_get_cb , +.Nm SSL_CTX_sess_get_new_cb , +.Nm SSL_CTX_sess_get_remove_cb , +.Nm SSL_CTX_sess_get_get_cb +.Nd provide callback functions for server side external session caching +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_sess_set_new_cb +.Fa "SSL_CTX *ctx" +.Fa "int (*new_session_cb)(SSL *, SSL_SESSION *)" +.Fc +.Ft void +.Fo SSL_CTX_sess_set_remove_cb +.Fa "SSL_CTX *ctx" +.Fa "void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)" +.Fc +.Ft void +.Fo SSL_CTX_sess_set_get_cb +.Fa "SSL_CTX *ctx" +.Fa "SSL_SESSION (*get_session_cb)(SSL *, const unsigned char *, int, int *)" +.Fc +.Ft int +.Fo "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))" +.Fa "SSL *ssl" +.Fa "SSL_SESSION *sess" +.Fc +.Ft void +.Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))" +.Fa "SSL_CTX *ctx" +.Fa "SSL_SESSION *sess" +.Fc +.Ft SSL_SESSION * +.Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))" +.Fa "SSL *ssl" +.Fa "const unsigned char *data" +.Fa "int len" +.Fa "int *copy" +.Fc +.Ft int +.Fo "(*new_session_cb)" +.Fa "SSL *ssl" +.Fa "SSL_SESSION *sess" +.Fc +.Ft void +.Fo "(*remove_session_cb)" +.Fa "SSL_CTX *ctx" +.Fa "SSL_SESSION *sess" +.Fc +.Ft SSL_SESSION * +.Fo "(*get_session_cb)" +.Fa "SSL *ssl" +.Fa "unsigned char *data" +.Fa "int len" +.Fa "int *copy" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_sess_set_new_cb +sets the callback function which is automatically called whenever a new session +was negotiated. +.Pp +.Fn SSL_CTX_sess_set_remove_cb +sets the callback function which is automatically called whenever a session is +removed by the SSL engine (because it is considered faulty or the session has +become obsolete because of exceeding the timeout value). +.Pp +.Fn SSL_CTX_sess_set_get_cb +sets the callback function which is called whenever a SSL/TLS client proposes +to resume a session but the session cannot be found in the internal session +cache (see +.Xr SSL_CTX_set_session_cache_mode 3 ) . +(SSL/TLS server only.) +.Pp +.Fn SSL_CTX_sess_get_new_cb , +.Fn SSL_CTX_sess_get_remove_cb , +and +.Fn SSL_CTX_sess_get_get_cb +retrieve the function pointers of the provided callback functions. +If a callback function has not been set, the +.Dv NULL +pointer is returned. +.Pp +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 +.Xr d2i_SSL_SESSION 3 +interface. +.Pp +The +.Fn new_session_cb +function is called whenever a new session has been negotiated and session +caching is enabled (see +.Xr SSL_CTX_set_session_cache_mode 3 ) . +The +.Fn new_session_cb +function is passed the +.Fa ssl +connection and the ssl session +.Fa sess . +If the callback returns 0, the session will be immediately removed again. +.Pp +The +.Fn remove_session_cb +function is called whenever the SSL engine removes a session from the +internal cache. +This happens when the session is removed because it is expired or when a +connection was not shut down cleanly. +It also happens for all sessions in the internal session cache when +.Xr SSL_CTX_free 3 +is called. +The +.Fn remove_session_cb +function is passed the +.Fa ctx +and the +.Vt ssl +session +.Fa sess . +It does not provide any feedback. +.Pp +The +.Fn get_session_cb +function is only called on SSL/TLS servers with the session id proposed by the +client. +The +.Fn get_session_cb +function is always called, also when session caching was disabled. +The +.Fn get_session_cb +function is passed the +.Fa ssl +connection, the session id of length +.Fa length +at the memory location +.Fa data . +With the parameter +.Fa copy +the callback can require the SSL engine to increment the reference count of the +.Vt SSL_SESSION +object, +Normally the reference count is not incremented and therefore the session must +not be explicitly freed with +.Xr SSL_SESSION_free 3 . +.Sh SEE ALSO +.Xr d2i_SSL_SESSION 3 , +.Xr ssl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_free 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_SESSION_free 3 +.Sh HISTORY +.Fn SSL_CTX_sess_set_new_cb , +.Fn SSL_CTX_sess_set_get_cb , +.Fn SSL_CTX_sess_get_new_cb , +and +.Fn SSL_CTX_sess_get_get_cb +first appeared in SSLeay 0.6.0. +.Fn SSL_CTX_sess_set_remove_cb +and +.Fn SSL_CTX_sess_get_remove_cb +first appeared in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_sessions.3 b/static/openbsd/man3/SSL_CTX_sessions.3 new file mode 100644 index 00000000..627c694c --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_sessions.3 @@ -0,0 +1,87 @@ +.\" $OpenBSD: SSL_CTX_sessions.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SESSIONS 3 +.Os +.Sh NAME +.Nm SSL_CTX_sessions +.Nd access internal session cache +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft LHASH_OF(SSL_SESSION) * +.Fn SSL_CTX_sessions "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_sessions +returns a pointer to the lhash databases containing the internal session cache +for +.Fa ctx . +.Pp +The sessions in the internal session cache are kept in an +lhash-type database +(see +.Xr lh_new 3 ) . +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 +lhash operations, +so that the database must not be modified directly but by using the +.Xr SSL_CTX_add_session 3 +family of functions. +.Sh SEE ALSO +.Xr lh_new 3 , +.Xr ssl 3 , +.Xr SSL_CTX_add_session 3 , +.Xr SSL_CTX_set_session_cache_mode 3 +.Sh HISTORY +.Fn SSL_CTX_sessions +first appeared in SSLeay 0.5.2 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_set1_groups.3 b/static/openbsd/man3/SSL_CTX_set1_groups.3 new file mode 100644 index 00000000..8cd620d3 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set1_groups.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: SSL_CTX_set1_groups.3,v 1.3 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL SSL_CTX_set1_curves.pod de4d764e Nov 9 14:51:06 2016 +0000 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2013, 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET1_GROUPS 3 +.Os +.Sh NAME +.Nm SSL_CTX_set1_groups , +.Nm SSL_CTX_set1_groups_list , +.Nm SSL_set1_groups , +.Nm SSL_set1_groups_list , +.Nm SSL_CTX_set1_curves , +.Nm SSL_CTX_set1_curves_list , +.Nm SSL_set1_curves , +.Nm SSL_set1_curves_list +.Nd choose supported EC groups +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_set1_groups +.Fa "SSL_CTX *ctx" +.Fa "const int *glist" +.Fa "size_t glistlen" +.Fc +.Ft int +.Fo SSL_CTX_set1_groups_list +.Fa "SSL_CTX *ctx" +.Fa "const char *list" +.Fc +.Ft int +.Fo SSL_set1_groups +.Fa "SSL *ssl" +.Fa "const int *glist" +.Fa "size_t glistlen" +.Fc +.Ft int +.Fo SSL_set1_groups_list +.Fa "SSL *ssl" +.Fa "const char *list" +.Fc +.Ft int +.Fo SSL_CTX_set1_curves +.Fa "SSL_CTX *ctx" +.Fa "const int *clist" +.Fa "size_t clistlen" +.Fc +.Ft int +.Fo SSL_CTX_set1_curves_list +.Fa "SSL_CTX *ctx" +.Fa "const char *list" +.Fc +.Ft int +.Fo SSL_set1_curves +.Fa "SSL *ssl" +.Fa "const int *clist" +.Fa "size_t clistlen" +.Fc +.Ft int +.Fo SSL_set1_curves_list +.Fa "SSL *ssl" +.Fa "const char *list" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set1_groups +sets the supported groups for +.Fa ctx +to the +.Fa glistlen +groups in the array +.Fa glist . +The array consists of group NIDs in preference order. +For a TLS client, the groups are used directly in the supported groups +extension. +For a TLS server, the groups are used to determine the set of shared +groups. +.Pp +.Fn SSL_CTX_set1_groups_list +sets the supported groups for +.Fa ctx +to the +.Fa list +represented as a colon separated list of group NIDs or names, for example +"P-521:P-384:P-256". +.Pp +.Fn SSL_set1_groups +and +.Fn SSL_set1_groups_list +are similar except that they set supported groups for the SSL structure +.Fa ssl +only. +.Pp +The curve functions are deprecated synonyms for the equivalently +named group functions and are identical in every respect except +that they are implemented as macros. +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. +.Pp +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 +All these functions return 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_set_cipher_list 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_new 3 +.Sh HISTORY +The curve functions first appeared in OpenSSL 1.0.2 +and the group functions in OpenSSL 1.1.1. +Both have been available since +.Ox 6.1 . diff --git a/static/openbsd/man3/SSL_CTX_set_alpn_select_cb.3 b/static/openbsd/man3/SSL_CTX_set_alpn_select_cb.3 new file mode 100644 index 00000000..ff694082 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_alpn_select_cb.3 @@ -0,0 +1,306 @@ +.\" $OpenBSD: SSL_CTX_set_alpn_select_cb.3,v 1.12 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 87b81496 Apr 19 12:38:27 2017 -0400 +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Todd Short . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_ALPN_SELECT_CB 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_alpn_protos , +.Nm SSL_set_alpn_protos , +.Nm SSL_CTX_set_alpn_select_cb , +.Nm SSL_select_next_proto , +.Nm SSL_get0_alpn_selected +.Nd handle application layer protocol negotiation (ALPN) +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_set_alpn_protos +.Fa "SSL_CTX *ctx" +.Fa "const unsigned char *protos" +.Fa "unsigned int protos_len" +.Fc +.Ft int +.Fo SSL_set_alpn_protos +.Fa "SSL *ssl" +.Fa "const unsigned char *protos" +.Fa "unsigned int protos_len" +.Fc +.Ft void +.Fo SSL_CTX_set_alpn_select_cb +.Fa "SSL_CTX *ctx" +.Fa "int (*cb)(SSL *ssl, const unsigned char **out,\ + unsigned char *outlen, const unsigned char *in,\ + unsigned int inlen, void *arg)" +.Fa "void *arg" +.Fc +.Ft int +.Fo SSL_select_next_proto +.Fa "unsigned char **out" +.Fa "unsigned char *outlen" +.Fa "const unsigned char *peer_list" +.Fa "unsigned int peer_list_len" +.Fa "const unsigned char *supported_list" +.Fa "unsigned int supported_list_len" +.Fc +.Ft void +.Fo SSL_get0_alpn_selected +.Fa "const SSL *ssl" +.Fa "const unsigned char **data" +.Fa "unsigned int *len" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_alpn_protos +and +.Fn SSL_set_alpn_protos +are used by the client to set the list of protocols available to be +negotiated. +The +.Fa protos +must be in protocol-list format, described below. +The length of +.Fa protos +is specified in +.Fa protos_len . +.Pp +.Fn SSL_CTX_set_alpn_select_cb +sets the application callback +.Fa cb +used by a server to select which protocol to use for the incoming +connection. +When +.Fa cb +is +.Dv NULL , +ALPN is not used. +The +.Fa arg +value is a pointer which is passed to the application callback. +.Pp +.Fa cb +is the application defined callback. +The +.Fa in , +.Fa inlen +parameters are a vector in protocol-list format. +The value of the +.Fa out , +.Fa outlen +vector should be set to the value of a single protocol selected from the +.Fa in , +.Fa inlen +vector. +The +.Fa out +buffer may point directly into +.Fa in , +or to a buffer that outlives the handshake. +The +.Fa arg +parameter is the pointer set via +.Fn SSL_CTX_set_alpn_select_cb . +.Pp +.Fn SSL_select_next_proto +is a helper function used to select protocols. +It is expected that this function is called from the application +callback +.Fa cb . +If +.Fn SSL_select_next_proto +returns +.Dv OPENSSL_NPN_NO_OVERLAP , +.Fa cb +should ignore +.Fa out +and fail by returning +.Dv SSL_TLSEXT_ERR_ALERT_FATAL . +The protocol data in +.Fa peer_list , +.Fa peer_list_len +and +.Fa supported_list , +.Fa supported_list_len +must be two non-empty lists, validly encoded +in the protocol-list format described below. +The first item in the +.Fa peer_list +that matches an item in the +.Fa supported_list +is selected, and returned in +.Fa out , +.Fa outlen . +The +.Fa out +value will point into either +.Fa peer_list +or +.Fa supported_list , +so it must not be modified and +should be copied immediately. +If no match is found, the first item in +.Fa supported_list +is returned in +.Fa out , +.Fa outlen . +.Pp +.Fn SSL_get0_alpn_selected +returns a pointer to the selected protocol in +.Fa data +with length +.Fa len . +It is not NUL-terminated. +.Fa data +is set to +.Dv NULL +and +.Fa len +is set to 0 if no protocol has been selected. +.Fa data +must not be freed. +.Pp +The protocol-lists must be in wire-format, which is defined as a vector +of non-empty, 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. +The length of the vector is not in the vector itself, but in a separate +variable. +.Pp +For example: +.Bd -literal +const unsigned char *vector = "\ex06" "spdy/1" "\ex08" "http/1.1"; +unsigned int length = strlen(vector); +.Ed +.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 +.Fn SSL_CTX_set_alpn_protos +and +.Fn SSL_set_alpn_protos +return 0 on success or non-zero on failure. +WARNING: these functions reverse the return value convention. +.Pp +.Fn SSL_select_next_proto +returns one of the following: +.Bl -tag -width Ds +.It OPENSSL_NPN_NEGOTIATED +A match was found and is returned in +.Fa out , +.Fa outlen . +.It OPENSSL_NPN_NO_OVERLAP +No match was found. +The first item in +.Fa supported_list , +.Fa supported_list_len +is returned in +.Fa out , +.Fa outlen . +.El +.Pp +The ALPN select callback +.Fa cb +must return one of the following: +.Bl -tag -width Ds +.It SSL_TLSEXT_ERR_OK +ALPN protocol selected. +.It SSL_TLSEXT_ERR_ALERT_FATAL +There was no overlap between the client's supplied list and the +server configuration. +.It SSL_TLSEXT_ERR_NOACK +ALPN protocol not selected, e.g., because no ALPN protocols are +configured for this connection. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_tlsext_servername_arg 3 , +.Xr SSL_CTX_set_tlsext_servername_callback 3 +.Sh STANDARDS +.Rs +.%T TLS Application-Layer Protocol Negotiation Extension +.%R RFC 7301 +.Re +.Pp +.Rs +.%T TLS Next Protocol Negotiation Extension +.%U https://datatracker.ietf.org/doc/html/draft-agl-tls-nextprotoneg +.Re +.Sh HISTORY +.Fn SSL_select_next_proto +first appeared in OpenSSL 1.0.1 and has been available since +.Ox 5.3 . +.Pp +.Fn SSL_CTX_set_alpn_protos , +.Fn SSL_set_alpn_protos , +.Fn SSL_CTX_set_alpn_select_cb , +and +.Fn SSL_get0_alpn_selected +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 5.7 . +.Sh CAVEATS +The fallback to the first supported protocol in +.Fn SSL_select_next_proto +comes from the opportunistic fallback mechanism in the NPN extension. +This behavior does not make sense for ALPN, +where missing protocol overlap should result in a handshake failure. +To avoid accidental selection of a protocol that the server does not +support, it is recommended to pass the locally configured protocols +as second pair of protocols in the ALPN callback. +.Sh BUGS +The +.Fa out +argument of +.Fn SSL_select_next_proto +should have been const. diff --git a/static/openbsd/man3/SSL_CTX_set_cert_store.3 b/static/openbsd/man3/SSL_CTX_set_cert_store.3 new file mode 100644 index 00000000..75c145fd --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_cert_store.3 @@ -0,0 +1,147 @@ +.\" $OpenBSD: SSL_CTX_set_cert_store.3,v 1.9 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2002, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_CERT_STORE 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_cert_store , +.Nm SSL_CTX_set1_cert_store , +.Nm SSL_CTX_get_cert_store +.Nd manipulate X509 certificate verification storage +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_set_cert_store "SSL_CTX *ctx" "X509_STORE *store" +.Ft void +.Fn SSL_CTX_set1_cert_store "SSL_CTX *ctx" "X509_STORE *store" +.Ft X509_STORE * +.Fn SSL_CTX_get_cert_store "const SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_cert_store +sets the verification storage of +.Fa ctx +to or replaces it with +.Fa store . +If another +.Vt X509_STORE +object is currently set in +.Fa ctx , +it will be freed. +.Pp +.Fn SSL_CTX_set1_cert_store +sets the verification storage of +.Fa ctx +to or replaces it with +.Fa store . +The +.Fa store Ns 's +reference count is incremented. +.Pp +.Fn SSL_CTX_get_cert_store +returns a pointer to the current certificate verification storage. +.Pp +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 +.Vt X509_STORE . +From the +.Vt X509_STORE +the +.Vt X509_STORE_CTX +used when verifying certificates is created. +.Pp +Typically the trusted certificate store is handled indirectly via using +.Xr SSL_CTX_load_verify_locations 3 . +Using the +.Fn SSL_CTX_set_cert_store +and +.Fn SSL_CTX_get_cert_store +functions it is possible to manipulate the +.Vt X509_STORE +object beyond the +.Xr SSL_CTX_load_verify_locations 3 +call. +.Pp +Currently no detailed documentation on how to use the +.Vt X509_STORE +object is available. +Not all members of the +.Vt X509_STORE +are used when the verification takes place. +So will, for example, the +.Fn verify_callback +be overridden with the +.Fn verify_callback +set via the +.Xr SSL_CTX_set_verify 3 +family of functions. +This document must therefore be updated when documentation about the +.Vt X509_STORE +object and its handling becomes available. +.Sh RETURN VALUES +.Fn SSL_CTX_get_cert_store +returns the current setting. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr X509_STORE_new 3 +.Sh HISTORY +.Fn SSL_CTX_set_cert_store +and +.Fn SSL_CTX_get_cert_store +first appeared in SSLeay 0.8.1 and have been available since +.Ox 2.4 . +.Pp +.Fn SSL_CTX_set1_cert_store +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 7.6 . diff --git a/static/openbsd/man3/SSL_CTX_set_cert_verify_callback.3 b/static/openbsd/man3/SSL_CTX_set_cert_verify_callback.3 new file mode 100644 index 00000000..2e2beac8 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_cert_verify_callback.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: SSL_CTX_set_cert_verify_callback.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2002 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_CERT_VERIFY_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_cert_verify_callback +.Nd set peer certificate verification procedure +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_cert_verify_callback +.Fa "SSL_CTX *ctx" +.Fa "int (*callback)(X509_STORE_CTX *, void *)" +.Fa "void *arg" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_cert_verify_callback +sets the verification callback function for +.Fa ctx . +.Vt SSL +objects that are created from +.Fa ctx +inherit the setting valid at the time when +.Xr SSL_new 3 +is called. +.Pp +Whenever a certificate is verified during a SSL/TLS handshake, +a verification function is called. +If the application does not explicitly specify a verification callback +function, the built-in verification function is used. +If a verification callback +.Fa callback +is specified via +.Fn SSL_CTX_set_cert_verify_callback , +the supplied callback function is called instead. +By setting +.Fa callback +to +.Dv NULL , +the default behaviour is restored. +.Pp +When the verification must be performed, +.Fa callback +will be called with the arguments +.Fn callback "X509_STORE_CTX *x509_store_ctx" "void *arg" . +The argument +.Fa arg +is specified by the application when setting +.Fa callback . +.Pp +.Fa callback +should return 1 to indicate verification success and 0 to indicate verification +failure. +If +.Dv SSL_VERIFY_PEER +is set and +.Fa callback +returns 0, the handshake will fail. +As the verification procedure may allow the connection to continue in case of +failure (by always returning 1) the verification result must be set in any case +using the +.Fa error +member of +.Fa x509_store_ctx +so that the calling application will be informed about the detailed result of +the verification procedure! +.Pp +Within +.Fa x509_store_ctx , +.Fa callback +has access to the +.Fa verify_callback +function set using +.Xr SSL_CTX_set_verify 3 . +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr SSL_get_verify_result 3 +.Sh HISTORY +.Fn SSL_CTX_set_cert_verify_callback +first appeared in SSLeay 0.6.1 and has been available since +.Ox 2.4 . +.Pp +Previous to OpenSSL 0.9.7, the +.Fa arg +argument to +.Fn SSL_CTX_set_cert_verify_callback +was ignored, and +.Fa callback +was called +simply as +.Ft int +.Fn (*callback) "X509_STORE_CTX *" . +To compile software written for previous versions of OpenSSL, +a dummy argument will have to be added to +.Fa callback . +.Sh CAVEATS +Do not mix the verification callback described in this function with the +.Fa verify_callback +function called during the verification process. +The latter is set using the +.Xr SSL_CTX_set_verify 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 +.Fa verify_callback +function. +.Sh BUGS +.Fn SSL_CTX_set_cert_verify_callback +does not provide diagnostic information. diff --git a/static/openbsd/man3/SSL_CTX_set_cipher_list.3 b/static/openbsd/man3/SSL_CTX_set_cipher_list.3 new file mode 100644 index 00000000..6201dc9f --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_cipher_list.3 @@ -0,0 +1,376 @@ +.\" $OpenBSD: SSL_CTX_set_cipher_list.3,v 1.19 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2020 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. +.\" +.\" The original file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_CIPHER_LIST 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_cipher_list , +.Nm SSL_set_cipher_list +.Nd choose list of available SSL_CIPHERs +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_set_cipher_list "SSL_CTX *ctx" "const char *control" +.Ft int +.Fn SSL_set_cipher_list "SSL *ssl" "const char *control" +.Sh DESCRIPTION +.Fn SSL_CTX_set_cipher_list +sets the list of available cipher suites for +.Fa ctx +using the +.Fa control +string. +The list of cipher suites is inherited by all +.Fa ssl +objects created from +.Fa ctx . +.Pp +.Fn SSL_set_cipher_list +sets the list of cipher suites only for +.Fa ssl . +.Pp +The control string consists of one or more control words +separated by colon characters +.Pq Ql \&: . +Space +.Pq Ql \ \& , +semicolon +.Pq Ql \&; , +and comma +.Pq Ql \&, +characters can also be used as separators. +Each control words selects a set of cipher suites +and can take one of the following optional prefix characters: +.Bl -tag -width Ds +.It \&No prefix: +Those of the selected cipher suites that have not been made available +yet are added to the end of the list of available cipher suites, +preserving their order. +.It Prefixed minus sign Pq Ql \- : +Those of the selected cipher suites that have been made available +earlier are moved back from the list of available cipher suites to +the beginning of the list of unavailable cipher suites, +also preserving their order. +.It Prefixed plus sign Pq Ql + : +Those of the selected cipher suites have been made available earlier +are moved to end of the list of available cipher suites, reducing +their priority, but preserving the order among themselves. +.It Prefixed exclamation mark Pq Ql \&! : +The selected cipher suites are permanently deleted, no matter whether +they had earlier been made available or not, and can no longer +be added or re-added by later words. +.El +.Pp +The following special words can only be used without a prefix: +.Bl -tag -width Ds +.It Cm DEFAULT +An alias for +.Sm off +.Cm ALL No :! Cm aNULL No :! Cm eNULL . +.Sm on +It can only be used as the first word. +The +.Cm DEFAULT +cipher list can be displayed with the +.Xr openssl 1 +.Cm ciphers +command. +.It Cm @SECLEVEL=n +Set the security level to n, which should be a number between +zero and five. +See +.Xr SSL_CTX_set_security_level 3 +for details. +.It Cm @STRENGTH +Sort the list by decreasing encryption strength, +preserving the order of cipher suites that have the same strength. +It is usually given as the last word. +.El +.Pp +The following words can be used to select groups of cipher suites, +with or without a prefix character. +If two or more of these words are joined with plus signs +.Pq Ql + +to form a longer word, only the intersection of the specified sets +is selected. +.Bl -tag -width Ds +.It Cm ADH +Cipher suites using ephemeral DH for key exchange +without doing any server authentication. +Equivalent to +.Cm DH Ns + Ns Cm aNULL . +.It Cm AEAD +Cipher suites using Authenticated Encryption with Additional Data. +.It Cm AECDH +Cipher suites using ephemeral ECDH for key exchange +without doing any server authentication. +Equivalent to +.Cm ECDH Ns + Ns Cm aNULL . +.It Cm aECDSA +Cipher suites using ECDSA server authentication. +.It Cm AES +Cipher suites using AES or AESGCM for symmetric encryption. +.It Cm AES128 +Cipher suites using AES(128) or AESGCM(128) for symmetric encryption. +.It Cm AES256 +Cipher suites using AES(256) or AESGCM(256) for symmetric encryption. +.It Cm AESGCM +Cipher suites using AESGCM for symmetric encryption. +.It Cm aGOST +An alias for +.Cm aGOST01 . +.It Cm aGOST01 +Cipher suites using GOST R 34.10-2001 server authentication. +.It Cm ALL +All cipher suites except those selected by +.Cm eNULL . +.It Cm aNULL +Cipher suites that don't do any server authentication. +Not enabled by +.Cm DEFAULT . +Beware of man-in-the-middle attacks. +.It Cm aRSA +Cipher suites using RSA server authentication. +.It Cm CAMELLIA +Cipher suites using Camellia for symmetric encryption. +.It Cm CAMELLIA128 +Cipher suites using Camellia(128) for symmetric encryption. +.It Cm CAMELLIA256 +Cipher suites using Camellia(256) for symmetric encryption. +.It Cm CHACHA20 +Cipher suites using ChaCha20-Poly1305 for symmetric encryption. +.It Cm COMPLEMENTOFALL +Cipher suites that are not included in +.Cm ALL . +Currently an alias for +.Cm eNULL . +.It Cm COMPLEMENTOFDEFAULT +Cipher suites that are included in +.Cm ALL , +but not included in +.Cm DEFAULT . +Currently similar to +.Cm aNULL Ns :! Ns Cm eNULL +except for the order of the cipher suites which are +.Em not +selected. +.It Cm 3DES +Cipher suites using triple DES for symmetric encryption. +.It Cm DH +Cipher suites using ephemeral DH for key exchange. +.It Cm DHE +Cipher suites using ephemeral DH for key exchange, +but excluding those that don't do any server authentication. +Similar to +.Cm DH Ns :! Ns Cm aNULL +except for the order of the cipher suites which are +.Em not +selected. +.It Cm ECDH +Cipher suites using ephemeral ECDH for key exchange. +.It Cm ECDHE +Cipher suites using ephemeral ECDH for key exchange, +but excluding those that don't do any server authentication. +Similar to +.Cm ECDH Ns :! Ns Cm aNULL +except for the order of the cipher suites which are +.Em not +selected. +.It Cm ECDSA +An alias for +.Cm aECDSA . +.It Cm eNULL +Cipher suites that do not use any encryption. +Not enabled by +.Cm DEFAULT , +and not even included in +.Cm ALL . +.It Cm GOST89MAC +Cipher suites using GOST 28147-89 for message authentication +instead of HMAC. +.It Cm GOST94 +Cipher suites using HMAC based on GOST R 34.11-94 +for message authentication. +.It Cm HIGH +Cipher suites of high strength. +.It Cm kGOST +Cipher suites using VKO 34.10 key exchange, specified in RFC 4357. +.It Cm kRSA +Cipher suites using RSA key exchange. +.It Cm LOW +Cipher suites of low strength. +.It Cm MD5 +Cipher suites using MD5 for message authentication. +.It Cm MEDIUM +Cipher suites of medium strength. +.It Cm NULL +An alias for +.Cm eNULL . +.It Cm RC4 +Cipher suites using RC4 for symmetric encryption. +.It Cm RSA +Cipher suites using RSA for both key exchange and server authentication. +Equivalent to +.Cm kRSA Ns + Ns Cm aRSA . +.It Cm SHA +An alias for +.Cm SHA1 . +.It Cm SHA1 +Cipher suites using SHA1 for message authentication. +.It Cm SHA256 +Cipher suites using SHA256 for message authentication. +.It Cm SHA384 +Cipher suites using SHA384 for message authentication. +.It Cm SSLv3 +An alias for +.Cm TLSv1 . +.It Cm STREEBOG256 +Cipher suites using STREEBOG256 for message authentication. +.It Cm TLSv1 +Cipher suites usable with the TLSv1.0, TLSv1.1, and TLSv1.2 protocols. +.It Cm TLSv1.2 +Cipher suites for the TLSv1.2 protocol. +.It Cm TLSv1.3 +Cipher suites for the TLSv1.3 protocol. +If the +.Fa control +string selects at least one cipher suite but neither contains the word +.Cm TLSv1.3 +nor specifically includes nor excludes any TLSv1.3 cipher suites, all the +.Cm TLSv1.3 +cipher suites are made available, too. +.El +.Pp +The full words returned by the +.Xr openssl 1 +.Cm ciphers +command can be used to select individual cipher suites. +.Pp +The following are deprecated aliases: +.Pp +.Bl -column kEECDH ECDHE -compact -offset indent +.It avoid: Ta use: +.It Cm EDH Ta Cm DHE +.It Cm EECDH Ta Cm ECDHE +.It Cm kEDH Ta Cm DH +.It Cm kEECDH Ta Cm ECDH +.El +.Pp +Unknown words are silently ignored, selecting no cipher suites. +Failure is only flagged if the +.Fa control +string contains invalid bytes +or if no matching cipher suites are available at all. +.Pp +On the client side, including a cipher suite into the list of +available cipher suites is sufficient for using it. +On the server side, all cipher suites have additional requirements. +ADH ciphers don't need a certificate, but DH-parameters must have been set. +All other cipher suites need a corresponding certificate and key. +.Pp +A 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 +.Xr SSL_CTX_set_tmp_dh_callback 3 ) . +.Pp +When these conditions are not met +for any cipher suite in the list (for example, 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 +.Dq no shared cipher +.Pq Dv SSL_R_NO_SHARED_CIPHER +error is generated and the handshake will fail. +.Sh RETURN VALUES +.Fn SSL_CTX_set_cipher_list +and +.Fn SSL_set_cipher_list +return 1 if any cipher suite could be selected and 0 on complete failure. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set1_groups 3 , +.Xr SSL_CTX_set_tmp_dh_callback 3 , +.Xr SSL_CTX_use_certificate 3 , +.Xr SSL_get_ciphers 3 +.Sh HISTORY +.Fn SSL_CTX_set_cipher_list +and +.Fn SSL_set_cipher_list +first appeared in SSLeay 0.5.2 and have been available since +.Ox 2.4 . +.Sh CAVEATS +In LibreSSL, +.Fn SSL_CTX_set_cipher_list +and +.Fn SSL_set_cipher_list +can be used to configure the list of available cipher suites for +all versions of the TLS protocol, whereas in OpenSSL, they only +control cipher suites for protocols up to TLSv1.2. +If compatibility with OpenSSL is required, the list of +available TLSv1.3 cipher suites can only be changed with +.Fn SSL_set_ciphersuites . diff --git a/static/openbsd/man3/SSL_CTX_set_client_CA_list.3 b/static/openbsd/man3/SSL_CTX_set_client_CA_list.3 new file mode 100644 index 00000000..520be043 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_client_CA_list.3 @@ -0,0 +1,184 @@ +.\" $OpenBSD: SSL_CTX_set_client_CA_list.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_CLIENT_CA_LIST 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_client_CA_list , +.Nm SSL_set_client_CA_list , +.Nm SSL_CTX_add_client_CA , +.Nm SSL_add_client_CA +.Nd set list of CAs sent to the client when requesting a client certificate +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_set_client_CA_list "SSL_CTX *ctx" "STACK_OF(X509_NAME) *list" +.Ft void +.Fn SSL_set_client_CA_list "SSL *s" "STACK_OF(X509_NAME) *list" +.Ft int +.Fn SSL_CTX_add_client_CA "SSL_CTX *ctx" "X509 *cacert" +.Ft int +.Fn SSL_add_client_CA "SSL *ssl" "X509 *cacert" +.Sh DESCRIPTION +.Fn SSL_CTX_set_client_CA_list +sets the +.Fa list +of CAs sent to the client when requesting a client certificate for +.Fa ctx . +.Pp +.Fn SSL_set_client_CA_list +sets the +.Fa list +of CAs sent to the client when requesting a client certificate for the chosen +.Fa ssl , +overriding the setting valid for +.Fa ssl Ns 's +.Vt SSL_CTX +object. +.Pp +.Fn SSL_CTX_add_client_CA +adds the CA name extracted from +.Fa cacert +to the list of CAs sent to the client when requesting a client certificate for +.Fa ctx . +.Pp +.Fn SSL_add_client_CA +adds the CA name extracted from +.Fa cacert +to the list of CAs sent to the client when requesting a client certificate for +the chosen +.Fa ssl , +overriding the setting valid for +.Fa ssl Ns 's +.Va SSL_CTX +object. +.Pp +When a TLS/SSL server requests a client certificate (see +.Fn SSL_CTX_set_verify ) , +it sends a list of CAs for which it will accept certificates to the client. +.Pp +This list must explicitly be set using +.Fn SSL_CTX_set_client_CA_list +for +.Fa ctx +and +.Fn SSL_set_client_CA_list +for the specific +.Fa ssl . +The list specified overrides the previous setting. +The CAs listed do not become trusted +.Po +.Fa list +only contains the names, not the complete certificates +.Pc ; +use +.Xr SSL_CTX_load_verify_locations 3 +to additionally load them for verification. +.Pp +If the list of acceptable CAs is compiled in a file, the +.Xr SSL_load_client_CA_file 3 +function can be used to help importing the necessary data. +.Pp +.Fn SSL_CTX_add_client_CA +and +.Fn SSL_add_client_CA +can be used to add additional items the list of client CAs. +If no list was specified before using +.Fn SSL_CTX_set_client_CA_list +or +.Fn SSL_set_client_CA_list , +a new client CA list for +.Fa ctx +or +.Fa ssl +(as appropriate) is opened. +.Pp +These functions are only useful for TLS/SSL servers. +.Sh RETURN VALUES +.Fn SSL_CTX_add_client_CA +and +.Fn SSL_add_client_CA +have the following return values: +.Bl -tag -width Ds +.It 0 +A failure while manipulating the +.Dv STACK_OF Ns +.Pq Vt X509_NAME +object occurred or the +.Vt X509_NAME +could not be extracted from +.Fa cacert . +Check the error stack to find out the reason. +.It 1 +The operation succeeded. +.El +.Sh EXAMPLES +Scan all certificates in +.Fa CAfile +and list them as acceptable CAs: +.Bd -literal +SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile)); +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_get_client_CA_list 3 , +.Xr SSL_load_client_CA_file 3 , +.Xr X509_NAME_new 3 +.Sh HISTORY +.Fn SSL_CTX_set_client_CA_list , +.Fn SSL_set_client_CA_list , +.Fn SSL_CTX_add_client_CA , +and +.Fn SSL_add_client_CA +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_set_client_cert_cb.3 b/static/openbsd/man3/SSL_CTX_set_client_cert_cb.3 new file mode 100644 index 00000000..2cf82756 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_client_cert_cb.3 @@ -0,0 +1,192 @@ +.\" $OpenBSD: SSL_CTX_set_client_cert_cb.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2002 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_CLIENT_CERT_CB 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_client_cert_cb , +.Nm SSL_CTX_get_client_cert_cb +.Nd handle client certificate callback function +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_client_cert_cb +.Fa "SSL_CTX *ctx" +.Fa "int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)" +.Fc +.Ft int +.Fo "(*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))" +.Fa "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey" +.Fc +.Ft int +.Fn "(*client_cert_cb)" "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey" +.Sh DESCRIPTION +.Fn SSL_CTX_set_client_cert_cb +sets the +.Fa client_cert_cb() +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 +.Fa client_cert_cb +is +.Dv NULL , +no callback function is used. +.Pp +.Fn SSL_CTX_get_client_cert_cb +returns a pointer to the currently set callback function. +.Pp +.Fn client_cert_cb +is the application-defined callback. +If it wants to set a certificate, +a certificate/private key combination must be set using the +.Fa x509 +and +.Fa pkey +arguments and 1 must be returned. +The certificate will be installed into +.Fa ssl . +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. +.Xr SSL_get_error 3 +will return +.Dv 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 +.Fa client_cert_cb() . +It is the job of the +.Fa client_cert_cb() +to store information +about the state of the last call, if required to continue. +.Pp +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 has been set using the +.Xr SSL_CTX_use_certificate 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 +.Vt 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 +.Vt SSL +object using the +.Fn SSL_use_certificate +and +.Fn SSL_use_private_key +functions. +Thus it will permanently install the certificate and key for this SSL object. +It will not be reset by calling +.Xr SSL_clear 3 . +If the callback returns no certificate, the OpenSSL library will not send a +certificate. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_use_certificate 3 , +.Xr SSL_free 3 , +.Xr SSL_get_client_CA_list 3 +.Sh HISTORY +.Fn SSL_CTX_set_client_cert_cb +and +.Fn SSL_CTX_get_client_cert_cb +first appeared in SSLeay 0.6.6 and have been available since +.Ox 2.4 . +.Sh BUGS +The +.Fa client_cert_cb() +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 be accomplished only by either adding the intermediate CA certificates +into the trusted certificate store for the +.Vt 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 +.Xr SSL_CTX_add_extra_chain_cert 3 +function, which is only available for the +.Vt 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 +.Vt SSL +object has been used in conjunction with the callback function, +the certificate will be set for the +.Vt SSL +object and will not be cleared even when +.Xr SSL_clear 3 +is called. +It is therefore +.Em mandatory +to destroy the +.Vt SSL +object using +.Xr SSL_free 3 +and create a new one to return to the previous state. diff --git a/static/openbsd/man3/SSL_CTX_set_default_passwd_cb.3 b/static/openbsd/man3/SSL_CTX_set_default_passwd_cb.3 new file mode 100644 index 00000000..e3da1bec --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_default_passwd_cb.3 @@ -0,0 +1,217 @@ +.\" $OpenBSD: SSL_CTX_set_default_passwd_cb.3,v 1.10 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 +.\" selective merge up to: OpenSSL 18bad535 Apr 9 15:13:55 2019 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Lutz Jaenicke +.\" and Christian Heimes . +.\" Copyright (c) 2000, 2001, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_DEFAULT_PASSWD_CB 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_default_passwd_cb , +.Nm SSL_CTX_set_default_passwd_cb_userdata , +.Nm SSL_CTX_get_default_passwd_cb , +.Nm SSL_CTX_get_default_passwd_cb_userdata +.Nd set or get passwd callback for encrypted PEM file handling +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_set_default_passwd_cb "SSL_CTX *ctx" "pem_password_cb *cb" +.Ft void +.Fn SSL_CTX_set_default_passwd_cb_userdata "SSL_CTX *ctx" "void *userdata" +.Ft pem_password_cb * +.Fn SSL_CTX_get_default_passwd_cb "SSL_CTX *ctx" +.Ft void * +.Fn SSL_CTX_get_default_passwd_cb_userdata "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_default_passwd_cb +sets the password callback for loading a certificate or private key +from encrypted PEM format. +In particular, the callback is used by +.Xr SSL_CTX_use_certificate_file 3 , +.Xr SSL_use_certificate_file 3 , +.Xr SSL_CTX_use_certificate_chain_file 3 , +.Xr SSL_use_certificate_chain_file 3 , +.Xr SSL_CTX_use_certificate_chain_mem 3 , +.Xr SSL_CTX_use_PrivateKey_file 3 , +.Xr SSL_use_PrivateKey_file 3 , +.Xr SSL_CTX_use_RSAPrivateKey_file 3 , +and +.Xr SSL_use_RSAPrivateKey_file 3 . +.Pp +The function pointer type of the +.Fa cb +argument is documented in the +.Xr pem_password_cb 3 +manual page. +If +.Fn SSL_CTX_set_default_passwd_cb +is not called on +.Fa ctx +or if it is called with a +.Fa cb +argument of +.Dv NULL , +.Xr PEM_def_callback 3 +is used instead. +.Pp +.Fn SSL_CTX_set_default_passwd_cb_userdata +sets a pointer to the +.Fa userdata +which will be provided to the password callback on invocation. +.Pp +Since the +.Fa cb +passed to +.Fn SSL_CTX_set_default_passwd_cb +will only be used for reading and decryption and not for writing and +encryption, the library will only call it with a +.Fa verify +argument of 0. +.Pp +If an application program only needs to read and decrypt +one single private key, it can be practical to have the +callback handle the password dialog interactively. +This happens by default if neither +.Fn SSL_CTX_set_default_passwd_cb +nor +.Fn SSL_CTX_set_default_passwd_cb_userdata +is called. +In that case, the library uses +.Xr PEM_def_callback 3 +with a +.Fa userdata +argument of +.Dv NULL . +.Pp +If several keys have to be handled, it can be practical +to ask for the password once, for example using +.Xr UI_UTIL_read_pw_string 3 , +then keep it in memory and use it several times by passing a pointer to it to +.Fn SSL_CTX_set_default_passwd_cb_userdata . +.Xr PEM_def_callback 3 +is able to handle this case, too, so calling +.Fn SSL_CTX_set_default_passwd_cb +is not needed in this case either. +.Pp +Other items in PEM formatting (certificates) can also be encrypted; it is +however atypical, as certificate information is considered public. +.Sh RETURN VALUES +.Fn SSL_CTX_get_default_passwd_cb +returns a function pointer to the password callback currently set in +.Fa ctx , +or +.Dv NULL +if none is set. +.Pp +.Fn SSL_CTX_get_default_passwd_cb_userdata +returns a pointer to the userdata currently set in +.Fa ctx , +or +.Dv NULL +if none is set. +.Sh EXAMPLES +The following example provides a subset of the functionality of +.Xr PEM_def_callback 3 , +except that +.Xr PEM_def_callback 3 +does not NUL-terminate and copies up to +.Fa size +rather than +.Fa size No \- 1 +bytes. +It interprets +.Fa userdata +as a NUL-terminated string and copies it to the +.Fa password +buffer, truncating the copy if it does not fit. +.Bd -literal +int +trivial_passwd_cb(char *password, int size, int verify, void *userdata) +{ + strlcpy(password, userdata, size); + return strlen(password); +} +.Ed +.Sh SEE ALSO +.Xr pem_password_cb 3 , +.Xr ssl 3 , +.Xr SSL_CTX_use_certificate 3 +.Sh HISTORY +.Fn SSL_CTX_set_default_passwd_cb +first appeared in SSLeay 0.6.2 and has been available since +.Ox 2.4 . +.Pp +.Fn SSL_CTX_set_default_passwd_cb_userdata +first appeared in OpenSSL 0.9.4 and has been available since +.Ox 2.6 . +.Pp +.Fn SSL_CTX_get_default_passwd_cb +and +.Fn SSL_CTX_get_default_passwd_cb_userdata +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_CTX_set_generate_session_id.3 b/static/openbsd/man3/SSL_CTX_set_generate_session_id.3 new file mode 100644 index 00000000..29c102ac --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_generate_session_id.3 @@ -0,0 +1,222 @@ +.\" $OpenBSD: SSL_CTX_set_generate_session_id.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_GENERATE_SESSION_ID 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_generate_session_id , +.Nm SSL_set_generate_session_id , +.Nm SSL_has_matching_session_id , +.Nm GEN_SESSION_CB +.Nd manipulate generation of SSL session IDs (server only) +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft typedef int +.Fo (*GEN_SESSION_CB) +.Fa "const SSL *ssl" +.Fa "unsigned char *id" +.Fa "unsigned int *id_len" +.Fc +.Ft int +.Fn SSL_CTX_set_generate_session_id "SSL_CTX *ctx" "GEN_SESSION_CB cb" +.Ft int +.Fn SSL_set_generate_session_id "SSL *ssl" "GEN_SESSION_CB cb" +.Ft int +.Fo SSL_has_matching_session_id +.Fa "const SSL *ssl" "const unsigned char *id" "unsigned int id_len" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_generate_session_id +sets the callback function for generating new session ids for SSL/TLS sessions +for +.Fa ctx +to be +.Fa cb . +.Pp +.Fn SSL_set_generate_session_id +sets the callback function for generating new session ids for SSL/TLS sessions +for +.Fa ssl +to be +.Fa cb . +.Pp +.Fn SSL_has_matching_session_id +checks, whether a session with id +.Fa id +(of length +.Fa id_len ) +is already contained in the internal session cache +of the parent context of +.Fa ssl . +.Pp +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 +.Fa id +into and a pointer to the maximum allowed length +.Fa id_len . +The buffer at location +.Fa id +is only guaranteed to have the size +.Fa id_len . +The callback is only allowed to generate a shorter id and reduce +.Fa id_len ; +the callback +.Em must never +increase +.Fa id_len +or write to the location +.Fa id +exceeding the given limit. +.Pp +The location +.Fa id +is filled with 0x00 before the callback is called, +so the callback may only fill part of the possible length and leave +.Fa id_len +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 TLSv1). +In order to ensure the uniqueness of the generated session id, +the callback must call +.Fn SSL_has_matching_session_id +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 cannot guarantee uniqueness, +it is recommended to use the maximum +.Fa id_len +and fill in the bytes not used to code special information with random data to +avoid collisions. +.Pp +.Fn SSL_has_matching_session_id +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 +.Fn SSL_has_matching_session_id +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 +.Fn SSL_CTX_set_generate_session_id +and +.Fn SSL_set_generate_session_id +always return 1. +.Pp +.Fn SSL_has_matching_session_id +returns 1 if another session with the same id is already in the cache. +.Sh EXAMPLES +The callback function listed will generate a session id with the server id +given, and will fill the rest with pseudo random bytes: +.Bd -literal +const char session_id_prefix = "www-18"; + +#define MAX_SESSION_ID_ATTEMPTS 10 +static int +generate_session_id(const 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 \(en but there will be + * worse effects anyway, e.g., the server could only + * possibly create one session ID (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; +} +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_get_version 3 +.Sh HISTORY +.Fn SSL_CTX_set_generate_session_id , +.Fn SSL_set_generate_session_id +and +.Fn SSL_has_matching_session_id +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/SSL_CTX_set_info_callback.3 b/static/openbsd/man3/SSL_CTX_set_info_callback.3 new file mode 100644 index 00000000..ec251b5b --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_info_callback.3 @@ -0,0 +1,234 @@ +.\" $OpenBSD: SSL_CTX_set_info_callback.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_INFO_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_info_callback , +.Nm SSL_CTX_get_info_callback , +.Nm SSL_set_info_callback , +.Nm SSL_get_info_callback +.Nd handle information callback for SSL connections +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_info_callback +.Fa "SSL_CTX *ctx" +.Fa "void (*callback)(const SSL *ssl, int where, int ret)" +.Fc +.Ft void +.Fo "(*SSL_CTX_get_info_callback(const SSL_CTX *ctx))" +.Fa "const SSL *ssl" +.Fa "int where" +.Fa "int ret" +.Fc +.Ft void +.Fo SSL_set_info_callback +.Fa "SSL *ssl" +.Fa "void (*callback)(const SSL *ssl, int where, int ret)" +.Fc +.Ft void +.Fo "(*SSL_get_info_callback(const SSL *ssl))" +.Fa "const SSL *ssl" +.Fa "int where" +.Fa "int ret" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_info_callback +sets the +.Fa callback +function that can be used to obtain state information for SSL objects created +from +.Fa ctx +during connection setup and use. +The setting for +.Fa ctx +is overridden from the setting for a specific SSL object, if specified. +When +.Fa callback +is +.Dv NULL , +no callback function is used. +.Pp +.Fn SSL_set_info_callback +sets the +.Fa callback +function that can be used to +obtain state information for +.Fa ssl +during connection setup and use. +When +.Fa callback +is +.Dv NULL , +the callback setting currently valid for +.Fa ctx +is used. +.Pp +.Fn SSL_CTX_get_info_callback +returns a pointer to the currently set information callback function for +.Fa ctx . +.Pp +.Fn SSL_get_info_callback +returns a pointer to the currently set information callback function for +.Fa ssl . +.Pp +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 the state changes, +an alert appears, or an error occurs. +.Pp +The callback function is called as +.Fn callback "SSL *ssl" "int where" "int ret" . +The +.Fa where +argument specifies information about where (in which context) +the callback function was called. +If +.Fa ret +is 0, an error condition occurred. +If an alert is handled, +.Dv SSL_CB_ALERT +is set and +.Fa ret +specifies the alert information. +.Pp +.Fa where +is a bitmask made up of the following bits: +.Bl -tag -width Ds +.It Dv SSL_CB_LOOP +Callback has been called to indicate state change inside a loop. +.It Dv SSL_CB_EXIT +Callback has been called to indicate error exit of a handshake function. +(May be soft error with retry option for non-blocking setups.) +.It Dv SSL_CB_READ +Callback has been called during read operation. +.It Dv SSL_CB_WRITE +Callback has been called during write operation. +.It Dv SSL_CB_ALERT +Callback has been called due to an alert being sent or received. +.It Dv SSL_CB_READ_ALERT +.It Dv SSL_CB_WRITE_ALERT +.It Dv SSL_CB_ACCEPT_LOOP +.It Dv SSL_CB_ACCEPT_EXIT +.It Dv SSL_CB_CONNECT_LOOP +.It Dv SSL_CB_CONNECT_EXIT +.It Dv SSL_CB_HANDSHAKE_START +Callback has been called because a new handshake is started. +.It Dv SSL_CB_HANDSHAKE_DONE +Callback has been called because a handshake is finished. +.El +.Pp +The current state information can be obtained using the +.Xr SSL_state_string 3 +family of functions. +.Pp +The +.Fa ret +information can be evaluated using the +.Xr SSL_alert_type_string 3 +family of functions. +.Sh RETURN VALUES +.Fn SSL_CTX_get_info_callback +and +.Fn SSL_get_info_callback +return a pointer to the current callback or +.Dv NULL +if none is set. +.Sh EXAMPLES +The following example callback function prints state strings, +information about alerts being handled and error messages to the +.Va bio_err +.Vt BIO . +.Bd -literal +void +apps_ssl_info_callback(SSL *s, int where, int ret) +{ + const char *str; + int w; + + 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)); + } + } +} +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_alert_type_string 3 , +.Xr SSL_state_string 3 +.Sh HISTORY +These functions first appeared in SSLeay 0.6.0 +and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_set_keylog_callback.3 b/static/openbsd/man3/SSL_CTX_set_keylog_callback.3 new file mode 100644 index 00000000..0cb36b07 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_keylog_callback.3 @@ -0,0 +1,57 @@ +.\" $OpenBSD: SSL_CTX_set_keylog_callback.3,v 1.4 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL pod checked up to: 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" Copyright (c) 2021 Bob Beck +.\" +.\" 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: June 8 2025 $ +.Dt SSL_CTX_SET_KEYLOG_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_keylog_callback , +.Nm SSL_CTX_get_keylog_callback +.Nd set and get the unused key logging callback +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft typedef void +.Fo (*SSL_CTX_keylog_cb_func) +.Fa "const SSL *ssl" +.Fa "const char *line" +.Fc +.Ft void +.Fn SSL_CTX_set_keylog_callback "SSL_CTX *ctx" "SSL_CTX_keylog_cb_func cb" +.Ft SSL_CTX_keylog_cb_func +.Fn SSL_CTX_get_keylog_callback "const SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_keylog_callback +sets the TLS key logging callback. +This callback is never called in LibreSSL. +.Pp +.Fn SSL_CTX_get_keylog_callback +retrieves the previously set TLS key logging callback. +.Pp +These functions are provided only for compatibility with OpenSSL. +.Sh RETURN VALUES +.Fn SSL_CTX_get_keylog_callback +returns the previously set TLS key logging callback, or +.Dv NULL +if no callback has been set. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_new 3 +.Sh HISTORY +These function first appeared in OpenSSL 1.1.1 +and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/SSL_CTX_set_max_cert_list.3 b/static/openbsd/man3/SSL_CTX_set_max_cert_list.3 new file mode 100644 index 00000000..700f534f --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_max_cert_list.3 @@ -0,0 +1,155 @@ +.\" $OpenBSD: SSL_CTX_set_max_cert_list.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_MAX_CERT_LIST 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_max_cert_list , +.Nm SSL_CTX_get_max_cert_list , +.Nm SSL_set_max_cert_list , +.Nm SSL_get_max_cert_list +.Nd manipulate allowed size for the peer's certificate chain +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_set_max_cert_list "SSL_CTX *ctx" "long size" +.Ft long +.Fn SSL_CTX_get_max_cert_list "SSL_CTX *ctx" +.Ft long +.Fn SSL_set_max_cert_list "SSL *ssl" "long size" +.Ft long +.Fn SSL_get_max_cert_list "SSL *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_max_cert_list +sets the maximum size allowed for the peer's certificate chain for all +.Vt SSL +objects created from +.Fa ctx +to be +.Fa size +bytes. +The +.Vt SSL +objects inherit the setting valid for +.Fa ctx +at the time +.Xr SSL_new 3 +is being called. +.Pp +.Fn SSL_CTX_get_max_cert_list +returns the currently set maximum size for +.Fa ctx . +.Pp +.Fn SSL_set_max_cert_list +sets the maximum size allowed for the peer's certificate chain for +.Fa ssl +to be +.Fa size +bytes. +This setting stays valid until a new value is set. +.Pp +.Fn SSL_get_max_cert_list +returns the currently set maximum size for +.Fa ssl . +.Pp +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 bound 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 16bit DOS platform). +This should be sufficient for usual certificate chains +(OpenSSL's default maximum chain length is 10, see +.Xr SSL_CTX_set_verify 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 for example the work on +.%T "Internet X.509 Public Key Infrastructure Proxy Certificate Profile" +and +.%T "TLS Delegation Protocol" +at +.Lk https://www.ietf.org/ +and +.Lk 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 a +.Dv SSL_R_EXCESSIVE_MESSAGE_SIZE +error. +.Sh RETURN VALUES +.Fn SSL_CTX_set_max_cert_list +and +.Fn SSL_set_max_cert_list +return the previously set value. +.Pp +.Fn SSL_CTX_get_max_cert_list +and +.Fn SSL_get_max_cert_list +return the currently set value. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_ctrl 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr SSL_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/SSL_CTX_set_min_proto_version.3 b/static/openbsd/man3/SSL_CTX_set_min_proto_version.3 new file mode 100644 index 00000000..50a5fc44 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_min_proto_version.3 @@ -0,0 +1,157 @@ +.\" $OpenBSD: SSL_CTX_set_min_proto_version.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 3edabd3c Sep 14 09:28:39 2017 +0200 +.\" +.\" This file was written by Kurt Roeckx and +.\" Christian Heimes . +.\" Copyright (c) 2015, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_MIN_PROTO_VERSION 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_min_proto_version , +.Nm SSL_CTX_set_max_proto_version , +.Nm SSL_CTX_get_min_proto_version , +.Nm SSL_CTX_get_max_proto_version , +.Nm SSL_set_min_proto_version , +.Nm SSL_set_max_proto_version , +.Nm SSL_get_min_proto_version , +.Nm SSL_get_max_proto_version +.Nd get and set minimum and maximum supported protocol version +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_set_min_proto_version +.Fa "SSL_CTX *ctx" +.Fa "uint16_t version" +.Fc +.Ft int +.Fo SSL_CTX_set_max_proto_version +.Fa "SSL_CTX *ctx" +.Fa "uint16_t version" +.Fc +.Ft int +.Fo SSL_CTX_get_min_proto_version +.Fa "SSL_CTX *ctx" +.Fc +.Ft int +.Fo SSL_CTX_get_max_proto_version +.Fa "SSL_CTX *ctx" +.Fc +.Ft int +.Fo SSL_set_min_proto_version +.Fa "SSL *ssl" +.Fa "uint16_t version" +.Fc +.Ft int +.Fo SSL_set_max_proto_version +.Fa "SSL *ssl" +.Fa "uint16_t version" +.Fc +.Ft int +.Fo SSL_get_min_proto_version +.Fa "SSL *ssl" +.Fc +.Ft int +.Fo SSL_get_max_proto_version +.Fa "SSL *ssl" +.Fc +.Sh DESCRIPTION +These functions get or set the minimum and maximum supported protocol +versions for +.Fa ctx +or +.Fa ssl . +This works in combination with the options set via +.Xr SSL_CTX_set_options 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 will enable protocol +versions down to the lowest or up to the highest version supported +by the library, respectively. +.Pp +Currently supported versions are +.Dv TLS1_VERSION , +.Dv TLS1_1_VERSION , +and +.Dv TLS1_2_VERSION +for TLS and +.Dv DTLS1_VERSION +and +.Dv DTLS1_2_VERSION +for DTLS. +.Pp +In other implementations, these functions may be implemented as macros. +.Sh RETURN VALUES +The setter functions return 1 on success or 0 on failure. +.Pp +The getter functions return the configured version or 0 if +.Fa ctx +or +.Fa ssl +has been configured to automatically use the lowest or highest +version supported by the library. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_set_options 3 +.Sh HISTORY +The setter functions first appeared in BoringSSL in December 2014, +with shorter names without the +.Sy proto_ +part. +Two years later, OpenSSL included them in their 1.1.0 release, +gratuitously changing the names; Google shrugged and adopted +the longer names one month later. +They have been available since +.Ox 6.2 . +.Pp +The getter functions first appeared in OpenSSL 1.1.0g +and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_CTX_set_mode.3 b/static/openbsd/man3/SSL_CTX_set_mode.3 new file mode 100644 index 00000000..62a7a6de --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_mode.3 @@ -0,0 +1,205 @@ +.\" $OpenBSD: SSL_CTX_set_mode.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 8671b898 Jun 3 02:48:34 2008 +0000 +.\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Lutz Jaenicke and +.\" Ben Laurie . +.\" Copyright (c) 2001, 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_MODE 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_mode , +.Nm SSL_set_mode , +.Nm SSL_CTX_clear_mode , +.Nm SSL_clear_mode , +.Nm SSL_CTX_get_mode , +.Nm SSL_get_mode +.Nd manipulate SSL engine mode +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_set_mode "SSL_CTX *ctx" "long mode" +.Ft long +.Fn SSL_set_mode "SSL *ssl" "long mode" +.Ft long +.Fn SSL_CTX_clear_mode "SSL_CTX *ctx" "long mode" +.Ft long +.Fn SSL_clear_mode "SSL *ssl" "long mode" +.Ft long +.Fn SSL_CTX_get_mode "SSL_CTX *ctx" +.Ft long +.Fn SSL_get_mode "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_CTX_set_mode +and +.Fn SSL_set_mode +enable the options contained in the bitmask +.Fa mode +for the +.Fa ctx +or +.Fa ssl +object, respectively. +Options that were already enabled before the call are not disabled. +.Pp +.Fn SSL_CTX_clear_mode +and +.Fn SSL_clear_mode +disable the options contained in the bitmask +.Fa mode +for the +.Fa ctx +or +.Fa ssl +object. +.Pp +.Fn SSL_CTX_get_mode +and +.Fn SSL_get_mode +return a bitmask representing the options +that are currently enabled for the +.Fa ctx +or +.Fa ssl +object. +.Pp +The following options are available: +.Bl -tag -width Ds +.It Dv SSL_MODE_ENABLE_PARTIAL_WRITE +Allow +.Fn SSL_write ... n +to return +.Ms r +with +.EQ +0 < r < n +.EN +(i.e., report success when just a single record has been written). +When not set (the default), +.Xr SSL_write 3 +will only report success once the complete chunk was written. +Once +.Xr SSL_write 3 +returns with +.Ms r , +.Ms r +bytes have been successfully written and the next call to +.Xr SSL_write 3 +must only send the +.Ms n \(mi r +bytes left, imitating the behaviour of +.Xr write 2 . +.It Dv SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER +Make it possible to retry +.Xr SSL_write 3 +with changed buffer location (the buffer contents must stay the same). +This is not the default to avoid the misconception that non-blocking +.Xr SSL_write 3 +behaves like non-blocking +.Xr write 2 . +.It Dv SSL_MODE_AUTO_RETRY +Never bother the application with retries if the transport is blocking. +If a renegotiation takes place during normal operation, a +.Xr SSL_read 3 +or +.Xr SSL_write 3 +would return +with \(mi1 and indicate the need to retry with +.Dv SSL_ERROR_WANT_READ . +In a non-blocking environment applications must be prepared to handle +incomplete read/write operations. +In a blocking environment, applications are not always prepared to deal with +read/write operations returning without success report. +The flag +.Dv SSL_MODE_AUTO_RETRY +will cause read/write operations to only return after the handshake and +successful completion. +.It Dv SSL_MODE_RELEASE_BUFFERS +When we no longer need a read buffer or a write buffer for a given +.Vt 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. +.El +.Sh RETURN VALUES +.Fn SSL_CTX_set_mode , +.Fn SSL_set_mode , +.Fn SSL_CTX_clear_mode , +and +.Fn SSL_clear_mode +return the new mode bitmask after adding or clearing +.Fa mode . +.Pp +.Fn SSL_CTX_get_mode +and +.Fn SSL_get_mode +return the current bitmask. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_ctrl 3 , +.Xr SSL_read 3 , +.Xr SSL_write 3 +.Sh HISTORY +.Fn SSL_CTX_set_mode , +.Fn SSL_set_mode , +.Fn SSL_CTX_get_mode , +and +.Fn SSL_get_mode +first appeared in OpenSSL 0.9.4 and have been available since +.Ox 2.6 . +.Pp +.Fn SSL_CTX_clear_mode +and +.Fn SSL_clear_mode +first appeared in OpenSSL 0.9.8m and have been available since +.Ox 4.9 . +.Pp +.Dv SSL_MODE_AUTO_RETRY +was added in OpenSSL 0.9.6. diff --git a/static/openbsd/man3/SSL_CTX_set_msg_callback.3 b/static/openbsd/man3/SSL_CTX_set_msg_callback.3 new file mode 100644 index 00000000..65df0601 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_msg_callback.3 @@ -0,0 +1,184 @@ +.\" $OpenBSD: SSL_CTX_set_msg_callback.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL SSL_CTX_set_msg_callback.pod e9b77246 Jan 20 19:58:49 2017 +0100 +.\" OpenSSL SSL_CTX_set_msg_callback.pod b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Bodo Moeller . +.\" Copyright (c) 2001, 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_MSG_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_msg_callback , +.Nm SSL_CTX_set_msg_callback_arg , +.Nm SSL_set_msg_callback , +.Nm SSL_set_msg_callback_arg +.Nd install callback for observing protocol messages +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_msg_callback +.Fa "SSL_CTX *ctx" +.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)" +.Fc +.Ft void +.Fn SSL_CTX_set_msg_callback_arg "SSL_CTX *ctx" "void *arg" +.Ft void +.Fo SSL_set_msg_callback +.Fa "SSL *ssl" +.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)" +.Fc +.Ft void +.Fn SSL_set_msg_callback_arg "SSL *ssl" "void *arg" +.Sh DESCRIPTION +.Fn SSL_CTX_set_msg_callback +or +.Fn SSL_set_msg_callback +can be used to define a message callback function +.Fa cb +for observing all SSL/TLS protocol messages (such as handshake messages) +that are received or sent. +.Fn SSL_CTX_set_msg_callback_arg +and +.Fn SSL_set_msg_callback_arg +can be used to set argument +.Fa arg +to the callback function, which is available for arbitrary application use. +.Pp +.Fn SSL_CTX_set_msg_callback +and +.Fn SSL_CTX_set_msg_callback_arg +specify default settings that will be copied to new +.Vt SSL +objects by +.Xr SSL_new 3 . +.Fn SSL_set_msg_callback +and +.Fn SSL_set_msg_callback_arg +modify the actual settings of an +.Vt SSL +object. +Using a +.Dv NULL +pointer for +.Fa cb +disables the message callback. +.Pp +When +.Fa cb +is called by the SSL/TLS library for a protocol message, +the function arguments have the following meaning: +.Bl -tag -width Ds +.It Fa write_p +This flag is 0 when a protocol message has been received and 1 when a protocol +message has been sent. +.It Fa version +The protocol version according to which the protocol message is +interpreted by the library, such as +.Dv TLS1_VERSION , +.Dv TLS1_1_VERSION , +.Dv TLS1_2_VERSION , +.Dv DTLS1_VERSION , +or +.Dv DTLS1_2_VERSION . +.It Fa content_type +This is one of the +.Em ContentType +values defined in the protocol specification +.Po +.Dv SSL3_RT_CHANGE_CIPHER_SPEC , +.Dv SSL3_RT_ALERT , +.Dv SSL3_RT_HANDSHAKE , +but never +.Dv SSL3_RT_APPLICATION_DATA +because the callback will only be called for protocol messages. +.Pc +.It Fa buf , Fa len +.Fa buf +points to a buffer containing the protocol message, which consists of +.Fa len +bytes. +The buffer is no longer valid after the callback function has returned. +.It Fa ssl +The +.Vt SSL +object that received or sent the message. +.It Fa arg +The user-defined argument optionally defined by +.Fn SSL_CTX_set_msg_callback_arg +or +.Fn SSL_set_msg_callback_arg . +.El +.Pp +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, +.Fa version +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, +.Fa version +will be +.Dv SSL3_VERSION . +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_new 3 +.Sh HISTORY +.Fn SSL_CTX_set_msg_callback , +.Fn SSL_CTX_set_msg_callback_arg , +.Fn SSL_set_msg_callback +and +.Fn SSL_set_msg_callback_arg +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/SSL_CTX_set_num_tickets.3 b/static/openbsd/man3/SSL_CTX_set_num_tickets.3 new file mode 100644 index 00000000..09338772 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_num_tickets.3 @@ -0,0 +1,64 @@ +.\" $OpenBSD: SSL_CTX_set_num_tickets.3,v 1.3 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL pod checked up to: 5402f96a Sep 11 09:58:52 2021 +0100 +.\" +.\" Copyright (c) 2021 Bob Beck +.\" +.\" 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: June 8 2025 $ +.Dt SSL_CTX_SET_NUM_TICKETS 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_num_tickets , +.Nm SSL_CTX_get_num_tickets , +.Nm SSL_set_num_tickets , +.Nm SSL_get_num_tickets +.Nd set and get the number of TLS 1.3 session tickets to be sent +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_set_num_tickets "SSL_CTX *ctx" "size_t num_tickets" +.Ft size_t +.Fn SSL_CTX_get_num_tickets "const SSL_CTX *ctx" +.Ft int +.Fn SSL_set_num_tickets "SSL *ssl" "size_t num_tickets" +.Ft size_t +.Fn SSL_get_num_tickets "const SSL *ssl" +.Sh DESCRIPTION +These functions set and retrieve +the configured number of session tickets for +.Fa ctx +and +.Fa ssl , +respectively. +.Pp +They are provided only for compatibility with OpenSSL +and have no effect in LibreSSL. +.Sh RETURN VALUES +.Fn SSL_CTX_set_num_tickets +and +.Fn SSL_set_num_tickets +always return 1. +.Pp +.Fn SSL_CTX_get_num_tickets +and +.Fn SSL_get_num_tickets +return the previously set number of tickets, or 0 if it has not been set. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_new 3 +.Sh HISTORY +These function first appeared in OpenSSL 1.1.1 +and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/SSL_CTX_set_options.3 b/static/openbsd/man3/SSL_CTX_set_options.3 new file mode 100644 index 00000000..5e81c978 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_options.3 @@ -0,0 +1,375 @@ +.\" $OpenBSD: SSL_CTX_set_options.3,v 1.17 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 7946ab33 Dec 6 17:56:41 2015 +0100 +.\" selective merge up to: OpenSSL edb79c3a Mar 29 10:07:14 2017 +1000 +.\" +.\" This file was written by Lutz Jaenicke , +.\" Bodo Moeller , and +.\" Dr. Stephen Henson . +.\" Copyright (c) 2001-2003, 2005, 2007, 2009, 2010, 2013-2015 +.\" The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_OPTIONS 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_options , +.Nm SSL_set_options , +.Nm SSL_CTX_clear_options , +.Nm SSL_clear_options , +.Nm SSL_CTX_get_options , +.Nm SSL_get_options , +.Nm SSL_get_secure_renegotiation_support +.Nd manipulate SSL options +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_set_options "SSL_CTX *ctx" "long options" +.Ft long +.Fn SSL_set_options "SSL *ssl" "long options" +.Ft long +.Fn SSL_CTX_clear_options "SSL_CTX *ctx" "long options" +.Ft long +.Fn SSL_clear_options "SSL *ssl" "long options" +.Ft long +.Fn SSL_CTX_get_options "SSL_CTX *ctx" +.Ft long +.Fn SSL_get_options "SSL *ssl" +.Ft long +.Fn SSL_get_secure_renegotiation_support "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_CTX_set_options +adds the options set via bitmask in +.Fa options +to +.Fa ctx . +Options already set before are not cleared! +.Pp +.Fn SSL_set_options +adds the options set via bitmask in +.Fa options +to +.Fa ssl . +Options already set before are not cleared! +.Pp +.Fn SSL_CTX_clear_options +clears the options set via bitmask in +.Fa options +to +.Fa ctx . +.Pp +.Fn SSL_clear_options +clears the options set via bitmask in +.Fa options +to +.Fa ssl . +.Pp +.Fn SSL_CTX_get_options +returns the options set for +.Fa ctx . +.Pp +.Fn SSL_get_options +returns the options set for +.Fa ssl . +.Pp +.Fn SSL_get_secure_renegotiation_support +indicates whether the peer supports secure renegotiation. +.Pp +All these functions are implemented using macros. +.Pp +The behaviour of the SSL library can be changed by setting several options. +The options are coded as bitmasks and can be combined by a bitwise OR +operation (|). +.Pp +.Fn SSL_CTX_set_options +and +.Fn SSL_set_options +affect the (external) protocol behaviour of the SSL library. +The (internal) behaviour of the API can be changed by using the similar +.Xr SSL_CTX_set_mode 3 +and +.Xr SSL_set_mode 3 +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 +.Xr SSL_new 3 , +the current option setting is copied. +Changes to +.Fa ctx +do not affect already created +.Vt SSL +objects. +.Fn SSL_clear +does not affect the settings. +.Pp +The following +.Em bug workaround +options are available: +.Bl -tag -width Ds +.It Dv SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS +Disables a countermeasure against a 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. +.It Dv SSL_OP_ALL +This is currently an alias for +.Dv SSL_OP_LEGACY_SERVER_CONNECT . +.El +.Pp +It is usually safe to use +.Dv SSL_OP_ALL +to enable the bug workaround options if compatibility with somewhat broken +implementations is desired. +.Pp +The following +.Em modifying +options are available: +.Bl -tag -width Ds +.It Dv SSL_OP_CIPHER_SERVER_PREFERENCE +When choosing a cipher, use the server's preferences instead of the client +preferences. +When not set, the server will always follow the client's preferences. +When set, the server will choose following its own preferences. +.It Dv SSL_OP_COOKIE_EXCHANGE +Turn on Cookie Exchange as described in RFC 4347 Section 4.2.1. +Only affects DTLS connections. +.It Dv SSL_OP_LEGACY_SERVER_CONNECT +Allow legacy insecure renegotiation between OpenSSL and unpatched servers +.Em only : +this option is currently set by default. +See the +.Sx SECURE RENEGOTIATION +section for more details. +.It Dv SSL_OP_NO_DTLSv1 +Do not use the DTLSv1 protocol. +Deprecated; use +.Xr SSL_CTX_set_min_proto_version 3 +instead. +.It Dv SSL_OP_NO_DTLSv1_2 +Do not use the DTLSv1.2 protocol. +Deprecated; use +.Xr SSL_CTX_set_min_proto_version 3 +instead. +.It Dv SSL_OP_NO_QUERY_MTU +Do not query the MTU. +Only affects DTLS connections. +.It Dv 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. +.It Dv SSL_OP_NO_TICKET +Normally clients and servers using TLSv1.2 and earlier will, where possible, +transparently make use of +RFC 5077 tickets for stateless session resumption. +.Pp +If this option is set, this functionality is disabled and tickets will not be +used by clients or servers. +.It Dv SSL_OP_NO_TLSv1 +Do not use the TLSv1.0 protocol. +Deprecated; use +.Xr SSL_CTX_set_min_proto_version 3 +instead. +.It Dv SSL_OP_NO_TLSv1_1 +Do not use the TLSv1.1 protocol. +Deprecated; use +.Xr SSL_CTX_set_min_proto_version 3 +instead. +.It Dv SSL_OP_NO_TLSv1_2 +Do not use the TLSv1.2 protocol. +Deprecated; use +.Xr SSL_CTX_set_max_proto_version 3 +instead. +.El +.Pp +The following options used to be supported at some point in the past +and no longer have any effect: +.Dv SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION , +.Dv SSL_OP_EPHEMERAL_RSA , +.Dv SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER , +.Dv SSL_OP_MICROSOFT_SESS_ID_BUG , +.Dv SSL_OP_NETSCAPE_CA_DN_BUG , +.Dv SSL_OP_NETSCAPE_CHALLENGE_BUG , +.Dv SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG , +.Dv SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG , +.Dv SSL_OP_NO_COMPRESSION , +.Dv SSL_OP_NO_SSLv2 , +.Dv SSL_OP_NO_SSLv3 , +.Dv SSL_OP_PKCS1_CHECK_1 , +.Dv SSL_OP_PKCS1_CHECK_2 , +.Dv SSL_OP_SAFARI_ECDHE_ECDSA_BUG , +.Dv SSL_OP_SINGLE_DH_USE , +.Dv SSL_OP_SINGLE_ECDH_USE , +.Dv SSL_OP_SSLEAY_080_CLIENT_DH_BUG , +.Dv SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG , +.Dv SSL_OP_TLS_BLOCK_PADDING_BUG , +.Dv SSL_OP_TLS_D5_BUG , +.Dv SSL_OP_TLS_ROLLBACK_BUG , +.Dv SSL_OP_TLSEXT_PADDING . +.Sh SECURE RENEGOTIATION +OpenSSL 0.9.8m and later always attempts to use secure renegotiation as +described in RFC 5746. +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 +.Dq patched . +A server not supporting secure +renegotiation is referred to as +.Dq unpatched . +.Pp +The following sections describe the operations permitted by OpenSSL's secure +renegotiation implementation. +.Ss Patched client and server +Connections and renegotiation are always permitted by OpenSSL implementations. +.Ss Unpatched client and patched OpenSSL server +The initial connection succeeds but client renegotiation is denied by the +server with a +.Em no_renegotiation +warning alert. +.Pp +If the patched OpenSSL server attempts to renegotiate, a fatal +.Em handshake_failure +alert is sent. +This is because the server code may be unaware of the unpatched nature of the +client. +.Pp +Note that a bug in OpenSSL clients earlier than 0.9.8m (all of which +are unpatched) will result in the connection hanging if it receives a +.Em no_renegotiation +alert. +OpenSSL versions 0.9.8m and later will regard a +.Em no_renegotiation +alert as fatal and respond with a fatal +.Em handshake_failure +alert. +This is because the OpenSSL API currently has no provision to indicate to an +application that a renegotiation attempt was refused. +.Ss Patched OpenSSL client and unpatched server +If the option +.Dv SSL_OP_LEGACY_SERVER_CONNECT +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 +The option +.Dv SSL_OP_LEGACY_SERVER_CONNECT +is currently set by default even though it has security implications: +otherwise it would be impossible to connect to unpatched servers (i.e., all of +them initially) and this is clearly not acceptable. +Renegotiation is permitted because this does not add any additional security +issues: during an attack clients do not see any renegotiations anyway. +.Pp +As more servers become patched, the option +.Dv SSL_OP_LEGACY_SERVER_CONNECT +will +.Em not +be set by default in a future version of OpenSSL. +.Pp +OpenSSL client applications wishing to ensure they can connect to unpatched +servers should always +.Em set +.Dv SSL_OP_LEGACY_SERVER_CONNECT . +.Pp +OpenSSL client applications that want to ensure they can +.Em not +connect to unpatched servers (and thus avoid any security issues) should always +.Em clear +.Dv SSL_OP_LEGACY_SERVER_CONNECT +using +.Fn SSL_CTX_clear_options +or +.Fn SSL_clear_options . +.Sh RETURN VALUES +.Fn SSL_CTX_set_options +and +.Fn SSL_set_options +return the new options bitmask after adding +.Fa options . +.Pp +.Fn SSL_CTX_clear_options +and +.Fn SSL_clear_options +return the new options bitmask after clearing +.Fa options . +.Pp +.Fn SSL_CTX_get_options +and +.Fn SSL_get_options +return the current bitmask. +.Pp +.Fn SSL_get_secure_renegotiation_support +returns 1 is the peer supports secure renegotiation and 0 if it does not. +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_ctrl 3 , +.Xr SSL_CTX_set_min_proto_version 3 , +.Xr SSL_new 3 +.Sh HISTORY +.Fn SSL_CTX_set_options +and +.Fn SSL_set_options +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . +.Pp +.Fn SSL_CTX_get_options +and +.Fn SSL_get_options +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . +.Pp +.Fn SSL_CTX_clear_options , +.Fn SSL_clear_options , +and +.Fn SSL_get_secure_renegotiation_support +first appeared in OpenSSL 0.9.8m and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/SSL_CTX_set_quiet_shutdown.3 b/static/openbsd/man3/SSL_CTX_set_quiet_shutdown.3 new file mode 100644 index 00000000..20b88216 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_quiet_shutdown.3 @@ -0,0 +1,162 @@ +.\" $OpenBSD: SSL_CTX_set_quiet_shutdown.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_QUIET_SHUTDOWN 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_quiet_shutdown , +.Nm SSL_CTX_get_quiet_shutdown , +.Nm SSL_set_quiet_shutdown , +.Nm SSL_get_quiet_shutdown +.Nd manipulate shutdown behaviour +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_set_quiet_shutdown "SSL_CTX *ctx" "int mode" +.Ft int +.Fn SSL_CTX_get_quiet_shutdown "const SSL_CTX *ctx" +.Ft void +.Fn SSL_set_quiet_shutdown "SSL *ssl" "int mode" +.Ft int +.Fn SSL_get_quiet_shutdown "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_CTX_set_quiet_shutdown +sets the +.Dq quiet shutdown +flag for +.Fa ctx +to be +.Fa mode . +.Vt SSL +objects created from +.Fa ctx +inherit the +.Fa mode +valid at the time +.Xr SSL_new 3 +is called. +.Fa mode +may be 0 or 1. +.Pp +.Fn SSL_CTX_get_quiet_shutdown +returns the +.Dq quiet shutdown +setting of +.Fa ctx . +.Pp +.Fn SSL_set_quiet_shutdown +sets the +.Dq quiet shutdown +flag for +.Fa ssl +to be +.Fa mode . +The setting stays valid until +.Fa ssl +is removed with +.Xr SSL_free 3 +or +.Fn SSL_set_quiet_shutdown +is called again. +It is not changed when +.Xr SSL_clear 3 +is called. +.Fa mode +may be 0 or 1. +.Pp +.Fn SSL_get_quiet_shutdown +returns the +.Dq quiet shutdown +setting of +.Fa ssl . +.Pp +Normally when a SSL connection is finished, the parties must send out +.Dq close notify +alert messages using +.Xr SSL_shutdown 3 +for a clean shutdown. +.Pp +When setting the +.Dq quiet shutdown +flag to 1, +.Xr SSL_shutdown 3 +will set the internal flags to +.Dv SSL_SENT_SHUTDOWN Ns | Ns Dv SSL_RECEIVED_SHUTDOWN +.Po +.Xr SSL_shutdown 3 +then behaves like +.Xr SSL_set_shutdown 3 +called with +.Dv SSL_SENT_SHUTDOWN Ns | Ns Dv SSL_RECEIVED_SHUTDOWN +.Pc . +The session is thus considered to be shut down, but no +.Dq 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 +.Fn SSL_CTX_get_quiet_shutdown +and +.Fn SSL_get_quiet_shutdown +return the current setting. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_free 3 , +.Xr SSL_new 3 , +.Xr SSL_set_shutdown 3 , +.Xr SSL_shutdown 3 +.Sh HISTORY +These functions first appeared in SSLeay 0.8.1 +and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_set_read_ahead.3 b/static/openbsd/man3/SSL_CTX_set_read_ahead.3 new file mode 100644 index 00000000..208ecfbf --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_read_ahead.3 @@ -0,0 +1,145 @@ +.\" $OpenBSD: SSL_CTX_set_read_ahead.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_READ_AHEAD 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_read_ahead , +.Nm SSL_CTX_get_read_ahead , +.Nm SSL_set_read_ahead , +.Nm SSL_get_read_ahead , +.Nm SSL_CTX_get_default_read_ahead +.Nd manage whether to read as many input bytes as possible +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_read_ahead +.Fa "SSL_CTX *ctx" +.Fa "int yes" +.Fc +.Ft long +.Fo SSL_CTX_get_read_ahead +.Fa "SSL_CTX *ctx" +.Fc +.Ft void +.Fo SSL_set_read_ahead +.Fa "SSL *s" +.Fa "int yes" +.Fc +.Ft long +.Fo SSL_get_read_ahead +.Fa "const SSL *s" +.Fc +.Ft long +.Fo SSL_CTX_get_default_read_ahead +.Fa "SSL_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_read_ahead +and +.Fn SSL_set_read_ahead +set whether as many input bytes as possible are read for non-blocking +reads. +For example if +.Ar x +bytes are currently required by OpenSSL, but +.Ar y +bytes are available from the underlying BIO (where +.Ar y No > Ar x ) , +then OpenSSL will read all +.Ar y +bytes into its buffer (provided that the buffer is large enough) if +reading ahead is on, or +.Ar x +bytes otherwise. +The parameter +.Fa yes +should be 0 to ensure reading ahead is off, or non zero otherwise. +.Pp +.Fn SSL_CTX_get_read_ahead +and +.Fn SSL_get_read_ahead +indicate whether reading ahead is set or not. +.Pp +.Fn SSL_CTX_get_default_read_ahead +is identical to +.Fn SSL_CTX_get_read_ahead . +.Pp +These functions are implemented as macros. +.Pp +These functions have no effect when used with DTLS. +.Sh RETURN VALUES +.Fn SSL_CTX_get_read_ahead +and +.Fn SSL_get_read_ahead +return 0 if reading ahead is off or non-zero otherwise, +except that the return values are undefined for DTLS. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_pending 3 +.Sh HISTORY +.Fn SSL_set_read_ahead +and +.Fn SSL_get_read_ahead +appeared in SSLeay 0.4 or earlier and have been available since +.Ox 2.4 . +.Pp +.Fn SSL_CTX_set_read_ahead , +.Fn SSL_CTX_get_read_ahead , +and +.Fn SSL_CTX_get_default_read_ahead +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . +.Sh CAVEATS +Switching read ahead on can impact the behaviour of the +.Xr SSL_pending 3 +function. diff --git a/static/openbsd/man3/SSL_CTX_set_security_level.3 b/static/openbsd/man3/SSL_CTX_set_security_level.3 new file mode 100644 index 00000000..2d3afa57 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_security_level.3 @@ -0,0 +1,160 @@ +.\" $OpenBSD: SSL_CTX_set_security_level.3,v 1.3 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2022 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 $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_SECURITY_LEVEL 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_security_level , +.Nm SSL_set_security_level , +.Nm SSL_CTX_get_security_level , +.Nm SSL_get_security_level +.Nd change security level for TLS +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_security_level +.Fa "SSL_CTX *ctx" +.Fa "int level" +.Fc +.Ft void +.Fo SSL_set_security_level +.Fa "SSL *s" +.Fa "int level" +.Fc +.Ft int +.Fo SSL_CTX_get_security_level +.Fa "const SSL_CTX *ctx" +.Fc +.Ft int +.Fo SSL_get_security_level +.Fa "const SSL *s" +.Fc +.Sh DESCRIPTION +A security level is a set of restrictions on algorithms, key lengths, +protocol versions, and other features in TLS connections. +These restrictions apply in addition to those that exist from individually +selecting supported features, for example ciphers, curves, or algorithms. +.Pp +The following table shows properties of the various security levels: +.Bl -column # sec 15360 ECC TLS SHA1 -offset indent +.It # Ta sec Ta \0\0RSA Ta ECC Ta TLS Ta MAC +.It 0 Ta \0\00 Ta \0\0\0\00 Ta \0\00 Ta 1.0 Ta MD5 +.It 1 Ta \080 Ta \01024 Ta 160 Ta 1.0 Ta RC4 +.It 2 Ta 112 Ta \02048 Ta 224 Ta 1.0 Ta +.It 3 Ta 128 Ta \03072 Ta 256 Ta 1.1 Ta SHA1 +.It 4 Ta 192 Ta \07680 Ta 384 Ta 1.2 Ta +.It 5 Ta 256 Ta 15360 Ta 512 Ta 1.2 Ta +.El +.Pp +The meaning of the columns is as follows: +.Pp +.Bl -tag -width features -compact +.It # +The number of the +.Fa level . +.It sec +The minimum security strength measured in bits, which is approximately +the binary logarithm of the number of operations an attacker has +to perform in order to break a cryptographic key. +This minimum strength is enforced for all relevant parameters +including cipher suite encryption algorithms, ECC curves, signature +algorithms, DH parameter sizes, and certificate algorithms and key +sizes. +See SP800-57 below +.Sx SEE ALSO +for details on individual algorithms. +.It RSA +The minimum key length in bits for the RSA and DH algorithms. +.It ECC +The minimum key length in bits for ECC algorithms. +.It TLS +The minimum TLS protocol version. +.It MAC +Cipher suites using the given MACs are allowed on this level +and on lower levels, but not on higher levels. +.El +.Pp +Level 0 is only provided for backward compatibility and permits everything. +.Pp +Level 3 and higher disable support for session tickets +and only accept cipher suites that provide forward secrecy. +.Pp +The functions +.Fn SSL_CTX_set_security_level +and +.Fn SSL_set_security_level +choose the security +.Fa level +for +.Fa ctx +or +.Fa s , +respectively. +If not set, security level 1 is used. +.Pp +.Xr SSL_CTX_new 3 +initializes the security level of the new object to 1. +.Pp +.Xr SSL_new 3 +and +.Xr SSL_set_SSL_CTX 3 +copy the security level from the context to the SSL object. +.Pp +.Xr SSL_dup 3 +copies the security level from the old to the new object. +.Sh RETURN VALUES +.Fn SSL_CTX_get_security_level +and +.Fn SSL_get_security_level +return the security level configured in +.Fa ctx +or +.Fa s , +respectively. +.Sh SEE ALSO +.Xr EVP_PKEY_security_bits 3 , +.Xr RSA_security_bits 3 , +.Xr ssl 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_new 3 +.Rs +.%A Elaine Barker +.%T Recommendation for Key Management +.%I U.S. National Institute of Standards and Technology +.%R NIST Special Publication 800-57 Part 1 Revision 5 +.%U https://doi.org/10.6028/NIST.SP.800-57pt1r5 +.%C Gaithersburg, MD +.%D May 2020 +.Re +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 7.2 . +.Sh CAVEATS +Applications which do not check the return values +of configuration functions will misbehave. +For example, if an application does not check the return value +after trying to set a certificate and the certificate is rejected +because of the security level, the application may behave as if +no certificate had been provided at all. +.Pp +While some restrictions may be handled gracefully by negotiations +between the client and the server, other restrictions may be +fatal and abort the TLS handshake. +For example, this can happen if the peer certificate contains a key +that is too short or if the DH parameter size is too small. diff --git a/static/openbsd/man3/SSL_CTX_set_session_cache_mode.3 b/static/openbsd/man3/SSL_CTX_set_session_cache_mode.3 new file mode 100644 index 00000000..d19ff795 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_session_cache_mode.3 @@ -0,0 +1,199 @@ +.\" $OpenBSD: SSL_CTX_set_session_cache_mode.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 67adf0a7 Dec 25 19:58:38 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke and +.\" Geoff Thorpe . +.\" Copyright (c) 2001, 2002 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_SESSION_CACHE_MODE 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_session_cache_mode , +.Nm SSL_CTX_get_session_cache_mode +.Nd enable/disable session caching +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_set_session_cache_mode "SSL_CTX ctx" "long mode" +.Ft long +.Fn SSL_CTX_get_session_cache_mode "SSL_CTX ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_session_cache_mode +enables/disables session caching by setting the operational mode for +.Ar ctx +to +.Ar mode . +.Pp +.Fn SSL_CTX_get_session_cache_mode +returns the currently used cache mode. +.Pp +The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. +The sessions can be held in memory for each +.Fa ctx , +if more than one +.Vt SSL_CTX +object is being maintained, the sessions are unique for each +.Vt SSL_CTX +object. +.Pp +In order to reuse a session, a client must send the session's 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 +.Pq Dv 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 +.Xr SSL_CTX_set_session_id_context 3 ) . +.Pp +The following session cache modes and modifiers are available: +.Bl -tag -width Ds +.It Dv SSL_SESS_CACHE_OFF +No session caching for client or server takes place. +.It Dv 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 +.Xr SSL_set_session 3 +function. +This option is not activated by default. +.It Dv 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 +.Dv 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. +.It Dv SSL_SESS_CACHE_BOTH +Enable both +.Dv SSL_SESS_CACHE_CLIENT +and +.Dv SSL_SESS_CACHE_SERVER +at the same time. +.It Dv SSL_SESS_CACHE_NO_AUTO_CLEAR +Normally the session cache is checked for expired sessions every 255 +connections using the +.Xr SSL_CTX_flush_sessions 3 +function. +Since this may lead to a delay which cannot be controlled, +the automatic flushing may be disabled and +.Xr SSL_CTX_flush_sessions 3 +can be called explicitly by the application. +.It Dv 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. +.It Dv SSL_SESS_CACHE_NO_INTERNAL_STORE +Depending on the presence of +.Dv SSL_SESS_CACHE_CLIENT +and/or +.Dv 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 +.Vt SSL_CTX . +This flag will prevent sessions being stored in the internal cache +(though the application can add them manually using +.Xr SSL_CTX_add_session 3 ) . +Note: +in any SSL/TLS servers where external caching is configured, any successful +session lookups in the external cache (e.g., for session-resume requests) would +normally be copied into the local cache before processing continues \(en this +flag prevents these additions to the internal cache as well. +.It Dv SSL_SESS_CACHE_NO_INTERNAL +Enable both +.Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP +and +.Dv SSL_SESS_CACHE_NO_INTERNAL_STORE +at the same time. +.El +.Pp +The default mode is +.Dv SSL_SESS_CACHE_SERVER . +.Sh RETURN VALUES +.Fn SSL_CTX_set_session_cache_mode +returns the previously set cache mode. +.Pp +.Fn SSL_CTX_get_session_cache_mode +returns the currently set cache mode. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_add_session 3 , +.Xr SSL_CTX_ctrl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_sess_number 3 , +.Xr SSL_CTX_sess_set_cache_size 3 , +.Xr SSL_CTX_sess_set_get_cb 3 , +.Xr SSL_CTX_set_session_id_context 3 , +.Xr SSL_CTX_set_timeout 3 , +.Xr SSL_session_reused 3 , +.Xr SSL_set_session 3 +.Sh HISTORY +.Fn SSL_CTX_set_session_cache_mode +and +.Fn SSL_CTX_get_session_cache_mode +first appeared in SSLeay 0.6.1 and have been available since +.Ox 2.4 . +.Pp +.Dv SSL_SESS_CACHE_NO_INTERNAL_STORE +and +.Dv SSL_SESS_CACHE_NO_INTERNAL +were introduced in OpenSSL 0.9.6h. diff --git a/static/openbsd/man3/SSL_CTX_set_session_id_context.3 b/static/openbsd/man3/SSL_CTX_set_session_id_context.3 new file mode 100644 index 00000000..53923888 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_session_id_context.3 @@ -0,0 +1,161 @@ +.\" $OpenBSD: SSL_CTX_set_session_id_context.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2004 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_SESSION_ID_CONTEXT 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_session_id_context , +.Nm SSL_set_session_id_context +.Nd set context within which session can be reused (server side only) +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_set_session_id_context +.Fa "SSL_CTX *ctx" +.Fa "const unsigned char *sid_ctx" +.Fa "unsigned int sid_ctx_len" +.Fc +.Ft int +.Fo SSL_set_session_id_context +.Fa "SSL *ssl" +.Fa "const unsigned char *sid_ctx" +.Fa "unsigned int sid_ctx_len" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_session_id_context +sets the context +.Fa sid_ctx +of length +.Fa sid_ctx_len +within which a session can be reused for the +.Fa ctx +object. +.Pp +.Fn SSL_set_session_id_context +sets the context +.Fa sid_ctx +of length +.Fa sid_ctx_len +within which a session can be reused for the +.Fa ssl +object. +.Pp +Sessions are generated within a certain context. +When exporting/importing sessions with +.Xr i2d_SSL_SESSION 3 +and +.Xr d2i_SSL_SESSION 3 , +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 +.Fa sid_ctx +which is used to distinguish the contexts and is stored in exported sessions. +The +.Fa sid_ctx +can be any kind of binary data with a given length; it is therefore possible +to use, for instance, the name of the application, the hostname, the service +name... +.Pp +The session id context becomes part of the session. +The session id context is set by the SSL/TLS server. +The +.Fn SSL_CTX_set_session_id_context +and +.Fn SSL_set_session_id_context +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 +.Fa sid_ctx +is limited to +.Dv SSL_MAX_SSL_SESSION_ID_LENGTH . +.Sh 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 +.Fn SSL_CTX_set_session_id_context +and +.Fn SSL_set_session_id_context +return the following values: +.Bl -tag -width Ds +.It 0 +The length +.Fa sid_ctx_len +of the session id context +.Fa sid_ctx +exceeded +the maximum allowed length of +.Dv SSL_MAX_SSL_SESSION_ID_LENGTH . +The error is logged to the error stack. +.It 1 +The operation succeeded. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_SESSION_set1_id_context 3 +.Sh HISTORY +.Fn SSL_set_session_id_context +first appeared in OpenSSL 0.9.2b. +.Fn SSL_CTX_set_session_id_context +first appeared in OpenSSL 0.9.3. +Both functions have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/SSL_CTX_set_ssl_version.3 b/static/openbsd/man3/SSL_CTX_set_ssl_version.3 new file mode 100644 index 00000000..fe9febe4 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_ssl_version.3 @@ -0,0 +1,147 @@ +.\" $OpenBSD: SSL_CTX_set_ssl_version.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_SSL_VERSION 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_ssl_version , +.Nm SSL_set_ssl_method , +.Nm SSL_CTX_get_ssl_method , +.Nm SSL_get_ssl_method +.Nd choose a new TLS/SSL method +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_set_ssl_version "SSL_CTX *ctx" "const SSL_METHOD *method" +.Ft int +.Fn SSL_set_ssl_method "SSL *s" "const SSL_METHOD *method" +.Ft const SSL_METHOD * +.Fn SSL_CTX_get_ssl_method "SSL_CTX *ctx" +.Ft const SSL_METHOD * +.Fn SSL_get_ssl_method "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_CTX_set_ssl_version +sets a new default TLS/SSL +.Fa method +for +.Vt SSL +objects newly created from this +.Fa ctx . +.Vt SSL +objects already created with +.Xr SSL_new 3 +are not affected, except when +.Xr SSL_clear 3 +is called. +.Pp +.Fn SSL_set_ssl_method +sets a new TLS/SSL +.Fa method +for a particular +.Vt SSL +object +.Fa s . +It may be reset when +.Xr SSL_clear 3 +is called. +.Pp +.Fn SSL_CTX_get_ssl_method +and +.Fn SSL_get_ssl_method +return a function pointer to the TLS/SSL method set in +.Fa ctx +and +.Fa ssl , +respectively. +.Pp +The available +.Fa method +choices are described in +.Xr SSL_CTX_new 3 . +.Pp +When +.Xr SSL_clear 3 +is called and no session is connected to an +.Vt SSL +object, the method of the +.Vt SSL +object is reset to the method currently set in the corresponding +.Vt SSL_CTX +object. +.Sh RETURN VALUES +The following return values can occur for +.Fn SSL_CTX_set_ssl_version +and +.Fn SSL_set_ssl_method : +.Bl -tag -width Ds +.It 0 +The new choice failed. +Check the error stack to find out the reason. +.It 1 +The operation succeeded. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_new 3 , +.Xr SSL_set_connect_state 3 +.Sh HISTORY +.Fn SSL_CTX_set_ssl_version , +.Fn SSL_set_ssl_method , +and +.Fn SSL_get_ssl_method +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Fn SSL_CTX_get_ssl_method +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.0 . diff --git a/static/openbsd/man3/SSL_CTX_set_timeout.3 b/static/openbsd/man3/SSL_CTX_set_timeout.3 new file mode 100644 index 00000000..da2f8115 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_timeout.3 @@ -0,0 +1,119 @@ +.\" $OpenBSD: SSL_CTX_set_timeout.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_TIMEOUT 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_timeout , +.Nm SSL_CTX_get_timeout +.Nd manipulate timeout values for session caching +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_set_timeout "SSL_CTX *ctx" "long t" +.Ft long +.Fn SSL_CTX_get_timeout "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_timeout +sets the timeout for newly created sessions for +.Fa ctx +to +.Fa t . +The timeout value +.Fa t +must be given in seconds. +.Pp +.Fn SSL_CTX_get_timeout +returns the currently set timeout value for +.Fa ctx . +.Pp +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 +.Xr SSL_SESSION_get_time 3 +family of functions. +.Pp +Expired sessions are removed from the internal session cache, whenever +.Xr SSL_CTX_flush_sessions 3 +is called, either directly by the application or automatically (see +.Xr SSL_CTX_set_session_cache_mode 3 ) . +.Pp +The default value for session timeout is decided on a per-protocol basis; see +.Xr SSL_get_default_timeout 3 . +All currently supported protocols have the same default timeout value of 300 +seconds. +.Sh RETURN VALUES +.Fn SSL_CTX_set_timeout +returns the previously set timeout value. +.Pp +.Fn SSL_CTX_get_timeout +returns the currently set timeout value. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_get_default_timeout 3 , +.Xr SSL_SESSION_get_time 3 +.Sh HISTORY +.Fn SSL_CTX_set_timeout +and +.Fn SSL_CTX_get_timeout +first appeared in SSLeay 0.6.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_CTX_set_tlsext_servername_callback.3 b/static/openbsd/man3/SSL_CTX_set_tlsext_servername_callback.3 new file mode 100644 index 00000000..b6cece25 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_tlsext_servername_callback.3 @@ -0,0 +1,248 @@ +.\" $OpenBSD: SSL_CTX_set_tlsext_servername_callback.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 190b9a03 Jun 28 15:46:13 2017 +0800 +.\" selective merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 +.\" +.\" This file was written by Jon Spillett , +.\" Paul Yang , and +.\" Matt Caswell . +.\" Copyright (c) 2017, 2019 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_TLSEXT_SERVERNAME_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_tlsext_servername_callback , +.Nm SSL_CTX_set_tlsext_servername_arg , +.Nm SSL_get_servername_type , +.Nm SSL_get_servername , +.Nm SSL_set_tlsext_host_name +.Nd handle server name indication (SNI) +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fo SSL_CTX_set_tlsext_servername_callback +.Fa "SSL_CTX *ctx" +.Fa "int (*cb)(SSL *ssl, int *alert, void *arg)" +.Fc +.Ft long +.Fo SSL_CTX_set_tlsext_servername_arg +.Fa "SSL_CTX *ctx" +.Fa "void *arg" +.Fc +.Ft const char * +.Fo SSL_get_servername +.Fa "const SSL *ssl" +.Fa "const int type" +.Fc +.Ft int +.Fo SSL_get_servername_type +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_set_tlsext_host_name +.Fa "SSL *ssl" +.Fa "const char *name" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_tlsext_servername_callback +sets the application callback +.Fa cb +used by a server to perform any actions or configuration required based +on the servername extension received in the incoming connection. +Like the ALPN callback, it is executed during Client Hello processing. +When +.Fa cb +is +.Dv NULL , +SNI is not used. +.Pp +The servername callback should return one of the following values: +.Bl -tag -width Ds +.It Dv SSL_TLSEXT_ERR_OK +This is used to indicate that the servername requested by the client +has been accepted. +Typically a server will call +.Xr SSL_set_SSL_CTX 3 +in the callback to set up a different configuration +for the selected servername in this case. +.It Dv 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 +.Fa alert +parameter to the callback. +By default this value is initialised to +.Dv SSL_AD_UNRECOGNIZED_NAME . +.It Dv 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 +.Fa alert +parameter as for +.Dv 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 +.Dv SSL_TLSEXT_ERR_NOACK . +.It Dv 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. +.El +.Pp +.Fn SSL_CTX_set_tlsext_servername_arg +sets a context-specific argument to be passed into the callback via the +.Fa arg +parameter for +.Fa ctx . +.ig end_of_get_servername_details +.\" I would suggest to comment out that second wall text of dubious +.\" usefulness and see if we can meet all these documented API +.\" requirements in the future or decide that it's not worth the +.\" effort. -- tb@ Aug 30, 2021 +.Pp +The behaviour of +.Fn SSL_get_servername +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. +.Bl -tag -width Ds +.It On the client, before the handshake: +If a servername has been set via a call to +.Fn SSL_set_tlsext_host_name , +then it will return that servername. +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. +Otherwise it returns +.Dv NULL . +.It On the client, during or after the handshake,\ + if 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. +Otherwise it returns the servername set via +.Fn SSL_set_tlsext_host_name +or +.Dv NULL +if it was not called. +.It On the client, during or after the handshake,\ + if a TLSv1.2 (or below) resumption did not occur: +It will return the servername set via +.Fn SSL_set_tlsext_host_name +or +.Dv NULL +if it was not called. +.It On the server, before the handshake: +The function will always return +.Dv NULL +before the handshake. +.It On the server, after the servername extension has been processed,\ + if 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 +.Dv NULL +otherwise. +.It On the server, after the servername extension has been processed,\ + if a TLSv1.2 (or below) resumption did not occur: +The function will return the servername +requested by the client in this handshake or +.Dv NULL +if none was requested. +.El +.Pp +Note that the early 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. +.end_of_get_servername_details +.Pp +.Fn SSL_set_tlsext_host_name +sets the server name indication ClientHello extension +to contain the value +.Fa name , +or clears it if +.Fa name +is +.Dv NULL . +The type of server name indication +extension is set to +.Dv TLSEXT_NAMETYPE_host_name +as defined in RFC 3546. +.Pp +All three functions are implemented as macros. +.Sh RETURN VALUES +.Fn SSL_CTX_set_tlsext_servername_callback +and +.Fn SSL_CTX_set_tlsext_servername_arg +always return 1 indicating success. +.Pp +.Fn SSL_get_servername +returns a servername extension value of the specified type if provided +in the Client Hello, or +.Dv NULL +otherwise. +.Pp +.Fn SSL_get_servername_type +returns the servername type or -1 if no servername is present. +Currently the only supported type (defined in RFC 3546) is +.Dv TLSEXT_NAMETYPE_host_name . +.Pp +.Fn SSL_set_tlsext_host_name +returns 1 on success or 0 in case of an error. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_callback_ctrl 3 , +.Xr SSL_CTX_set_alpn_select_cb 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8f +and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/SSL_CTX_set_tlsext_status_cb.3 b/static/openbsd/man3/SSL_CTX_set_tlsext_status_cb.3 new file mode 100644 index 00000000..c9763f9d --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_tlsext_status_cb.3 @@ -0,0 +1,239 @@ +.\" $OpenBSD: SSL_CTX_set_tlsext_status_cb.3,v 1.9 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 43c34894 Nov 30 16:04:51 2015 +0000 +.\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_TLSEXT_STATUS_CB 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_tlsext_status_cb , +.Nm SSL_CTX_get_tlsext_status_cb , +.Nm SSL_CTX_set_tlsext_status_arg , +.Nm SSL_CTX_get_tlsext_status_arg , +.Nm SSL_set_tlsext_status_type , +.Nm SSL_get_tlsext_status_type , +.Nm SSL_get_tlsext_status_ocsp_resp , +.Nm SSL_set_tlsext_status_ocsp_resp +.Nd OCSP Certificate Status Request functions +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/tls1.h +.Ft long +.Fo SSL_CTX_set_tlsext_status_cb +.Fa "SSL_CTX *ctx" +.Fa "int (*callback)(SSL *, void *)" +.Fc +.Ft long +.Fo SSL_CTX_get_tlsext_status_cb +.Fa "SSL_CTX *ctx" +.Fa "int (*callback)(SSL *, void *)" +.Fc +.Ft long +.Fo SSL_CTX_set_tlsext_status_arg +.Fa "SSL_CTX *ctx" +.Fa "void *arg" +.Fc +.Ft long +.Fo SSL_CTX_get_tlsext_status_arg +.Fa "SSL_CTX *ctx" +.Fa "void **arg" +.Fc +.Ft long +.Fo SSL_set_tlsext_status_type +.Fa "SSL *s" +.Fa "int type" +.Fc +.Ft long +.Fo SSL_get_tlsext_status_type +.Fa "SSL *s" +.Fc +.Ft long +.Fo SSL_get_tlsext_status_ocsp_resp +.Fa ssl +.Fa "unsigned char **resp" +.Fc +.Ft long +.Fo SSL_set_tlsext_status_ocsp_resp +.Fa ssl +.Fa "unsigned char *resp" +.Fa "int len" +.Fc +.Sh 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 +.Fn SSL_set_tlsext_status_type +function on an individual +.Vt SSL +object prior to the start of the handshake. +Currently the only supported type is +.Dv TLSEXT_STATUSTYPE_ocsp . +This value should be passed in the +.Fa type +argument. +.Pp +The client should additionally provide a callback function to decide +what to do with the returned OCSP response by calling +.Fn SSL_CTX_set_tlsext_status_cb . +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 +.Fn SSL_CTX_set_tlsext_status_arg . +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). +.Pp +The callback previously set via +.Fn SSL_CTX_set_tlsext_status_cb +can be retrieved by calling +.Fn SSL_CTX_get_tlsext_status_cb , +and the argument by calling +.Fn SSL_CTX_get_tlsext_status_arg . +.Pp +On the client side, +.Fn SSL_get_tlsext_status_type +can be used to determine whether the client has previously called +.Fn SSL_set_tlsext_status_type . +It will return +.Dv TLSEXT_STATUSTYPE_ocsp +if it has been called or \-1 otherwise. +On the server side, +.Fn SSL_get_tlsext_status_type +can be used to determine whether the client requested OCSP stapling. +If the client requested it, then this function will return +.Dv TLSEXT_STATUSTYPE_ocsp , +or \-1 otherwise. +.Pp +The response returned by the server can be obtained via a call to +.Fn SSL_get_tlsext_status_ocsp_resp . +The value +.Pf * Fa resp +will be updated to point to the OCSP response data and the return value +will be the length of that data. +If the server has not provided any response data, then +.Pf * Fa resp +will be +.Dv NULL +and the return value from +.Fn SSL_get_tlsext_status_ocsp_resp +will be -1. +.Pp +A server application must also call the +.Fn SSL_CTX_set_tlsext_status_cb +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 +.Xr SSL_get_certificate 3 , +obtain the OCSP response to be sent back, and then set that response +data by calling +.Fn SSL_set_tlsext_status_ocsp_resp . +A pointer to the response data should be provided in the +.Fa resp +argument, and the length of that data should be in the +.Fa len +argument. +.Sh 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 +.Dv SSL_TLSEXT_ERR_OK +(meaning that the OCSP response that has been set should be returned), +.Dv SSL_TLSEXT_ERR_NOACK +(meaning that an OCSP response should not be returned), or +.Dv SSL_TLSEXT_ERR_ALERT_FATAL +(meaning that a fatal error has occurred). +.Pp +.Fn SSL_CTX_set_tlsext_status_cb , +.Fn SSL_CTX_get_tlsext_status_cb , +.Fn SSL_CTX_set_tlsext_status_arg , +.Fn SSL_CTX_get_tlsext_status_arg , +.Fn SSL_set_tlsext_status_type , +and +.Fn SSL_set_tlsext_status_ocsp_resp +always return 1, indicating success. +.Pp +.Fn SSL_get_tlsext_status_type +returns +.Dv TLSEXT_STATUSTYPE_ocsp +on the client side if +.Fn SSL_set_tlsext_status_type +was previously called, or on the server side +if the client requested OCSP stapling. +Otherwise \-1 is returned. +.Pp +.Fn SSL_get_tlsext_status_ocsp_resp +returns the length of the OCSP response data +or \-1 if there is no OCSP response data. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_callback_ctrl 3 +.Sh HISTORY +.Fn SSL_CTX_set_tlsext_status_cb , +.Fn SSL_CTX_set_tlsext_status_arg , +.Fn SSL_set_tlsext_status_type , +.Fn SSL_get_tlsext_status_ocsp_resp , +and +.Fn SSL_set_tlsext_status_ocsp_resp +first appeared in OpenSSL 0.9.8h and have been available since +.Ox 4.5 . +.Pp +.Fn SSL_CTX_get_tlsext_status_cb +and +.Fn SSL_CTX_get_tlsext_status_arg +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +.Pp +.Fn SSL_get_tlsext_status_type +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.0 . diff --git a/static/openbsd/man3/SSL_CTX_set_tlsext_ticket_key_cb.3 b/static/openbsd/man3/SSL_CTX_set_tlsext_ticket_key_cb.3 new file mode 100644 index 00000000..0427f7dc --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_tlsext_ticket_key_cb.3 @@ -0,0 +1,301 @@ +.\" $OpenBSD: SSL_CTX_set_tlsext_ticket_key_cb.3,v 1.9 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Rich Salz +.\" Copyright (c) 2014, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_TLSEXT_TICKET_KEY_CB 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_tlsext_ticket_key_cb +.Nd set a callback for session ticket processing +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/tls1.h +.Ft long +.Fo SSL_CTX_set_tlsext_ticket_key_cb +.Fa "SSL_CTX sslctx" +.Fa "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)" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_tlsext_ticket_key_cb +sets a callback function +.Fa cb +for handling session tickets for the ssl context +.Fa sslctx . +Session tickets, defined in RFC 5077, provide an enhanced session +resumption capability where the server implementation is not required to +maintain per session state. +.Pp +The callback function +.Fa cb +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 the callback function to help implement a +common TLS ticket construction state according to RFC 5077 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 a session ticket +extension to the server. +The client can only 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 +The callback is called with +.Fa ctx +and +.Fa hctx +which were newly allocated with +.Xr EVP_CIPHER_CTX_new 3 +and +.Xr HMAC_CTX_new 3 , +respectively. +.Pp +For new sessions tickets, when the client doesn't 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 +.Fa enc +equal to 1. +The OpenSSL library expects that the function will set an arbitrary +.Fa key_name , +initialize +.Fa iv , +and set the cipher context +.Fa ctx +and the hash context +.Fa hctx . +.Pp +The +.Fa key_name +is 16 characters long and is used as a key identifier. +.Pp +The +.Fa iv +length is the length of the IV of the corresponding cipher. +The maximum IV length is +.Dv EVP_MAX_IV_LENGTH +bytes defined in +.In openssl/evp.h . +.Pp +The initialization vector +.Fa iv +should be a random value. +The cipher context +.Fa ctx +should use the initialisation vector +.Fa iv . +The cipher context can be set using +.Xr EVP_EncryptInit_ex 3 . +The hmac context can be set using +.Xr HMAC_Init_ex 3 . +.Pp +When the client presents a session ticket, the callback function +with be called with +.Fa enc +set to 0 indicating that the +.Fa cb +function should retrieve a set of parameters. +In this case +.Fa key_name +and +.Fa iv +have already been parsed out of the session ticket. +The OpenSSL library expects that the +.Em key_name +will be used to retrieve a cryptographic parameters and that the +cryptographic context +.Fa ctx +will be set with the retrieved parameters and the initialization vector +.Fa iv +using a function like +.Xr EVP_DecryptInit_ex 3 . +The +.Fa hctx +needs to be set using +.Xr HMAC_Init_ex 3 . +.Pp +If the +.Fa key_name +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 +.Fa enc +equal to 1 to set the new ticket. +.Pp +The return value of the +.Fa cb +function is used by OpenSSL to determine what further processing will +occur. +The following return values have meaning: +.Bl -tag -width Ds +.It 2 +This indicates that the +.Fa ctx +and +.Fa hctx +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 +.Fa cb +again with an +.Fa enc +argument of 1 to set the new ticket (see RFC 5077 3.3 paragraph 2). +.It 1 +This indicates that the +.Fa ctx +and +.Fa hctx +have been set and the session can continue on those parameters. +.It 0 +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. +.Pp +If called with +.Fa enc +equal to 0, the library will call the +.Fa cb +again to get a new set of parameters. +.It less than 0 +This indicates an error. +.El +.Pp +Session resumption shortcuts the TLS so that the client certificate +negotiation don't occur. +It makes up for this by storing 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 ciphersuite 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 ciphersuite 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 +This function returns 0 to indicate that the callback function was set. +.Sh EXAMPLES +Reference Implementation: +.Bd -literal +SSL_CTX_set_tlsext_ticket_key_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, HMAC_CTX *hctx, int enc) +{ + if (enc) { /* create new session */ + if (RAND_bytes(iv, EVP_MAX_IV_LENGTH)) + return -1; /* insufficient random */ + + key = currentkey(); /* something you need to implement */ + if (!key) { + /* current key doesn't exist or isn't 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) /* key couldn't be created */ + return 0; + } + memcpy(key_name, key->name, 16); + + EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, + key->aes_key, iv); + HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); + + return 1; + + } else { /* retrieve session */ + key = findkey(name); + + if (!key || key->expire < now()) + return 0; + + HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); + EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, + key->aes_key, iv ); + + if (key->expire < (now() - RENEW_TIME)) + /* this session will get a new ticket + * even though the current is still valid */ + return 2; + + return 1; + } +} +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_add_session 3 , +.Xr SSL_CTX_callback_ctrl 3 , +.Xr SSL_CTX_sess_number 3 , +.Xr SSL_CTX_sess_set_get_cb 3 , +.Xr SSL_CTX_set_session_id_context 3 , +.Xr SSL_session_reused 3 , +.Xr SSL_set_session 3 +.Sh HISTORY +.Fn SSL_CTX_set_tlsext_ticket_key_cb +first appeared in OpenSSL 0.9.8h and has been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/SSL_CTX_set_tlsext_use_srtp.3 b/static/openbsd/man3/SSL_CTX_set_tlsext_use_srtp.3 new file mode 100644 index 00000000..4acd452a --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_tlsext_use_srtp.3 @@ -0,0 +1,198 @@ +.\" $OpenBSD: SSL_CTX_set_tlsext_use_srtp.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_TLSEXT_USE_SRTP 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_tlsext_use_srtp , +.Nm SSL_set_tlsext_use_srtp , +.Nm SSL_get_srtp_profiles , +.Nm SSL_get_selected_srtp_profile +.Nd Configure and query SRTP support +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/srtp.h +.Ft int +.Fo SSL_CTX_set_tlsext_use_srtp +.Fa "SSL_CTX *ctx" +.Fa "const char *profiles" +.Fc +.Ft int +.Fo SSL_set_tlsext_use_srtp +.Fa "SSL *ssl" +.Fa "const char *profiles" +.Fc +.Ft STACK_OF(SRTP_PROTECTION_PROFILE) * +.Fo SSL_get_srtp_profiles +.Fa "SSL *ssl" +.Fc +.Ft SRTP_PROTECTION_PROFILE * +.Fo SSL_get_selected_srtp_profile +.Fa "SSL *ssl" +.Fc +.Sh DESCRIPTION +SRTP is the Secure Real-Time Transport Protocol. +OpenSSL implements support for the "use_srtp" DTLS extension +defined in RFC 5764. +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 RFC 5763. +OpenSSL does not implement SRTP itself or RFC 5763. +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 is ignored if a TLS connection is attempted. +.Pp +An OpenSSL client wishing to send the "use_srtp" extension should call +.Fn SSL_CTX_set_tlsext_use_srtp +to set its use for all +.Vt SSL +objects subsequently created from +.Fa ctx . +Alternatively a client may call +.Fn SSL_set_tlsext_use_srtp +to set its use for an individual +.Vt SSL +object. +The +.Fa profiles +parameter should point to a NUL-terminated, colon delimited list of +SRTP protection profile names. +.Pp +The currently supported protection profile names are: +.Bl -tag -width Ds +.It Dv SRTP_AES128_CM_SHA1_80 +This corresponds to SRTP_AES128_CM_HMAC_SHA1_80 defined in RFC 5764. +.It Dv SRTP_AES128_CM_SHA1_32 +This corresponds to SRTP_AES128_CM_HMAC_SHA1_32 defined in RFC 5764. +.It Dv SRTP_AEAD_AES_128_GCM +This corresponds to SRTP_AEAD_AES_128_GCM defined in RFC 7714. +.It Dv SRTP_AEAD_AES_256_GCM +This corresponds to SRTP_AEAD_AES_256_GCM defined in RFC 7714. +.El +.Pp +Supplying an unrecognised protection profile name results in an error. +.Pp +An OpenSSL server wishing to support the "use_srtp" extension should +also call +.Fn SSL_CTX_set_tlsext_use_srtp +or +.Fn SSL_set_tlsext_use_srtp +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 +.Fn SSL_get_srtp_profiles . +This returns a stack of +.Vt 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 +.Fn SSL_get_selected_srtp_profile . +This function returns +.Dv 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 by calling +.Xr SSL_export_keying_material 3 +with a +.Fa label +of +.Qq EXTRACTOR-dtls_srtp , +a +.Fa context +of +.Dv NULL , +and a +.Fa use_context +argument of 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. +.Sh RETURN VALUES +Contrary to OpenSSL conventions, +.Fn SSL_CTX_set_tlsext_use_srtp +and +.Fn SSL_set_tlsext_use_srtp +return 0 on success or 1 on error. +.Pp +.Fn SSL_get_srtp_profiles +returns a stack of +.Vt SRTP_PROTECTION_PROFILE +objects on success or +.Dv NULL +on error or if no protection profiles have been configured. +.Pp +.Fn SSL_get_selected_srtp_profile +returns a pointer to an +.Vt SRTP_PROTECTION_PROFILE +object if one has been negotiated or +.Dv NULL +otherwise. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_export_keying_material 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.1 +and have been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/SSL_CTX_set_tmp_dh_callback.3 b/static/openbsd/man3/SSL_CTX_set_tmp_dh_callback.3 new file mode 100644 index 00000000..9fa83065 --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_tmp_dh_callback.3 @@ -0,0 +1,230 @@ +.\" $OpenBSD: SSL_CTX_set_tmp_dh_callback.3,v 1.12 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2014, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_TMP_DH_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_tmp_dh_callback , +.Nm SSL_CTX_set_tmp_dh , +.Nm SSL_set_tmp_dh_callback , +.Nm SSL_set_tmp_dh +.Nd handle DH keys for ephemeral key exchange +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_tmp_dh_callback +.Fa "SSL_CTX *ctx" +.Fa "DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)" +.Fc +.Ft long +.Fn SSL_CTX_set_tmp_dh "SSL_CTX *ctx" "DH *dh" +.Ft void +.Fo SSL_set_tmp_dh_callback +.Fa "SSL *ssl" +.Fa "DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength" +.Fc +.Ft long +.Fn SSL_set_tmp_dh "SSL *ssl" "DH *dh" +.Sh DESCRIPTION +.Fn SSL_CTX_set_tmp_dh_callback +sets the callback function for +.Fa ctx +to be used when a DH parameters are required to +.Fa tmp_dh_callback . +The callback is inherited by all +.Vt ssl +objects created from +.Fa ctx . +.Pp +.Fn SSL_CTX_set_tmp_dh +sets DH parameters to be used by +.Fa ctx . +The key is inherited by all +.Fa ssl +objects created from +.Fa ctx . +.Pp +.Fn SSL_set_tmp_dh_callback +sets the callback only for +.Fa ssl . +.Pp +.Fn SSL_set_tmp_dh +sets the parameters only for +.Fa ssl . +.Pp +These functions apply to SSL/TLS servers only. +.Pp +When using a cipher with RSA authentication, +an ephemeral DH key exchange can take place. +In these cases, the session data are 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 attackers 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 but supply the parameters. +DH parameters can be reused, +as the actual key is newly generated during the negotiation. +The risk in reusing DH parameters is that an attacker may specialize on a very +often used DH group. +Applications should therefore generate their own DH parameters during the +installation process using the +.Xr openssl 1 +.Cm dhparam +application. +This application guarantees that "strong" primes are used. +.Pp +Files +.Pa dh2048.pem +and +.Pa dh4096.pem +in the +.Pa apps +directory of the current version of the OpenSSL distribution contain the +.Sq SKIP +DH parameters, +which use safe primes and were generated verifiably pseudo-randomly. +These files can be converted into C code using the +.Fl C +option of the +.Xr openssl 1 +.Cm dhparam +application. +Generation of custom DH parameters during installation should still +be preferred to stop an attacker from specializing on a commonly +used group. +The file +.Pa dh1024.pem +contains old parameters that must not be used by applications. +.Pp +An application may either directly specify the DH parameters or can supply the +DH parameters via a callback function. +.Pp +Previous versions of the callback used +.Fa is_export +and +.Fa keylength +parameters to control parameter generation for export and non-export +cipher suites. +Modern servers that do not support export ciphersuites are advised +to either use +.Fn SSL_CTX_set_tmp_dh +or alternatively, use the callback but ignore +.Fa keylength +and +.Fa is_export +and simply supply at least 2048-bit parameters in the callback. +.Sh RETURN VALUES +.Fn SSL_CTX_set_tmp_dh +and +.Fn SSL_set_tmp_dh +do return 1 on success and 0 on failure. +Check the error queue to find out the reason of failure. +.Sh EXAMPLES +Set up DH parameters with a key length of 2048 bits. +Error handling is partly left out. +.Pp +Command-line parameter generation: +.Pp +.Dl openssl dhparam -out dh_param_2048.pem 2048 +.Pp +Code for setting up parameters during server initialization: +.Bd -literal +SSL_CTX ctx = SSL_CTX_new(); +\&... + +/* Set up ephemeral DH parameters. */ +DH *dh_2048 = NULL; +FILE *paramfile; +paramfile = fopen("dh_param_2048.pem", "r"); +if (paramfile) { + dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); + fclose(paramfile); +} else { + /* Error. */ +} +if (dh_2048 == NULL) { + /* Error. */ +} +if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) { + /* Error. */ +} +.Ed +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_CTX_set_cipher_list 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_set_tmp_ecdh 3 +.Sh HISTORY +.Fn SSL_CTX_set_tmp_dh_callback +and +.Fn SSL_CTX_set_tmp_dh +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn SSL_set_tmp_dh_callback +and +.Fn SSL_set_tmp_dh +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/SSL_CTX_set_tmp_rsa_callback.3 b/static/openbsd/man3/SSL_CTX_set_tmp_rsa_callback.3 new file mode 100644 index 00000000..7009ac6a --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_tmp_rsa_callback.3 @@ -0,0 +1,115 @@ +.\" $OpenBSD: SSL_CTX_set_tmp_rsa_callback.3,v 1.10 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 0b30fc90 Dec 19 15:23:05 2013 -0500 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2006, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_TMP_RSA_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_tmp_rsa_callback , +.Nm SSL_CTX_set_tmp_rsa , +.Nm SSL_CTX_need_tmp_RSA , +.Nm SSL_set_tmp_rsa_callback , +.Nm SSL_set_tmp_rsa , +.Nm SSL_need_tmp_RSA +.Nd handle RSA keys for ephemeral key exchange +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_tmp_rsa_callback +.Fa "SSL_CTX *ctx" +.Fa "RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)" +.Fc +.Ft long +.Fn SSL_CTX_set_tmp_rsa "SSL_CTX *ctx" "RSA *rsa" +.Ft long +.Fn SSL_CTX_need_tmp_RSA "SSL_CTX *ctx" +.Ft void +.Fo SSL_set_tmp_rsa_callback +.Fa "SSL_CTX *ctx" +.Fa "RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)" +.Fc +.Ft long +.Fn SSL_set_tmp_rsa "SSL *ssl" "RSA *rsa" +.Ft long +.Fn SSL_need_tmp_RSA "SSL *ssl" +.Sh DESCRIPTION +Since they mattered only for deliberately insecure RSA authentication +mandated by historical U.S. export restrictions, these functions +are all deprecated and have no effect except that +.Fn SSL_CTX_set_tmp_rsa_callback , +.Fn SSL_CTX_set_tmp_rsa , +.Fn SSL_set_tmp_rsa_callback , +and +.Fn SSL_set_tmp_rsa +issue error messages when called. +.Sh RETURN VALUES +These functions always return 0, indicating failure. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_cipher_list 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_CTX_set_tmp_dh_callback 3 , +.Xr SSL_new 3 , +.Xr SSL_set_tmp_ecdh 3 +.Sh HISTORY +.Fn SSL_CTX_set_tmp_rsa_callback , +.Fn SSL_CTX_set_tmp_rsa , +and +.Fn SSL_CTX_need_tmp_RSA +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn SSL_set_tmp_rsa_callback , +.Fn SSL_set_tmp_rsa , +and +.Fn SSL_need_tmp_RSA +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/SSL_CTX_set_verify.3 b/static/openbsd/man3/SSL_CTX_set_verify.3 new file mode 100644 index 00000000..656c85af --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_set_verify.3 @@ -0,0 +1,480 @@ +.\" $OpenBSD: SSL_CTX_set_verify.3,v 1.10 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 +.\" selective merge up to: OpenSSL 1cb7eff4 Sep 10 13:56:40 2019 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2002, 2003, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_SET_VERIFY 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_verify , +.Nm SSL_set_verify , +.Nm SSL_CTX_set_verify_depth , +.Nm SSL_set_verify_depth +.Nd set peer certificate verification parameters +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_verify +.Fa "SSL_CTX *ctx" +.Fa "int mode" +.Fa "int (*verify_callback)(int, X509_STORE_CTX *)" +.Fc +.Ft void +.Fo SSL_set_verify +.Fa "SSL *s" +.Fa "int mode" +.Fa "int (*verify_callback)(int, X509_STORE_CTX *)" +.Fc +.Ft void +.Fn SSL_CTX_set_verify_depth "SSL_CTX *ctx" "int depth" +.Ft void +.Fn SSL_set_verify_depth "SSL *s" "int depth" +.Ft int +.Fn verify_callback "int preverify_ok" "X509_STORE_CTX *x509_ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_verify +sets the verification flags for +.Fa ctx +to be +.Fa mode +and +specifies the +.Fa verify_callback +function to be used. +If no callback function shall be specified, the +.Dv NULL +pointer can be used for +.Fa verify_callback . +.Pp +.Fn SSL_set_verify +sets the verification flags for +.Fa ssl +to be +.Fa mode +and specifies the +.Fa verify_callback +function to be used. +If no callback function shall be specified, the +.Dv NULL +pointer can be used for +.Fa verify_callback . +In this case last +.Fa verify_callback +set specifically for this +.Fa ssl +remains. +If no special callback was set before, the default callback for the underlying +.Fa ctx +is used, that was valid at the time +.Fa ssl +was created with +.Xr SSL_new 3 . +Within the callback function, +.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 +can be called to get the data index of the current +.Vt SSL +object that is doing the verification. +.Pp +.Fn SSL_CTX_set_verify_depth +sets the maximum +.Fa depth +for the certificate chain verification that shall be allowed for +.Fa ctx . +(See the +.Sx BUGS +section.) +.Pp +.Fn SSL_set_verify_depth +sets the maximum +.Fa depth +for the certificate chain verification that shall be allowed for +.Fa ssl . +(See the +.Sx BUGS +section.) +.Pp +The verification of certificates can be controlled by a set of bitwise ORed +.Fa mode +flags: +.Bl -tag -width Ds +.It Dv SSL_VERIFY_NONE +.Em Server mode : +the server will not send a client certificate request to the client, +so the client will not send a certificate. +.Pp +.Em Client mode : +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 +.Xr SSL_get_verify_result 3 +function. +The handshake will be continued regardless of the verification result. +.It Dv SSL_VERIFY_PEER +.Em Server mode : +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 +.Dv SSL_VERIFY_FAIL_IF_NO_PEER_CERT +and +.Dv SSL_VERIFY_CLIENT_ONCE +flags. +.Pp +.Em Client mode : +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, +.Dv SSL_VERIFY_PEER +is ignored. +.It Dv SSL_VERIFY_FAIL_IF_NO_PEER_CERT +.Em Server mode : +if the client did not return a certificate, the TLS/SSL +handshake is immediately terminated with a +.Dq handshake failure +alert. +This flag must be used together with +.Dv SSL_VERIFY_PEER . +.Pp +.Em Client mode : +ignored +.It Dv SSL_VERIFY_CLIENT_ONCE +.Em Server mode : +only request a client certificate on the initial TLS/SSL handshake. +Do not ask for a client certificate again in case of a renegotiation. +This flag must be used together with +.Dv SSL_VERIFY_PEER . +.Pp +.Em Client mode : +ignored +.El +.Pp +Exactly one of the +.Fa mode +flags +.Dv SSL_VERIFY_NONE +and +.Dv SSL_VERIFY_PEER +must be set at any time. +.Pp +The actual verification procedure is performed either using the built-in +verification procedure or using another application provided verification +function set with +.Xr SSL_CTX_set_cert_verify_callback 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 +.Fa verify_callback Ns () +function, but the way this information is used may be different. +.Pp +.Fn SSL_CTX_set_verify_depth +and +.Fn SSL_set_verify_depth +set the limit up to which depth certificates in a chain are used during the +verification procedure. +If the certificate chain is longer than allowed, +the certificates above the limit are ignored. +Error messages are generated as if these certificates would not be present, +most likely a +.Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY +will be issued. +The depth count is +.Dq level 0: peer certificate , +.Dq level 1: CA certificate , +.Dq level 2: higher level CA certificate , +and so on. +Setting the maximum depth to 2 allows the levels 0, 1, and 2. +The default depth limit is 100, +allowing for the peer certificate and an additional 100 CA certificates. +.Pp +The +.Fa verify_callback +function is used to control the behaviour when the +.Dv SSL_VERIFY_PEER +flag is set. +It must be supplied by the application and receives two arguments: +.Fa preverify_ok +indicates whether the verification of the certificate in question was passed +(preverify_ok=1) or not (preverify_ok=0). +.Fa x509_ctx +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's certificate. +At each level signatures and issuer attributes are checked. +Whenever a verification error is found, the error number is stored in +.Fa x509_ctx +and +.Fa verify_callback +is called with +.Fa preverify_ok +equal to 0. +By applying +.Fn X509_CTX_store_* +functions +.Fa verify_callback +can locate the certificate in question and perform additional steps (see +.Sx EXAMPLES ) . +If no error is found for a certificate, +.Fa verify_callback +is called with +.Fa preverify_ok +equal to 1 before advancing to the next level. +.Pp +The return value of +.Fa verify_callback +controls the strategy of the further verification process. +If +.Fa verify_callback +returns 0, the verification process is immediately stopped with +.Dq verification failed +state. +If +.Dv SSL_VERIFY_PEER +is set, a verification failure alert is sent to the peer and the TLS/SSL +handshake is terminated. +If +.Fa verify_callback +returns 1, the verification process is continued. +If +.Fa verify_callback +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 +.Xr SSL_get_verify_result 3 +or by maintaining its own error storage managed by +.Fa verify_callback . +.Pp +If no +.Fa verify_callback +is specified, the default callback will be used. +Its return value is identical to +.Fa preverify_ok , +so that any verification +failure will lead to a termination of the TLS/SSL handshake with an +alert message, if +.Dv SSL_VERIFY_PEER +is set. +.Sh EXAMPLES +The following code sequence realizes an example +.Fa verify_callback +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 +.Vt SSL +structure (see +.Xr SSL_get_ex_new_index 3 , +.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 ) . +.Bd -literal +\&... + +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(ctx->current_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 the 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 */ + } +} +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_get_verify_mode 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_cert_verify_callback 3 , +.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 , +.Xr SSL_get_ex_new_index 3 , +.Xr SSL_get_peer_certificate 3 , +.Xr SSL_get_verify_result 3 , +.Xr SSL_new 3 , +.Xr SSL_set1_host 3 +.Sh HISTORY +.Fn SSL_set_verify +appeared in SSLeay 0.4 or earlier. +.Fn SSL_CTX_set_verify +first appeared in SSLeay 0.6.4. +Both functions have been available since +.Ox 2.4 . +.Pp +.Fn SSL_CTX_set_verify_depth +and +.Fn SSL_set_verify_depth +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . +.Sh BUGS +In client mode, it is not checked whether the +.Dv SSL_VERIFY_PEER +flag is set, but whether +.Dv SSL_VERIFY_NONE +is not set. +This can lead to unexpected behaviour, if the +.Dv SSL_VERIFY_PEER +and +.Dv SSL_VERIFY_NONE +are not used as required (exactly one must be set at any time). +.Pp +The certificate verification depth set with +.Fn SSL[_CTX]_verify_depth +stops the verification at a certain depth. +The error message produced will be that of an incomplete certificate chain and +not +.Dv X509_V_ERR_CERT_CHAIN_TOO_LONG +as may be expected. diff --git a/static/openbsd/man3/SSL_CTX_use_certificate.3 b/static/openbsd/man3/SSL_CTX_use_certificate.3 new file mode 100644 index 00000000..27ec834d --- /dev/null +++ b/static/openbsd/man3/SSL_CTX_use_certificate.3 @@ -0,0 +1,452 @@ +.\" $OpenBSD: SSL_CTX_use_certificate.3,v 1.18 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 3aaa1bd0 Mar 28 16:35:25 2017 +1000 +.\" selective merge up to: OpenSSL d1f7a1e6 Apr 26 14:05:40 2018 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2002, 2003, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CTX_USE_CERTIFICATE 3 +.Os +.Sh NAME +.Nm SSL_CTX_use_certificate , +.Nm SSL_CTX_use_certificate_ASN1 , +.Nm SSL_CTX_use_certificate_file , +.Nm SSL_use_certificate , +.Nm SSL_use_certificate_ASN1 , +.Nm SSL_use_certificate_chain_file , +.Nm SSL_use_certificate_file , +.Nm SSL_CTX_use_certificate_chain_file , +.Nm SSL_CTX_use_certificate_chain_mem , +.Nm SSL_CTX_use_PrivateKey , +.Nm SSL_CTX_use_PrivateKey_ASN1 , +.Nm SSL_CTX_use_PrivateKey_file , +.Nm SSL_CTX_use_RSAPrivateKey , +.Nm SSL_CTX_use_RSAPrivateKey_ASN1 , +.Nm SSL_CTX_use_RSAPrivateKey_file , +.Nm SSL_use_PrivateKey_file , +.Nm SSL_use_PrivateKey_ASN1 , +.Nm SSL_use_PrivateKey , +.Nm SSL_use_RSAPrivateKey , +.Nm SSL_use_RSAPrivateKey_ASN1 , +.Nm SSL_use_RSAPrivateKey_file , +.Nm SSL_CTX_check_private_key , +.Nm SSL_check_private_key +.Nd load certificate and key data +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_use_certificate "SSL_CTX *ctx" "X509 *x" +.Ft int +.Fn SSL_CTX_use_certificate_ASN1 "SSL_CTX *ctx" "int len" "unsigned char *d" +.Ft int +.Fn SSL_CTX_use_certificate_file "SSL_CTX *ctx" "const char *file" "int type" +.Ft int +.Fn SSL_use_certificate "SSL *ssl" "X509 *x" +.Ft int +.Fn SSL_use_certificate_ASN1 "SSL *ssl" "unsigned char *d" "int len" +.Ft int +.Fn SSL_use_certificate_chain_file "SSL *ssl" "const char *file" +.Ft int +.Fn SSL_use_certificate_file "SSL *ssl" "const char *file" "int type" +.Ft int +.Fn SSL_CTX_use_certificate_chain_file "SSL_CTX *ctx" "const char *file" +.Ft int +.Fn SSL_CTX_use_certificate_chain_mem "SSL_CTX *ctx" "void *buf" "int len" +.Ft int +.Fn SSL_CTX_use_PrivateKey "SSL_CTX *ctx" "EVP_PKEY *pkey" +.Ft int +.Fo SSL_CTX_use_PrivateKey_ASN1 +.Fa "int pk" "SSL_CTX *ctx" "unsigned char *d" "long len" +.Fc +.Ft int +.Fn SSL_CTX_use_PrivateKey_file "SSL_CTX *ctx" "const char *file" "int type" +.Ft int +.Fn SSL_CTX_use_RSAPrivateKey "SSL_CTX *ctx" "RSA *rsa" +.Ft int +.Fn SSL_CTX_use_RSAPrivateKey_ASN1 "SSL_CTX *ctx" "unsigned char *d" "long len" +.Ft int +.Fn SSL_CTX_use_RSAPrivateKey_file "SSL_CTX *ctx" "const char *file" "int type" +.Ft int +.Fn SSL_use_PrivateKey "SSL *ssl" "EVP_PKEY *pkey" +.Ft int +.Fn SSL_use_PrivateKey_ASN1 "int pk" "SSL *ssl" "unsigned char *d" "long len" +.Ft int +.Fn SSL_use_PrivateKey_file "SSL *ssl" "const char *file" "int type" +.Ft int +.Fn SSL_use_RSAPrivateKey "SSL *ssl" "RSA *rsa" +.Ft int +.Fn SSL_use_RSAPrivateKey_ASN1 "SSL *ssl" "const unsigned char *d" "long len" +.Ft int +.Fn SSL_use_RSAPrivateKey_file "SSL *ssl" "const char *file" "int type" +.Ft int +.Fn SSL_CTX_check_private_key "const SSL_CTX *ctx" +.Ft int +.Fn SSL_check_private_key "const SSL *ssl" +.Sh DESCRIPTION +These functions load the certificates and private keys into the +.Vt SSL_CTX +or +.Vt SSL +object, respectively. +.Pp +The +.Fn SSL_CTX_* +class of functions loads the certificates and keys into the +.Vt SSL_CTX +object +.Fa ctx . +The information is passed to +.Vt SSL +objects +.Fa ssl +created from +.Fa ctx +with +.Xr SSL_new 3 +by copying, so that changes applied to +.Fa ctx +do not propagate to already existing +.Vt SSL +objects. +.Pp +The +.Fn SSL_* +class of functions only loads certificates and keys into a specific +.Vt SSL +object. +The specific information is kept when +.Xr SSL_clear 3 +is called for this +.Vt SSL +object. +.Pp +.Fn SSL_CTX_use_certificate +loads the certificate +.Fa x +into +.Fa ctx ; +.Fn SSL_use_certificate +loads +.Fa x +into +.Fa ssl . +The rest of the certificates needed to form the complete certificate chain can +be specified using the +.Xr SSL_CTX_add_extra_chain_cert 3 +function. +.Pp +.Fn SSL_CTX_use_certificate_ASN1 +loads the ASN1 encoded certificate from the memory location +.Fa d +(with length +.Fa len ) +into +.Fa ctx ; +.Fn SSL_use_certificate_ASN1 +loads the ASN1 encoded certificate into +.Fa ssl . +.Pp +.Fn SSL_CTX_use_certificate_file +loads the first certificate stored in +.Fa file +into +.Fa ctx . +The formatting +.Fa type +of the certificate must be specified from the known types +.Dv SSL_FILETYPE_PEM +and +.Dv SSL_FILETYPE_ASN1 . +.Fn SSL_use_certificate_file +loads the certificate from +.Fa file +into +.Fa ssl . +See the +.Sx NOTES +section on why +.Fn SSL_CTX_use_certificate_chain_file +should be preferred. +.Pp +The +.Fn SSL_CTX_use_certificate_chain* +functions load a certificate chain into +.Fa ctx . +The certificates must be in PEM format and must be sorted starting with the +subject's certificate (actual client or server certificate), +followed by intermediate CA certificates if applicable, +and ending at the highest level (root) CA. +With the exception of +.Fn SSL_use_certificate_chain_file , +there is no corresponding function working on a single +.Vt SSL +object. +.Pp +.Fn SSL_CTX_use_PrivateKey +adds +.Fa pkey +as private key to +.Fa ctx . +.Fn SSL_CTX_use_RSAPrivateKey +adds the private key +.Fa rsa +of type RSA to +.Fa ctx . +.Fn SSL_use_PrivateKey +adds +.Fa pkey +as private key to +.Fa ssl ; +.Fn SSL_use_RSAPrivateKey +adds +.Fa rsa +as private key of type RSA to +.Fa ssl . +If a certificate has already been set and the private does not belong to the +certificate, an error is returned. +To change a certificate private key pair, +the new certificate needs to be set with +.Fn SSL_use_certificate +or +.Fn SSL_CTX_use_certificate +before setting the private key with +.Fn SSL_CTX_use_PrivateKey +or +.Fn SSL_use_PrivateKey . +.Pp +.Fn SSL_CTX_use_PrivateKey_ASN1 +adds the private key of type +.Fa pk +stored at memory location +.Fa d +(length +.Fa len ) +to +.Fa ctx . +.Fn SSL_CTX_use_RSAPrivateKey_ASN1 +adds the private key of type RSA stored at memory location +.Fa d +(length +.Fa len ) +to +.Fa ctx . +.Fn SSL_use_PrivateKey_ASN1 +and +.Fn SSL_use_RSAPrivateKey_ASN1 +add the private key to +.Fa ssl . +.Pp +.Fn SSL_CTX_use_PrivateKey_file +adds the first private key found in +.Fa file +to +.Fa ctx . +The formatting +.Fa type +of the private key must be specified from the known types +.Dv SSL_FILETYPE_PEM +and +.Dv SSL_FILETYPE_ASN1 . +.Fn SSL_CTX_use_RSAPrivateKey_file +adds the first private RSA key found in +.Fa file +to +.Fa ctx . +.Fn SSL_use_PrivateKey_file +adds the first private key found in +.Fa file +to +.Fa ssl ; +.Fn SSL_use_RSAPrivateKey_file +adds the first private RSA key found to +.Fa ssl . +.Pp +The +.Fn SSL_CTX_check_private_key +function is seriously misnamed. +It compares the +.Em public +key components and parameters of an OpenSSL private key with the +corresponding certificate loaded into +.Fa ctx . +If more than one key/certificate pair (RSA/ECDSA) is installed, +the last item installed will be compared. +If, e.g., the last item was an RSA certificate or key, +the RSA key/certificate pair will be checked. +.Fn SSL_check_private_key +performs the same +.Em public +key comparison for +.Fa ssl . +If no key/certificate was explicitly added for this +.Fa ssl , +the last item added into +.Fa ctx +will be checked. +.Pp +Despite the name, neither +.Fn SSL_CTX_check_private_key +nor +.Fn SSL_check_private_key +checks whether the private key component is indeed a private key, +nor whether it matches the public key component. +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. +.Sh 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 +.Xr SSL_CTX_set_cipher_list 3 . +.Pp +When reading certificates and private keys from file, files of type +.Dv SSL_FILETYPE_ASN1 +(also known as +.Em DER , +binary encoding) can only contain one certificate or private key; consequently, +.Fn SSL_CTX_use_certificate_chain_file +is only applicable to PEM formatting. +Files of type +.Dv SSL_FILETYPE_PEM +can contain more than one item. +.Pp +.Fn SSL_CTX_use_certificate_chain_file +adds the first certificate found in the file to the certificate store. +The other certificates are added to the store of chain certificates using +.Xr SSL_CTX_add1_chain_cert 3 . +It is recommended to use the +.Fn SSL_CTX_use_certificate_chain_file +instead of the +.Fn SSL_CTX_use_certificate_file +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 +.Xr SSL_CTX_load_verify_locations 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 +.Xr SSL_CTX_set_default_passwd_cb 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.) +.Sh RETURN VALUES +On success, the functions return 1. +Otherwise check out the error stack to find out the reason. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_add1_chain_cert 3 , +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_cipher_list 3 , +.Xr SSL_CTX_set_client_CA_list 3 , +.Xr SSL_CTX_set_client_cert_cb 3 , +.Xr SSL_CTX_set_default_passwd_cb 3 , +.Xr SSL_new 3 , +.Xr X509_check_private_key 3 +.Sh HISTORY +.Fn SSL_use_certificate , +.Fn SSL_use_certificate_file , +.Fn SSL_use_RSAPrivateKey , +and +.Fn SSL_use_RSAPrivateKey_file +appeared in SSLeay 0.4 or earlier. +.Fn SSL_use_certificate_ASN1 +and +.Fn SSL_use_RSAPrivateKey_ASN1 +first appeared in SSLeay 0.5.1. +.Fn SSL_use_PrivateKey_file , +.Fn SSL_use_PrivateKey_ASN1 , +and +.Fn SSL_use_PrivateKey +first appeared in SSLeay 0.6.0. +.Fn SSL_CTX_use_certificate , +.Fn SSL_CTX_use_certificate_ASN1 , +.Fn SSL_CTX_use_certificate_file , +.Fn SSL_CTX_use_PrivateKey , +.Fn SSL_CTX_use_PrivateKey_ASN1 , +.Fn SSL_CTX_use_PrivateKey_file , +.Fn SSL_CTX_use_RSAPrivateKey , +.Fn SSL_CTX_use_RSAPrivateKey_ASN1 , +and +.Fn SSL_CTX_use_RSAPrivateKey_file +first appeared in SSLeay 0.6.1. +.Fn SSL_CTX_check_private_key +and +.Fn SSL_check_private_key +first appeared in SSLeay 0.6.5. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn SSL_CTX_use_certificate_chain_file +first appeared in OpenSSL 0.9.4 and has been available since +.Ox 2.6 . +.Pp +.Fn SSL_use_certificate_chain_file +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.9 . +.Pp +Support for DER encoded private keys +.Pq Dv SSL_FILETYPE_ASN1 +in +.Fn SSL_CTX_use_PrivateKey_file +and +.Fn SSL_use_PrivateKey_file +was added in 0.9.8. +.Pp +.Fn SSL_CTX_use_certificate_chain_mem +first appeared in +.Ox 5.7 . diff --git a/static/openbsd/man3/SSL_SESSION_free.3 b/static/openbsd/man3/SSL_SESSION_free.3 new file mode 100644 index 00000000..af02a273 --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_free.3 @@ -0,0 +1,149 @@ +.\" $OpenBSD: SSL_SESSION_free.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL b31db505 Mar 24 16:01:50 2017 +0000 +.\" +.\" This file was written by Lutz Jaenicke +.\" and Matt Caswell . +.\" Copyright (c) 2000, 2001, 2009, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_FREE 3 +.Os +.Sh NAME +.Nm SSL_SESSION_up_ref , +.Nm SSL_SESSION_free +.Nd SSL_SESSION reference counting +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_SESSION_up_ref "SSL_SESSION *session" +.Ft void +.Fn SSL_SESSION_free "SSL_SESSION *session" +.Sh DESCRIPTION +.Fn SSL_SESSION_up_ref +increments the reference count of the given +.Fa session +by 1. +.Pp +.Fn SSL_SESSION_free +decrements the reference count of the given +.Fa session +by 1. +If the reference count reaches 0, it frees the memory used by the +.Fa session . +If +.Fa session +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Vt SSL_SESSION +objects are allocated when a TLS/SSL handshake operation is successfully +completed. +Depending on the settings, see +.Xr SSL_CTX_set_session_cache_mode 3 , +the +.Vt SSL_SESSION +objects are internally referenced by the +.Vt SSL_CTX +and linked into its session cache. +.Vt SSL +objects may be using the +.Vt SSL_SESSION +object; as a session may be reused, several +.Vt SSL +objects may be using one +.Vt SSL_SESSION +object at the same time. +It is therefore crucial to keep the reference count (usage information) correct +and not delete a +.Vt 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 +.Vt SSL_SESSION +object is completely freed as the reference count incorrectly becomes 0, but it +is still referenced in the internal session cache and the cache list is +processed during a +.Xr SSL_CTX_flush_sessions 3 +operation. +.Pp +.Fn SSL_SESSION_free +must only be called for +.Vt SSL_SESSION +objects, for which the reference count was explicitly incremented (e.g., by +calling +.Xr SSL_get1_session 3 ; +see +.Xr SSL_get_session 3 ) +or when the +.Vt SSL_SESSION +object was generated outside a TLS handshake operation, e.g., by using +.Xr d2i_SSL_SESSION 3 . +It must not be called on other +.Vt SSL_SESSION +objects, as this would cause incorrect reference counts and therefore program +failures. +.Sh RETURN VALUES +.Fn SSL_SESSION_up_ref +returns 1 on success or 0 on error. +.Sh SEE ALSO +.Xr d2i_SSL_SESSION 3 , +.Xr ssl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +.Fn SSL_SESSION_free +first appeared in SSLeay 0.5.2 and has been available since +.Ox 2.4 . +.Pp +.Fn SSL_SESSION_up_ref +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_SESSION_get0_cipher.3 b/static/openbsd/man3/SSL_SESSION_get0_cipher.3 new file mode 100644 index 00000000..4e5b0bb0 --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_get0_cipher.3 @@ -0,0 +1,95 @@ +.\" $OpenBSD: SSL_SESSION_get0_cipher.3,v 1.2 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL d42e7759f Mar 30 19:40:04 2017 +0200 +.\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Rich Salz . +.\" Copyright (c) 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_GET0_CIPHER 3 +.Os +.Sh NAME +.Nm SSL_SESSION_get0_cipher +.Nd retrieve the SSL cipher associated with a session +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft const SSL_CIPHER * +.Fo SSL_SESSION_get0_cipher +.Fa "const SSL_SESSION *session" +.Fc +.Sh DESCRIPTION +.Fn SSL_SESSION_get0_cipher +retrieves the cipher that was used by the connection when the session +was created, or +.Dv NULL +if it cannot be determined. +.Pp +The value returned is a pointer to an object maintained within +.Fa session +and should not be released. +.Sh RETURN VALUES +.Fn SSL_SESSION_get0_cipher +returns the +.Vt SSL_CIPHER +associated with +.Fa session +or +.Dv NULL +if it cannot be determined. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CIPHER_get_name 3 , +.Xr SSL_get_current_cipher 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +The +.Fn SSL_SESSION_get0_cipher +function first appeared in OpenSSL 1.1.0 +and has been available since +.Ox 7.0 . diff --git a/static/openbsd/man3/SSL_SESSION_get0_peer.3 b/static/openbsd/man3/SSL_SESSION_get0_peer.3 new file mode 100644 index 00000000..98ae1bab --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_get0_peer.3 @@ -0,0 +1,81 @@ +.\" $OpenBSD: SSL_SESSION_get0_peer.3,v 1.3 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL SSL_SESSION_get0_peer.pod b31db505 Mar 24 16:01:50 2017 +0000 +.\" +.\" This file was written by Matt Caswell +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_GET0_PEER 3 +.Os +.Sh NAME +.Nm SSL_SESSION_get0_peer +.Nd get details about peer's certificate for a session +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft X509 * +.Fo SSL_SESSION_get0_peer +.Fa "SSL_SESSION *s" +.Fc +.Sh DESCRIPTION +.Fn SSL_SESSION_get0_peer +returns a pointer to the peer certificate associated with the session +.Fa s +or +.Dv NULL +if no peer certificate is available. +The caller should not free the returned value, unless +.Xr X509_up_ref 3 +has also been called. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +.Fn SSL_SESSION_get0_peer +first appeared in OpenSSL 1.0.1 and has been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/SSL_SESSION_get_compress_id.3 b/static/openbsd/man3/SSL_SESSION_get_compress_id.3 new file mode 100644 index 00000000..da0d48ff --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_get_compress_id.3 @@ -0,0 +1,79 @@ +.\" $OpenBSD: SSL_SESSION_get_compress_id.3,v 1.4 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL SSL_SESSION_get_compress_id.pod b31db505 Mar 24 16:01:50 2017 +.\" +.\" This file was written by Matt Caswell +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_GET_COMPRESS_ID 3 +.Os +.Sh NAME +.Nm SSL_SESSION_get_compress_id +.Nd get details about the compression associated with a session +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft unsigned int +.Fo SSL_SESSION_get_compress_id +.Fa "const SSL_SESSION *s" +.Fc +.Sh DESCRIPTION +If compression has been negotiated for an ssl session, +.Fn SSL_SESSION_get_compress_id +returns 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 SEE ALSO +.Xr ssl 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_get_id 3 , +.Xr SSL_SESSION_get_protocol_version 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +.Fn SSL_SESSION_get_compress_id +first appeared in OpenSSL 1.0.1 and has been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/SSL_SESSION_get_ex_new_index.3 b/static/openbsd/man3/SSL_SESSION_get_ex_new_index.3 new file mode 100644 index 00000000..55cde1c6 --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_get_ex_new_index.3 @@ -0,0 +1,135 @@ +.\" $OpenBSD: SSL_SESSION_get_ex_new_index.3,v 1.4 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm SSL_SESSION_get_ex_new_index , +.Nm SSL_SESSION_set_ex_data , +.Nm SSL_SESSION_get_ex_data +.Nd internal application specific data functions +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_SESSION_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fn SSL_SESSION_set_ex_data "SSL_SESSION *session" "int idx" "void *arg" +.Ft void * +.Fn SSL_SESSION_get_ex_data "const SSL_SESSION *session" "int idx" +.Bd -literal + 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); +.Ed +.Sh 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 +.Fn SSL_SESSION_get_ex_new_index +is used to register a new index for application-specific data. +.Pp +.Fn SSL_SESSION_set_ex_data +is used to store application data at +.Fa arg +for +.Fa idx +into the +.Fa session +object. +.Pp +.Fn SSL_SESSION_get_ex_data +is used to retrieve the information for +.Fa idx +from +.Fa session . +.Pp +A detailed description for the +.Fn *_get_ex_new_index +functionality +can be found in +.Xr RSA_get_ex_new_index 3 . +The +.Fn *_get_ex_data +and +.Fn *_set_ex_data +functionality is described in +.Xr CRYPTO_set_ex_data 3 . +.Sh WARNINGS +The application data is only maintained for sessions held in memory. +The application data is not included when dumping the session with +.Xr i2d_SSL_SESSION 3 +(and all functions indirectly calling the dump functions like +.Xr PEM_write_SSL_SESSION 3 +and +.Xr PEM_write_bio_SSL_SESSION 3 ) +and can therefore not be restored. +.Sh SEE ALSO +.Xr CRYPTO_set_ex_data 3 , +.Xr RSA_get_ex_new_index 3 , +.Xr ssl 3 +.Sh HISTORY +.Fn SSL_SESSION_get_ex_new_index , +.Fn SSL_SESSION_set_ex_data , +and +.Fn SSL_SESSION_get_ex_data +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_SESSION_get_id.3 b/static/openbsd/man3/SSL_SESSION_get_id.3 new file mode 100644 index 00000000..eb14d241 --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_get_id.3 @@ -0,0 +1,113 @@ +.\" $OpenBSD: SSL_SESSION_get_id.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL SSL_SESSION_set1_id 17b60280 Dec 21 09:08:25 2017 +0100 +.\" +.\" This file was written by Remi Gacogne +.\" and Matt Caswell . +.\" Copyright (c) 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_GET_ID 3 +.Os +.Sh NAME +.Nm SSL_SESSION_get_id , +.Nm SSL_SESSION_set1_id +.Nd get and set the SSL session ID +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft const unsigned char * +.Fo SSL_SESSION_get_id +.Fa "const SSL_SESSION *s" +.Fa "unsigned int *len" +.Fc +.Ft int +.Fo SSL_SESSION_set1_id +.Fa "SSL_SESSION *s" +.Fa "const unsigned char *sid" +.Fa "unsigned int sid_len" +.Fc +.Sh DESCRIPTION +.Fn SSL_SESSION_get_id +returns a pointer to the internal session ID value for the session +.Fa s . +The length of the ID in bytes is stored in +.Pf * Fa len . +The length may be 0. +The caller should not free the returned pointer directly. +.Pp +.Fn SSL_SESSION_set1_id +sets the session ID for +.Fa s +to a copy of the +.Fa sid +of length +.Fa sid_len . +.Sh RETURN VALUES +.Fn SSL_SESSION_get_id +returns a pointer to the session ID value. +.Pp +.Fn SSL_SESSION_set1_id +returns 1 for success and 0 for failure, +for example if the supplied session ID length exceeds +.Dv SSL_MAX_SSL_SESSION_ID_LENGTH . +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_copy_session_id 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_get_compress_id 3 , +.Xr SSL_SESSION_get_protocol_version 3 , +.Xr SSL_SESSION_has_ticket 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +.Fn SSL_SESSION_get_id +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Pp +.Fn SSL_SESSION_set1_id +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_SESSION_get_protocol_version.3 b/static/openbsd/man3/SSL_SESSION_get_protocol_version.3 new file mode 100644 index 00000000..dad9eab7 --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_get_protocol_version.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: SSL_SESSION_get_protocol_version.3,v 1.3 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by TJ Saunders +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_GET_PROTOCOL_VERSION 3 +.Os +.Sh NAME +.Nm SSL_SESSION_get_protocol_version +.Nd get the session protocol version +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_SESSION_get_protocol_version +.Fa "const SSL_SESSION *s" +.Fc +.Sh DESCRIPTION +.Fn SSL_SESSION_get_protocol_version +returns the protocol version number used by the session +.Fa s . +.Sh RETURN VALUES +.Fn SSL_SESSION_get_protocol_version +returns a constant like +.Dv TLS1_VERSION +or +.Dv TLS1_2_VERSION . +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_get0_peer 3 , +.Xr SSL_SESSION_get_compress_id 3 , +.Xr SSL_SESSION_get_id 3 , +.Xr SSL_SESSION_get_time 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +.Fn SSL_SESSION_get_protocol_version +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_SESSION_get_time.3 b/static/openbsd/man3/SSL_SESSION_get_time.3 new file mode 100644 index 00000000..28aeedf7 --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_get_time.3 @@ -0,0 +1,166 @@ +.\" $OpenBSD: SSL_SESSION_get_time.3,v 1.9 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005, 2006, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_GET_TIME 3 +.Os +.Sh NAME +.Nm SSL_SESSION_get_time , +.Nm SSL_SESSION_set_time , +.Nm SSL_SESSION_get_timeout , +.Nm SSL_SESSION_set_timeout , +.Nm SSL_get_time , +.Nm SSL_set_time , +.Nm SSL_get_timeout , +.Nm SSL_set_timeout +.Nd retrieve and manipulate session time and timeout settings +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_SESSION_get_time "const SSL_SESSION *s" +.Ft long +.Fn SSL_SESSION_set_time "SSL_SESSION *s" "long tm" +.Ft long +.Fn SSL_SESSION_get_timeout "const SSL_SESSION *s" +.Ft long +.Fn SSL_SESSION_set_timeout "SSL_SESSION *s" "long tm" +.Ft long +.Fn SSL_get_time "const SSL_SESSION *s" +.Ft long +.Fn SSL_set_time "SSL_SESSION *s" "long tm" +.Ft long +.Fn SSL_get_timeout "const SSL_SESSION *s" +.Ft long +.Fn SSL_set_timeout "SSL_SESSION *s" "long tm" +.Sh DESCRIPTION +.Fn SSL_SESSION_get_time +returns the time at which the session +.Fa s +was established. +The time is given in seconds since the Epoch and therefore compatible to the +time delivered by the +.Xr time 3 +call. +.Pp +.Fn SSL_SESSION_set_time +replaces the creation time of the session +.Fa s +with +the chosen value +.Fa tm . +.Pp +.Fn SSL_SESSION_get_timeout +returns the timeout value set for session +.Fa s +in seconds. +.Pp +.Fn SSL_SESSION_set_timeout +sets the timeout value for session +.Fa s +in seconds to +.Fa tm . +.Pp +The +.Fn SSL_get_time , +.Fn SSL_set_time , +.Fn SSL_get_timeout , +and +.Fn SSL_set_timeout +functions are synonyms for the +.Fn SSL_SESSION_* +counterparts. +.Pp +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 +.Xr SSL_CTX_set_timeout 3 . +Using these functions it is possible to extend or shorten the lifetime of the +session. +.Sh RETURN VALUES +.Fn SSL_SESSION_get_time +and +.Fn SSL_SESSION_get_timeout +return the currently valid values. +.Pp +.Fn SSL_SESSION_set_time +and +.Fn SSL_SESSION_set_timeout +return 1 on success. +.Pp +If any of the function is passed the +.Dv NULL +pointer for the session +.Fa s , +0 is returned. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_timeout 3 , +.Xr SSL_get_default_timeout 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_has_ticket 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +.Fn SSL_get_time , +.Fn SSL_get_timeout , +and +.Fn SSL_set_timeout +appeared in SSLeay 0.4 or earlier. +.Fn SSL_set_time +first appeared in SSLeay 0.5.2. +.Fn SSL_SESSION_get_time , +.Fn SSL_SESSION_set_time , +.Fn SSL_SESSION_get_timeout , +and +.Fn SSL_SESSION_set_timeout +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_SESSION_has_ticket.3 b/static/openbsd/man3/SSL_SESSION_has_ticket.3 new file mode 100644 index 00000000..07b894c4 --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_has_ticket.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: SSL_SESSION_has_ticket.3,v 1.3 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL f2baac27 Feb 8 15:43:16 2015 +0000 +.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_HAS_TICKET 3 +.Os +.Sh NAME +.Nm SSL_SESSION_has_ticket , +.Nm SSL_SESSION_get_ticket_lifetime_hint +.Nd get details about the ticket associated with a session +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_SESSION_has_ticket +.Fa "const SSL_SESSION *s" +.Fc +.Ft unsigned long +.Fo SSL_SESSION_get_ticket_lifetime_hint +.Fa "const SSL_SESSION *s" +.Fc +.Sh DESCRIPTION +.Fn SSL_SESSION_has_ticket +returns 1 if there is a Session Ticket associated with +.Fa s +or 0 otherwise. +.Pp +.Fn SSL_SESSION_get_ticket_lifetime_hint +returns the lifetime hint in seconds associated with the session ticket. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_SESSION_get_id 3 , +.Xr SSL_SESSION_get_time 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_SESSION_is_resumable.3 b/static/openbsd/man3/SSL_SESSION_is_resumable.3 new file mode 100644 index 00000000..ddc037c1 --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_is_resumable.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: SSL_SESSION_is_resumable.3,v 1.2 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_IS_RESUMABLE 3 +.Os +.Sh NAME +.Nm SSL_SESSION_is_resumable +.Nd determine whether an SSL_SESSION object can be used for resumption +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_SESSION_is_resumable +.Fa "const SSL_SESSION *session" +.Fc +.Sh DESCRIPTION +.Fn SSL_SESSION_is_resumable +determines whether the +.Fa session +object can be used to resume a session. +Note that attempting to resume with a non-resumable session +will result in a full handshake. +.Sh RETURN VALUES +.Fn SSL_SESSION_is_resumable +returns 1 if the session is resumable or 0 otherwise. +It always returns 0 with LibreSSL. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_sess_set_new_cb 3 , +.Xr SSL_get_session 3 +.Sh HISTORY +.Fn SSL_SESSION_is_resumable +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 7.0 . diff --git a/static/openbsd/man3/SSL_SESSION_new.3 b/static/openbsd/man3/SSL_SESSION_new.3 new file mode 100644 index 00000000..182266a3 --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_new.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: SSL_SESSION_new.3,v 1.12 2025/10/24 13:18:22 tb Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: October 24 2025 $ +.Dt SSL_SESSION_NEW 3 +.Os +.Sh NAME +.Nm SSL_SESSION_new , +.Nm SSL_SESSION_dup +.Nd construct a new SSL_SESSION object +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft SSL_SESSION * +.Fn SSL_SESSION_new void +.Ft SSL_SESSION * +.Fn SSL_SESSION_dup "const SSL_SESSION *src" +.Sh DESCRIPTION +.Fn SSL_SESSION_new +allocates and initializes a new +.Vt SSL_SESSION +object. +The reference count is set to 1, the time to the current time, and +the timeout to five minutes. +.Pp +When the object is no longer needed, it can be destructed with +.Xr SSL_SESSION_free 3 . +.Pp +.Fn SSL_SESSION_new +is used internally, for example by +.Xr SSL_connect 3 . +.Pp +.Fn SSL_SESSION_dup +creates a deep copy of +.Fa src +with the exception that +the reference count is set to 1, that +the peer certificate is shared with +.Fa src , +and that the new session is not part of any session cache. +.Sh RETURN VALUES +.Fn SSL_SESSION_new +and +.Fn SSL_SESSION_dup +return the new +.Vt SSL_SESSION +object or +.Dv NULL +if insufficient memory is available. +.Pp +After failure, +.Xr ERR_get_error 3 +returns +.Dv ERR_R_MALLOC_FAILURE . +.Sh SEE ALSO +.Xr d2i_SSL_SESSION 3 , +.Xr PEM_read_SSL_SESSION 3 , +.Xr ssl 3 , +.Xr SSL_connect 3 , +.Xr SSL_copy_session_id 3 , +.Xr SSL_CTX_add_session 3 , +.Xr SSL_CTX_sess_set_get_cb 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_free 3 , +.Xr SSL_SESSION_get0_peer 3 , +.Xr SSL_SESSION_get_compress_id 3 , +.Xr SSL_SESSION_get_ex_new_index 3 , +.Xr SSL_SESSION_get_id 3 , +.Xr SSL_SESSION_get_master_key 3 , +.Xr SSL_SESSION_get_protocol_version 3 , +.Xr SSL_SESSION_get_time 3 , +.Xr SSL_SESSION_has_ticket 3 , +.Xr SSL_SESSION_is_resumable 3 , +.Xr SSL_SESSION_print 3 , +.Xr SSL_SESSION_set1_id_context 3 , +.Xr SSL_set_session 3 +.Sh HISTORY +.Fn SSL_SESSION_new +first appeared in SSLeay 0.5.2 and has been available since +.Ox 2.4 . +.Pp +.Fn SSL_SESSION_dup +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 7.9 . diff --git a/static/openbsd/man3/SSL_SESSION_print.3 b/static/openbsd/man3/SSL_SESSION_print.3 new file mode 100644 index 00000000..65742140 --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_print.3 @@ -0,0 +1,75 @@ +.\" $OpenBSD: SSL_SESSION_print.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_PRINT 3 +.Os +.Sh NAME +.Nm SSL_SESSION_print , +.Nm SSL_SESSION_print_fp +.Nd print some properties of an SSL_SESSION object +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_SESSION_print +.Fa "BIO *bp" +.Fa "const SSL_SESSION *session" +.Fc +.Ft int +.Fo SSL_SESSION_print_fp +.Fa "FILE *fp" +.Fa "const SSL_SESSION *session" +.Fc +.Sh DESCRIPTION +.Fn SSL_SESSION_print +prints some properties of +.Fa session +in a human-readable format to the +.Fa "BIO *bp" , +including protocol version, cipher name, session ID, +session ID context, master key, session ticket lifetime hint, +session ticket, start time, timeout, and verify return code. +.Pp +.Fn SSL_SESSION_print_fp +does the same as +.Fn SSL_SESSION_print +except that it prints to the +.Fa "FILE *fp" . +.Sh RETURN VALUES +.Fn SSL_SESSION_print +and +.Fn SSL_SESSION_print_fp +return 1 for success or 0 for failure. +.Pp +In some cases, the reason for failure can be determined with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr d2i_SSL_SESSION 3 , +.Xr PEM_read_SSL_SESSION 3 , +.Xr ssl 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_free 3 , +.Xr SSL_SESSION_get_ex_new_index 3 , +.Xr SSL_SESSION_get_time 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +.Fn SSL_SESSION_print +first appeared in SSLeay 0.5.2. +.Fn SSL_SESSION_print_fp +first appeared in SSLeay 0.6.0. +Both functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_SESSION_set1_id_context.3 b/static/openbsd/man3/SSL_SESSION_set1_id_context.3 new file mode 100644 index 00000000..24f1de4f --- /dev/null +++ b/static/openbsd/man3/SSL_SESSION_set1_id_context.3 @@ -0,0 +1,114 @@ +.\" $OpenBSD: SSL_SESSION_set1_id_context.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL SSL_SESSION_get0_id_context b31db505 Mar 24 16:01:50 2017 +.\" +.\" This file was written by Matt Caswell +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_SET1_ID_CONTEXT 3 +.Os +.Sh NAME +.Nm SSL_SESSION_get0_id_context , +.Nm SSL_SESSION_set1_id_context +.Nd get and set the SSL ID context associated with a session +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft const unsigned char * +.Fo SSL_SESSION_get0_id_context +.Fa "const SSL_SESSION *s" +.Fa "unsigned int *len" +.Fc +.Ft int +.Fo SSL_SESSION_set1_id_context +.Fa "SSL_SESSION *s" +.Fa "const unsigned char *sid_ctx" +.Fa "unsigned int sid_ctx_len" +.Fc +.Sh DESCRIPTION +.Fn SSL_SESSION_get0_id_context +returns the ID context associated with +.Fa s . +The length of the ID context in bytes is written to +.Pf * Fa len +if +.Fa len +is not +.Dv NULL . +.Pp +.Fn SSL_SESSION_set1_id_context +takes a copy of the provided ID context given in +.Fa sid_ctx +and associates it with the session +.Fa s . +The length of the ID context is given by +.Fa sid_ctx_len +which must not exceed +.Dv SSL_MAX_SID_CTX_LENGTH +bytes. +.Sh RETURN VALUES +.Fn SSL_SESSION_get0_id_context +returns an internal pointer to an object maintained within +.Fa s +that should not be freed by the caller. +.Pp +.Fn SSL_SESSION_set1_id_context +returns 1 on success or 0 on error. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_session_id_context 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +.Fn SSL_SESSION_set1_id_context +first appeared in OpenSSL 1.0.1 and has been available since +.Ox 5.3 . +.Pp +.Fn SSL_SESSION_get0_id_context +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_accept.3 b/static/openbsd/man3/SSL_accept.3 new file mode 100644 index 00000000..ecb757aa --- /dev/null +++ b/static/openbsd/man3/SSL_accept.3 @@ -0,0 +1,156 @@ +.\" $OpenBSD: SSL_accept.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2002, 2003 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_ACCEPT 3 +.Os +.Sh NAME +.Nm SSL_accept +.Nd wait for a TLS/SSL client to initiate a TLS/SSL handshake +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_accept "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_accept +waits for a TLS/SSL client to initiate the TLS/SSL handshake. +The communication channel must already have been set and assigned to the +.Fa ssl +object by setting an underlying +.Vt BIO . +.Pp +The behaviour of +.Fn SSL_accept +depends on the underlying +.Vt BIO . +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_accept +will only return once the handshake has been finished or an error occurred. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_accept +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_accept +to continue the handshake, indicating the problem by the return value \(mi1. +In this case a call to +.Xr SSL_get_error 3 +with the +return value of +.Fn SSL_accept +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_accept . +The action depends on the underlying +.Dv BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The TLS/SSL handshake was not successful but was shut down controlled and by +the specifications of the TLS/SSL protocol. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.It 1 +The TLS/SSL handshake was successfully completed, +and a TLS/SSL connection has been established. +.It <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 of action is need to continue the operation for non-blocking +.Vt BIO Ns +s. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.El +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_get_error 3 , +.Xr SSL_set_connect_state 3 , +.Xr SSL_shutdown 3 +.Sh HISTORY +.Fn SSL_accept +appeared in SSLeay 0.4 or earlier and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_alert_type_string.3 b/static/openbsd/man3/SSL_alert_type_string.3 new file mode 100644 index 00000000..0f051cc0 --- /dev/null +++ b/static/openbsd/man3/SSL_alert_type_string.3 @@ -0,0 +1,254 @@ +.\" $OpenBSD: SSL_alert_type_string.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2011 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_ALERT_TYPE_STRING 3 +.Os +.Sh NAME +.Nm SSL_alert_type_string , +.Nm SSL_alert_type_string_long , +.Nm SSL_alert_desc_string , +.Nm SSL_alert_desc_string_long +.Nd get textual description of alert information +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft const char * +.Fn SSL_alert_type_string "int value" +.Ft const char * +.Fn SSL_alert_type_string_long "int value" +.Ft const char * +.Fn SSL_alert_desc_string "int value" +.Ft const char * +.Fn SSL_alert_desc_string_long "int value" +.Sh DESCRIPTION +.Fn SSL_alert_type_string +returns a one letter string indicating the type of the alert specified by +.Fa value . +.Pp +.Fn SSL_alert_type_string_long +returns a string indicating the type of the alert specified by +.Fa value . +.Pp +.Fn SSL_alert_desc_string +returns a two letter string as a short form describing the reason of the alert +specified by +.Fa value . +.Pp +.Fn SSL_alert_desc_string_long +returns a string describing the reason of the alert specified by +.Fa value . +.Pp +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 +.Dq close notify +alert is sent as a warning alert. +Other examples for non-fatal errors are certificate errors +.Po +.Dq certificate expired , +.Dq unsupported certificate +.Pc , +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 at +its 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 +The following strings can occur for +.Fn SSL_alert_type_string +or +.Fn SSL_alert_type_string_long : +.Bl -tag -width Ds +.It \(dqW\(dq/\(dqwarning\(dq +.It \(dqF\(dq/\(dqfatal\(dq +.It \(dqU\(dq/\(dqunknown\(dq +This indicates that no support is available for this alert type. +Probably +.Fa value +does not contain a correct alert message. +.El +.Pp +The following strings can occur for +.Fn SSL_alert_desc_string +or +.Fn SSL_alert_desc_string_long : +.Bl -tag -width Ds +.It \(dqCN\(dq/\(dqclose notify\(dq +The connection shall be closed. +This is a warning alert. +.It \(dqUM\(dq/\(dqunexpected message\(dq +An inappropriate message was received. +This alert is always fatal and should never be observed in communication +between proper implementations. +.It \(dqBM\(dq/\(dqbad record mac\(dq +This alert is returned if a record is received with an incorrect MAC. +This message is always fatal. +.It \(dqDF\(dq/\(dqdecompression failure\(dq +The decompression function received improper input +(e.g., data that would expand to excessive length). +This message is always fatal. +.It \(dqHF\(dq/\(dqhandshake failure\(dq +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. +.It \(dqNC\(dq/\(dqno certificate\(dq +A client, that was asked to send a certificate, does not send a certificate +(SSLv3 only). +.It \(dqBC\(dq/\(dqbad certificate\(dq +A certificate was corrupt, contained signatures that did not verify correctly, +etc. +.It \(dqUC\(dq/\(dqunsupported certificate\(dq +A certificate was of an unsupported type. +.It \(dqCR\(dq/\(dqcertificate revoked\(dq +A certificate was revoked by its signer. +.It \(dqCE\(dq/\(dqcertificate expired\(dq +A certificate has expired or is not currently valid. +.It \(dqCU\(dq/\(dqcertificate unknown\(dq +Some other (unspecified) issue arose in processing the certificate, +rendering it unacceptable. +.It \(dqIP\(dq/\(dqillegal parameter\(dq +A field in the handshake was out of range or inconsistent with other fields. +This is always fatal. +.It \(dqDC\(dq/\(dqdecryption failed\(dq +A TLSCiphertext decrypted in an invalid way: either it wasn't an even multiple +of the block length or its padding values, when checked, weren't correct. +This message is always fatal. +.It \(dqRO\(dq/\(dqrecord overflow\(dq +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. +.It \(dqCA\(dq/\(dqunknown CA\(dq +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't be matched with a known, trusted CA. +This message is always fatal. +.It \(dqAD\(dq/\(dqaccess denied\(dq +A valid certificate was received, but when access control was applied, +the sender decided not to proceed with negotiation. +This message is always fatal. +.It \(dqDE\(dq/\(dqdecode error\(dq +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. +.It \(dqCY\(dq/\(dqdecrypt error\(dq +A handshake cryptographic operation failed, including being unable to correctly +verify a signature, decrypt a key exchange, or validate a finished message. +.It \(dqER\(dq/\(dqexport restriction\(dq +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. +.It \(dqPV\(dq/\(dqprotocol version\(dq +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. +.It \(dqIS\(dq/\(dqinsufficient security\(dq +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. +.It \(dqIE\(dq/\(dqinternal error\(dq +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. +.It \(dqIF\(dq/\(dqinappropriate fallback\(dq +Sent by a server in response to an invalid connection retry attempt from +a client (see RFC 7507). +.It \(dqUS\(dq/\(dquser canceled\(dq +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. +.It \(dqNR\(dq/\(dqno renegotiation\(dq +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. +.It \(dqUP\(dq/\(dqunknown PSK identity\(dq +Sent by the server to indicate that it does not recognize a PSK identity or an +SRP identity. +.It \(dqCQ\(dq/\(dqcertificate required\(dq +Sent by servers when a client certificate is desired but none was provided +by the client. +.It \(dqAP\(dq/\(dqno application protocol\(dq +Sent by servers when a client ALPN extension advertises only protocols that +the server does not support (see RFC 7301). +.It \(dqUK\(dq/\(dqunknown\(dq +This indicates that no description is available for this alert type. +Probably +.Fa value +does not contain a correct alert message. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_info_callback 3 +.Sh HISTORY +These functions first appeared in SSLeay 0.8.0 +and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_clear.3 b/static/openbsd/man3/SSL_clear.3 new file mode 100644 index 00000000..5e4da125 --- /dev/null +++ b/static/openbsd/man3/SSL_clear.3 @@ -0,0 +1,145 @@ +.\" $OpenBSD: SSL_clear.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2002, 2011, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CLEAR 3 +.Os +.Sh NAME +.Nm SSL_clear +.Nd reset SSL object to allow another connection +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_clear "SSL *ssl" +.Sh DESCRIPTION +Reset +.Fa ssl +to allow another connection. +All settings (method, ciphers, BIOs) are kept. +.Pp +.Fn SSL_clear +is used to prepare an +.Vt 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 +.Em open , +it is considered bad and will be removed from the session cache, +as required by RFC 2246. +A session is considered open if +.Xr SSL_shutdown 3 +was not called for the connection or at least +.Xr SSL_set_shutdown 3 +was used to +set the +.Dv 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 for example the special method used during the +session will be kept for the next handshake. +So if the session was a TLSv1 session, a +.Vt SSL +client object will use a TLSv1 client method for the next handshake and a +.Vt SSL +server object will use a TLSv1 server method, even if +.Fn TLS_*_method Ns s +were chosen on startup. +This might lead to connection failures (see +.Xr SSL_new 3 ) +for a description of the method's properties. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The +.Fn SSL_clear +operation could not be performed. +Check the error stack to find out the reason. +.It 1 +The +.Fn SSL_clear +operation was successful. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_client_cert_cb 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_free 3 , +.Xr SSL_new 3 , +.Xr SSL_set_shutdown 3 , +.Xr SSL_shutdown 3 +.Sh HISTORY +.Fn SSL_clear +first appeared in SSLeay 0.4.5b and has been available since +.Ox 2.4 . +.Sh CAVEATS +.Fn SSL_clear +resets the +.Vt 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 +.Xr SSL_get_session 3 ; +.Xr SSL_new 3 ; +.Xr SSL_set_session 3 ; +.Xr SSL_free 3 +instead to avoid such failures (or simply +.Xr SSL_free 3 ; +.Xr SSL_new 3 +if session reuse is not desired). diff --git a/static/openbsd/man3/SSL_connect.3 b/static/openbsd/man3/SSL_connect.3 new file mode 100644 index 00000000..a0cd8f84 --- /dev/null +++ b/static/openbsd/man3/SSL_connect.3 @@ -0,0 +1,155 @@ +.\" $OpenBSD: SSL_connect.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2002, 2003 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_CONNECT 3 +.Os +.Sh NAME +.Nm SSL_connect +.Nd initiate the TLS/SSL handshake with a TLS/SSL server +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_connect "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_connect +initiates the TLS/SSL handshake with a server. +The communication channel must already have been set and assigned to the +.Fa ssl +by setting an underlying +.Vt BIO . +.Pp +The behaviour of +.Fn SSL_connect +depends on the underlying +.Vt BIO . +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_connect +will only return once the handshake has been finished or an error occurred. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_connect +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_connect +to continue the handshake, indicating the problem with the return value \(mi1. +In this case a call to +.Xr SSL_get_error 3 +with the return value of +.Fn SSL_connect +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_connect . +The action depends on the underlying +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.It 1 +The TLS/SSL handshake was successfully completed, +and a TLS/SSL connection has been established. +.It <0 +The TLS/SSL handshake was not successful, because either a fatal error occurred +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 +non-blocking +.Vt BIO Ns s . +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.El +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_get_error 3 , +.Xr SSL_set_connect_state 3 , +.Xr SSL_shutdown 3 +.Sh HISTORY +.Fn SSL_connect +appeared in SSLeay 0.4 or earlier and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_copy_session_id.3 b/static/openbsd/man3/SSL_copy_session_id.3 new file mode 100644 index 00000000..75a52e88 --- /dev/null +++ b/static/openbsd/man3/SSL_copy_session_id.3 @@ -0,0 +1,80 @@ +.\" $OpenBSD: SSL_copy_session_id.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt SSL_COPY_SESSION_ID 3 +.Os +.Sh NAME +.Nm SSL_copy_session_id +.Nd copy session details between SSL objects +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_copy_session_id +.Fa "SSL *to" +.Fa "const SSL *from" +.Fc +.Sh DESCRIPTION +.Fn SSL_copy_session_id +copies the following data from +.Fa from +to +.Fa to : +.Bl -dash +.It +the pointer to the +.Vt SSL_SESSION +object, incrementing its reference count by 1 +.It +the pointer to the +.Vt SSL_METHOD +object; if that changes the method, protocol-specific data is +reinitialized +.It +the pointer to the +.Vt CERT +object, incrementing its reference count by 1 +.It +the session ID context +.El +.Pp +This function is used internally by +.Xr SSL_dup 3 +and by +.Xr BIO_ssl_copy_session_id 3 . +.Sh RETURN VALUES +.Fn SSL_copy_session_id +returns 1 on success and 0 on error. +.Sh SEE ALSO +.Xr BIO_ssl_copy_session_id 3 , +.Xr ssl 3 , +.Xr SSL_dup 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_get_id 3 , +.Xr SSL_SESSION_new 3 , +.Xr SSL_set_session 3 , +.Xr SSL_set_session_id_context 3 +.Sh HISTORY +.Fn SSL_copy_session_id +appeared in SSLeay 0.4 or earlier and has been available since +.Ox 2.4 . +.Sh BUGS +Failures of +.Xr CRYPTO_add 3 +are silently ignored and may leave +.Fa to +in an invalid or inconsistent state. diff --git a/static/openbsd/man3/SSL_do_handshake.3 b/static/openbsd/man3/SSL_do_handshake.3 new file mode 100644 index 00000000..78b41db2 --- /dev/null +++ b/static/openbsd/man3/SSL_do_handshake.3 @@ -0,0 +1,153 @@ +.\" $OpenBSD: SSL_do_handshake.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Martin Sjoegren . +.\" Copyright (c) 2002 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_DO_HANDSHAKE 3 +.Os +.Sh NAME +.Nm SSL_do_handshake +.Nd perform a TLS/SSL handshake +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_do_handshake "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_do_handshake +will wait for a 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 +.Xr SSL_set_connect_state 3 +or +.Xr SSL_set_accept_state 3 . +.Pp +The behaviour of +.Fn SSL_do_handshake +depends on the underlying +.Vt BIO . +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_do_handshake +will only return once the handshake has been finished or an error occurred. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_do_handshake +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_do_handshake +to continue the handshake. +In this case a call to +.Xr SSL_get_error 3 +with the return value of +.Fn SSL_do_handshake +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_do_handshake . +The action depends on the underlying +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.It 1 +The TLS/SSL handshake was successfully completed, +and a TLS/SSL connection has been established. +.It <0 +The TLS/SSL handshake was not successful because either a fatal error occurred +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 +non-blocking +.Vt BIO Ns s . +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.El +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_get_error 3 , +.Xr SSL_set_connect_state 3 +.Sh HISTORY +.Fn SSL_do_handshake +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_dup.3 b/static/openbsd/man3/SSL_dup.3 new file mode 100644 index 00000000..f7d999fb --- /dev/null +++ b/static/openbsd/man3/SSL_dup.3 @@ -0,0 +1,63 @@ +.\" $OpenBSD: SSL_dup.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt SSL_DUP 3 +.Os +.Sh NAME +.Nm SSL_dup +.Nd deep copy of an SSL object +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft SSL * +.Fo SSL_dup +.Fa "SSL *ssl" +.Fc +.Sh DESCRIPTION +.Fn SSL_dup +constructs a new +.Vt SSL +object in the same context as +.Fa ssl +and copies much of the contained data from +.Fa ssl +to the new +.Vt SSL +object, but many fields, for example tlsext data, are not copied. +.Pp +As an exception from deep copying, if a session is already established, +the new object shares +.Fa ssl->cert +with the original object. +.Sh RETURN VALUES +.Fn SSL_dup +returns the new +.Vt SSL +object or +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_copy_session_id 3 , +.Xr SSL_free 3 , +.Xr SSL_new 3 , +.Xr SSL_set_security_level 3 +.Sh HISTORY +.Fn SSL_dup +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_dup_CA_list.3 b/static/openbsd/man3/SSL_dup_CA_list.3 new file mode 100644 index 00000000..553c03bd --- /dev/null +++ b/static/openbsd/man3/SSL_dup_CA_list.3 @@ -0,0 +1,56 @@ +.\" $OpenBSD: SSL_dup_CA_list.3,v 1.7 2025/06/08 22:47:20 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt SSL_DUP_CA_LIST 3 +.Os +.Sh NAME +.Nm SSL_dup_CA_list +.Nd deep copy of a stack of X.509 Name objects +.\" The capital "N" in "Name" is intentional (X.509 syntax). +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft STACK_OF(X509_NAME) * +.Fo SSL_dup_CA_list +.Fa "const STACK_OF(X509_NAME) *sk" +.Fc +.Sh DESCRIPTION +.Fn SSL_dup_CA_list +constructs a new +.Vt STACK_OF(X509_NAME) +object and places copies of all the +.Vt X509_NAME +objects found on +.Fa sk +on it. +.Sh RETURN VALUES +.Fn SSL_dup_CA_list +returns the new +.Vt STACK_OF(X509_NAME) +or +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_client_CA_list 3 , +.Xr SSL_get_client_CA_list 3 , +.Xr SSL_load_client_CA_file 3 , +.Xr X509_NAME_new 3 +.Sh HISTORY +.Fn SSL_dup_CA_list +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_export_keying_material.3 b/static/openbsd/man3/SSL_export_keying_material.3 new file mode 100644 index 00000000..d3daa3a5 --- /dev/null +++ b/static/openbsd/man3/SSL_export_keying_material.3 @@ -0,0 +1,134 @@ +.\" $OpenBSD: SSL_export_keying_material.3,v 1.4 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL a599574b Jun 28 17:18:27 2017 +0100 +.\" OpenSSL 23cec1f4 Jun 21 13:55:02 2017 +0100 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_EXPORT_KEYING_MATERIAL 3 +.Os +.Sh NAME +.Nm SSL_export_keying_material +.Nd obtain keying material for application use +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_export_keying_material +.Fa "SSL *s" +.Fa "unsigned char *out" +.Fa "size_t olen" +.Fa "const char *label" +.Fa "size_t llen" +.Fa "const unsigned char *context" +.Fa "size_t contextlen" +.Fa "int use_context" +.Fc +.Sh DESCRIPTION +During the creation of a TLS or DTLS connection, +shared keying material is established between the two endpoints. +The function +.Fn SSL_export_keying_material +enables an application to use some of this keying material +for its own purposes in accordance with RFC 5705. +.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 +.Fa s , +.Fa olen +bytes of data will be written to +.Fa out . +The application specific context should be supplied +in the location pointed to by +.Fa context +and should be +.Fa contextlen +bytes long. +Provision of a context is optional. +If the context should be omitted entirely, then +.Fa use_context +should be set to 0. +Otherwise it should be any other value. +If +.Fa use_context +is 0, then the values of +.Fa context +and +.Fa contextlen +are ignored. +.Pp +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. +.Pp +An application specific label should be provided in the location pointed +to by +.Fa label +and should be +.Fa llen +bytes long. +Typically this will be a value from the +.Lk https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels "IANA Exporter Label Registry" . +.Pp +Alternatively, labels beginning with "EXPERIMENTAL" are permitted by the +standard to be used without registration. +.Sh RETURN VALUES +.Fn SSL_export_keying_material +returns 1 on success or 0 or -1 on failure. +.Sh SEE ALSO +.Xr ssl 3 +.Sh HISTORY +.Fn SSL_export_keying_material +first appeared in OpenSSL 1.0.1 and has been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/SSL_free.3 b/static/openbsd/man3/SSL_free.3 new file mode 100644 index 00000000..b630bc8a --- /dev/null +++ b/static/openbsd/man3/SSL_free.3 @@ -0,0 +1,116 @@ +.\" $OpenBSD: SSL_free.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_FREE 3 +.Os +.Sh NAME +.Nm SSL_free +.Nd free an allocated SSL structure +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_free "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_free +decrements the reference count of +.Fa ssl , +and removes the +.Vt SSL +structure pointed to by +.Fa ssl +and frees up the allocated memory if the reference count has reached 0. +If +.Fa ssl +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn SSL_free +also calls the +.Xr free 3 Ns +ing procedures for indirectly affected items, if applicable: the buffering +.Vt BIO , +the read and write +.Vt BIOs , +cipher lists specially created for this +.Fa ssl , +the +.Sy SSL_SESSION . +Do not explicitly free these indirectly freed up items before or after calling +.Fn SSL_free , +as trying to free things twice may lead to program failure. +.Pp +The +.Fa ssl +session has reference counts from two users: the +.Vt SSL +object, for which the reference count is removed by +.Fn SSL_free +and the internal session cache. +If the session is considered bad, because +.Xr SSL_shutdown 3 +was not called for the connection and +.Xr SSL_set_shutdown 3 +was not used to set the +.Vt SSL_SENT_SHUTDOWN +state, the session will also be removed from the session cache as required by +RFC 2246. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_new 3 , +.Xr SSL_set_shutdown 3 , +.Xr SSL_shutdown 3 +.Sh HISTORY +.Fn SSL_free +appeared in SSLeay 0.4 or earlier and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_SSL_CTX.3 b/static/openbsd/man3/SSL_get_SSL_CTX.3 new file mode 100644 index 00000000..eaf1b6ff --- /dev/null +++ b/static/openbsd/man3/SSL_get_SSL_CTX.3 @@ -0,0 +1,80 @@ +.\" $OpenBSD: SSL_get_SSL_CTX.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_SSL_CTX 3 +.Os +.Sh NAME +.Nm SSL_get_SSL_CTX +.Nd get the SSL_CTX from which an SSL is created +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft SSL_CTX * +.Fn SSL_get_SSL_CTX "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_SSL_CTX +returns a pointer to the +.Vt SSL_CTX +object from which +.Fa ssl +was created with +.Xr SSL_new 3 . +.Sh RETURN VALUES +The pointer to the +.Vt SSL_CTX +object is returned. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_new 3 +.Sh HISTORY +.Fn SSL_get_SSL_CTX +first appeared in SSLeay 0.5.1 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_certificate.3 b/static/openbsd/man3/SSL_get_certificate.3 new file mode 100644 index 00000000..72ae7ec5 --- /dev/null +++ b/static/openbsd/man3/SSL_get_certificate.3 @@ -0,0 +1,65 @@ +.\" $OpenBSD: SSL_get_certificate.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt SSL_GET_CERTIFICATE 3 +.Os +.Sh NAME +.Nm SSL_get_certificate , +.Nm SSL_get_privatekey +.Nd get SSL certificate and private key +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft X509 * +.Fo SSL_get_certificate +.Fa "const SSL *ssl" +.Fc +.Ft EVP_PKEY * +.Fo SSL_get_privatekey +.Fa "const SSL *ssl" +.Fc +.Sh DESCRIPTION +These functions retrieve certificate and key data from an +.Vt SSL +object. +They return internal pointers that must not be freed by the application +program. +.Sh RETURN VALUES +.Fn SSL_get_certificate +returns the active X.509 certificate currently used by +.Fa ssl +or +.Dv NULL +if none is active. +.Pp +.Fn SSL_get_privatekey +returns the active private key currently used by +.Fa ssl +or +.Dv NULL +if none is active. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_check_private_key 3 , +.Xr SSL_use_certificate 3 +.Sh HISTORY +.Fn SSL_get_certificate +first appeared in SSLeay 0.5.2a. +.Fn SSL_get_privatekey +first appeared in SSLeay 0.8.0. +Both functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_ciphers.3 b/static/openbsd/man3/SSL_get_ciphers.3 new file mode 100644 index 00000000..d723f795 --- /dev/null +++ b/static/openbsd/man3/SSL_get_ciphers.3 @@ -0,0 +1,250 @@ +.\" $OpenBSD: SSL_get_ciphers.3,v 1.12 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" selective merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2020 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. +.\" +.\" The original file was written by Lutz Jaenicke , +.\" Nick Mathewson , Kurt Roeckx , +.\" Kazuki Yamaguchi , and Benjamin Kaduk . +.\" Copyright (c) 2000, 2005, 2015, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_CIPHERS 3 +.Os +.Sh NAME +.Nm SSL_get_ciphers , +.Nm SSL_CTX_get_ciphers , +.Nm SSL_get1_supported_ciphers , +.Nm SSL_get_client_ciphers , +.Nm SSL_get_cipher_list +.Nd get lists of available SSL_CIPHERs +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft STACK_OF(SSL_CIPHER) * +.Fn SSL_get_ciphers "const SSL *ssl" +.Ft STACK_OF(SSL_CIPHER) * +.Fn SSL_CTX_get_ciphers "const SSL_CTX *ctx" +.Ft STACK_OF(SSL_CIPHER) * +.Fn SSL_get1_supported_ciphers "SSL *ssl" +.Ft STACK_OF(SSL_CIPHER) * +.Fn SSL_get_client_ciphers "const SSL *ssl" +.Ft const char * +.Fn SSL_get_cipher_list "const SSL *ssl" "int priority" +.Sh DESCRIPTION +.Fn SSL_get_ciphers +returns the stack of available +.Vt SSL_CIPHER Ns s +for +.Fa ssl , +sorted by preference. +.Pp +.Fn SSL_CTX_get_ciphers +returns the stack of available +.Vt SSL_CIPHER Ns s +for +.Fa ctx . +.Pp +.Fn SSL_get1_supported_ciphers +returns a stack of enabled +.Vt SSL_CIPHER Ns s +for +.Fa ssl +as it would be sent in a ClientHello, sorted by preference. +The list depends on settings like the cipher list, the supported +protocol versions, the security level, and the enabled signature +algorithms. +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. +.Pp +.Fn SSL_get_client_ciphers +returns the stack of available +.Vt SSL_CIPHER Ns s +matching the list received from the client on +.Fa ssl . +.Pp +The details of the ciphers obtained by +.Fn SSL_get_ciphers , +.Fn SSL_CTX_get_ciphers , +.Fn SSL_get1_supported_ciphers , +and +.Fn SSL_get_client_ciphers +can be obtained using the +.Xr SSL_CIPHER_get_name 3 +family of functions. +.Pp +.Fn SSL_get_cipher_list +is deprecated \(em use +.Fn SSL_get_ciphers +instead \(em and badly misnamed; it does not return a list +but the name of one element of the return value of +.Fn SSL_get_ciphers , +with the index given by the +.Fa priority +argument. +Passing 0 selects the cipher with the highest priority. +To iterate over all available ciphers in decreasing priority, +repeatedly increment the argument by 1 until +.Dv NULL +is returned. +.Sh RETURN VALUES +.Fn SSL_get_ciphers +returns an internal pointer to a list of ciphers or +.Dv NULL +if +.Fa ssl +is +.Dv NULL +or if no ciphers are available. +The returned pointer may not only become invalid when +.Fa ssl +is destroyed or when +.Xr SSL_set_cipher_list 3 +is called on it, but also when the +.Vt SSL_CTX +object in use by +.Fa ssl +at the time of the call is freed or when +.Xr SSL_CTX_set_cipher_list 3 +is called on that context object. +.Pp +.Fn SSL_CTX_get_ciphers +returns an internal pointer to a list of ciphers or +.Dv NULL +if +.Fa ctx +is +.Dv NULL +or if no ciphers are available. +The returned pointer becomes invalid when +.Fa ctx +is destroyed or when +.Xr SSL_CTX_set_cipher_list 3 +is called on it. +.Pp +.Fn SSL_get1_supported_ciphers +returns a newly allocated list of ciphers or +.Dv NULL +if +.Fa ssl +is +.Dv NULL , +if no ciphers are available, or if an error occurs. +When the returned pointer is no longer needed, the caller is +responsible for freeing it using +.Fn sk_SSL_CIPHER_free . +.Pp +.Fn SSL_get_client_ciphers +returns an internal pointer to a list of ciphers or +.Dv NULL +if +.Fa ssl +is +.Dv NULL , +has no active session, +or is not operating in server mode. +The returned pointer becomes invalid when the +.Vt SSL_SESSION +object is destroyed, even if the +.Fa ssl +object remains valid. +It may also become invalid in other circumstances, +for example when processing a new ClientHello. +.Pp +.Fn SSL_get_cipher_list +returns an internal pointer to a string or +.Dv NULL +if +.Fa ssl +is +.Dv NULL , +if no ciphers are available, or if +.Fa priority +is greater than or equal to the number of available ciphers. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CIPHER_get_name 3 , +.Xr SSL_CTX_set_cipher_list 3 +.Sh HISTORY +.Fn SSL_get_cipher_list +first appeared in SSLeay 0.5.2. +.Fn SSL_get_ciphers +first appeared in SSLeay 0.8.0. +Both functions have been available since +.Ox 2.4 . +.Pp +.Fn SSL_CTX_get_ciphers +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . +.Pp +.Fn SSL_get1_supported_ciphers +and +.Fn SSL_get_client_ciphers +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.5 . diff --git a/static/openbsd/man3/SSL_get_client_CA_list.3 b/static/openbsd/man3/SSL_get_client_CA_list.3 new file mode 100644 index 00000000..8be70204 --- /dev/null +++ b/static/openbsd/man3/SSL_get_client_CA_list.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: SSL_get_client_CA_list.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2002, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_CLIENT_CA_LIST 3 +.Os +.Sh NAME +.Nm SSL_get_client_CA_list , +.Nm SSL_CTX_get_client_CA_list +.Nd get list of client CAs +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft STACK_OF(X509_NAME) * +.Fn SSL_get_client_CA_list "const SSL *s" +.Ft STACK_OF(X509_NAME) * +.Fn SSL_CTX_get_client_CA_list "const SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_get_client_CA_list +returns the list of client CAs explicitly set for +.Fa ctx +using +.Xr SSL_CTX_set_client_CA_list 3 . +.Pp +.Fn SSL_get_client_CA_list +returns the list of client CAs explicitly set for +.Fa ssl +using +.Fn SSL_set_client_CA_list +or +.Fa ssl Ns 's +.Vt SSL_CTX +object with +.Xr SSL_CTX_set_client_CA_list 3 , +when in server mode. +In client mode, +.Fn SSL_get_client_CA_list +returns the list of client CAs sent from the server, if any. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_client_CA_list 3 , +.Xr SSL_CTX_set_client_cert_cb 3 , +.Xr X509_NAME_new 3 +.Sh HISTORY +.Fn SSL_get_client_CA_list +and +.Fn SSL_CTX_get_client_CA_list +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_client_random.3 b/static/openbsd/man3/SSL_get_client_random.3 new file mode 100644 index 00000000..131972b6 --- /dev/null +++ b/static/openbsd/man3/SSL_get_client_random.3 @@ -0,0 +1,151 @@ +.\" $OpenBSD: SSL_get_client_random.3,v 1.3 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Nick Mathewson +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_CLIENT_RANDOM 3 +.Os +.Sh NAME +.Nm SSL_get_client_random , +.Nm SSL_get_server_random , +.Nm SSL_SESSION_get_master_key +.Nd get internal TLS handshake random values and master key +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft size_t +.Fo SSL_get_client_random +.Fa "const SSL *ssl" +.Fa "unsigned char *out" +.Fa "size_t outlen" +.Fc +.Ft size_t +.Fo SSL_get_server_random +.Fa "const SSL *ssl" +.Fa "unsigned char *out" +.Fa "size_t outlen" +.Fc +.Ft size_t +.Fo SSL_SESSION_get_master_key +.Fa "const SSL_SESSION *session" +.Fa "unsigned char *out" +.Fa "size_t outlen" +.Fc +.Sh DESCRIPTION +.Fn SSL_get_client_random +extracts the random value that was sent from the client to the server +during the initial TLS handshake. +It copies at most +.Fa outlen +bytes of this value into the buffer +.Fa out . +If +.Fa outlen +is zero, nothing is copied. +.Pp +.Fn SSL_get_server_random +behaves the same, but extracts the random value that was sent +from the server to the client during the initial TLS handshake. +.Pp +.Fn SSL_SESSION_get_master_key +behaves the same, but extracts the master secret used to guarantee the +security of the TLS session. +The security of the TLS session depends on keeping the master key +secret: do not expose it, or any information about it, to anybody. +To calculate another secret value that depends on the master secret, +use +.Xr SSL_export_keying_material 3 +instead. +.Pp +All these functions expose internal values from the TLS handshake, +for use in low-level protocols. +Avoid using them unless implementing a feature +that requires access to the internal protocol details. +.Pp +Despite the names of +.Fn SSL_get_client_random +and +.Fn SSL_get_server_random , +they are not random number generators. +Instead, they return the mostly-random values that were already +generated and used in the TLS protocol. +.Pp +In current versions of the TLS protocols, +the length of client_random and server_random is always +.Dv SSL3_RANDOM_SIZE +bytes. +Support for other +.Fa outlen +arguments is provided for the unlikely event that a future +version or variant of TLS uses some other length. +.Pp +Finally, though the client_random and server_random values are called +.Dq random , +many TLS implementations generate four bytes of those values +based on their view of the current time. +.Sh RETURN VALUES +If +.Fa outlen +is greater than 0, these functions return the number of bytes +actually copied, which is less than or equal to +.Fa outlen . +If +.Fa outlen +is 0, these functions return the maximum number of bytes they would +copy \(em that is, the length of the underlying field. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_export_keying_material 3 , +.Xr SSL_SESSION_get_id 3 , +.Xr SSL_SESSION_get_time 3 , +.Xr SSL_SESSION_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_get_current_cipher.3 b/static/openbsd/man3/SSL_get_current_cipher.3 new file mode 100644 index 00000000..37f64090 --- /dev/null +++ b/static/openbsd/man3/SSL_get_current_cipher.3 @@ -0,0 +1,123 @@ +.\" $OpenBSD: SSL_get_current_cipher.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2005, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_CURRENT_CIPHER 3 +.Os +.Sh NAME +.Nm SSL_get_current_cipher , +.Nm SSL_get_cipher , +.Nm SSL_get_cipher_name , +.Nm SSL_get_cipher_bits , +.Nm SSL_get_cipher_version +.Nd get SSL_CIPHER of a connection +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft const SSL_CIPHER * +.Fn SSL_get_current_cipher "const SSL *ssl" +.Ft const char * +.Fn SSL_get_cipher "const SSL *ssl" +.Ft const char * +.Fn SSL_get_cipher_name "const SSL *ssl" +.Ft int +.Fn SSL_get_cipher_bits "const SSL *ssl" "int *np" +.Ft char * +.Fn SSL_get_cipher_version "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_current_cipher +returns a pointer to an +.Vt SSL_CIPHER +object containing the description of the actually used cipher of a connection +established with the +.Fa ssl +object. +See +.Xr SSL_CIPHER_get_name 3 +for more details. +.Pp +.Fn SSL_get_cipher_name +obtains the name of the currently used cipher. +.Fn SSL_get_cipher +is identical to +.Fn SSL_get_cipher_name . +.Pp +.Fn SSL_get_cipher_bits +obtains the number of secret/algorithm bits used and +.Fn SSL_get_cipher_version +returns the protocol name. +.Pp +.Fn SSL_get_cipher , +.Fn SSL_get_cipher_name , +.Fn SSL_get_cipher_bits , +and +.Fn SSL_get_cipher_version +are implemented as macros. +.Sh RETURN VALUES +.Fn SSL_get_current_cipher +returns the cipher actually used, or +.Dv NULL +if no session has been established. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CIPHER_get_name 3 +.Sh HISTORY +.Fn SSL_get_cipher +appeared in SSLeay 0.4 or earlier. +.Fn SSL_get_cipher_bits +first appeared in SSLeay 0.6.4. +.Fn SSL_get_cipher_name +and +.Fn SSL_get_cipher_version +first appeared in SSLeay 0.8.0. +.Fn SSL_get_current_cipher +first appeared in SSLeay 0.8.1. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_default_timeout.3 b/static/openbsd/man3/SSL_get_default_timeout.3 new file mode 100644 index 00000000..ef119780 --- /dev/null +++ b/static/openbsd/man3/SSL_get_default_timeout.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: SSL_get_default_timeout.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_DEFAULT_TIMEOUT 3 +.Os +.Sh NAME +.Nm SSL_get_default_timeout +.Nd get default session timeout value +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_get_default_timeout "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_default_timeout +returns the default timeout value assigned to +.Vt SSL_SESSION +objects negotiated for the protocol valid for +.Fa ssl . +.Pp +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 +.Xr SSL_CTX_set_timeout 3 , +the hardcoded default timeout for the protocol will be used. +.Pp +.Fn SSL_get_default_timeout +return this hardcoded value, which is 300 seconds for all currently supported +protocols (SSLv2, SSLv3, and TLSv1). +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_SESSION_get_time 3 +.Sh HISTORY +.Fn SSL_get_default_timeout +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_error.3 b/static/openbsd/man3/SSL_get_error.3 new file mode 100644 index 00000000..ba64b779 --- /dev/null +++ b/static/openbsd/man3/SSL_get_error.3 @@ -0,0 +1,218 @@ +.\" $OpenBSD: SSL_get_error.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" +.\" This file was written by Bodo Moeller . +.\" Copyright (c) 2000, 2001, 2002, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_ERROR 3 +.Os +.Sh NAME +.Nm SSL_get_error +.Nd obtain result code for TLS/SSL I/O operation +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_get_error "const SSL *ssl" "int ret" +.Sh DESCRIPTION +.Fn SSL_get_error +returns a result code (suitable for the C +.Dq switch +statement) for a preceding call to +.Xr SSL_connect 3 , +.Xr SSL_accept 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_read 3 , +.Xr SSL_peek 3 , +or +.Xr SSL_write 3 +on +.Fa ssl . +The value returned by that TLS/SSL I/O function must be passed to +.Fn SSL_get_error +in parameter +.Fa ret . +.Pp +In addition to +.Fa ssl +and +.Fa ret , +.Fn SSL_get_error +inspects the current thread's OpenSSL error queue. +Thus, +.Fn SSL_get_error +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's error queue must be empty before the TLS/SSL I/O operation +is attempted, or +.Fn SSL_get_error +will not work reliably. +.Sh RETURN VALUES +The following return values can currently occur: +.Bl -tag -width Ds +.It Dv SSL_ERROR_NONE +The TLS/SSL I/O operation completed. +This result code is returned if and only if +.Fa ret +> 0. +.It Dv SSL_ERROR_ZERO_RETURN +The TLS/SSL connection has been closed. +If the protocol version is SSL 3.0 or TLS 1.0, this result code is returned +only if a closure alert has occurred in the protocol, i.e., if the connection +has been closed cleanly. +Note that in this case +.Dv SSL_ERROR_ZERO_RETURN +does not necessarily indicate that the underlying transport has been closed. +.It Dv SSL_ERROR_WANT_READ , Dv SSL_ERROR_WANT_WRITE +The operation did not complete; +the same TLS/SSL I/O function should be called again later. +If, by then, the underlying +.Vt BIO +has data available for reading (if the result code is +.Dv SSL_ERROR_WANT_READ ) +or allows writing data +.Pq Dv SSL_ERROR_WANT_WRITE , +then some TLS/SSL protocol progress will take place, +i.e., at least part of a TLS/SSL record will be read or written. +Note that the retry may again lead to a +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE +condition. +There is no fixed upper limit for the number of iterations that may be +necessary until progress becomes visible at application protocol level. +.Pp +For socket +.Fa BIO Ns +s (e.g., when +.Fn SSL_set_fd +was used), +.Xr select 2 +or +.Xr poll 2 +on the underlying socket can be used to find out when the TLS/SSL I/O function +should be retried. +.Pp +Caveat: Any TLS/SSL I/O function can lead to either of +.Dv SSL_ERROR_WANT_READ +and +.Dv SSL_ERROR_WANT_WRITE . +In particular, +.Xr SSL_read 3 +or +.Xr SSL_peek 3 +may want to write data and +.Xr SSL_write 3 +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); +.Xr SSL_read 3 , +.Xr SSL_peek 3 , +and +.Xr SSL_write 3 +will handle any pending handshakes. +.It Dv SSL_ERROR_WANT_CONNECT , Dv 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 +.Xr connect 2 Ns / Ns +.Xr accept 2 . +The SSL function should be +called again when the connection is established. +These messages can only appear with a +.Xr BIO_s_connect 3 +or +.Xr BIO_s_accept 3 +.Vt BIO , +respectively. +In order to find out when the connection has been successfully established, +on many platforms +.Xr select 2 +or +.Xr poll 2 +for writing on the socket file descriptor can be used. +.It Dv SSL_ERROR_WANT_X509_LOOKUP +The operation did not complete because an application callback set by +.Xr SSL_CTX_set_client_cert_cb 3 +has asked to be called again. +The TLS/SSL I/O function should be called again later. +Details depend on the application. +.It Dv SSL_ERROR_SYSCALL +Some I/O error occurred. +The OpenSSL error queue may contain more information on the error. +If the error queue is empty (i.e., +.Fn ERR_get_error +returns 0), +.Fa ret +can be used to find out more about the error: +If +.Fa ret +== 0, an +.Dv EOF +was observed that violates the protocol. +If +.Fa ret +== \(mi1, the underlying +.Vt BIO +reported an +I/O error (for socket I/O on Unix systems, consult +.Dv errno +for details). +.It Dv SSL_ERROR_SSL +A failure in the SSL library occurred, usually a protocol error. +The OpenSSL error queue contains more information on the error. +.El +.Sh SEE ALSO +.Xr err 3 , +.Xr ssl 3 +.Sh HISTORY +.Fn SSL_get_error +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_ex_data_X509_STORE_CTX_idx.3 b/static/openbsd/man3/SSL_get_ex_data_X509_STORE_CTX_idx.3 new file mode 100644 index 00000000..234034ac --- /dev/null +++ b/static/openbsd/man3/SSL_get_ex_data_X509_STORE_CTX_idx.3 @@ -0,0 +1,117 @@ +.\" $OpenBSD: SSL_get_ex_data_X509_STORE_CTX_idx.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_EX_DATA_X509_STORE_CTX_IDX 3 +.Os +.Sh NAME +.Nm SSL_get_ex_data_X509_STORE_CTX_idx +.Nd get ex_data index to access SSL structure from X509_STORE_CTX +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_get_ex_data_X509_STORE_CTX_idx void +.Sh DESCRIPTION +.Fn SSL_get_ex_data_X509_STORE_CTX_idx +returns the index number under which the pointer to the +.Vt SSL +object is stored into the +.Vt X509_STORE_CTX +object. +.Pp +Whenever a +.Vt X509_STORE_CTX +object is created for the verification of the peer's certificate during a +handshake, a pointer to the +.Vt SSL +object is stored into the +.Vt X509_STORE_CTX +object to identify the connection affected. +To retrieve this pointer the +.Xr X509_STORE_CTX_get_ex_data 3 +function can be used with the correct index. +This index is globally the same for all +.Vt X509_STORE_CTX +objects and can be retrieved using +.Fn SSL_get_ex_data_X509_STORE_CTX_idx . +The index value is set when +.Fn SSL_get_ex_data_X509_STORE_CTX_idx +is first called either by the application program directly or indirectly during +other SSL setup functions or during the handshake. +.Pp +The value depends on other index values defined for +.Vt X509_STORE_CTX +objects before the SSL index is created. +.Sh RETURN VALUES +.Bl -tag -width Ds +.It \(>=0 +The index value to access the pointer. +.It <0 +An error occurred, check the error stack for a detailed error message. +.El +.Sh EXAMPLES +The index returned from +.Fn SSL_get_ex_data_X509_STORE_CTX_idx +provides access to +.Vt SSL +object for the connection during the +.Fn verify_callback +when checking the peer's certificate. +Check the example in +.Xr SSL_CTX_set_verify 3 . +.Sh SEE ALSO +.Xr CRYPTO_set_ex_data 3 , +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 +.Sh HISTORY +.Fn SSL_get_ex_data_X509_STORE_CTX_idx +first appeared in SSLeay 0.9.1 and has been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/SSL_get_ex_new_index.3 b/static/openbsd/man3/SSL_get_ex_new_index.3 new file mode 100644 index 00000000..811df94f --- /dev/null +++ b/static/openbsd/man3/SSL_get_ex_new_index.3 @@ -0,0 +1,137 @@ +.\" $OpenBSD: SSL_get_ex_new_index.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm SSL_get_ex_new_index , +.Nm SSL_set_ex_data , +.Nm SSL_get_ex_data +.Nd internal application specific data functions +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fn SSL_set_ex_data "SSL *ssl" "int idx" "void *arg" +.Ft void * +.Fn SSL_get_ex_data "const SSL *ssl" "int idx" +.Bd -literal +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); +.Ed +.Sh 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 +.Fn SSL_get_ex_new_index +is used to register a new index for application specific data. +.Pp +.Fn SSL_set_ex_data +is used to store application data at +.Fa arg +for +.Fa idx +into the +.Fa ssl +object. +.Pp +.Fn SSL_get_ex_data +is used to retrieve the information for +.Fa idx +from +.Fa ssl . +.Pp +A detailed description for the +.Fn *_get_ex_new_index +functionality can be found in +.Xr RSA_get_ex_new_index 3 . +The +.Fn *_get_ex_data +and +.Fn *_set_ex_data +functionality is described in +.Xr CRYPTO_set_ex_data 3 . +.Sh EXAMPLES +An example of how to use the functionality is included in the example +.Fn verify_callback +in +.Xr SSL_CTX_set_verify 3 . +.Sh SEE ALSO +.Xr CRYPTO_set_ex_data 3 , +.Xr RSA_get_ex_new_index 3 , +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 +.Sh HISTORY +Precursor functions +.Fn SSL_set_app_data +and +.Fn SSL_get_app_data +first appeared in SSLeay 0.6.1. +.Pp +.Fn SSL_get_ex_new_index , +.Fn SSL_set_ex_data , +and +.Fn SSL_get_ex_data +first appeared in SSLeay 0.9.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_fd.3 b/static/openbsd/man3/SSL_get_fd.3 new file mode 100644 index 00000000..3a7948d3 --- /dev/null +++ b/static/openbsd/man3/SSL_get_fd.3 @@ -0,0 +1,104 @@ +.\" $OpenBSD: SSL_get_fd.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2005, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_FD 3 +.Os +.Sh NAME +.Nm SSL_get_fd , +.Nm SSL_get_rfd , +.Nm SSL_get_wfd +.Nd get file descriptor linked to an SSL object +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_get_fd "const SSL *ssl" +.Ft int +.Fn SSL_get_rfd "const SSL *ssl" +.Ft int +.Fn SSL_get_wfd "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_fd +returns the file descriptor which is linked to +.Fa ssl . +.Fn SSL_get_rfd +and +.Fn SSL_get_wfd +return the file descriptors for the read or the write channel, +which can be different. +If the read and the write channel are different, +.Fn SSL_get_fd +will return the file descriptor of the read channel. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It \(mi1 +The operation failed, because the underlying +.Vt BIO +is not of the correct type (suitable for file descriptors). +.It \(>=0 +The file descriptor linked to +.Fa ssl . +.El +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_set_fd 3 +.Sh HISTORY +.Fn SSL_get_fd +appeared in SSLeay 0.4 or earlier and has been available since +.Ox 2.4 . +.Pp +.Fn SSL_get_rfd +and +.Fn SSL_get_wfd +first appeared in OpenSSL 0.9.6c and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/SSL_get_finished.3 b/static/openbsd/man3/SSL_get_finished.3 new file mode 100644 index 00000000..e5c8a36c --- /dev/null +++ b/static/openbsd/man3/SSL_get_finished.3 @@ -0,0 +1,78 @@ +.\" $OpenBSD: SSL_get_finished.3,v 1.3 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2020 Theo Buehler +.\" +.\" 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: June 8 2025 $ +.Dt SSL_GET_FINISHED 3 +.Os +.Sh NAME +.Nm SSL_get_finished , +.Nm SSL_get_peer_finished +.Nd get last sent or last expected finished message +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft size_t +.Fn SSL_get_finished "const SSL *ssl" "void *buf" "size_t count" +.Ft size_t +.Fn SSL_get_peer_finished "const SSL *ssl" "void *buf" "size_t count" +.Sh DESCRIPTION +.Fn SSL_get_finished +and +.Fn SSL_get_peer_finished +copy +.Fa count +bytes from the last finished message sent to the peer +or expected from the peer into the +caller-provided buffer +.Fa buf . +.Pp +The finished message is computed from a checksum of the handshake records +exchanged with the peer. +Its length depends on the ciphersuite in use and is at most +.Dv EVP_MAX_MD_SIZE , +i.e., 64 bytes. +.\" In TLSv1.3 the length is equal to the length of the hash algorithm +.\" used by the hash-based message authentication code (HMAC), +.\" which is currently either 32 bytes for SHA-256 or 48 bytes for SHA-384. +.\" In TLSv1.2 the length defaults to 12 bytes, but it can explicitly be +.\" specified by the ciphersuite to be longer. +.\" In TLS versions 1.1 and 1.0, the finished message has a fixed length +.\" of 12 bytes. +.Sh RETURN VALUES +.Fn SSL_get_finished +and +.Fn SSL_get_peer_finished +return the number of bytes copied into +.Fa buf . +The return value is zero if the handshake has not reached the +finished message. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_get_session 3 , +.Xr SSL_set_session 3 +.Sh STANDARDS +RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3, +section 4.4.4: Finished. +.Pp +RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2, +section 7.4.9: Finished. +.Sh HISTORY +.Fn SSL_get_finished +and +.Fn SSL_get_peer_finished +first appeared in SSLeay 0.9.5 +and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/SSL_get_peer_cert_chain.3 b/static/openbsd/man3/SSL_get_peer_cert_chain.3 new file mode 100644 index 00000000..c4f778aa --- /dev/null +++ b/static/openbsd/man3/SSL_get_peer_cert_chain.3 @@ -0,0 +1,108 @@ +.\" $OpenBSD: SSL_get_peer_cert_chain.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL SSL_get_peer_cert_chain.pod 1f164c6f Jan 18 01:40:36 2017 +0100 +.\" OpenSSL SSL_get_peer_cert_chain.pod 9b86974e Aug 17 15:21:33 2015 -0400 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2005, 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_PEER_CERT_CHAIN 3 +.Os +.Sh NAME +.Nm SSL_get_peer_cert_chain +.Nd get the X509 certificate chain sent by the peer +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft STACK_OF(X509) * +.Fn SSL_get_peer_cert_chain "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_peer_cert_chain +returns a pointer to +.Dv STACK_OF Ns Po Vt X509 Pc +certificates forming the certificate chain of the peer. +If called on the client side, the stack also contains the peer's certificate; +if called on the server side, the peer's certificate must be obtained +separately using +.Xr SSL_get_peer_certificate 3 . +If the peer did not present a certificate, +.Dv NULL +is returned. +.Pp +.Fn SSL_get_peer_cert_chain +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) +and it is not a verified chain. +.Pp +If the session is resumed, peers do not send certificates, so a +.Dv NULL +pointer is returned. +Applications can call +.Fn SSL_session_reused +to determine whether a session is resumed. +.Pp +The reference count of the +.Dv STACK_OF Ns Po Vt X509 Pc +object is not incremented. +If the corresponding session is freed, the pointer must not be used any longer. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv 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. +.It Pointer to a Dv STACK_OF Ns Po X509 Pc +The return value points to the certificate chain presented by the peer. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_get_peer_certificate 3 +.Sh HISTORY +.Fn SSL_get_peer_cert_chain +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_peer_certificate.3 b/static/openbsd/man3/SSL_get_peer_certificate.3 new file mode 100644 index 00000000..9ac35a60 --- /dev/null +++ b/static/openbsd/man3/SSL_get_peer_certificate.3 @@ -0,0 +1,106 @@ +.\" $OpenBSD: SSL_get_peer_certificate.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_PEER_CERTIFICATE 3 +.Os +.Sh NAME +.Nm SSL_get_peer_certificate +.Nd get the X509 certificate of the peer +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft X509 * +.Fn SSL_get_peer_certificate "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_peer_certificate +returns a pointer to the X509 certificate the peer presented. +If the peer did not present a certificate, +.Dv NULL +is returned. +.Pp +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 +.Xr SSL_CTX_set_verify 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 +.Xr SSL_get_verify_result 3 +to check the verification state. +.Pp +The reference count of the +.Vt X509 +object is incremented by one, so that it will not be destroyed when the session +containing the peer certificate is freed. +The +.Vt X509 +object must be explicitly freed using +.Xr X509_free 3 . +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +No certificate was presented by the peer or no connection was established. +.It Pointer to an X509 certificate +The return value points to the certificate presented by the peer. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr SSL_get0_peername 3 , +.Xr SSL_get_verify_result 3 +.Sh HISTORY +.Fn SSL_get_peer_certificate +appeared in SSLeay 0.4 or earlier and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_rbio.3 b/static/openbsd/man3/SSL_get_rbio.3 new file mode 100644 index 00000000..7179277f --- /dev/null +++ b/static/openbsd/man3/SSL_get_rbio.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: SSL_get_rbio.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_RBIO 3 +.Os +.Sh NAME +.Nm SSL_get_rbio , +.Nm SSL_get_wbio +.Nd get BIO linked to an SSL object +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft BIO * +.Fn SSL_get_rbio "SSL *ssl" +.Ft BIO * +.Fn SSL_get_wbio "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_rbio +and +.Fn SSL_get_wbio +return pointers to the +.Vt BIO Ns s +for the read or the write channel, which can be different. +The reference count of the +.Vt BIO +is not incremented. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +No +.Vt BIO +was connected to the +.Vt SSL +object. +.It Any other pointer +The +.Vt BIO +linked to +.Fa ssl . +.El +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_set_bio 3 +.Sh HISTORY +.Fn SSL_get_rbio +and +.Fn SSL_get_wbio +first appeared in SSLeay 0.6.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_server_tmp_key.3 b/static/openbsd/man3/SSL_get_server_tmp_key.3 new file mode 100644 index 00000000..c55036d5 --- /dev/null +++ b/static/openbsd/man3/SSL_get_server_tmp_key.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: SSL_get_server_tmp_key.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL SSL_get_server_tmp_key.pod 508fafd8 Apr 3 15:41:21 2017 +0100 +.\" +.\" This file was written by Matt Caswell +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_SERVER_TMP_KEY 3 +.Os +.Sh NAME +.Nm SSL_get_server_tmp_key +.Nd temporary server key during a handshake +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fo SSL_get_server_tmp_key +.Fa "SSL *ssl" +.Fa "EVP_PKEY **key" +.Fc +.Sh DESCRIPTION +.Fn SSL_get_server_tmp_key +retrieves the temporary key provided by the server +and used during key exchange. +For example, if ECDHE is in use, +this represents the server's public ECDHE key. +.Pp +In case of success, a copy of the key is stored in +.Pf * Fa key . +It is the caller's responsibility to free this key after use using +.Xr EVP_PKEY_free 3 . +.Pp +This function may only be called by the client. +.Pp +This function is implemented as a macro. +.Sh RETURN VALUES +.Fn SSL_get_server_tmp_key +returns 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr EVP_PKEY_free 3 , +.Xr ssl 3 , +.Xr SSL_ctrl 3 +.Sh HISTORY +.Fn SSL_get_server_tmp_key +first appeared in OpenSSL 1.0.2 and has been available since +.Ox 6.1 . diff --git a/static/openbsd/man3/SSL_get_session.3 b/static/openbsd/man3/SSL_get_session.3 new file mode 100644 index 00000000..597888a0 --- /dev/null +++ b/static/openbsd/man3/SSL_get_session.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: SSL_get_session.3,v 1.9 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2005, 2013, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_SESSION 3 +.Os +.Sh NAME +.Nm SSL_get_session , +.Nm SSL_get0_session , +.Nm SSL_get1_session +.Nd retrieve TLS/SSL session data +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft SSL_SESSION * +.Fn SSL_get_session "const SSL *ssl" +.Ft SSL_SESSION * +.Fn SSL_get0_session "const SSL *ssl" +.Ft SSL_SESSION * +.Fn SSL_get1_session "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_session +returns a pointer to the +.Vt SSL_SESSION +actually used in +.Fa ssl . +The reference count of the +.Vt SSL_SESSION +is not incremented, so that the pointer can become invalid by other operations. +.Pp +.Fn SSL_get0_session +is the same as +.Fn SSL_get_session . +.Pp +.Fn SSL_get1_session +is the same as +.Fn SSL_get_session , +but the reference count of the +.Vt SSL_SESSION +is incremented by one. +.Pp +The +.Fa ssl +session contains all information required to re-establish the connection +without a new handshake. +.Pp +.Fn SSL_get0_session +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 +.Xr SSL_clear 3 +or +.Xr SSL_free 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 +.Xr SSL_CTX_flush_sessions 3 . +.Pp +If the data is to be kept, +.Fn SSL_get1_session +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, +.Xr SSL_SESSION_free 3 +must be explicitly called once to decrement the reference count again. +.Pp +.Vt SSL_SESSION +objects keep internal link information about the session cache list when being +inserted into one +.Vt SSL_CTX +object's session cache. +One +.Vt SSL_SESSION +object, regardless of its reference count, must therefore only be used with one +.Vt SSL_CTX +object (and the +.Vt SSL +objects created from this +.Vt SSL_CTX +object). +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +There is no session available in +.Fa ssl . +.It Pointer to an Vt SSL_SESSION +The return value points to the data of an +.Vt SSL +session. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_free 3 , +.Xr SSL_SESSION_free 3 , +.Xr SSL_SESSION_get0_peer 3 , +.Xr SSL_SESSION_get_compress_id 3 , +.Xr SSL_SESSION_get_id 3 , +.Xr SSL_SESSION_get_protocol_version 3 , +.Xr SSL_SESSION_get_time 3 , +.Xr SSL_SESSION_new 3 , +.Xr SSL_SESSION_print 3 , +.Xr SSL_set_session 3 +.Sh HISTORY +.Fn SSL_get_session +first appeared in SSLeay 0.5.2 and has been available since +.Ox 2.4 . +.Pp +.Fn SSL_get0_session +and +.Fn SSL_get1_session +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/SSL_get_shared_ciphers.3 b/static/openbsd/man3/SSL_get_shared_ciphers.3 new file mode 100644 index 00000000..90117805 --- /dev/null +++ b/static/openbsd/man3/SSL_get_shared_ciphers.3 @@ -0,0 +1,104 @@ +.\" $OpenBSD: SSL_get_shared_ciphers.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt SSL_GET_SHARED_CIPHERS 3 +.Os +.Sh NAME +.Nm SSL_get_shared_ciphers +.Nd ciphers supported by both client and server +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft char * +.Fo SSL_get_shared_ciphers +.Fa "const SSL *ssl" +.Fa "char *buf" +.Fa "int len" +.Fc +.Sh DESCRIPTION +If +.Fa ssl +contains a session in server mode, +.Fn SSL_get_shared_ciphers +puts as many names of ciphers that are supported by both the client +and the server into the buffer +.Fa buf +as the buffer is long enough to contain. +Names are separated by colons. +At most +.Fa len +bytes are written to +.Fa buf +including the terminating NUL character. +.Sh RETURN VALUES +.Fn SSL_get_shared_ciphers +returns +.Fa buf +on success or +.Dv NULL +on failure. +The following situations cause failure: +.Bl -bullet +.It +.Xr SSL_is_server 3 +is false, i.e., +.Ar ssl +is not set to server mode. +.It +.Xr SSL_get_ciphers 3 +is +.Dv NULL +or empty, i.e., no ciphers are available for use by the server. +.It +.Xr SSL_get_session 3 +is +.Dv NULL , +i.e., +.Ar ssl +contains no session. +.It +.Xr SSL_get_client_ciphers 3 +is +.Dv NULL +or empty, i.e., +.Ar ssl +contains no information about ciphers supported by the client, +or the client does not support any ciphers. +.It +The +.Fa len +argument is less than 2. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_get_ciphers 3 +.Sh HISTORY +.Fn SSL_get_shared_ciphers +first appeared in SSLeay 0.4.5b and has been available since +.Ox 2.4 . +.Sh BUGS +If the list is too long to fit into +.Fa len +bytes, it is silently truncated after the last cipher name that fits, +and all following ciphers are skipped. +If the buffer is very short such that even the first cipher name +does not fit, an empty string is returned even when some shared +ciphers are actually available. +.Pp +There is no easy way to find out how much space is required for +.Fa buf +or whether the supplied space was sufficient. diff --git a/static/openbsd/man3/SSL_get_state.3 b/static/openbsd/man3/SSL_get_state.3 new file mode 100644 index 00000000..0e1a20e6 --- /dev/null +++ b/static/openbsd/man3/SSL_get_state.3 @@ -0,0 +1,162 @@ +.\" $OpenBSD: SSL_get_state.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt SSL_GET_STATE 3 +.Os +.Sh NAME +.Nm SSL_get_state , +.Nm SSL_state , +.Nm SSL_in_accept_init , +.Nm SSL_in_before , +.Nm SSL_in_connect_init , +.Nm SSL_in_init , +.Nm SSL_is_init_finished +.Nd inspect the state of the SSL state machine +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_get_state +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_state +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_in_accept_init +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_in_before +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_in_connect_init +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_in_init +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_is_init_finished +.Fa "const SSL *ssl" +.Fc +.Sh DESCRIPTION +.Fn SSL_get_state +returns an encoded representation of the current state of the SSL +state machine. +.Fn SSL_state +is a deprecated alias for +.Fn SSL_get_state . +.Pp +The following bits may be set: +.Bl -tag -width Ds +.It Dv SSL_ST_ACCEPT +This bit is set by +.Xr SSL_accept 3 +and by +.Xr SSL_set_accept_state 3 . +It indicates that +.Fa ssl +is set up for server mode and no client initiated the TLS handshake yet. +The function +.Fn SSL_in_accept_init +returns non-zero if this bit is set or 0 otherwise. +.It Dv SSL_ST_BEFORE +This bit is set by the +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_set_accept_state 3 , +and +.Xr SSL_set_connect_state 3 +functions. +It indicates that the TLS handshake was not initiated yet. +The function +.Fn SSL_in_before +returns non-zero if this bit is set or 0 otherwise. +.It Dv SSL_ST_CONNECT +This bit is set by +.Xr SSL_connect 3 +and by +.Xr SSL_set_connect_state 3 . +It indicates that +.Fa ssl +is set up for client mode and no TLS handshake was initiated yet. +The function +.Fn SSL_in_connect_init +returns non-zero if this bit is set or 0 otherwise. +.El +.Pp +The following masks can be used: +.Bl -tag -width Ds +.It Dv SSL_ST_INIT +Set if +.Dv SSL_ST_ACCEPT +or +.Dv SSL_ST_CONNECT +is set. +The function +.Fn SSL_in_init +returns a non-zero value if one of these is set or 0 otherwise. +.It Dv SSL_ST_MASK +This mask includes all bits except +.Dv SSL_ST_ACCEPT , +.Dv SSL_ST_BEFORE , +and +.Dv SSL_ST_CONNECT . +.It Dv SSL_ST_OK +The state is set to this value when a connection is established. +The function +.Fn SSL_is_init_finished +returns a non-zero value if the state equals this constant, or 0 otherwise. +.It Dv SSL_ST_RENEGOTIATE +The program is about to renegotiate, for example when entering +.Xr SSL_read 3 +or +.Xr SSL_write 3 +right after +.Xr SSL_renegotiate 3 +was called. +.El +.Pp +The meaning of other bits is protocol-dependent. +Application programs usually do not need to inspect any of those +other bits. +.Pp +All these functions may be implemented as macros. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_renegotiate 3 , +.Xr SSL_set_connect_state 3 +.Sh HISTORY +.Fn SSL_is_init_finished +first appeared in SSLeay 0.4.5b. +.Fn SSL_state +first appeared in SSLeay 0.5.2. +.Fn SSL_in_accept_init , +.Fn SSL_in_connect_init , +and +.Fn SSL_in_init +first appeared in SSLeay 0.6.0. +.Fn SSL_in_before +first appeared in SSLeay 0.8.0. +.Fn SSL_get_state +first appeared in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_get_verify_result.3 b/static/openbsd/man3/SSL_get_verify_result.3 new file mode 100644 index 00000000..32a397f4 --- /dev/null +++ b/static/openbsd/man3/SSL_get_verify_result.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: SSL_get_verify_result.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_VERIFY_RESULT 3 +.Os +.Sh NAME +.Nm SSL_get_verify_result +.Nd get result of peer certificate verification +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fn SSL_get_verify_result "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_verify_result +returns the result of the verification of the X509 certificate presented by the +peer, if any. +.Pp +.Fn SSL_get_verify_result +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 +.Fn SSL_get_verify_result . +.Pp +The verification result is part of the established session and is restored when +a session is reused. +.Sh RETURN VALUES +The following return values can currently occur: +.Bl -tag -width Ds +.It Dv X509_V_OK +The verification succeeded or no peer certificate was presented. +.It Any other value +Documented in +.Xr openssl 1 . +.El +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr SSL_get0_peername 3 , +.Xr SSL_get_peer_certificate 3 , +.Xr SSL_set_verify_result 3 +.Sh HISTORY +.Fn SSL_get_verify_result +first appeared in SSLeay 0.6.1 and has been available since +.Ox 2.4 . +.Sh BUGS +If no peer certificate was presented, the returned result code is +.Dv X509_V_OK . +This is because no verification error occurred; +however, it does not indicate success. +.Fn SSL_get_verify_result +is only useful in connection with +.Xr SSL_get_peer_certificate 3 . diff --git a/static/openbsd/man3/SSL_get_version.3 b/static/openbsd/man3/SSL_get_version.3 new file mode 100644 index 00000000..d32dd34e --- /dev/null +++ b/static/openbsd/man3/SSL_get_version.3 @@ -0,0 +1,118 @@ +.\" $OpenBSD: SSL_get_version.3,v 1.10 2025/06/08 22:49:42 schwarze Exp $ +.\" full merge up to: OpenSSL e417070c Jun 8 11:37:06 2016 -0400 +.\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_GET_VERSION 3 +.Os +.Sh NAME +.Nm SSL_get_version , +.Nm SSL_is_dtls , +.Nm SSL_version +.Nd get the protocol information of a connection +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft const char * +.Fn SSL_get_version "const SSL *ssl" +.Ft int +.Fn SSL_is_dtls "const SSL *ssl" +.Ft int +.Fn SSL_version "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_version +returns the name of the protocol used for the connection +.Fa ssl . +.Pp +.Fn SSL_is_dtls +returns 1 if the connection is using DTLS, 0 if not. +.Pp +.Fn SSL_version +returns an integer constant representing that protocol. +.Pp +These functions only return reliable results +after the initial handshake has been completed. +.Sh RETURN VALUES +The following strings or integers can be returned by +.Fn SSL_get_version +and +.Fn SSL_version : +.Bl -tag -width Ds +.It Qo TLSv1 Qc No or Dv TLS1_VERSION +The connection uses the TLSv1.0 protocol. +.It Qo TLSv1.1 Qc No or Dv TLS1_1_VERSION +The connection uses the TLSv1.1 protocol. +.It Qo TLSv1.2 Qc No or Dv TLS1_2_VERSION +The connection uses the TLSv1.2 protocol. +.It Qo TLSv1.3 Qc No or Dv TLS1_3_VERSION +The connection uses the TLSv1.3 protocol. +.It Qo DTLSv1 Qc No or Dv DTLS1_VERSION +The connection uses the Datagram Transport Layer Security 1.0 protocol. +.It Qo DTLSv1.2 Qc No or Dv DTLS1_2_VERSION +The connection uses the Datagram Transport Layer Security 1.2 protocol. +.It Qq unknown +This indicates an unknown protocol version; +it cannot currently happen with LibreSSL. +.El +.Pp +.Fn SSL_is_dtls +returns 1 if the connection uses DTLS, 0 if not. +.Sh SEE ALSO +.Xr ssl 3 +.Sh HISTORY +.Fn SSL_get_version +and +.Fn SSL_version +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn SSL_is_dtls +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.9 . diff --git a/static/openbsd/man3/SSL_library_init.3 b/static/openbsd/man3/SSL_library_init.3 new file mode 100644 index 00000000..d25a2486 --- /dev/null +++ b/static/openbsd/man3/SSL_library_init.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: SSL_library_init.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2006, 2010 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_LIBRARY_INIT 3 +.Os +.Sh NAME +.Nm SSL_library_init , +.Nm OpenSSL_add_ssl_algorithms , +.Nm SSLeay_add_ssl_algorithms +.Nd initialize SSL library by registering algorithms +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_library_init void +.Ft int +.Fn OpenSSL_add_ssl_algorithms void +.Ft int +.Fn SSLeay_add_ssl_algorithms void +.Sh DESCRIPTION +These functions are deprecated. +It is never useful for any application program to call any of them explicitly. +The library automatically calls them internally whenever needed. +.Pp +.Fn SSL_library_init +registers the available ciphers and digests +which are used directly or indirectly by TLS. +.Pp +.Fn OpenSSL_add_ssl_algorithms +and +.Fn SSLeay_add_ssl_algorithms +are synonyms for +.Fn SSL_library_init +and are implemented as macros. +.Sh RETURN VALUES +.Fn SSL_library_init +always returns 1. +.Sh SEE ALSO +.Xr ssl 3 +.Sh HISTORY +.Fn SSLeay_add_ssl_algorithms +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . +.Pp +.Fn SSL_library_init +first appeared in OpenSSL 0.9.2b and has been available since +.Ox 2.6 . +.Pp +.Fn OpenSSL_add_ssl_algorithms +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/SSL_load_client_CA_file.3 b/static/openbsd/man3/SSL_load_client_CA_file.3 new file mode 100644 index 00000000..e57900c9 --- /dev/null +++ b/static/openbsd/man3/SSL_load_client_CA_file.3 @@ -0,0 +1,186 @@ +.\" $OpenBSD: SSL_load_client_CA_file.3,v 1.10 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016 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. +.\" +.\" The original file was written by Lutz Jaenicke . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_LOAD_CLIENT_CA_FILE 3 +.Os +.Sh NAME +.Nm SSL_load_client_CA_file , +.Nm SSL_add_file_cert_subjects_to_stack , +.Nm SSL_add_dir_cert_subjects_to_stack +.Nd load certificate names from files +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft STACK_OF(X509_NAME) * +.Fn SSL_load_client_CA_file "const char *file" +.Ft int +.Fo SSL_add_file_cert_subjects_to_stack +.Fa "STACK_OF(X509_NAME) *stack" +.Fa "const char *file" +.Fc +.Ft int +.Fo SSL_add_dir_cert_subjects_to_stack +.Fa "STACK_OF(X509_NAME) *stack" +.Fa "const char *dir" +.Fc +.Sh DESCRIPTION +.Fn SSL_load_client_CA_file +reads PEM formatted certificates from +.Fa file +and returns a new +.Vt STACK_OF(X509_NAME) +with the subject names found. +While the name suggests the specific usage as a support function for +.Xr SSL_CTX_set_client_CA_list 3 , +it is not limited to CA certificates. +.Pp +.Fn SSL_add_file_cert_subjects_to_stack +is similar except that the names are added to the existing +.Fa stack . +.Pp +.Fn SSL_add_dir_cert_subjects_to_stack +calls +.Fn SSL_add_file_cert_subjects_to_stack +on every file in the directory +.Fa dir . +.Pp +If a name is already on the stack, all these functions skip it and +do not add it again. +.Sh RETURN VALUES +.Fn SSL_load_client_CA_file +returns a pointer to the new +.Vt STACK_OF(X509_NAME) +or +.Dv NULL on failure . +.Pp +.Fn SSL_add_file_cert_subjects_to_stack +and +.Fn SSL_add_dir_cert_subjects_to_stack +return 1 for success or 0 for failure. +.Pp +All these functions treat empty files and directories as failures. +.Pp +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Sh EXAMPLES +Load names of CAs from a file and use it as a client CA list: +.Bd -literal +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_handling(); +\&... +.Ed +.Sh SEE ALSO +.Xr PEM_read_bio_X509 3 , +.Xr ssl 3 , +.Xr SSL_CTX_set_client_CA_list 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_NAME_new 3 +.Sh HISTORY +.Fn SSL_load_client_CA_file +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . +.Pp +.Fn SSL_add_file_cert_subjects_to_stack +and +.Fn SSL_add_dir_cert_subjects_to_stack +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . +.Sh AUTHORS +.Fn SSL_add_file_cert_subjects_to_stack +and +.Fn SSL_add_dir_cert_subjects_to_stack +were written by +.An Ben Laurie Aq Mt ben@openssl.org +in 1999. +.Sh BUGS +In some cases of failure, for example for empty files and directories, +these functions fail to report an error, in the sense that +.Xr ERR_get_error 3 +does not work. +.Pp +Even in case of failure, for example when parsing one of the +files or certificates fails, +.Fn SSL_add_file_cert_subjects_to_stack +and +.Fn SSL_add_dir_cert_subjects_to_stack +may still have added some certificates to the stack. +.Pp +The behaviour of +.Fn SSL_add_dir_cert_subjects_to_stack +is non-deterministic. +If parsing one file fails, parsing of the whole directory is aborted. +Files in the directory are not parsed in any specific order. +For example, adding an empty file to +.Fa dir +may or may not cause some of the other files to be ignored. diff --git a/static/openbsd/man3/SSL_new.3 b/static/openbsd/man3/SSL_new.3 new file mode 100644 index 00000000..3906a346 --- /dev/null +++ b/static/openbsd/man3/SSL_new.3 @@ -0,0 +1,111 @@ +.\" $OpenBSD: SSL_new.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 1c7ae3dd Mar 29 19:17:55 2017 +1000 +.\" +.\" This file was written by Richard Levitte +.\" and Matt Caswell . +.\" Copyright (c) 2000, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_NEW 3 +.Os +.Sh NAME +.Nm SSL_new , +.Nm SSL_up_ref +.Nd create a new SSL structure for a connection +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft SSL * +.Fn SSL_new "SSL_CTX *ctx" +.Ft int +.Fn SSL_up_ref "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_new +creates a new +.Vt SSL +structure which is needed to hold the data for a TLS/SSL connection. +The new structure inherits the settings of the underlying context +.Fa ctx : +connection method, options, verification settings, +timeout settings, security level. +The reference count of the new structure is set to 1. +.Pp +.Fn SSL_up_ref +increments the reference count of +.Fa ssl +by 1. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +The creation of a new +.Vt SSL +structure failed. +Check the error stack to find out the reason. +.It Pointer to an Vt SSL No structure +The return value points to an allocated +.Vt SSL +structure. +.El +.Pp +.Fn SSL_up_ref +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_CTX_set_security_level 3 , +.Xr SSL_free 3 , +.Xr SSL_get_SSL_CTX 3 +.Sh HISTORY +.Fn SSL_new +appeared in SSLeay 0.4 or earlier and has been available since +.Ox 2.4 . +.Pp +.Fn SSL_up_ref +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_num_renegotiations.3 b/static/openbsd/man3/SSL_num_renegotiations.3 new file mode 100644 index 00000000..d366f97c --- /dev/null +++ b/static/openbsd/man3/SSL_num_renegotiations.3 @@ -0,0 +1,76 @@ +.\" $OpenBSD: SSL_num_renegotiations.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt SSL_NUM_RENEGOTIATIONS 3 +.Os +.Sh NAME +.Nm SSL_num_renegotiations , +.Nm SSL_clear_num_renegotiations , +.Nm SSL_total_renegotiations +.Nd renegotiation counters +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fo SSL_num_renegotiations +.Fa "SSL *ssl" +.Fc +.Ft long +.Fo SSL_clear_num_renegotiations +.Fa "SSL *ssl" +.Fc +.Ft long +.Fo SSL_total_renegotiations +.Fa "SSL *ssl" +.Fc +.Sh DESCRIPTION +.Fn SSL_num_renegotiations +reports the number of renegotiations initiated in +.Fa ssl +since +.Xr SSL_new 3 , +.Xr SSL_clear 3 , +or +.Fn SSL_clear_num_renegotiations +was last called on that object. +.Pp +.Fn SSL_clear_num_renegotiations +does the same and additionally resets the renegotiation counter to 0. +.Pp +.Fn SSL_total_renegotiations +reports the number of renegotiations initiated in +.Fa ssl +since +.Xr SSL_new 3 +or +.Xr SSL_clear 3 +was last called on that object. +.Pp +These functions are implemented as macros. +.Sh RETURN VALUES +All these functions return a number of renegotiations. +.Sh SEE ALSO +.Xr BIO_set_ssl_renegotiate_bytes 3 , +.Xr ssl 3 , +.Xr SSL_ctrl 3 , +.Xr SSL_read 3 , +.Xr SSL_renegotiate 3 , +.Xr SSL_write 3 +.Sh HISTORY +These functions first appeared in SSLeay 0.9.0 +and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_pending.3 b/static/openbsd/man3/SSL_pending.3 new file mode 100644 index 00000000..c304302e --- /dev/null +++ b/static/openbsd/man3/SSL_pending.3 @@ -0,0 +1,91 @@ +.\" $OpenBSD: SSL_pending.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" +.\" This file was written by Lutz Jaenicke , +.\" Bodo Moeller , and Matt Caswell . +.\" Copyright (c) 2000, 2005, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_PENDING 3 +.Os +.Sh NAME +.Nm SSL_pending +.Nd obtain number of readable bytes buffered in an SSL object +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_pending "const SSL *ssl" +.Sh DESCRIPTION +Data is received in whole blocks known as records from the peer. +A whole record is processed, for example decrypted, in one go and +is buffered until it is read by the application via a call to +.Xr SSL_read 3 . +.Pp +.Fn SSL_pending +returns the number of bytes of application data which are available +for immediate read. +.Pp +.Fn SSL_pending +takes into account only bytes from the TLS/SSL record that is +currently being processed (if any). +.Sh RETURN VALUES +.Fn SSL_pending +returns the number of buffered and processed application data +bytes that are pending and are available for immediate read. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_read 3 +.Sh HISTORY +.Fn SSL_pending +appeared in SSLeay 0.4 or earlier and has been available since +.Ox 2.4 . +.Sh BUGS +Up to OpenSSL 0.9.6, +.Fn SSL_pending +did not check if the record type of pending data is application data. diff --git a/static/openbsd/man3/SSL_read.3 b/static/openbsd/man3/SSL_read.3 new file mode 100644 index 00000000..3d42fd8a --- /dev/null +++ b/static/openbsd/man3/SSL_read.3 @@ -0,0 +1,279 @@ +.\" $OpenBSD: SSL_read.3,v 1.9 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL 5a2443ae Nov 14 11:37:36 2016 +0000 +.\" partial merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file was written by Lutz Jaenicke and +.\" Matt Caswell . +.\" Copyright (c) 2000, 2001, 2008, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_READ 3 +.Os +.Sh NAME +.Nm SSL_read_ex , +.Nm SSL_read , +.Nm SSL_peek_ex , +.Nm SSL_peek +.Nd read bytes from a TLS connection +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_read_ex "SSL *ssl" "void *buf" "size_t num" "size_t *readbytes" +.Ft int +.Fn SSL_read "SSL *ssl" "void *buf" "int num" +.Ft int +.Fn SSL_peek_ex "SSL *ssl" "void *buf" "size_t num" "size_t *readbytes" +.Ft int +.Fn SSL_peek "SSL *ssl" "void *buf" "int num" +.Sh DESCRIPTION +.Fn SSL_read_ex +and +.Fn SSL_read +try to read +.Fa num +bytes from the specified +.Fa ssl +into the buffer +.Fa buf . +On success +.Fn SSL_read_ex +stores the number of bytes actually read in +.Pf * Fa readbytes . +.Pp +.Fn SSL_peek_ex +and +.Fn SSL_peek +are identical to +.Fn SSL_read_ex +and +.Fn SSL_read , +respectively, +except that no bytes are removed from the underlying BIO during +the read, such that a subsequent call to +.Fn SSL_read_ex +or +.Fn SSL_read +will yield at least the same bytes once again. +.Pp +In the following, +.Fn SSL_read_ex , +.Fn SSL_read , +.Fn SSL_peek_ex , +and +.Fn SSL_peek +are called +.Dq read functions . +.Pp +If necessary, a read function will negotiate a TLS session, if +not already explicitly performed by +.Xr SSL_connect 3 +or +.Xr SSL_accept 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 +.Vt BIO . +.Pp +For the transparent negotiation to succeed, the +.Fa ssl +must have been initialized to client or server mode. +This is done by calling +.Xr SSL_set_connect_state 3 +or +.Xr SSL_set_accept_state 3 +before the first call to a read function. +.Pp +The read functions work based on the TLS records. +The data are received in records (with a maximum record size of 16kB). +Only when a record has been completely received, it can be processed +(decrypted and checked for integrity). +Therefore, data that was not retrieved at the last read call can +still be buffered inside the TLS layer and will be retrieved on the +next read call. +If +.Fa num +is higher than the number of bytes buffered, 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 the record will be returned. +As the size of a 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 the underlying +.Vt BIO +is blocking, +a read function will only return once the read operation has been +finished or an error occurred, except when a renegotiation takes +place, in which case an +.Dv SSL_ERROR_WANT_READ +may occur. +This behavior can be controlled with the +.Dv SSL_MODE_AUTO_RETRY +flag of the +.Xr SSL_CTX_set_mode 3 +call. +.Pp +If the underlying +.Vt BIO +is non-blocking, a read function will also return when the underlying +.Vt BIO +could not satisfy the needs of the function to continue the operation. +In this case a call to +.Xr SSL_get_error 3 +with the return value of the read function will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +As at any time a re-negotiation is possible, a read function may +also cause write operations. +The calling process must then repeat the call after taking appropriate +action to satisfy the needs of the read function. +The action depends on the underlying +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Pp +.Xr SSL_pending 3 +can be used to find out whether there are buffered bytes available for +immediate retrieval. +In this case a read function can be called without blocking or +actually receiving new data from the underlying socket. +.Pp +When a read function operation has to be repeated because of +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE , +it must be repeated with the same arguments. +.Sh RETURN VALUES +.Fn SSL_read_ex +and +.Fn SSL_peek_ex +return 1 for success or 0 for failure. +Success means that one 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 +.Xr SSL_get_error 3 +to find out the reason which indicates whether the call is retryable or not. +.Pp +For +.Fn SSL_read +and +.Fn SSL_peek , +the following return values can occur: +.Bl -tag -width Ds +.It >0 +The read operation was successful. +The return value is the number of bytes actually read from the +TLS connection. +.It 0 +The read operation was not successful. +The reason may either be a clean shutdown due to a +.Dq close notify +alert sent by the peer (in which case the +.Dv SSL_RECEIVED_SHUTDOWN +flag in the ssl shutdown state is set (see +.Xr SSL_shutdown 3 +and +.Xr SSL_set_shutdown 3 ) . +It is also possible that the peer simply shut down the underlying transport and +the shutdown is incomplete. +Call +.Xr SSL_get_error 3 +with the return value to find out whether an error occurred or the connection +was shut down cleanly +.Pq Dv SSL_ERROR_ZERO_RETURN . +.It <0 +The read operation was not successful, because either an error occurred or +action must be taken by the calling process. +Call +.Xr SSL_get_error 3 +with the return value to find out the reason. +.El +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_set_mode 3 , +.Xr SSL_get_error 3 , +.Xr SSL_pending 3 , +.Xr SSL_set_connect_state 3 , +.Xr SSL_set_shutdown 3 , +.Xr SSL_shutdown 3 , +.Xr SSL_write 3 +.Sh HISTORY +.Fn SSL_read +appeared in SSLeay 0.4 or earlier. +.Fn SSL_peek +first appeared in SSLeay 0.6.6. +Both functions have been available since +.Ox 2.4 . +.Pp +.Fn SSL_read_ex +and +.Fn SSL_peek_ex +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/SSL_read_early_data.3 b/static/openbsd/man3/SSL_read_early_data.3 new file mode 100644 index 00000000..d36b1e49 --- /dev/null +++ b/static/openbsd/man3/SSL_read_early_data.3 @@ -0,0 +1,175 @@ +.\" $OpenBSD: SSL_read_early_data.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" content checked up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 +.\" +.\" Copyright (c) 2020 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 $Mdocdate: June 8 2025 $ +.Dt SSL_READ_EARLY_DATA 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_max_early_data , +.Nm SSL_set_max_early_data , +.Nm SSL_SESSION_set_max_early_data , +.Nm SSL_CTX_get_max_early_data , +.Nm SSL_get_max_early_data , +.Nm SSL_SESSION_get_max_early_data , +.Nm SSL_write_early_data , +.Nm SSL_read_early_data , +.Nm SSL_get_early_data_status +.Nd transmit application data during the handshake +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_set_max_early_data +.Fa "SSL_CTX *ctx" +.Fa "uint32_t max_bytes" +.Fc +.Ft int +.Fo SSL_set_max_early_data +.Fa "SSL *ssl" +.Fa "uint32_t max_bytes" +.Fc +.Ft int +.Fo SSL_SESSION_set_max_early_data +.Fa "SSL_SESSION *session" +.Fa "uint32_t max_bytes" +.Fc +.Ft uint32_t +.Fo SSL_CTX_get_max_early_data +.Fa "const SSL_CTX *ctx" +.Fc +.Ft uint32_t +.Fo SSL_get_max_early_data +.Fa "const SSL *ssl" +.Fc +.Ft uint32_t +.Fo SSL_SESSION_get_max_early_data +.Fa "const SSL_SESSION *session" +.Fc +.Ft int +.Fo SSL_write_early_data +.Fa "SSL *ssl" +.Fa "const void *buf" +.Fa "size_t len" +.Fa "size_t *written" +.Fc +.Ft int +.Fo SSL_read_early_data +.Fa "SSL *ssl" +.Fa "void *buf" +.Fa "size_t maxlen" +.Fa "size_t *readbytes" +.Fc +.Ft int +.Fo SSL_get_early_data_status +.Fa "const SSL *ssl" +.Fc +.Sh DESCRIPTION +In LibreSSL, these functions have no effect. +They are only provided because some application programs +expect the API to be available when TLSv1.3 is supported. +Using these functions is strongly discouraged because they provide +marginal benefit in the first place even when implemented and +used as designed, because they have absurdly complicated semantics, +and because when they are used, inconspicuous oversights are likely +to cause serious security vulnerabilities. +.Pp +If these functions are used, other TLS implementations +may allow the transfer of application data during the initial handshake. +Even when used as designed, security of the connection is compromised; +in particular, application data is exchanged with unauthenticated peers, +and there is no forward secrecy. +Other downsides include an increased risk of replay attacks. +.Pp +.Fn SSL_CTX_set_max_early_data , +.Fn SSL_set_max_early_data , +and +.Fn SSL_SESSION_set_max_early_data +are intended to configure the maximum number of bytes per session +that can be transmitted during the handshake. +With LibreSSL, all arguments are ignored. +.Pp +An endpoint can attempt to send application data with +.Fn SSL_write_early_data +during the handshake. +With LibreSSL, such attempts always fail and set +.Pf * Fa written +to 0. +.Pp +A server can attempt to read application data from the client using +.Fn SSL_read_early_data +during the handshake. +With LibreSSL, no such data is ever accepted and +.Pf * Fa readbytes +is always set to 0. +.Sh RETURN VALUES +.Fn SSL_CTX_set_max_early_data , +.Fn SSL_set_max_early_data , +and +.Fn SSL_SESSION_set_max_early_data +return 1 for success or 0 for failure. +With LibreSSL, they always succeed. +.Pp +.Fn SSL_CTX_get_max_early_data , +.Fn SSL_get_max_early_data , +and +.Fn SSL_SESSION_get_max_early_data +return the maximum number of bytes of application data +that will be accepted from the peer during the handshake. +With LibreSSL, they always return 0. +.Pp +.Fn SSL_write_early_data +returns 1 for success or 0 for failure. +With LibreSSL, it always fails. +.Pp +With LibreSSL, +.Fn SSL_read_early_data +always returns +.Dv SSL_READ_EARLY_DATA_FINISH +on the server side and +.Dv SSL_READ_EARLY_DATA_ERROR +on the client side. +.Dv SSL_READ_EARLY_DATA_SUCCESS +can occur with other implementations, but not with LibreSSL. +.Pp +With LibreSSL, +.Fn SSL_get_early_data_status +always returns +.Dv SSL_EARLY_DATA_REJECTED . +With other implementations, it might also return +.Dv SSL_EARLY_DATA_NOT_SENT +or +.Dv SSL_EARLY_DATA_ACCEPTED . +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_read 3 , +.Xr SSL_write 3 +.Sh STANDARDS +RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3: +.Bl -tag -width "section 4.2.10" -compact +.It Section 2.3 +0-RTT data +.It Section 4.2.10 +Early Data Indication +.It Section 8 +0-RTT and Anti-Replay +.It Appendix E.5 +Replay Attacks on 0-RTT +.El +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.1 +and have been available since +.Ox 7.0 . diff --git a/static/openbsd/man3/SSL_renegotiate.3 b/static/openbsd/man3/SSL_renegotiate.3 new file mode 100644 index 00000000..badfe8c6 --- /dev/null +++ b/static/openbsd/man3/SSL_renegotiate.3 @@ -0,0 +1,167 @@ +.\" $OpenBSD: SSL_renegotiate.3,v 1.10 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL SSL_key_update.pod 4fbfe86a Feb 16 17:04:40 2017 +0000 +.\" +.\" This file is a derived work. +.\" Some parts are covered by the following Copyright and license: +.\" +.\" 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. +.\" +.\" Other parts were written by Matt Caswell . +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_RENEGOTIATE 3 +.Os +.Sh NAME +.Nm SSL_renegotiate , +.Nm SSL_renegotiate_abbreviated , +.Nm SSL_renegotiate_pending +.Nd initiate a new TLS handshake +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_renegotiate +.Fa "SSL *ssl" +.Fc +.Ft int +.Fo SSL_renegotiate_abbreviated +.Fa "SSL *ssl" +.Fc +.Ft int +.Fo SSL_renegotiate_pending +.Fa "SSL *ssl" +.Fc +.Sh DESCRIPTION +When called from the client side, +.Fn SSL_renegotiate +schedules a completely new handshake over an existing TLS connection. +The next time an I/O operation such as +.Fn SSL_read +or +.Fn SSL_write +takes place on the connection, a check is performed to confirm +that it is a suitable time to start a renegotiation. +If so, a new handshake is initiated immediately. +An existing session associated with the connection is not resumed. +.Pp +This function is automatically called by +.Xr SSL_read 3 +and +.Xr SSL_write 3 +whenever the renegotiation byte count set by +.Xr BIO_set_ssl_renegotiate_bytes 3 +or the timeout set by +.Xr BIO_set_ssl_renegotiate_timeout 3 +are exceeded. +.Pp +When called from the client side, +.Fn SSL_renegotiate_abbreviated +is similar to +.Fn SSL_renegotiate +except that resuming the session associated with the current +connection is attempted in the new handshake. +.Pp +When called from the server side, +.Fn SSL_renegotiate +and +.Fn SSL_renegotiate_abbreviated +behave identically. +They both schedule a request for a new handshake to be sent to the client. +The next time an I/O operation is performed, 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, it is handled transparently during +any I/O function. +.Pp +If a LibreSSL client receives a renegotiation request from a server, +it is also handled transparently during any I/O function. +The client attempts to resume the current session in the new +handshake. +For historical reasons, DTLS clients do not attempt to resume +the session in the new handshake. +.Sh RETURN VALUES +.Fn SSL_renegotiate +and +.Fn SSL_renegotiate_abbreviated +return 1 on success or 0 on error. +.Pp +.Fn SSL_renegotiate_pending +returns 1 if a renegotiation or renegotiation request has been +scheduled but not yet acted on, or 0 otherwise. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_num_renegotiations 3 , +.Xr SSL_read 3 , +.Xr SSL_write 3 +.Sh HISTORY +.Fn SSL_renegotiate +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . +.Pp +.Fn SSL_renegotiate_pending +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Pp +.Fn SSL_renegotiate_abbreviated +first appeared in OpenSSL 1.0.1 and has been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/SSL_rstate_string.3 b/static/openbsd/man3/SSL_rstate_string.3 new file mode 100644 index 00000000..624c1b08 --- /dev/null +++ b/static/openbsd/man3/SSL_rstate_string.3 @@ -0,0 +1,109 @@ +.\" $OpenBSD: SSL_rstate_string.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_RSTATE_STRING 3 +.Os +.Sh NAME +.Nm SSL_rstate_string , +.Nm SSL_rstate_string_long +.Nd get textual description of state of an SSL object during read operation +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft const char * +.Fn SSL_rstate_string "SSL *ssl" +.Ft const char * +.Fn SSL_rstate_string_long "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_rstate_string +returns a 2-letter string indicating the current read state of the +.Vt SSL +object +.Fa ssl . +.Pp +.Fn SSL_rstate_string_long +returns a string indicating the current read state of the +.Vt SSL +object +.Fa ssl . +.Pp +When performing a read operation, the SSL/TLS engine must parse the record, +consisting of header and body. +When working in a blocking environment, +.Fn SSL_rstate_string[_long] +should always return +.Qo RD Qc Ns / Ns Qo read done Qc . +.Pp +This function should only seldom be needed in applications. +.Sh RETURN VALUES +.Fn SSL_rstate_string +and +.Fn SSL_rstate_string_long +can return the following values: +.Bl -tag -width Ds +.It Qo RH Qc Ns / Ns Qo read header Qc +The header of the record is being evaluated. +.It Qo RB Qc Ns / Ns Qo read body Qc +The body of the record is being evaluated. +.It Qo RD Qc Ns / Ns Qo read done Qc +The record has been completely processed. +.It Qo unknown Qc Ns / Ns Qo unknown Qc +The read state is unknown. +This should never happen. +.El +.Sh SEE ALSO +.Xr ssl 3 +.Sh HISTORY +.Fn SSL_rstate_string +and +.Fn SSL_rstate_string_long +first appeared in SSLeay 0.6.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_session_reused.3 b/static/openbsd/man3/SSL_session_reused.3 new file mode 100644 index 00000000..33401446 --- /dev/null +++ b/static/openbsd/man3/SSL_session_reused.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: SSL_session_reused.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SESSION_REUSED 3 +.Os +.Sh NAME +.Nm SSL_session_reused +.Nd query whether a reused session was negotiated during handshake +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_session_reused "SSL *ssl" +.Sh DESCRIPTION +Query whether a reused session was negotiated during the handshake. +.Pp +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 set that can be queried by the application. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +A new session was negotiated. +.It 1 +A session was reused. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_ctrl 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_set_session 3 +.Sh HISTORY +.Fn SSL_session_reused +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_set1_host.3 b/static/openbsd/man3/SSL_set1_host.3 new file mode 100644 index 00000000..2c6cdbe5 --- /dev/null +++ b/static/openbsd/man3/SSL_set1_host.3 @@ -0,0 +1,173 @@ +.\" $OpenBSD: SSL_set1_host.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" selective merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 +.\" +.\" This file was written by Viktor Dukhovni +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SET1_HOST 3 +.Os +.Sh NAME +.Nm SSL_set1_host , +.Nm SSL_set_hostflags , +.Nm SSL_get0_peername +.Nd SSL server verification parameters +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fo SSL_set1_host +.Fa "SSL *ssl" +.Fa "const char *hostname" +.Fc +.Ft void +.Fo SSL_set_hostflags +.Fa "SSL *ssl" +.Fa "unsigned int flags" +.Fc +.Ft const char * +.Fo SSL_get0_peername +.Fa "SSL *ssl" +.Fc +.Sh DESCRIPTION +.Fn SSL_set1_host +configures a server hostname check in the +.Fa ssl +client, setting the expected DNS hostname to +.Fa hostname +and clearing any previously specified hostname. +If +.Fa hostname +is +.Dv NULL +or the empty string, name checks are not performed on the peer certificate. +If a nonempty +.Fa hostname +is specified, certificate verification automatically checks the peer +hostname via +.Xr X509_check_host 3 +with +.Fa flags +set to 0. +.Pp +.Fn SSL_set_hostflags +sets the flags that will be passed to +.Xr X509_check_host 3 +when name checks are applicable, +by default the flags value is 0. +See +.Xr X509_check_host 3 +for the list of available flags and their meaning. +.Pp +.Fn SSL_get0_peername +returns the DNS hostname or subject CommonName from the peer certificate +that matched one of the reference identifiers. +Unless wildcard matching is disabled, the name matched in the peer +certificate may be a wildcard name. +A reference identifier starting with +.Sq \&. +indicates a parent domain prefix rather than a fixed name. +In this case, the matched peername may be a sub-domain +of the reference identifier. +The returned string is owned by the library and is no longer valid +once the associated +.Fa ssl +object is cleared or freed, or if 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 +.Xr X509_check_host 3 . +.Sh RETURN VALUES +.Fn SSL_set1_host +returns 1 for success or 0 for failure. +.Pp +.Fn SSL_get0_peername +returns the matched peername or +.Dv NULL +if peername verification is not applicable +or no trusted peername was matched. +Use +.Xr SSL_get_verify_result 3 +to determine whether verification succeeded. +.Sh EXAMPLES +The calls below check the hostname. +Wildcards are supported, but they 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. +.Bd -literal +if (!SSL_set1_host(ssl, "smtp.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 */ +} +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr SSL_get_peer_certificate 3 , +.Xr SSL_get_verify_result 3 , +.Xr X509_check_host 3 , +.Xr X509_VERIFY_PARAM_set1_host 3 +.Sh HISTORY +All three functions first appeared in OpenSSL 1.1.0. +.Fn SSL_set1_host +has been available since +.Ox 6.5 , +and +.Fn SSL_set_hostflags +and +.Fn SSL_get0_peername +since +.Ox 6.9 . diff --git a/static/openbsd/man3/SSL_set1_param.3 b/static/openbsd/man3/SSL_set1_param.3 new file mode 100644 index 00000000..2d255a09 --- /dev/null +++ b/static/openbsd/man3/SSL_set1_param.3 @@ -0,0 +1,138 @@ +.\" $OpenBSD: SSL_set1_param.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL man3/SSL_CTX_get0_param 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SET1_PARAM 3 +.Os +.Sh NAME +.Nm SSL_CTX_get0_param , +.Nm SSL_get0_param , +.Nm SSL_CTX_set1_param , +.Nm SSL_set1_param +.Nd get and set verification parameters +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft X509_VERIFY_PARAM * +.Fo SSL_CTX_get0_param +.Fa "SSL_CTX *ctx" +.Fc +.Ft X509_VERIFY_PARAM * +.Fo SSL_get0_param +.Fa "SSL *ssl" +.Fc +.Ft int +.Fo SSL_CTX_set1_param +.Fa "SSL_CTX *ctx" +.Fa "X509_VERIFY_PARAM *vpm" +.Fc +.Ft int +.Fo SSL_set1_param +.Fa "SSL *ssl" +.Fa "X509_VERIFY_PARAM *vpm" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_get0_param +and +.Fn SSL_get0_param +retrieve an internal pointer to the verification parameters for +.Fa ctx +or +.Fa ssl , +respectively. +The returned pointer must not be freed by the calling application, +but the application can modify the parameters pointed to, +to suit its needs: for example to add a hostname check. +.Pp +.Fn SSL_CTX_set1_param +and +.Fn SSL_set1_param +set the verification parameters to +.Fa vpm +for +.Fa ctx +or +.Fa ssl . +.Sh RETURN VALUES +.Fn SSL_CTX_get0_param +and +.Fn SSL_get0_param +return a pointer to an +.Vt X509_VERIFY_PARAM +structure. +.Pp +.Fn SSL_CTX_set1_param +and +.Fn SSL_set1_param +return 1 for success or 0 for failure. +.Sh EXAMPLES +Check that the hostname matches +.Pa www.foo.com +in the peer certificate: +.Bd -literal -offset indent +X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl); +X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0); +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr X509_VERIFY_PARAM_set_flags 3 +.Sh HISTORY +.Fn SSL_CTX_set1_param +and +.Fn SSL_set1_param +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +.Fn SSL_CTX_get0_param +and +.Fn SSL_get0_param +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_set_SSL_CTX.3 b/static/openbsd/man3/SSL_set_SSL_CTX.3 new file mode 100644 index 00000000..3a909dab --- /dev/null +++ b/static/openbsd/man3/SSL_set_SSL_CTX.3 @@ -0,0 +1,68 @@ +.\" $OpenBSD: SSL_set_SSL_CTX.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 2020 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 $Mdocdate: June 8 2025 $ +.Dt SSL_SET_SSL_CTX 3 +.Os +.Sh NAME +.Nm SSL_set_SSL_CTX +.Nd modify an SSL connection object to use another context +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft SSL_CTX * +.Fo SSL_set_SSL_CTX +.Fa "SSL *ssl" +.Fa "SSL_CTX* ctx" +.Fc +.Sh DESCRIPTION +.Fn SSL_set_SSL_CTX +causes +.Fa ssl +to use the context +.Fa ctx . +.Pp +If +.Fa ctx +is +.Dv NULL , +.Fa ssl +reverts to using the context that it was initially created from with +.Xr SSL_new 3 . +.Pp +If +.Fa ssl +already uses +.Fa ctx , +no action occurs. +.Sh RETURN VALUES +.Fn SSL_set_SSL_CTX +returns an internal pointer to the context that +.Fa ssl +is using as a result of the call, or +.Dv NULL +if memory allocation fails. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_get_SSL_CTX 3 , +.Xr SSL_new 3 , +.Xr SSL_set_security_level 3 +.Sh HISTORY +.Fn SSL_set_SSL_CTX +first appeared in OpenSSL 0.9.8f and has been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/SSL_set_bio.3 b/static/openbsd/man3/SSL_set_bio.3 new file mode 100644 index 00000000..98ce9a70 --- /dev/null +++ b/static/openbsd/man3/SSL_set_bio.3 @@ -0,0 +1,100 @@ +.\" $OpenBSD: SSL_set_bio.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL acb5b343 Sep 16 16:00:38 2000 +0000 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SET_BIO 3 +.Os +.Sh NAME +.Nm SSL_set_bio +.Nd connect the SSL object with a BIO +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_set_bio "SSL *ssl" "BIO *rbio" "BIO *wbio" +.Sh DESCRIPTION +.Fn SSL_set_bio +connects the +.Vt BIO Ns +s +.Fa rbio +and +.Fa wbio +for the read and write operations of the TLS/SSL (encrypted) side of +.Fa ssl . +.Pp +The SSL engine inherits the behaviour of +.Fa rbio +and +.Fa wbio , +respectively. +If a +.Vt BIO +is non-blocking, the +.Fa ssl +will also have non-blocking behaviour. +.Pp +If there was already a +.Vt BIO +connected to +.Fa ssl , +.Xr BIO_free 3 +will be called (for both the reading and writing side, if different). +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_get_rbio 3 , +.Xr SSL_shutdown 3 +.Sh HISTORY +.Fn SSL_set_bio +first appeared in SSLeay 0.6.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_set_connect_state.3 b/static/openbsd/man3/SSL_set_connect_state.3 new file mode 100644 index 00000000..b7d126d0 --- /dev/null +++ b/static/openbsd/man3/SSL_set_connect_state.3 @@ -0,0 +1,154 @@ +.\" $OpenBSD: SSL_set_connect_state.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" selective merge up to: OpenSSL dbd007d7 Jul 28 13:31:27 2017 +0800 +.\" +.\" This file was written by Lutz Jaenicke +.\" and Paul Yang . +.\" Copyright (c) 2001, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SET_CONNECT_STATE 3 +.Os +.Sh NAME +.Nm SSL_set_connect_state , +.Nm SSL_set_accept_state , +.Nm SSL_is_server +.Nd prepare SSL object to work in client or server mode +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_set_connect_state "SSL *ssl" +.Ft void +.Fn SSL_set_accept_state "SSL *ssl" +.Ft int +.Fn SSL_is_server "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_set_connect_state +sets +.Fa ssl +to work in client mode. +.Pp +.Fn SSL_set_accept_state +sets +.Fa ssl +to work in server mode. +.Pp +.Fn SSL_is_server +checks whether +.Fa ssl +is set to server mode. +.Pp +When the +.Vt SSL_CTX +object was created with +.Xr SSL_CTX_new 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 +.Xr SSL_CTX_set_ssl_version 3 +or +.Xr SSL_set_ssl_method 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 +.Xr SSL_connect 3 +or +.Xr SSL_accept 3 +routines, the correct handshake routines are automatically set. +When performing a transparent negotiation using +.Xr SSL_write 3 +or +.Xr SSL_read 3 , +the handshake routines must be explicitly set in advance using either +.Fn SSL_set_connect_state +or +.Fn SSL_set_accept_state . +.Pp +If +.Fn SSL_is_server +is called before +.Fn SSL_set_connect_state +or +.Fn SSL_set_accept_state +was called either automatically or explicitly, +the result depends on what method was used when the +.Fa SSL_CTX +was created. +If a generic method or a dedicated server method was passed to +.Xr SSL_CTX_new 3 , +.Fn SSL_is_server +returns 1; otherwise, it returns 0. +.Sh RETURN VALUES +.Fn SSL_is_server +returns 1 if +.Fa ssl +is set to server mode or 0 if it is set to client mode. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_set_ssl_version 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_new 3 , +.Xr SSL_read 3 , +.Xr SSL_write 3 +.Sh HISTORY +.Fn SSL_set_connect_state +and +.Fn SSL_set_accept_state +first appeared in SSLeay 0.6.0 and have been available since +.Ox 2.4 . +.Pp +.Fn SSL_is_server +first appeared in OpenSSL 1.0.2 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/SSL_set_fd.3 b/static/openbsd/man3/SSL_set_fd.3 new file mode 100644 index 00000000..3c4441e6 --- /dev/null +++ b/static/openbsd/man3/SSL_set_fd.3 @@ -0,0 +1,130 @@ +.\" $OpenBSD: SSL_set_fd.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SET_FD 3 +.Os +.Sh NAME +.Nm SSL_set_fd , +.Nm SSL_set_rfd , +.Nm SSL_set_wfd +.Nd connect the SSL object with a file descriptor +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_set_fd "SSL *ssl" "int fd" +.Ft int +.Fn SSL_set_rfd "SSL *ssl" "int fd" +.Ft int +.Fn SSL_set_wfd "SSL *ssl" "int fd" +.Sh DESCRIPTION +.Fn SSL_set_fd +sets the file descriptor +.Fa fd +as the input/output facility for the TLS/SSL (encrypted) side of +.Fa ssl . +.Fa fd +will typically be the socket file descriptor of a network connection. +.Pp +When performing the operation, a socket +.Vt BIO +is automatically created to interface between the +.Fa ssl +and +.Fa fd . +The +.Vt BIO +and hence the SSL engine inherit the behaviour of +.Fa fd . +If +.Fa fd +is non-blocking, the +.Fa ssl +will also have non-blocking behaviour. +.Pp +If there was already a +.Vt BIO +connected to +.Fa ssl , +.Xr BIO_free 3 +will be called (for both the reading and writing side, if different). +.Pp +.Fn SSL_set_rfd +and +.Fn SSL_set_wfd +perform the respective action, but only for the read channel or the write +channel, which can be set independently. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The operation failed. +Check the error stack to find out why. +.It 1 +The operation succeeded. +.El +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_get_fd 3 , +.Xr SSL_set_bio 3 , +.Xr SSL_shutdown 3 +.Sh HISTORY +.Fn SSL_set_fd +appeared in SSLeay 0.4 or earlier. +.Fn SSL_set_rfd +and +.Fn SSL_set_wfd +first appeared in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_set_max_send_fragment.3 b/static/openbsd/man3/SSL_set_max_send_fragment.3 new file mode 100644 index 00000000..d5265ebb --- /dev/null +++ b/static/openbsd/man3/SSL_set_max_send_fragment.3 @@ -0,0 +1,98 @@ +.\" $OpenBSD: SSL_set_max_send_fragment.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL doc/man3/SSL_CTX_set_split_send_fragment.pod +.\" OpenSSL 6782e5fd Oct 21 16:16:20 2016 +0100 +.\" +.\" This file was written by Matt Caswell . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SET_MAX_SEND_FRAGMENT 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_max_send_fragment , +.Nm SSL_set_max_send_fragment +.Nd control fragment sizes +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fo SSL_CTX_set_max_send_fragment +.Fa "SSL_CTX *ctx" +.Fa "long m" +.Fc +.Ft long +.Fo SSL_set_max_send_fragment +.Fa "SSL *ssl" +.Fa "long m" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_max_send_fragment +and +.Fn SSL_set_max_send_fragment +set the +.Sy max_send_fragment +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 +These functions are implemented using macros. +.Sh RETURN VALUES +These functions return 1 on success or 0 on failure. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_ctrl 3 , +.Xr SSL_CTX_set_read_ahead 3 , +.Xr SSL_pending 3 +.Sh HISTORY +.Fn SSL_CTX_set_max_send_fragment +and +.Fn SSL_set_max_send_fragment +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/SSL_set_psk_use_session_callback.3 b/static/openbsd/man3/SSL_set_psk_use_session_callback.3 new file mode 100644 index 00000000..d53f5b97 --- /dev/null +++ b/static/openbsd/man3/SSL_set_psk_use_session_callback.3 @@ -0,0 +1,87 @@ +.\" $OpenBSD: SSL_set_psk_use_session_callback.3,v 1.2 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL man3/SSL_CTX_set_psk_client_callback.pod +.\" checked up to 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt SSL_SET_PSK_USE_SESSION_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_set_psk_use_session_callback , +.Nm SSL_psk_use_session_cb_func +.Nd set TLS pre-shared key client callback +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft typedef int +.Fo (*SSL_psk_use_session_cb_func) +.Fa "SSL *ssl" +.Fa "const EVP_MD *md" +.Fa "const unsigned char **id" +.Fa "size_t *idlen" +.Fa "SSL_SESSION **session" +.Fc +.Ft void +.Fo SSL_set_psk_use_session_callback +.Fa "SSL *ssl" +.Fa "SSL_psk_use_session_cb_func cb" +.Fc +.Sh DESCRIPTION +LibreSSL provides the stub function +.Fn SSL_set_psk_use_session_callback +to allow compiling application programs +that contain optional support for TLSv1.3 pre-shared keys. +.Pp +LibreSSL does not support TLS pre-shared keys, +and no action occurs when +.Fn SSL_set_psk_use_session_callback +is called. +In particular, both arguments are ignored. +During session negotiation, +LibreSSL never calls the callback +.Fa cb +and always behaves as if that callback succeeded and set the +.Pf * Fa session +pointer to +.Dv NULL . +That is, LibreSSL never sends a pre-shared key to the server +and never aborts the handshake for lack of a pre-shared key. +.Pp +With OpenSSL, a client application wishing to use TLSv1.3 pre-shared keys +can install a callback function +.Fa cb +using +.Fn SSL_set_psk_use_session_callback . +The OpenSSL library may call +.Fa cb +once or twice during session negotiation. +If the callback fails, OpenSSL aborts connection setup. +If the callback succeeds but sets the +.Pf * Fa session +pointer to +.Dv NULL , +OpenSSL continues the handshake +but does not send a pre-shared key to the server. +.Sh RETURN VALUES +The +.Fn SSL_psk_use_session_cb_func +callback is expected to return 1 on success or 0 on failure. +.Sh HISTORY +.Fn SSL_set_psk_use_session_callback +and +.Fn SSL_psk_use_session_cb_func +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.0 . diff --git a/static/openbsd/man3/SSL_set_session.3 b/static/openbsd/man3/SSL_set_session.3 new file mode 100644 index 00000000..db3fc6a8 --- /dev/null +++ b/static/openbsd/man3/SSL_set_session.3 @@ -0,0 +1,120 @@ +.\" $OpenBSD: SSL_set_session.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 05ea606a May 20 20:52:46 2016 -0400 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SET_SESSION 3 +.Os +.Sh NAME +.Nm SSL_set_session +.Nd set a TLS/SSL session to be used during TLS/SSL connect +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_set_session "SSL *ssl" "SSL_SESSION *session" +.Sh DESCRIPTION +.Fn SSL_set_session +sets +.Fa session +to be used when the TLS/SSL connection is to be established. +.Fn SSL_set_session +is only useful for TLS/SSL clients. +When the session is set, the reference count of +.Fa session +is incremented +by 1. +If the session is not reused, the reference count is decremented again during +.Fn SSL_connect . +Whether the session was reused can be queried with the +.Xr SSL_session_reused 3 +call. +.Pp +If there is already a session set inside +.Fa ssl +(because it was set with +.Fn SSL_set_session +before or because the same +.Fa ssl +was already used for a connection), +.Xr SSL_SESSION_free 3 +will be called for that session. +.Pp +.Vt SSL_SESSION +objects keep internal link information about the session cache list when being +inserted into one +.Vt SSL_CTX +object's session cache. +One +.Vt SSL_SESSION +object, regardless of its reference count, must therefore only be used with one +.Vt SSL_CTX +object (and the +.Vt SSL +objects created from this +.Vt SSL_CTX +object). +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The operation failed; check the error stack to find out the reason. +.It 1 +The operation succeeded. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_free 3 , +.Xr SSL_session_reused 3 +.Sh HISTORY +.Fn SSL_set_session +first appeared in SSLeay 0.5.2 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_set_shutdown.3 b/static/openbsd/man3/SSL_set_shutdown.3 new file mode 100644 index 00000000..1c1d59e9 --- /dev/null +++ b/static/openbsd/man3/SSL_set_shutdown.3 @@ -0,0 +1,139 @@ +.\" $OpenBSD: SSL_set_shutdown.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SET_SHUTDOWN 3 +.Os +.Sh NAME +.Nm SSL_set_shutdown , +.Nm SSL_get_shutdown +.Nd manipulate shutdown state of an SSL connection +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_set_shutdown "SSL *ssl" "int mode" +.Ft int +.Fn SSL_get_shutdown "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_set_shutdown +sets the shutdown state of +.Fa ssl +to +.Fa mode . +.Pp +.Fn SSL_get_shutdown +returns the shutdown mode of +.Fa ssl . +.Pp +The shutdown state of an ssl connection is a bitmask of: +.Bl -tag -width Ds +.It 0 +No shutdown setting, yet. +.It Dv SSL_SENT_SHUTDOWN +A +.Dq close notify +shutdown alert was sent to the peer; the connection is being considered closed +and the session is closed and correct. +.It Dv SSL_RECEIVED_SHUTDOWN +A shutdown alert was received from the peer, either a normal +.Dq close notify +or a fatal error. +.El +.Pp +.Dv SSL_SENT_SHUTDOWN +and +.Dv 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 +.Fa ssl +session. +If the session is still open when +.Xr SSL_clear 3 +or +.Xr SSL_free 3 +is called, it is considered bad and removed according to RFC 2246. +The actual condition for a correctly closed session is +.Dv SSL_SENT_SHUTDOWN +(according to the TLS RFC, it is acceptable to only send the +.Dq close notify +alert but to not wait for the peer's answer when the underlying connection is +closed). +.Fn SSL_set_shutdown +can be used to set this state without sending a close alert to the peer (see +.Xr SSL_shutdown 3 ) . +.Pp +If a +.Dq close notify +was received, +.Dv SSL_RECEIVED_SHUTDOWN +will be set, but to set +.Dv SSL_SENT_SHUTDOWN +the application must still call +.Xr SSL_shutdown 3 +or +.Fn SSL_set_shutdown +itself. +.Sh RETURN VALUES +.Fn SSL_get_shutdown +returns the current setting. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_set_quiet_shutdown 3 , +.Xr SSL_free 3 , +.Xr SSL_shutdown 3 +.Sh HISTORY +.Fn SSL_set_shutdown +and +.Fn SSL_get_shutdown +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_set_tmp_ecdh.3 b/static/openbsd/man3/SSL_set_tmp_ecdh.3 new file mode 100644 index 00000000..0794efdf --- /dev/null +++ b/static/openbsd/man3/SSL_set_tmp_ecdh.3 @@ -0,0 +1,120 @@ +.\" $OpenBSD: SSL_set_tmp_ecdh.3,v 1.7 2025/06/08 22:52:00 schwarze Exp $ +.\" +.\" Copyright (c) 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 $Mdocdate: June 8 2025 $ +.Dt SSL_SET_TMP_ECDH 3 +.Os +.Sh NAME +.Nm SSL_set_tmp_ecdh , +.Nm SSL_CTX_set_tmp_ecdh , +.Nm SSL_set_ecdh_auto , +.Nm SSL_CTX_set_ecdh_auto , +.Nm SSL_set_tmp_ecdh_callback , +.Nm SSL_CTX_set_tmp_ecdh_callback +.Nd select a curve for ECDH ephemeral key exchange +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft long +.Fo SSL_set_tmp_ecdh +.Fa "SSL *ssl" +.Fa "EC_KEY *ecdh" +.Fc +.Ft long +.Fo SSL_CTX_set_tmp_ecdh +.Fa "SSL_CTX *ctx" +.Fa "EC_KEY *ecdh" +.Fc +.Ft long +.Fo SSL_set_ecdh_auto +.Fa "SSL *ssl" +.Fa "int state" +.Fc +.Ft long +.Fo SSL_CTX_set_ecdh_auto +.Fa "SSL_CTX *ctx" +.Fa "int state" +.Fc +.Ft void +.Fo SSL_set_tmp_ecdh_callback +.Fa "SSL *ssl" +.Fa "EC_KEY *(*ecdh)(SSL *ssl, int is_export, int keylength)" +.Fc +.Ft void +.Fo SSL_CTX_set_tmp_ecdh_callback +.Fa "SSL_CTX *ctx" +.Fa "EC_KEY *(*ecdh)(SSL *ssl, int is_export, int keylength)" +.Fc +.Sh DESCRIPTION +Automatic EC curve selection and generation is always enabled in +LibreSSL, and applications cannot manually provide EC keys for use +with ECDH key exchange. +.Pp +The only remaining effect of +.Fn SSL_set_tmp_ecdh +is that the curve of the given +.Fa ecdh +key becomes the only curve enabled for the +.Fa ssl +connection, so it is equivalent to calling +.Xr SSL_set1_groups_list 3 +with the same single curve name. +.Pp +.Fn SSL_CTX_set_tmp_ecdh +has the same effect on all connections that will be created from +.Fa ctx +in the future. +.Pp +The functions +.Fn SSL_set_ecdh_auto , +.Fn SSL_CTX_set_ecdh_auto , +.Fn SSL_set_tmp_ecdh_callback , +and +.Fn SSL_CTX_set_tmp_ecdh_callback +are deprecated and have no effect. +.Sh RETURN VALUES +.Fn SSL_set_tmp_ecdh +and +.Fn SSL_CTX_set_tmp_ecdh +return 1 on success or 0 on failure. +.Pp +.Fn SSL_set_ecdh_auto , +.Fn SSL_CTX_set_ecdh_auto , +.Fn SSL_set_tmp_ecdh_callback , +and +.Fn SSL_CTX_set_tmp_ecdh_callback +always return 1. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set1_groups 3 , +.Xr SSL_CTX_set_cipher_list 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_CTX_set_tmp_dh_callback 3 , +.Xr SSL_new 3 +.Sh HISTORY +.Fn SSL_set_tmp_ecdh , +.Fn SSL_CTX_set_tmp_ecdh , +.Fn SSL_set_tmp_ecdh_callback , +and +.Fn SSL_CTX_set_tmp_ecdh_callback +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn SSL_CTX_set_ecdh_auto +and +.Fn SSL_set_ecdh_auto +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 5.7 . diff --git a/static/openbsd/man3/SSL_set_verify_result.3 b/static/openbsd/man3/SSL_set_verify_result.3 new file mode 100644 index 00000000..f43d375b --- /dev/null +++ b/static/openbsd/man3/SSL_set_verify_result.3 @@ -0,0 +1,91 @@ +.\" $OpenBSD: SSL_set_verify_result.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SET_VERIFY_RESULT 3 +.Os +.Sh NAME +.Nm SSL_set_verify_result +.Nd override result of peer certificate verification +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft void +.Fn SSL_set_verify_result "SSL *ssl" "long verify_result" +.Sh DESCRIPTION +.Fn SSL_set_verify_result +sets +.Fa verify_result +of the object +.Fa ssl +to be the result of the verification of the X509 certificate presented by the +peer, if any. +.Pp +.Fn SSL_set_verify_result +overrides the verification result. +It only changes the verification result of the +.Fa ssl +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 +.Fa verify_result +are documented in +.Xr openssl 1 . +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_get_peer_certificate 3 , +.Xr SSL_get_verify_result 3 +.Sh HISTORY +.Fn SSL_set_verify_result +first appeared in SSLeay 0.6.1 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_shutdown.3 b/static/openbsd/man3/SSL_shutdown.3 new file mode 100644 index 00000000..ad49a47d --- /dev/null +++ b/static/openbsd/man3/SSL_shutdown.3 @@ -0,0 +1,254 @@ +.\" $OpenBSD: SSL_shutdown.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2000, 2001, 2004, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_SHUTDOWN 3 +.Os +.Sh NAME +.Nm SSL_shutdown +.Nd shut down a TLS/SSL connection +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_shutdown "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_shutdown +shuts down an active TLS/SSL connection. +It sends the +.Dq close notify +shutdown alert to the peer. +.Pp +.Fn SSL_shutdown +tries to send the +.Dq close notify +shutdown alert to the peer. +Whether the operation succeeds or not, the +.Dv SSL_SENT_SHUTDOWN +flag is set and a currently open session is considered closed and good and will +be kept in the session cache for further reuse. +.Pp +The shutdown procedure consists of 2 steps: the sending of the +.Dq close notify +shutdown alert and the reception of the peer's +.Dq close notify +shutdown alert. +According to the TLS standard, it is acceptable for an application to only send +its shutdown alert and then close the underlying connection without waiting for +the peer's response (this way resources can be saved, as the process can +already terminate or serve another connection). +When the underlying connection shall be used for more communications, +the complete shutdown procedure (bidirectional +.Dq close notify +alerts) must be performed, so that the peers stay synchronized. +.Pp +.Fn SSL_shutdown +supports both uni- and bidirectional shutdown by its 2 step behavior. +.Pp +When the application is the first party to send the +.Dq close notify +alert, +.Fn SSL_shutdown +will only send the alert and then set the +.Dv SSL_SENT_SHUTDOWN +flag (so that the session is considered good and will be kept in cache). +.Fn SSL_shutdown +will then return 0. +If a unidirectional shutdown is enough +(the underlying connection shall be closed anyway), this first call to +.Fn SSL_shutdown +is sufficient. +In order to complete the bidirectional shutdown handshake, +.Fn SSL_shutdown +must be called again. +The second call will make +.Fn SSL_shutdown +wait for the peer's +.Dq close notify +shutdown alert. +On success, the second call to +.Fn SSL_shutdown +will return 1. +.Pp +If the peer already sent the +.Dq close notify +alert and it was already processed implicitly inside another function +.Pq Xr SSL_read 3 , +the +.Dv SSL_RECEIVED_SHUTDOWN +flag is set. +.Fn SSL_shutdown +will send the +.Dq close notify +alert, set the +.Dv SSL_SENT_SHUTDOWN +flag and will immediately return with 1. +Whether +.Dv SSL_RECEIVED_SHUTDOWN +is already set can be checked using the +.Fn SSL_get_shutdown +(see also the +.Xr SSL_set_shutdown 3 +call). +.Pp +It is therefore recommended to check the return value of +.Fn SSL_shutdown +and call +.Fn SSL_shutdown +again, if the bidirectional shutdown is not yet complete (return value of the +first call is 0). +.Pp +The behaviour of +.Fn SSL_shutdown +additionally depends on the underlying +.Vt BIO . +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_shutdown +will only return once the +handshake step has been finished or an error occurred. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_shutdown +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_shutdown +to continue the handshake. +In this case a call to +.Xr SSL_get_error 3 +with the +return value of +.Fn SSL_shutdown +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_shutdown . +The action depends on the underlying +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Pp +.Fn SSL_shutdown +can be modified to only set the connection to +.Dq shutdown +state but not actually send the +.Dq close notify +alert messages; see +.Xr SSL_CTX_set_quiet_shutdown 3 . +When +.Dq quiet shutdown +is enabled, +.Fn SSL_shutdown +will always succeed and return 1. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The shutdown is not yet finished. +Call +.Fn SSL_shutdown +for a second time, if a bidirectional shutdown shall be performed. +The output of +.Xr SSL_get_error 3 +may be misleading, as an erroneous +.Dv SSL_ERROR_SYSCALL +may be flagged even though no error occurred. +.It 1 +The shutdown was successfully completed. +The +.Dq close notify +alert was sent and the peer's +.Dq close notify +alert was received. +.It \(mi1 +The shutdown was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. +It can also occur if action is need to continue the operation for non-blocking +.Vt BIO Ns +s. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.El +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_clear 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_set_quiet_shutdown 3 , +.Xr SSL_free 3 , +.Xr SSL_get_error 3 , +.Xr SSL_set_shutdown 3 +.Sh HISTORY +.Fn SSL_shutdown +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_state_string.3 b/static/openbsd/man3/SSL_state_string.3 new file mode 100644 index 00000000..d202056e --- /dev/null +++ b/static/openbsd/man3/SSL_state_string.3 @@ -0,0 +1,111 @@ +.\" $OpenBSD: SSL_state_string.3,v 1.5 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_STATE_STRING 3 +.Os +.Sh NAME +.Nm SSL_state_string , +.Nm SSL_state_string_long +.Nd get textual description of state of an SSL object +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft const char * +.Fn SSL_state_string "const SSL *ssl" +.Ft const char * +.Fn SSL_state_string_long "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_state_string +returns a 6 letter string indicating the current state of the +.Vt SSL +object +.Fa ssl . +.Pp +.Fn SSL_state_string_long +returns a string indicating the current state of the +.Vt SSL +object +.Fa ssl . +.Pp +During its use, an +.Vt SSL +object 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 non-blocking sockets, +the function call performing the handshake may return with +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE +condition, so that +.Fn SSL_state_string[_long] +may be called. +.Pp +For both blocking or non-blocking sockets, +the details state information can be used within the +.Fn info_callback +function set with the +.Xr SSL_set_info_callback 3 +call. +.Sh RETURN VALUES +Detailed description of possible states to be included later. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_info_callback 3 +.Sh HISTORY +.Fn SSL_state_string +and +.Fn SSL_state_string_long +first appeared in SSLeay 0.6.0 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_want.3 b/static/openbsd/man3/SSL_want.3 new file mode 100644 index 00000000..c7c2ee48 --- /dev/null +++ b/static/openbsd/man3/SSL_want.3 @@ -0,0 +1,162 @@ +.\" $OpenBSD: SSL_want.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_WANT 3 +.Os +.Sh NAME +.Nm SSL_want , +.Nm SSL_want_nothing , +.Nm SSL_want_read , +.Nm SSL_want_write , +.Nm SSL_want_x509_lookup +.Nd obtain state information TLS/SSL I/O operation +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_want "const SSL *ssl" +.Ft int +.Fn SSL_want_nothing "const SSL *ssl" +.Ft int +.Fn SSL_want_read "const SSL *ssl" +.Ft int +.Fn SSL_want_write "const SSL *ssl" +.Ft int +.Fn SSL_want_x509_lookup "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_want +returns state information for the +.Vt SSL +object +.Fa ssl . +.Pp +The other +.Fn SSL_want_* +calls are shortcuts for the possible states returned by +.Fn SSL_want . +.Pp +.Fn SSL_want +examines the internal state information of the +.Vt SSL +object. +Its return values are similar to those of +.Xr SSL_get_error 3 . +Unlike +.Xr SSL_get_error 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 +non-blocking I/O. +Error conditions are not handled and must be treated using +.Xr SSL_get_error 3 . +.Pp +The result returned by +.Fn SSL_want +should always be consistent with the result of +.Xr SSL_get_error 3 . +.Sh RETURN VALUES +The following return values can currently occur for +.Fn SSL_want : +.Bl -tag -width Ds +.It Dv SSL_NOTHING +There is no data to be written or to be read. +.It Dv SSL_WRITING +There are data in the SSL buffer that must be written to the underlying +.Vt BIO +layer in order to complete the actual +.Fn SSL_* +operation. +A call to +.Xr SSL_get_error 3 +should return +.Dv SSL_ERROR_WANT_WRITE . +.It Dv SSL_READING +More data must be read from the underlying +.Vt BIO +layer in order to +complete the actual +.Fn SSL_* +operation. +A call to +.Xr SSL_get_error 3 +should return +.Dv SSL_ERROR_WANT_READ . +.It Dv SSL_X509_LOOKUP +The operation did not complete because an application callback set by +.Xr SSL_CTX_set_client_cert_cb 3 +has asked to be called again. +A call to +.Xr SSL_get_error 3 +should return +.Dv SSL_ERROR_WANT_X509_LOOKUP . +.El +.Pp +.Fn SSL_want_nothing , +.Fn SSL_want_read , +.Fn SSL_want_write , +and +.Fn SSL_want_x509_lookup +return 1 when the corresponding condition is true or 0 otherwise. +.Sh SEE ALSO +.Xr err 3 , +.Xr ssl 3 , +.Xr SSL_get_error 3 +.Sh HISTORY +.Fn SSL_want , +.Fn SSL_want_nothing , +.Fn SSL_want_read , +and +.Fn SSL_want_write +first appeared in SSLeay 0.5.2. +.Fn SSL_want_x509_lookup +first appeared in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/SSL_write.3 b/static/openbsd/man3/SSL_write.3 new file mode 100644 index 00000000..54d0953e --- /dev/null +++ b/static/openbsd/man3/SSL_write.3 @@ -0,0 +1,250 @@ +.\" $OpenBSD: SSL_write.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" partial merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file was written by Lutz Jaenicke +.\" and Matt Caswell . +.\" Copyright (c) 2000, 2001, 2002, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt SSL_WRITE 3 +.Os +.Sh NAME +.Nm SSL_write_ex , +.Nm SSL_write +.Nd write bytes to a TLS connection +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft int +.Fn SSL_write_ex "SSL *ssl" "const void *buf" "size_t num" "size_t *written" +.Ft int +.Fn SSL_write "SSL *ssl" "const void *buf" "int num" +.Sh DESCRIPTION +.Fn SSL_write_ex +and +.Fn SSL_write +write +.Fa num +bytes from the buffer +.Fa buf +into the specified +.Fa ssl +connection. +On success +.Fn SSL_write_ex +stores the number of bytes written in +.Pf * Fa written . +.Pp +In the following, +.Fn SSL_write_ex +and +.Fn SSL_write +are called +.Dq write functions . +.Pp +If necessary, a write function negotiates a TLS session, +if not already explicitly performed by +.Xr SSL_connect 3 +or +.Xr SSL_accept 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 +.Vt BIO . +.Pp +For the transparent negotiation to succeed, the +.Fa ssl +must have been initialized to client or server mode. +This is done by calling +.Xr SSL_set_connect_state 3 +or +.Xr SSL_set_accept_state 3 +before the first call to a write function. +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +the write function +will only return once the write operation has been finished or an error +occurred, except when a renegotiation takes place, in which case a +.Dv SSL_ERROR_WANT_READ +may occur. +This behaviour can be controlled with the +.Dv SSL_MODE_AUTO_RETRY +flag of the +.Xr SSL_CTX_set_mode 3 +call. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +the write function will also return when the underlying +.Vt BIO +could not satisfy the needs of the function to continue the operation. +In this case a call to +.Xr SSL_get_error 3 +with the return value of the write function will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +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 +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt 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 +.Fa buf +of length +.Fa num +have been written. +This default behaviour can be changed with the +.Dv SSL_MODE_ENABLE_PARTIAL_WRITE +option of +.Xr SSL_CTX_set_mode 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 a write function call has to be repeated because +.Xr SSL_get_error 3 +returned +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE , +it must be repeated with the same arguments. +.Pp +When calling +.Fn SSL_write +with +.Fa num Ns =0 +bytes to be sent, the behaviour is undefined. +.Fn SSL_write_ex +can be called with +.Fa num Ns =0 , +but will not send application data to the peer. +.Sh RETURN VALUES +.Fn SSL_write_ex +returns 1 for success or 0 for failure. +Success means that all requested application data bytes have been +written to the TLS connection or, if +.Dv SSL_MODE_ENABLE_PARTIAL_WRITE +is in use, at least one application data byte has been written +to the TLS connection. +Failure means that not all the requested bytes have been written yet (if +.Dv SSL_MODE_ENABLE_PARTIAL_WRITE +is not in use) or no bytes could be written to the TLS connection (if +.Dv 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 +.Xr SSL_get_error 3 +to find out the reason +which indicates whether the call is retryable or not. +.Pp +For +.Fn SSL_write , +the following return values can occur: +.Bl -tag -width Ds +.It >0 +The write operation was successful. +The return value is the number of bytes actually written to the TLS +connection. +.It 0 +The write operation was not successful. +Probably the underlying connection was closed. +Call +.Xr SSL_get_error 3 +with the return value to find out whether an error occurred or the connection +was shut down cleanly +.Pq Dv SSL_ERROR_ZERO_RETURN . +.It <0 +The write operation was not successful, because either an error occurred or +action must be taken by the calling process. +Call +.Xr SSL_get_error 3 +with the return value to find out the reason. +.El +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_set_mode 3 , +.Xr SSL_get_error 3 , +.Xr SSL_read 3 , +.Xr SSL_set_connect_state 3 +.Sh HISTORY +.Fn SSL_write +appeared in SSLeay 0.4 or earlier and has been available since +.Ox 2.4 . +.Pp +.Fn SSL_write_ex +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/STACK_OF.3 b/static/openbsd/man3/STACK_OF.3 new file mode 100644 index 00000000..38bca99c --- /dev/null +++ b/static/openbsd/man3/STACK_OF.3 @@ -0,0 +1,208 @@ +.\" $OpenBSD: STACK_OF.3,v 1.6 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2018 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 $Mdocdate: June 8 2025 $ +.Dt STACK_OF 3 +.Os +.Sh NAME +.Nm STACK_OF +.Nd variable-sized arrays of pointers, called OpenSSL stacks +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/safestack.h +.Fn STACK_OF type +.Sh DESCRIPTION +The +.In openssl/safestack.h +header provides a fragile, unusually complicated system of +macro-generated wrappers around the functions described in the +.Xr OPENSSL_sk_new 3 +manual page. +It is intended to implement superficially type-safe variable-sized +arrays of pointers, somewhat misleadingly called +.Dq stacks +by OpenSSL. +Due to the excessive number of API functions, it is impossible to +properly document this system. +In particular, calling +.Xr man 1 +for any of the functions operating on stacks cannot yield any result. +.Pp +Unfortunately, application programs can hardly avoid using the concept +because several important OpenSSL APIs rely on it; see the +.Sx SEE ALSO +section for examples. +Even though both pages are more complicated than any manual page +ought to be, using the concept safely requires a complete understanding +of all the details in both this manual page and in +.Xr OPENSSL_sk_new 3 . +.Pp +The +.Fn STACK_OF +macro takes a +.Fa type +name as its argument, typically the name of a type +that has been defined as an alias for a specific +.Vt struct +type using a +.Sy typedef +declaration. +It expands to an incomplete +.Vt struct +type which is intended to represent a +.Dq stack +of objects of the given +.Fa type . +That type does not actually exist, so it is not possible to define, +for example, an automatic variable +.Ql STACK_OF(X509) my_certificates ; +it is only possible to define pointers to stacks, for example +.Ql STACK_OF(X509) *my_certificates . +The only way such pointers can ever be used is by wrapper functions +casting them to the type +.Vt _STACK * +described in +.Xr OPENSSL_sk_new 3 . +.Pp +For a considerable number of types, OpenSSL provides one wrapper +function for each function described in +.Xr OPENSSL_sk_new 3 . +The names of these wrapper functions are usually constructed by +inserting the name of the type and an underscore after the +.Sq sk_ +prefix of the function name. +Usually, where the real functions take +.Vt void * +arguments, the wrappers take pointers to the +.Fa type +in questions, and where the real functions take +.Vt _STACK * +arguments, the wrappers take pointers to +.Fn STACK_OF type . +The same applies to return values. +Various exceptions to all this exist, but the above applies to +all the types listed below. +.Pp +Using the above may make sense for the following types because +public API functions exist that take stacks of these types as +arguments or return them: +.Vt ASN1_INTEGER , +.Vt ASN1_OBJECT , +.Vt ASN1_UTF8STRING , +.Vt CMS_RecipientInfo , +.Vt CMS_SignerInfo , +.Vt CONF_VALUE , +.Vt GENERAL_NAMES , +.Vt GENERAL_SUBTREE , +.Vt OPENSSL_STRING Pq which is just Vt char * , +.Vt PKCS12_SAFEBAG , +.Vt PKCS7 , +.Vt PKCS7_RECIP_INFO , +.Vt PKCS7_SIGNER_INFO , +.Vt POLICYQUALINFO , +.Vt SRTP_PROTECTION_PROFILE , +.Vt SSL_CIPHER , +.Vt SSL_COMP , +.Vt X509 , +.Vt X509_ALGOR , +.Vt X509_ATTRIBUTE , +.Vt X509_CRL , +.Vt X509_EXTENSION , +.Vt X509_INFO , +.Vt X509_NAME , +.Vt X509_OBJECT , +.Vt X509_POLICY_NODE , +.Vt X509_REVOKED . +.Pp +Additionally, some public API functions use the following types +which are declared with +.Sy typedef : +.Bl -column STACK_OF(ACCESS_DESCRIPTION) AUTHORITY_INFO_ACCESS +.It Vt STACK_OF(ACCESS_DESCRIPTION) Ta Vt AUTHORITY_INFO_ACCESS +.It Vt STACK_OF(ASN1_OBJECT) Ta Vt EXTENDED_KEY_USAGE +.It Vt STACK_OF(ASN1_TYPE) Ta Vt ASN1_SEQUENCE_ANY +.It Vt STACK_OF(DIST_POINT) Ta Vt CRL_DIST_POINTS +.It Vt STACK_OF(GENERAL_NAME) Ta Vt GENERAL_NAMES +.It Vt STACK_OF(IPAddressFamily) Ta Vt IPAddrBlocks +.It Vt STACK_OF(POLICY_MAPPING) Ta Vt POLICY_MAPPINGS +.It Vt STACK_OF(POLICYINFO) Ta Vt CERTIFICATEPOLICIES +.It Vt STACK_OF(X509_ALGOR) Ta Vt X509_ALGORS +.It Vt STACK_OF(X509_EXTENSION) Ta Vt X509_EXTENSIONS +.El +.Pp +Even though the OpenSSL headers declare wrapper functions for many +more types and even though the OpenSSL documentation says that users +can declare their own stack types, using +.Fn STACK_OF +with any type not listed here is strongly discouraged. +For other types, there may be subtle, undocumented differences +in syntax and semantics, and attempting to declare custom stack +types is very error prone; using plain C arrays of pointers to +the desired type is much simpler and less dangerous. +.Sh EXAMPLES +The following program creates a certificate object, puts two +pointers to it on a stack, and uses +.Xr X509_free 3 +to clean up properly: +.Bd -literal +#include +#include +#include + +int +main(void) +{ + STACK_OF(X509) *stack; + X509 *x; + + if ((stack = sk_X509_new_null()) == NULL) + err(1, NULL); + if ((x = X509_new()) == NULL) + err(1, NULL); + if (sk_X509_push(stack, x) == 0) + err(1, NULL); + if (X509_up_ref(x) == 0) + errx(1, "X509_up_ref failed"); + if (sk_X509_push(stack, x) == 0) + err(1, NULL); + printf("%d pointers: %p, %p\en", sk_X509_num(stack), + sk_X509_value(stack, 0), sk_X509_value(stack, 1)); + sk_X509_pop_free(stack, X509_free); + + return 0; +} +.Ed +.Pp +The output looks similar to: +.Pp +.Dl 2 pointers: 0x4693ff24c00, 0x4693ff24c00 +.Sh SEE ALSO +.Xr crypto 3 , +.Xr OCSP_request_sign 3 , +.Xr OPENSSL_sk_new 3 , +.Xr PKCS12_parse 3 , +.Xr PKCS7_encrypt 3 , +.Xr SSL_CTX_set_client_CA_list 3 , +.Xr SSL_get_ciphers 3 , +.Xr SSL_get_peer_cert_chain 3 , +.Xr SSL_load_client_CA_file 3 , +.Xr X509_CRL_get_REVOKED 3 , +.Xr X509_STORE_CTX_get0_chain 3 +.Sh HISTORY +The +.Fn STACK_OF +macro first appeared in OpenSSL 0.9.3 and has been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/SipHash24_Init.3 b/static/openbsd/man3/SipHash24_Init.3 new file mode 100644 index 00000000..288547fe --- /dev/null +++ b/static/openbsd/man3/SipHash24_Init.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: SipHash24_Init.3,v 1.1 2019/08/30 22:20:43 deraadt Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" +.\" 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: August 30 2019 $ +.Dt SIPHASH24 3 +.Os +.Sh NAME +.Nm SipHash24_Init , +.Nm SipHash24_Update , +.Nm SipHash24_End , +.Nm SipHash24_Final , +.Nm SipHash24 +.Nd calculate SipHash24 hashes +.Sh SYNOPSIS +.In siphash.h +.Ft void +.Fn SipHash24_Init "SIPHASH_CTX *ctx" "const SIPHASH_KEY *key" +.Ft void +.Fn SipHash24_Update "SIPHASH_CTX *ctx" "const void *data" "size_t len" +.Ft uint64_t +.Fn SipHash24_End "SIPHASH_CTX *ctx" +.Ft void +.Fn SipHash24_Final "void *digest" "SIPHASH_CTX *ctx" +.Ft uint64_t +.Fn SipHash24 "const SIPHASH_KEY *key" "const void *data" "size_t len" +.Sh DESCRIPTION +The SipHash algorithm is a keyed hash algorithm optimised for short +inputs which produces a 64-bit digest of data. +The SipHash24 functions implement the algorithm with 2 compression +rounds and 4 finalisation rounds. +.Pp +.Fn SipHash24_Init +initialises a +.Vt SIPHASH_CTX +context +.Fa ctx +with the secret +.Fa key . +.Pp +.Fn SipHash24_Update +adds +.Fa data +of length +.Fa len +to the context +.Fa ctx . +.Pp +.Fn SipHash24_End +is called after all data has been added to +.Fa ctx +via +.Fn SipHash24_Update +and returns a message digest in the host's native endian. +.Pp +.Fn SipHash24_Final +is called after all data has been added to +.Fa ctx +via +.Fn SipHash24_Update +and stores the message digest at the address specified by the +.Fa digest +parameter. +The buffer at +.Fa digest +must be +.Dv SIPHASH_DIGEST_LENGTH +bytes long. +.Pp +.Fn SipHash24 +calculates the digest of +.Fa data +of length +.Fa len +with the secret +.Fa key . +.Pp +It is recommended that the +.Vt SIPHASH_KEY +key be generated with +.Xr arc4random_buf 3 . +.Sh RETURN VALUES +.Fn SipHash24_End +and +.Fn SipHash24 +return the 64-bit message digest in the host's native endian representation. +.Sh SEE ALSO +.Xr arc4random_buf 3 +.Sh HISTORY +These functions appeared in +.Ox 5.7 . diff --git a/static/openbsd/man3/TS_REQ_new.3 b/static/openbsd/man3/TS_REQ_new.3 new file mode 100644 index 00000000..796b58f4 --- /dev/null +++ b/static/openbsd/man3/TS_REQ_new.3 @@ -0,0 +1,183 @@ +.\" $OpenBSD: TS_REQ_new.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt TS_REQ_NEW 3 +.Os +.Sh NAME +.Nm TS_REQ_new , +.Nm TS_REQ_free , +.Nm TS_RESP_new , +.Nm TS_RESP_free , +.Nm TS_STATUS_INFO_new , +.Nm TS_STATUS_INFO_free , +.Nm TS_TST_INFO_new , +.Nm TS_TST_INFO_free , +.Nm TS_ACCURACY_new , +.Nm TS_ACCURACY_free , +.Nm TS_MSG_IMPRINT_new , +.Nm TS_MSG_IMPRINT_free +.Nd X.509 time-stamp protocol +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ts.h +.Ft TS_REQ * +.Fn TS_REQ_new void +.Ft void +.Fn TS_REQ_free "TS_REQ *req" +.Ft TS_RESP * +.Fn TS_RESP_new void +.Ft void +.Fn TS_RESP_free "TS_RESP *resp" +.Ft TS_STATUS_INFO * +.Fn TS_STATUS_INFO_new void +.Ft void +.Fn TS_STATUS_INFO_free "TS_STATUS_INFO *status" +.Ft TS_TST_INFO * +.Fn TS_TST_INFO_new void +.Ft void +.Fn TS_TST_INFO_free "TS_TST_INFO *token" +.Ft TS_ACCURACY * +.Fn TS_ACCURACY_new void +.Ft void +.Fn TS_ACCURACY_free "TS_ACCURACY *accuracy" +.Ft TS_MSG_IMPRINT * +.Fn TS_MSG_IMPRINT_new void +.Ft void +.Fn TS_MSG_IMPRINT_free "TS_MSG_IMPRINT *imprint" +.Sh DESCRIPTION +A time-stamping authority is a trusted third party which allows its +clients to prove that specific data existed at a particular point +in time. +Clients send time-stamping requests to the time-stamping server, +which returns time-stamp tokens to the clients. +.Pp +.Fn TS_REQ_new +allocates and initializes an empty +.Vt TS_REQ +object, representing an ASN.1 +.Vt TimeStampReq +structure defined in RFC 3161 section 2.4.1. +It can hold a hash of the datum to be time-stamped and some +auxiliary, optional information. +.Fn TS_REQ_free +frees +.Fa req . +.Pp +.Fn TS_RESP_new +allocates and initializes an empty +.Vt TS_RESP +object, representing an ASN.1 +.Vt TimeStampResp +structure defined in RFC 3161 section 2.4.2. +It can hold status information and a time-stamp token. +.Fn TS_RESP_free +frees +.Fa resp . +.Pp +.Fn TS_STATUS_INFO_new +allocates and initializes an empty +.Vt TS_STATUS_INFO +object, representing an ASN.1 +.Vt PKIStatusInfo +structure defined in RFC 3161 section 2.4.2. +It is used inside +.Vt TS_RESP +and describes the outcome of one time-stamp request. +.Fn TS_STATUS_INFO_free +frees +.Fa status . +.Pp +.Fn TS_TST_INFO_new +allocates and initializes an empty +.Vt TS_TST_INFO +object, representing an ASN.1 +.Vt TSTInfo +structure defined in RFC 3161 section 2.4.2. +It is the time-stamp token included in a +.Vt TS_RESP +object in case of success, and it can hold the hash of the datum +copied from a request, the time of generation, and some auxiliary +information. +.Fn TS_TST_INFO_free +frees +.Fa token . +.Pp +.Fn TS_ACCURACY_new +allocates and initializes an empty +.Vt TS_ACCURACY +object, representing an ASN.1 +.Vt Accuracy +structure defined in RFC 3161 section 2.4.2. +It can be used inside a +.Vt TS_TST_INFO +object and indicates the maximum error of the time stated in the token. +.Fn TS_ACCURACY_free +frees +.Fa accuracy . +.Pp +.Fn TS_MSG_IMPRINT_new +allocates and initializes an empty +.Vt TS_MSG_IMPRINT +object, representing an ASN.1 +.Vt MessageImprint +structure defined in RFC 3161 section 2.4.1. +It is used inside +.Vt TS_REQ +and +.Vt TS_RESP +objects. +It specifies a hash algorithm and stores the hash value of the datum. +.Fn TS_MSG_IMPRINT_free +frees +.Fa imprint . +.Sh RETURN VALUES +.Fn TS_REQ_new , +.Fn TS_RESP_new , +.Fn TS_STATUS_INFO_new , +.Fn TS_TST_INFO_new , +.Fn TS_ACCURACY_new , +and +.Fn TS_MSG_IMPRINT_new +return the new +.Vt TS_REQ , +.Vt TS_RESP , +.Vt TS_STATUS_INFO , +.Vt TS_TST_INFO , +.Vt TS_ACCURACY , +or +.Vt TS_MSG_IMPRINT +object, respectively, or +.Dv NULL +if an error occurred. +.Sh SEE ALSO +.Xr ACCESS_DESCRIPTION_new 3 , +.Xr ESS_SIGNING_CERT_new 3 , +.Xr X509_EXTENSION_new 3 +.Sh STANDARDS +RFC 3161: Internet X.509 Public Key Infrastructure Time-Stamp Protocol +.Pp +Note that RFC 3161 has been updated +by RFC 5816: ESSCertIDv2 Update for RFC 3161. +That update allows using the Signing Certificate Attribute Definition +Version 2 according to RFC 5035, but the current implementation +only supports the Signing Certificate Attribute Definition Version +1 according to RFC 2634, and hence only supports RFC 3161, but not +RFC 5816 functionality. +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.0 +and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/UI_create_method.3 b/static/openbsd/man3/UI_create_method.3 new file mode 100644 index 00000000..a116baaa --- /dev/null +++ b/static/openbsd/man3/UI_create_method.3 @@ -0,0 +1,285 @@ +.\" $OpenBSD: UI_create_method.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL UI_create_method.pod 8e3d46e5 Mar 11 10:51:04 2017 +0100 +.\" +.\" This file was written by Richard Levitte . +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt UI_CREATE_METHOD 3 +.Os +.Sh NAME +.Nm UI_create_method , +.Nm UI_destroy_method , +.Nm UI_method_set_opener , +.Nm UI_method_set_writer , +.Nm UI_method_set_flusher , +.Nm UI_method_set_reader , +.Nm UI_method_set_closer , +.Nm UI_method_set_prompt_constructor , +.Nm UI_method_get_opener , +.Nm UI_method_get_writer , +.Nm UI_method_get_flusher , +.Nm UI_method_get_reader , +.Nm UI_method_get_closer , +.Nm UI_method_get_prompt_constructor +.Nd user interface method creation and destruction +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ui.h +.Ft UI_METHOD * +.Fo UI_create_method +.Fa "const char *name" +.Fc +.Ft void +.Fo UI_destroy_method +.Fa "UI_METHOD *ui_method" +.Fc +.Ft int +.Fo UI_method_set_opener +.Fa "UI_METHOD *method" +.Fa "int (*opener)(UI *ui)" +.Fc +.Ft int +.Fo UI_method_set_writer +.Fa "UI_METHOD *method" +.Fa "int (*writer)(UI *ui, UI_STRING *uis)" +.Fc +.Ft int +.Fo UI_method_set_flusher +.Fa "UI_METHOD *method" +.Fa "int (*flusher)(UI *ui)" +.Fc +.Ft int +.Fo UI_method_set_reader +.Fa "UI_METHOD *method" +.Fa "int (*reader)(UI *ui, UI_STRING *uis)" +.Fc +.Ft int +.Fo UI_method_set_closer +.Fa "UI_METHOD *method" +.Fa "int (*closer)(UI *ui)" +.Fc +.Ft int +.Fo UI_method_set_prompt_constructor +.Fa "UI_METHOD *method" +.Fa "char *(*prompt_constructor)(UI *ui, const char *object_desc,\ + const char *object_name)" +.Fc +.Ft int +.Fo "(*UI_method_get_opener(const UI_METHOD *method))" +.Fa "UI *" +.Fc +.Ft int +.Fo "(*UI_method_get_writer(const UI_METHOD *method))" +.Fa "UI *" +.Fa "UI_STRING *" +.Fc +.Ft int +.Fo "(*UI_method_get_flusher(const UI_METHOD *method))" +.Fa "UI *" +.Fc +.Ft int +.Fo "(*UI_method_get_reader(const UI_METHOD *method))" +.Fa "UI *" +.Fa "UI_STRING *" +.Fc +.Ft int +.Fo "(*UI_method_get_closer(const UI_METHOD *method))" +.Fa "UI *" +.Fc +.Ft char * +.Fo "(*UI_method_get_prompt_constructor(UI_METHOD *method))" +.Fa "UI *" +.Fa "const char *" +.Fa "const char *" +.Fc +.Sh DESCRIPTION +A method contains a few functions that implement the low level of the +User Interface. +These functions are: +.Bl -tag -width Ds +.It 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. +.It 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. +.It 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. +.It 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. +.It 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. +.El +.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's treated as if 0 was returned. +.Pp +Regarding the writer and the reader, don't assume the former should only +write and don't assume the latter should only read. +This depends on the needs of the method. +.Pp +For example, a typical tty reader wouldn't 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 +.Xr UI_OpenSSL 3 +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 +.Xr UI_process 3 , +and it does it in five steps: +.Bl -enum +.It +Open the session using the opener function if that one is defined. +If an error occurs, jump to 5. +.It +For every UI String associated with the UI, call the writer function if +that one is defined. +If an error occurs, jump to 5. +.It +Flush everything using the flusher function if that one is defined. +If an error occurs, jump to 5. +.It +For every UI String associated with the UI, call the reader function if +that one is defined. +If an error occurs, jump to 5. +.It +Close the session using the closer function if that one is defined. +.El +.Pp +.Fn UI_create_method +creates a new UI method with a given +.Fa name . +.Pp +.Fn UI_destroy_method +destroys the given +.Fa ui_method . +.Pp +.Fn UI_method_set_opener , +.Fn UI_method_set_writer , +.Fn UI_method_set_flusher , +.Fn UI_method_set_reader +and +.Fn UI_method_set_closer +set one of the five main methods to the given function pointer. +.Pp +.Fn UI_method_set_prompt_constructor +sets the prompt constructor, see +.Xr UI_construct_prompt 3 . +.Sh RETURN VALUES +.Fn UI_create_method +returns a +.Vt UI_METHOD +pointer on success or +.Dv NULL +on error. +.Pp +.Fn UI_method_set_opener , +.Fn UI_method_set_writer , +.Fn UI_method_set_flusher , +.Fn UI_method_set_reader , +.Fn UI_method_set_closer , +and +.Fn UI_method_set_prompt_constructor +return 0 on success or -1 if the given method is +.Dv NULL . +.Pp +.Fn UI_method_get_opener , +.Fn UI_method_get_writer , +.Fn UI_method_get_flusher , +.Fn UI_method_get_reader , +.Fn UI_method_get_closer , +and +.Fn UI_method_get_prompt_constructor +return the requested function pointer if it is set in the method, +or otherwise +.Dv NULL . +.Sh SEE ALSO +.Xr UI_get_string_type 3 , +.Xr UI_new 3 +.Sh HISTORY +.Fn UI_create_method , +.Fn UI_destroy_method , +.Fn UI_method_set_opener , +.Fn UI_method_set_writer , +.Fn UI_method_set_flusher , +.Fn UI_method_set_reader , +.Fn UI_method_set_closer , +.Fn UI_method_get_opener , +.Fn UI_method_get_writer , +.Fn UI_method_get_flusher , +.Fn UI_method_get_reader , +and +.Fn UI_method_get_closer +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn UI_method_set_prompt_constructor +and +.Fn UI_method_get_prompt_constructor +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/UI_get_string_type.3 b/static/openbsd/man3/UI_get_string_type.3 new file mode 100644 index 00000000..84c774d9 --- /dev/null +++ b/static/openbsd/man3/UI_get_string_type.3 @@ -0,0 +1,282 @@ +.\" $OpenBSD: UI_get_string_type.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL UI_STRING.pod e9c9971b Jul 1 18:28:50 2017 +0200 +.\" +.\" This file was written by Richard Levitte +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt UI_GET_STRING_TYPE 3 +.Os +.Sh NAME +.Nm UI_get_string_type , +.Nm UI_get_input_flags , +.Nm UI_get0_output_string , +.Nm UI_get0_action_string , +.Nm UI_get0_result_string , +.Nm UI_get0_test_string , +.Nm UI_get_result_minsize , +.Nm UI_get_result_maxsize , +.Nm UI_set_result +.Nd OpenSSL user interface string parsing +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ui.h +.Bd -literal +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 */ +}; +.Ed +.Pp +.Ft enum UI_string_types +.Fo UI_get_string_type +.Fa "UI_STRING *uis" +.Fc +.Ft int +.Fo UI_get_input_flags +.Fa "UI_STRING *uis" +.Fc +.Ft const char * +.Fo UI_get0_output_string +.Fa "UI_STRING *uis" +.Fc +.Ft const char * +.Fo UI_get0_action_string +.Fa "UI_STRING *uis" +.Fc +.Ft const char * +.Fo UI_get0_result_string +.Fa "UI_STRING *uis" +.Fc +.Ft const char * +.Fo UI_get0_test_string +.Fa "UI_STRING *uis" +.Fc +.Ft int +.Fo UI_get_result_minsize +.Fa "UI_STRING *uis" +.Fc +.Ft int +.Fo UI_get_result_maxsize +.Fa "UI_STRING *uis" +.Fc +.Ft int +.Fo UI_set_result +.Fa "UI *ui" +.Fa "UI_STRING *uis" +.Fa "const char *result" +.Fc +.Sh DESCRIPTION +A +.Vt UI_STRING +gets created internally and added to a +.Vt UI +object whenever one of the functions +.Xr UI_add_input_string 3 , +.Xr UI_dup_input_string 3 , +.Xr UI_add_verify_string 3 , +.Xr UI_dup_verify_string 3 , +.Xr UI_add_input_boolean 3 , +.Xr UI_dup_input_boolean 3 , +.Xr UI_add_info_string 3 , +.Xr UI_dup_info_string 3 , +.Xr UI_add_error_string 3 +or +.Xr UI_dup_error_string 3 +is called. +For a +.Vt UI_METHOD +user, there's no need to know more. +For a +.Vt UI_METHOD +creator, it is of interest to fetch text from these +.Vt UI_STRING +objects as well as adding results to some of them. +.Pp +.Fn UI_get_string_type +is used to retrieve the type of the given +.Vt UI_STRING . +.Pp +.Fn UI_get_input_flags +is used to retrieve the flags associated with the given +.Vt UI_STRING . +.Pp +.Fn UI_get0_output_string +is used to retrieve the actual string to output (prompt, info, error, ...). +.Pp +.Fn UI_get0_action_string +is used to retrieve the action description associated with a +.Dv UIT_BOOLEAN +type +.Vt UI_STRING . +See +.Xr UI_add_input_boolean 3 . +.Pp +.Fn UI_get0_result_string +is used to retrieve the result of a prompt. +This is only useful for +.Dv UIT_PROMPT +and +.Dv UIT_VERIFY +type strings. +.Pp +.Fn UI_get0_test_string +is used to retrieve the string to compare the prompt result with. +This is only useful for +.Dv UIT_VERIFY +type strings. +.Pp +.Fn UI_get_result_minsize +and +.Fn UI_get_result_maxsize +are used to retrieve the minimum and maximum required size of the +result. +This is only useful for +.Dv UIT_PROMPT +and +.Dv UIT_VERIFY +type strings. +.Pp +.Fn UI_set_result +is used to set the result value of a prompt. +For +.Sy UIT_PROMPT +and +.Sy UIT_VERIFY +type UI strings, this sets the result retrievable with +.Fn UI_get0_result_string +by copying the contents of +.Fa result +if its length fits the minimum and maximum size requirements. +For +.Dv UIT_BOOLEAN +type UI strings, this sets the first character of the result retrievable +with +.Fn UI_get0_result_string +to the first of the +.Fa ok_chars +given with +.Xr UI_add_input_boolean 3 +or +.Xr UI_dup_input_boolean 3 +if the +.Fa result +matched any of them, or the first of the +.Fa cancel_chars +if the +.Fa result +matched any of them, otherwise it's set to the NUL char. +See +.Xr UI_add_input_boolean 3 +for more information on +.Fa ok_chars +and +.Fa cancel_chars . +.Sh RETURN VALUES +.Fn UI_get_string_type +returns the UI string type. +.Pp +.Fn UI_get_input_flags +returns the UI string flags. +.Pp +.Fn UI_get0_output_string +returns the UI string output string. +.Pp +.Fn UI_get0_action_string +returns the UI string action description string for +.Dv UIT_BOOLEAN +type UI strings, or +.Dv NULL +for any other type. +.Pp +.Fn UI_get0_result_string +returns the UI string result buffer for +.Dv UIT_PROMPT +and +.Dv UIT_VERIFY +type UI strings, or +.Dv NULL +for any other type. +.Pp +.Fn UI_get0_test_string +returns the UI string action description string for +.Dv UIT_VERIFY +type UI strings, or +.Dv NULL +for any other type. +.Pp +.Fn UI_get_result_minsize +returns the minimum allowed result size for the UI string for +.Dv UIT_PROMPT +and +.Dv UIT_VERIFY +type strings, or -1 for any other type. +.Pp +.Fn UI_get_result_maxsize +returns the minimum allowed result size for the UI string for +.Dv UIT_PROMPT +and +.Dv UIT_VERIFY +type strings, or -1 for any other type. +.Pp +.Fn UI_set_result +returns 0 on success or when the UI string is of any type other than +.Dv UIT_PROMPT , +.Dv UIT_VERIFY , +or +.Dv UIT_BOOLEAN , +or -1 on error. +.Sh SEE ALSO +.Xr UI_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/UI_new.3 b/static/openbsd/man3/UI_new.3 new file mode 100644 index 00000000..853219aa --- /dev/null +++ b/static/openbsd/man3/UI_new.3 @@ -0,0 +1,530 @@ +.\" $OpenBSD: UI_new.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 78b19e90 Jan 11 00:12:01 2017 +0100 +.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Richard Levitte . +.\" Copyright (c) 2001, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt UI_NEW 3 +.Os +.Sh NAME +.Nm UI_new , +.Nm UI_new_method , +.Nm UI_free , +.Nm UI_add_input_string , +.Nm UI_dup_input_string , +.Nm UI_add_verify_string , +.Nm UI_dup_verify_string , +.Nm UI_add_input_boolean , +.Nm UI_dup_input_boolean , +.Nm UI_add_info_string , +.Nm UI_dup_info_string , +.Nm UI_add_error_string , +.Nm UI_dup_error_string , +.Nm UI_construct_prompt , +.Nm UI_add_user_data , +.Nm UI_get0_user_data , +.Nm UI_get0_result , +.Nm UI_process , +.Nm UI_ctrl , +.Nm UI_set_default_method , +.Nm UI_get_default_method , +.Nm UI_get_method , +.Nm UI_set_method , +.Nm UI_OpenSSL , +.Nm UI_null +.Nd New User Interface +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ui.h +.Ft UI * +.Fn UI_new void +.Ft UI * +.Fo UI_new_method +.Fa "const UI_METHOD *method" +.Fc +.Ft void +.Fo UI_free +.Fa "UI *ui" +.Fc +.Ft int +.Fo UI_add_input_string +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "int flags" +.Fa "char *result_buf" +.Fa "int minsize" +.Fa "int maxsize" +.Fc +.Ft int +.Fo UI_dup_input_string +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "int flags" +.Fa "char *result_buf" +.Fa "int minsize" +.Fa "int maxsize" +.Fc +.Ft int +.Fo UI_add_verify_string +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "int flags" +.Fa "char *result_buf" +.Fa "int minsize" +.Fa "int maxsize" +.Fa "const char *test_buf" +.Fc +.Ft int +.Fo UI_dup_verify_string +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "int flags" +.Fa "char *result_buf" +.Fa "int minsize" +.Fa "int maxsize" +.Fa "const char *test_buf" +.Fc +.Ft int +.Fo UI_add_input_boolean +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "const char *action_desc" +.Fa "const char *ok_chars" +.Fa "const char *cancel_chars" +.Fa "int flags" +.Fa "char *result_buf" +.Fc +.Ft int +.Fo UI_dup_input_boolean +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "const char *action_desc" +.Fa "const char *ok_chars" +.Fa "const char *cancel_chars" +.Fa "int flags" +.Fa "char *result_buf" +.Fc +.Ft int +.Fo UI_add_info_string +.Fa "UI *ui" +.Fa "const char *text" +.Fc +.Ft int +.Fo UI_dup_info_string +.Fa "UI *ui" +.Fa "const char *text" +.Fc +.Ft int +.Fo UI_add_error_string +.Fa "UI *ui" +.Fa "const char *text" +.Fc +.Ft int +.Fo UI_dup_error_string +.Fa "UI *ui" +.Fa "const char *text" +.Fc +.Fd /* These are the possible flags. They can be OR'ed together. */ +.Fd #define UI_INPUT_FLAG_ECHO 0x01 +.Fd #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 +.Ft char * +.Fo UI_construct_prompt +.Fa "UI *ui_method" +.Fa "const char *object_desc" +.Fa "const char *object_name" +.Fc +.Ft void * +.Fo UI_add_user_data +.Fa "UI *ui" +.Fa "void *user_data" +.Fc +.Ft void * +.Fo UI_get0_user_data +.Fa "UI *ui" +.Fc +.Ft const char * +.Fo UI_get0_result +.Fa "UI *ui" +.Fa "int i" +.Fc +.Ft int +.Fo UI_process +.Fa "UI *ui" +.Fc +.Ft int +.Fo UI_ctrl +.Fa "UI *ui" +.Fa "int cmd" +.Fa "long i" +.Fa "void *p" +.Fa "void (*f)()" +.Fc +.Fd #define UI_CTRL_PRINT_ERRORS 1 +.Fd #define UI_CTRL_IS_REDOABLE 2 +.Ft void +.Fo UI_set_default_method +.Fa "const UI_METHOD *meth" +.Fc +.Ft const UI_METHOD * +.Fo UI_get_default_method +.Fa void +.Fc +.Ft const UI_METHOD * +.Fo UI_get_method +.Fa "UI *ui" +.Fc +.Ft const UI_METHOD * +.Fo UI_set_method +.Fa "UI *ui" +.Fa "const UI_METHOD *meth" +.Fc +.Ft const UI_METHOD * +.Fo UI_OpenSSL +.Fa void +.Fc +.Ft const UI_METHOD * +.Fo UI_null +.Fa void +.Fc +.Sh DESCRIPTION +UI stands for User Interface, and is a general purpose set of routines +to prompt the user for text-based information. +Through user-written methods (see +.Xr UI_create_method 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 +.Vt UI . +This context contains all the information needed to prompt correctly +as well as a reference to a +.Vt 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 +.Vt UI +with +.Fn UI_new +or +.Fn UI_new_method , +then add information to it with the +.Fn UI_add_* +or +.Fn UI_dup_* +functions. +Also, user-defined random data can be passed down to the underlying +method through calls to +.Fn UI_add_user_data . +The default UI method doesn't care about these data, but other methods +might. +Finally, use +.Fn UI_process +to actually perform the prompting and +.Fn UI_get0_result +to find the result to the prompt. +.Pp +A +.Vt 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 +.Fn UI_add_* +and +.Fn UI_dup_* +functions, and has to be used to get the corresponding result with +.Fn UI_get0_result . +.Pp +The functions are as follows: +.Pp +.Fn UI_new +creates a new +.Vt UI +using the default UI method. +When done with this UI, it should be freed using +.Fn UI_free . +.Pp +.Fn UI_new_method +creates a new +.Vt UI +using the given UI method. +When done with this UI, it should be freed using +.Fn UI_free . +.Pp +.Fn UI_OpenSSL +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 +.Fn UI_null +returns a UI method that does nothing. +Its use is to avoid getting internal defaults for passed +.Vt UI_METHOD +pointers. +.Pp +.Fn UI_free +removes +.Fa ui +from memory, along with all other pieces of memory that are connected +to it, like duplicated input strings, results and others. +If +.Fa ui +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn UI_add_input_string +and +.Fn UI_add_verify_string +add a prompt to +.Fa 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). +.Fn UI_add_verify_string +takes an 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 +.Fn UI_add_input_boolean +adds a prompt to +.Fa ui +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 really divided in two, one part being the +descriptive text (given through the +.Fa prompt +argument) and one describing the possible answers (given through the +.Fa action_desc +argument). +.Pp +.Fn UI_add_info_string +and +.Fn UI_add_error_string +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 +.Dv UI_INPUT_FLAG_ECHO , +which is relevant for +.Fn UI_add_input_string +and will have the users response be echoed (when prompting for a +password, this flag should obviously not be used), and +.Dv UI_INPUT_FLAG_DEFAULT_PWD , +which means that a default password of some sort will be used +(completely depending on the application and the UI method). +.Pp +.Fn UI_dup_input_string , +.Fn UI_dup_verify_string , +.Fn UI_dup_input_boolean , +.Fn UI_dup_info_string , +and +.Fn UI_dup_error_string +are basically the same as their +.Fn UI_add_* +counterparts, except that they make their own copies of all strings. +.Pp +.Fn UI_construct_prompt +is a helper function that can be used to create a prompt from two pieces +of information: a description and a name. +The default constructor (if there is none provided by the method used) +creates a string "Enter +.Em description +for +.Em name Ns :". +With the description "pass phrase" and the file name "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 +.Fn UI_add_user_data +adds a user data pointer for the method to use at any time. +The builtin UI method doesn't care about this info. +Note that several calls to this function doesn't add data - +the previous blob is replaced with the one given as argument. +.Pp +.Fn UI_get0_user_data +retrieves the data that has last been given to the +.Fa ui +with +.Fn UI_add_user_data . +.Pp +.Fn UI_get0_result +returns a pointer to the result buffer associated with the information +indexed by +.Fa i . +.Pp +.Fn UI_process +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, or 0 on success. +.Pp +.Fn UI_ctrl +adds extra control for the application author. +For now, it understands two commands: +.Dv UI_CTRL_PRINT_ERRORS , +which makes +.Fn UI_process +print the OpenSSL error stack as part of processing the +.Fa ui , +and +.Dv UI_CTRL_IS_REDOABLE , +which returns a flag saying if the used +.Fa ui +can be used again or not. +.Pp +.Fn UI_set_default_method +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 +.Fn UI_get_default_method +returns a pointer to the current default UI method. +.Pp +.Fn UI_get_method +returns the UI method associated with a given +.Fa ui . +.Pp +.Fn UI_set_method +changes the UI method associated with a given +.Fa ui . +.Sh RETURN VALUES +.Fn UI_new +and +.Fn UI_new_method +return a valid +.Vt UI +structure or +.Dv NULL +if an error occurred. +.Pp +.Fn UI_add_input_string , +.Fn UI_dup_input_string , +.Fn UI_add_verify_string , +.Fn UI_dup_verify_string , +.Fn UI_add_input_boolean , +.Fn UI_dup_input_boolean , +.Fn UI_add_info_string , +.Fn UI_dup_info_string , +.Fn UI_add_error_string , +and +.Fn UI_dup_error_string +return a positive number on success or a number +less than or equal to zero otherwise. +.Pp +.Fn UI_construct_prompt +and +.Fn UI_get0_result +return a string or +.Dv NULL +if an error occurred. +.Pp +.Fn UI_add_user_data +and +.Fn UI_get0_user_data +return a pointer to the user data that was contained in +.Fa ui +before the call. +In particular, +.Dv NULL +is a valid return value. +.Pp +.Fn UI_process +returns 0 on success or a negative value on error. +.Pp +.Fn UI_ctrl +returns a mask on success or \-1 on error. +.Pp +.Fn UI_get_default_method , +.Fn UI_OpenSSL +and +.Fn UI_null +always return a pointer to a valid +.Vt UI_METHOD +structure. +.Pp +.Fn UI_get_method +and +.Fn UI_set_method +return a pointer to the +.Vt UI_METHOD +structure that is installed in +.Fa ui +after the call. +The OpenSSL documentation says that they can fail and return +.Dv NULL , +but currently, this can only happen when and after +.Fn UI_set_method +is called with an explicit +.Dv NULL +argument. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr UI_create_method 3 , +.Xr UI_get_string_type 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.2 . +.Pp +.Fn UI_null +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 7.3 . +.Sh AUTHORS +.An Richard Levitte Aq Mt richard@levitte.org +for the OpenSSL project. diff --git a/static/openbsd/man3/X25519.3 b/static/openbsd/man3/X25519.3 new file mode 100644 index 00000000..3686df9b --- /dev/null +++ b/static/openbsd/man3/X25519.3 @@ -0,0 +1,212 @@ +.\" $OpenBSD: X25519.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $ +.\" contains some text from: BoringSSL curve25519.h, curve25519.c +.\" content also checked up to: OpenSSL f929439f Mar 15 12:19:16 2018 +0000 +.\" +.\" Copyright (c) 2015 Google Inc. +.\" Copyright (c) 2018, 2022 Ingo Schwarze +.\" +.\" 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 THE AUTHORS DISCLAIM ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS 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. +.\" +.\" According to the BoringSSL git history, those parts of the text in +.\" the present manual page that are Copyrighted by Google were probably +.\" written by Adam Langley in 2015. +.\" I fail to see any such text in the public domain files written +.\" by Daniel J. Bernstein and others that are included in SUPERCOP +.\" and that Adam Langley's BoringSSL implementation is based on. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X25519 3 +.Os +.Sh NAME +.Nm X25519 , +.Nm X25519_keypair , +.Nm ED25519_keypair , +.Nm ED25519_sign , +.Nm ED25519_verify +.Nd Elliptic Curve Diffie-Hellman and signature primitives based on Curve25519 +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/curve25519.h +.Ft int +.Fo X25519 +.Fa "uint8_t out_shared_key[X25519_KEY_LENGTH]" +.Fa "const uint8_t private_key[X25519_KEY_LENGTH]" +.Fa "const uint8_t peer_public_value[X25519_KEY_LENGTH]" +.Fc +.Ft void +.Fo X25519_keypair +.Fa "uint8_t out_public_value[X25519_KEY_LENGTH]" +.Fa "uint8_t out_private_key[X25519_KEY_LENGTH]" +.Fc +.Ft void +.Fo ED25519_keypair +.Fa "uint8_t out_public_key[ED25519_PUBLIC_KEY_LENGTH]" +.Fa "uint8_t out_private_key[ED25519_PRIVATE_KEY_LENGTH]" +.Fc +.Ft int +.Fo ED25519_sign +.Fa "uint8_t *out_sig" +.Fa "const uint8_t *message" +.Fa "size_t message_len" +.Fa "const uint8_t public_key[ED25519_PUBLIC_KEY_LENGTH]" +.Fa "const uint8_t private_key_seed[ED25519_PRIVATE_KEY_LENGTH]" +.Fc +.Ft int +.Fo ED25519_verify +.Fa "const uint8_t *message" +.Fa "size_t message_len" +.Fa "const uint8_t signature[ED25519_SIGNATURE_LENGTH]" +.Fa "const uint8_t public_key[ED25519_PUBLIC_KEY_LENGTH]" +.Fc +.Sh DESCRIPTION +Curve25519 is an elliptic curve over a prime field +specified in RFC 7748 section 4.1. +The prime field is defined by the prime number 2^255 - 19. +.Pp +X25519 +is the Diffie-Hellman primitive built from Curve25519 as described +in RFC 7748 section 5. +Section 6.1 describes the intended use in an Elliptic Curve Diffie-Hellman +(ECDH) protocol. +.Pp +.Fn X25519 +writes a shared key to +.Fa out_shared_key +that is calculated from the given +.Fa private_key +and the +.Fa peer_public_value +by scalar multiplication. +Do not use the shared key directly, rather use a key derivation +function and also include the two public values as inputs. +.Pp +.Fn X25519_keypair +sets +.Fa out_public_value +and +.Fa out_private_key +to a freshly generated public/private key pair. +First, the +.Fa out_private_key +is generated with +.Xr arc4random_buf 3 . +Then, the opposite of the masking described in RFC 7748 section 5 +is applied to it to make sure that the generated private key is never +correctly masked. +The purpose is to cause incorrect implementations on the peer side +to consistently fail. +Correct implementations will decode the key correctly even when it is +not correctly masked. +Finally, the +.Fa out_public_value +is calculated from the +.Fa out_private_key +by multiplying it with the Montgomery base point +.Vt uint8_t u[32] No = Brq 9 . +.Pp +The size of a public and private key is +.Dv X25519_KEY_LENGTH No = 32 +bytes each. +.Pp +Ed25519 is a signature scheme using a twisted Edwards curve +that is birationally equivalent to Curve25519. +.Pp +.Fn ED25519_keypair +sets +.Fa out_public_key +and +.Fa out_private_key +to a freshly generated public/private key pair. +First, the +.Fa out_private_key +is generated with +.Xr arc4random_buf 3 . +Then, the +.Fa out_public_key +is calculated from the private key. +.Pp +.Fn ED25519_sign +signs the +.Fa message +of +.Fa message_len +bytes using the +.Fa public_key +and the +.Fa private_key +and writes the signature to +.Fa out_sig . +.Pp +.Fn ED25519_verify +checks that signing the +.Fa message +of +.Fa message_len +bytes using the +.Fa public_key +would indeed result in the given +.Fa signature . +.Pp +The sizes of a public and private keys are +.Dv ED25519_PUBLIC_KEY_LENGTH +and +.Dv ED25519_PRIVATE_KEY_LENGTH , +which are both 32 bytes, and the size of a signature is +.Dv ED25519_SIGNATURE_LENGTH No = 64 +bytes. +.Sh RETURN VALUES +.Fn X25519 +and +.Fn ED25519_sign +return 1 on success or 0 on error. +.Fn X25519 +can fail if the input is a point of small order. +.Fn ED25519_sign +always succeeds in LibreSSL, but the API reserves the return value 0 +for memory allocation failure. +.Pp +.Fn ED25519_verify +returns 1 if the +.Fa signature +is valid or 0 otherwise. +.Sh SEE ALSO +.Xr ECDH_compute_key 3 , +.Xr EVP_DigestSign 3 , +.Xr EVP_DigestVerify 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_keygen 3 +.Rs +.%A Daniel J. Bernstein +.%R A state-of-the-art Diffie-Hellman function:\ + How do I use Curve25519 in my own software? +.%U https://cr.yp.to/ecdh.html +.Re +.Rs +.%A Daniel J. Bernstein +.%A Niels Duif +.%A Tanja Lange +.%A Peter Schwabe +.%A Bo-Yin Yang +.%T High-Speed High-Security Signatures +.%B Cryptographic Hardware and Embedded Systems \(em CHES 2011 +.%I Springer +.%J Lecture Notes in Computer Science +.%V vol 6917 +.%U https://doi.org/10.1007/978-3-642-23951-9_9 +.%C Nara, Japan +.%D September 29, 2011 +.Re +.Sh STANDARDS +RFC 7748: Elliptic Curves for Security +.Pp +RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA) diff --git a/static/openbsd/man3/X509V3_EXT_get_nid.3 b/static/openbsd/man3/X509V3_EXT_get_nid.3 new file mode 100644 index 00000000..78975874 --- /dev/null +++ b/static/openbsd/man3/X509V3_EXT_get_nid.3 @@ -0,0 +1,95 @@ +.\" $OpenBSD: X509V3_EXT_get_nid.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2024 Theo Buehler +.\" +.\" 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: June 8 2025 $ +.Dt X509V3_EXT_GET_NID 3 +.Os +.Sh NAME +.Nm X509V3_EXT_get_nid , +.Nm X509V3_EXT_get +.Nd retrieve X.509v3 certificate extension methods +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft const X509V3_EXT_METHOD * +.Fo X509V3_EXT_get_nid +.Fa "int nid" +.Fc +.Ft const X509V3_EXT_METHOD * +.Fo X509V3_EXT_get +.Fa "X509_EXTENSION *ext" +.Fc +.Sh DESCRIPTION +An X.509v3 certificate extension contains an Object Identifier (OID), +a boolean criticality indicator, and an opaque extension value +.Po +an +.Vt ASN1_OCTET_STRING +.Pc +whose meaning is determined by the OID. +The library's +.Vt X509V3_EXT_METHOD +type, +which is not yet documented in detail, +contains a numeric identifier (NID) to represent the OID and various +handlers for encoding, decoding, printing, and configuring the +extension's value. +Criticality is handled separately, for example as an argument to +.Xr X509V3_add1_i2d 3 . +.Sh RETURN VALUES +.Fn X509V3_EXT_get_nid +returns the +.Vt X509V3_EXT_METHOD +corresponding to the numeric identifier +.Fa nid , +or +.Dv NULL +if there is none. +.Pp +.Fn X509V3_EXT_get +returns the +.Vt X509V3_EXT_METHOD +associated with the extension type of +.Fa ext , +or +.Dv NULL +if there is none. +.Sh SEE ALSO +.Xr i2s_ASN1_ENUMERATED_TABLE 3 , +.Xr OBJ_create 3 , +.Xr v2i_ASN1_BIT_STRING 3 , +.Xr X509_EXTENSION_get_object 3 , +.Xr X509V3_get_d2i 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Bl -dash -compact +.It +section 4.2: Certificate Extensions +.El +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.2b and +have been available since +.Ox 2.6 . +.Sh CAVEATS +In LibreSSL, these functions only support built-in +.Fa nid +values corresponding to static built-in objects. +Other implementations have incomplete support for custom extension methods, +whose API is not threadsafe, does not affect the behavior of +.Xr X509_verify_cert 3 , +and has various other surprising quirks. +Both functions prefer built-in methods over custom methods with the same OID. diff --git a/static/openbsd/man3/X509V3_EXT_print.3 b/static/openbsd/man3/X509V3_EXT_print.3 new file mode 100644 index 00000000..8705e4d5 --- /dev/null +++ b/static/openbsd/man3/X509V3_EXT_print.3 @@ -0,0 +1,196 @@ +.\" $OpenBSD: X509V3_EXT_print.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021, 2024 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 $Mdocdate: June 8 2025 $ +.Dt X509V3_EXT_PRINT 3 +.Os +.Sh NAME +.Nm X509V3_EXT_print , +.Nm X509V3_EXT_print_fp +.Nd pretty-print an X.509 extension +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fo X509V3_EXT_print +.Fa "BIO *bio" +.Fa "X509_EXTENSION *ext" +.Fa "unsigned long flags" +.Fa "int indent" +.Fc +.Ft int +.Fo X509V3_EXT_print_fp +.Fa "FILE *file" +.Fa "X509_EXTENSION *ext" +.Fa "int flags" +.Fa "int indent" +.Fc +.Sh DESCRIPTION +.Fn X509V3_EXT_print +and +.Fn X509V3_EXT_print_fp +decode +.Fa ext +and print the data contained in it to the +.Fa bio +or +.Fa file , +respectively, in a human-readable format with a left margin of +.Fa indent +space characters. +The details of both the decoding and the printing depend on the type of +.Fa ext . +.Pp +For most extension types, the decoding is done in the same way +as it would be done by the appropriate public API function, for example: +.Pp +.Bl -tag -width NID_authority_key_identifier -compact +.It Sy extension type +.Sy decoding function +.It Dv NID_authority_key_identifier +.Xr d2i_AUTHORITY_KEYID 3 +.It Dv NID_certificate_policies +.Xr d2i_CERTIFICATEPOLICIES 3 +.It Dv NID_crl_number +.Xr d2i_ASN1_INTEGER 3 +.It Dv NID_crl_reason +.Xr d2i_ASN1_ENUMERATED 3 +.It Dv NID_hold_instruction_code +.Xr d2i_ASN1_OBJECT 3 +.It Dv NID_id_pkix_OCSP_CrlID +.Xr d2i_OCSP_CRLID 3 +.It Dv NID_id_pkix_OCSP_noCheck +.Xr d2i_ASN1_NULL 3 +.It Dv NID_id_pkix_OCSP_Nonce +non-public function built into the library +.It Dv NID_invalidity_date +.Xr d2i_ASN1_GENERALIZEDTIME 3 +.It Dv NID_key_usage +.Xr d2i_ASN1_BIT_STRING 3 +.It Dv NID_subject_alt_name +.Xr d2i_GENERAL_NAMES 3 +.It Dv NID_subject_key_identifier +.Xr d2i_ASN1_OCTET_STRING 3 +.El +.Pp +For some types, the printing is performed +by a dedicated non-public function built into the library. +For some other types, the printing function is a public API function, +for example: +.Pp +.Bl -tag -width NID_id_pkix_OCSP_archiveCutoff -compact +.It Sy extension type +.Sy printing function +.It Dv NID_crl_number +.Xr i2s_ASN1_INTEGER 3 +.It Dv NID_crl_reason +.Xr i2s_ASN1_ENUMERATED_TABLE 3 +.It Dv NID_delta_crl +.Xr i2s_ASN1_INTEGER 3 +.It Dv NID_hold_instruction_code +.Xr i2a_ASN1_OBJECT 3 +.It Dv NID_id_pkix_OCSP_archiveCutoff +.Xr ASN1_GENERALIZEDTIME_print 3 +.It Dv NID_id_pkix_OCSP_Nonce +.Xr i2a_ASN1_STRING 3 +.It Dv NID_inhibit_any_policy +.Xr i2s_ASN1_INTEGER 3 +.It Dv NID_invalidity_date +.Xr ASN1_GENERALIZEDTIME_print 3 +.It Dv NID_key_usage +.Xr i2v_ASN1_BIT_STRING 3 +.It Dv NID_subject_key_identifier +.Xr i2s_ASN1_OCTET_STRING 3 +.El +.Pp +Some of the public printing functions are not documented yet. +.Pp +If +.Fa ext +is of an unknown extension type or if decoding fails +while using the decoding function for the relevant type, +the action taken depends on the +.Fa flags +argument: +.Bl -bullet +.It +If the bit +.Dv X509V3_EXT_PARSE_UNKNOWN +is set, +.Xr ASN1_parse_dump 3 +is called on the BER-encoded data of the extension, passing \-1 for the +.Fa dump +argument. +Thus, some information about the encoding of the extension gets printed +and some about its decoded content, falling back to +.Xr BIO_dump_indent 3 +for the decoded content unless a dedicated printing method is known +for the respective data type(s). +Note that even if an extension type is unknown, the data type used +by the unknown extension, or, if that data type is constructed, of +the values contained in it, may still be known, which may allow +printing the content of even an unknown extension in a structured +or partially structured form. +.It +If the bit +.Dv X509V3_EXT_DUMP_UNKNOWN +is set, +.Xr BIO_dump_indent 3 +is called on the BER-encoded data of the extension without decoding +it first, which is usually less readable than the above but poses +a smaller risk of omitting or misrepresenting parts of the information. +.It +If the bit +.Dv X509V3_EXT_ERROR_UNKNOWN +is set, only the fixed string +.Qq "" +is printed for an unknown type or only the fixed string +.Qq "" +if the parsing functions fails, +but printing is considered as successful anyway. +.It +If more than one of these three bits is set, or if a bit in +.Dv X509V3_EXT_UNKNOWN_MASK +is set that is not listed above, nothing is printed, but printing +is considered as successful anyway. +.It +If none of the bits in +.Dv X509V3_EXT_UNKNOWN_MASK +are set, nothing is printed and printing is considered as failed. +.El +.Sh RETURN VALUES +.Fn X509V3_EXT_print +and +.Fn X509V3_EXT_print_fp +return 0 if failure was both detected and considered relevant. +Otherwise, 1 is returned, and in general the user cannot tell whether +failure simply went undetected, whether the function detected failure +but regarded it as irrelevant, or whether printing did indeed +succeed. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_get0_extensions 3 , +.Xr X509_get_ext 3 , +.Xr X509V3_extensions_print 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.2 and have been available since +.Ox 2.6 . +.Sh BUGS +These functions lack error handling throughout. +When a write operation fails, they will usually ignore the fact that +information was omitted from the output and report success to the +caller anyway. diff --git a/static/openbsd/man3/X509V3_extensions_print.3 b/static/openbsd/man3/X509V3_extensions_print.3 new file mode 100644 index 00000000..d95a4da0 --- /dev/null +++ b/static/openbsd/man3/X509V3_extensions_print.3 @@ -0,0 +1,101 @@ +.\" $OpenBSD: X509V3_extensions_print.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509V3_EXTENSIONS_PRINT 3 +.Os +.Sh NAME +.Nm X509V3_extensions_print +.Nd pretty-print an array of X.509 extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fo X509V3_extensions_print +.Fa "BIO *bio" +.Fa "char *title" +.Fa "const STACK_OF(X509_EXTENSION) *sk" +.Fa "unsigned long flags" +.Fa "int indent" +.Fc +.Sh DESCRIPTION +For each member of the variable sized array +.Fa sk , +.Fn X509V3_extensions_print +prints the following information to +.Fa bio +in the following order: +.Bl -bullet +.It +The extension type as printed by +.Xr i2a_ASN1_OBJECT 3 . +.It +If the extension is critical, the fixed string +.Qq "critical" . +.It +A human-readable representation of the data contained in the extension +as printed by +.Xr X509V3_EXT_print 3 , +passing through the +.Fa flags . +If that function indicates failure, +the BER-encoded data of the extension is dumped with +.Xr ASN1_STRING_print 3 +without decoding it first. +In both cases, an +.Fa indent +incremented by 4 space characters is used. +.El +.Pp +If +.Fa sk +is a +.Dv NULL +pointer or empty, +.Fn X509V3_extensions_print +prints nothing and indicates success. +.Pp +Unless +.Fa title +is +.Dv NULL , +it is printed on its own output line before the rest of the output, and +.Fa indent +is increased by 4 space characters. +This additional global indentation is cumulative +to the one applied to individual extensions mentioned above. +.Sh RETURN VALUES +.Fn X509V3_extensions_print +is intended to return 1 on success or 0 if an error occurs. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr STACK_OF 3 , +.Xr X509_EXTENSION_get_critical 3 , +.Xr X509_get0_extensions 3 , +.Xr X509_get_ext 3 , +.Xr X509V3_EXT_print 3 +.Sh HISTORY +.Fn X509V3_extensions_print +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Sh BUGS +Many parsing and printing errors are silently ignored, +and the function may return indicating success even though +.Fa sk +contains invalid data. +Even if all the data is valid, success may be indicated even when the +information printed is incomplete for various reasons, for example +due to memory allocation failures or I/O errors. diff --git a/static/openbsd/man3/X509V3_get_d2i.3 b/static/openbsd/man3/X509V3_get_d2i.3 new file mode 100644 index 00000000..7920fca0 --- /dev/null +++ b/static/openbsd/man3/X509V3_get_d2i.3 @@ -0,0 +1,508 @@ +.\" $OpenBSD: X509V3_get_d2i.3,v 1.26 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL ff7fbfd5 Nov 2 11:52:01 2015 +0000 +.\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023, 2024 Theo Buehler +.\" Copyright (c) 2024 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2014, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509V3_GET_D2I 3 +.Os +.Sh NAME +.Nm X509V3_get_d2i , +.Nm X509V3_add1_i2d , +.Nm X509V3_EXT_d2i , +.Nm X509V3_EXT_i2d , +.Nm X509_get_ext_d2i , +.Nm X509_add1_ext_i2d , +.Nm X509_CRL_get_ext_d2i , +.Nm X509_CRL_add1_ext_i2d , +.Nm X509_REVOKED_get_ext_d2i , +.Nm X509_REVOKED_add1_ext_i2d , +.Nm X509_get0_extensions , +.Nm X509_CRL_get0_extensions , +.Nm X509_REVOKED_get0_extensions , +.Nm X509_get0_uids +.Nd X509 extension decode and encode functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft void * +.Fo X509V3_get_d2i +.Fa "const STACK_OF(X509_EXTENSION) *x" +.Fa "int nid" +.Fa "int *crit" +.Fa "int *idx" +.Fc +.Ft int +.Fo X509V3_add1_i2d +.Fa "STACK_OF(X509_EXTENSION) **x" +.Fa "int nid" +.Fa "void *value" +.Fa "int crit" +.Fa "unsigned long flags" +.Fc +.Ft void * +.Fo X509V3_EXT_d2i +.Fa "X509_EXTENSION *ext" +.Fc +.Ft X509_EXTENSION * +.Fo X509V3_EXT_i2d +.Fa "int ext_nid" +.Fa "int crit" +.Fa "void *ext" +.Fc +.Ft void * +.Fo X509_get_ext_d2i +.Fa "const X509 *x" +.Fa "int nid" +.Fa "int *crit" +.Fa "int *idx" +.Fc +.Ft int +.Fo X509_add1_ext_i2d +.Fa "X509 *x" +.Fa "int nid" +.Fa "void *value" +.Fa "int crit" +.Fa "unsigned long flags" +.Fc +.Ft void * +.Fo X509_CRL_get_ext_d2i +.Fa "const X509_CRL *crl" +.Fa "int nid" +.Fa "int *crit" +.Fa "int *idx" +.Fc +.Ft int +.Fo X509_CRL_add1_ext_i2d +.Fa "X509_CRL *crl" +.Fa "int nid" +.Fa "void *value" +.Fa "int crit" +.Fa "unsigned long flags" +.Fc +.Ft void * +.Fo X509_REVOKED_get_ext_d2i +.Fa "const X509_REVOKED *r" +.Fa "int nid" +.Fa "int *crit" +.Fa "int *idx" +.Fc +.Ft int +.Fo X509_REVOKED_add1_ext_i2d +.Fa "X509_REVOKED *r" +.Fa "int nid" +.Fa "void *value" +.Fa "int crit" +.Fa "unsigned long flags" +.Fc +.Ft const STACK_OF(X509_EXTENSION) * +.Fo X509_get0_extensions +.Fa "const X509 *x" +.Fc +.Ft const STACK_OF(X509_EXTENSION) * +.Fo X509_CRL_get0_extensions +.Fa "const X509_CRL *crl" +.Fc +.Ft const STACK_OF(X509_EXTENSION) * +.Fo X509_REVOKED_get0_extensions +.Fa "const X509_REVOKED *r" +.Fc +.Ft void +.Fo X509_get0_uids +.Fa "const X509 *x" +.Fa "const ASN1_BIT_STRING **issuerUID" +.Fa "const ASN1_BIT_STRING **subjectUID" +.Fc +.Sh DESCRIPTION +.Fn X509V3_get_d2i +looks for an extension with OID +.Fa nid +in the extensions +.Fa x +and, if found, decodes it. +If +.Fa idx +is +.Dv NULL , +then only one occurrence of an extension is permissible. +Otherwise the first extension after index +.Pf * Fa idx +is returned and +.Pf * Fa idx +is updated to the location of the extension. +If +.Fa crit +is not +.Dv NULL , +then +.Pf * Fa crit +is set to a status value: -2 if the extension occurs multiple times +(this is only returned if +.Fa idx +is +.Dv NULL ) , +-1 if the extension could not be found, 0 if the extension is found +and is not critical, and 1 if it is critical. +A pointer to an extension specific structure or +.Dv NULL +is returned. +.Pp +.Fn X509V3_add1_i2d +adds extension +.Fa value +to STACK +.Pf * Fa x +(allocating a new STACK if necessary) using OID +.Fa nid +and criticality +.Fa crit +according to +.Fa flags . +.Pp +.Fn X509V3_EXT_d2i +attempts to decode the ASN.1 data contained in extension +.Fa ext +and returns a pointer to an extension specific structure or +.Dv NULL +if the extension could not be decoded (invalid syntax or not supported). +.Pp +.Fn X509V3_EXT_i2d +encodes the extension specific structure +.Fa ext +with OID +.Fa ext_nid +and criticality +.Fa crit . +.Pp +.Fn X509_get_ext_d2i +and +.Fn X509_add1_ext_i2d +operate on the extensions of certificate +.Fa x , +and are otherwise identical to +.Fn X509V3_get_d2i +and +.Fn X509V3_add1_i2d . +.Pp +.Fn X509_CRL_get_ext_d2i +and +.Fn X509_CRL_add1_ext_i2d +operate on the extensions of CRL +.Fa crl , +and are otherwise identical to +.Fn X509V3_get_d2i +and +.Fn X509V3_add1_i2d . +.Pp +.Fn X509_REVOKED_get_ext_d2i +and +.Fn X509_REVOKED_add1_ext_i2d +operate on the extensions of the +.Vt X509_REVOKED +structure +.Fa r +(i.e. for CRL entry extensions), and are otherwise identical to +.Fn X509V3_get_d2i +and +.Fn X509V3_add1_i2d . +.Pp +.Fn X509_get0_extensions , +.Fn X509_CRL_get0_extensions , +and +.Fn X509_REVOKED_get0_extensions +return a stack of all the extensions of a certificate, a CRL, +or a CRL entry, respectively. +.Pp +In almost all cases an extension can occur at most once and multiple +occurrences is an error. +Therefore the +.Fa idx +parameter is usually +.Dv NULL . +.Pp +The +.Fa flags +argument consists of two parts OR'ed together: +the operation mode and the optional silent flag. +The operation mode is the bitwise OR of the +.Fa flags +and the bitmask +.Dv X509V3_ADD_OP_MASK . +The following operation modes are recognized: +.Pp +.Dv X509V3_ADD_DEFAULT +appends a new extension only if the extension does not already exist. +An error is returned if the extension does already exist. +.Pp +.Dv X509V3_ADD_APPEND +appends a new extension, ignoring whether the extension already exists. +This is a misfeature and should not be used because certificates must +not include the same extension more than once. +.Pp +.Dv X509V3_ADD_REPLACE +replaces an extension if it exists otherwise appends a new extension. +.Pp +.Dv X509V3_ADD_REPLACE_EXISTING +replaces an existing extension if it exists otherwise returns an error. +.Pp +.Dv X509V3_ADD_KEEP_EXISTING +appends a new extension only if the extension does not already exist. +An error +.Sy is not +returned if the extension does already exist. +.Pp +.Dv X509V3_ADD_DELETE +deletes extension +.Fa nid +if it exists and errors otherwise. +No new extension is added. +.Pp +Any other operation mode results in an error. +.Pp +If +.Dv X509V3_ADD_SILENT +is OR'd into the +.Fa flags , +any error returned will not be added to the error queue. +.Pp +The function +.Fn X509V3_get_d2i +will return +.Dv 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 +.Pf * Fa crit . +.Pp +.Fn X509_get0_uids +returns the issuer and subject unique identifiers of the certificate +.Fa x +in +.Pf * Fa issuerUID +and +.Pf * Fa subjectUID . +If a unique identifier field is not present in +.Fa x , +.Dv NULL +is returned. +Either one of +.Fa issuerUID +and +.Fa subjectUID +can be +.Dv NULL . +.Sh SUPPORTED EXTENSIONS +The following sections contain a list of all supported extensions +including their name and NID. +.Ss PKIX Certificate Extensions +The following certificate extensions are defined in PKIX standards such +as RFC 5280. +.Bl -column 30n 30n +.It Basic Constraints Ta Dv NID_basic_constraints +.It Key Usage Ta Dv NID_key_usage +.It Extended Key Usage Ta Dv NID_ext_key_usage +.It Subject Key Identifier Ta Dv NID_subject_key_identifier +.It Authority Key Identifier Ta Dv NID_authority_key_identifier +.It Private Key Usage Period Ta Dv NID_private_key_usage_period +.It Subject Alternative Name Ta Dv NID_subject_alt_name +.It Issuer Alternative Name Ta Dv NID_issuer_alt_name +.It Authority Information Access Ta Dv NID_info_access +.It Subject Information Access Ta Dv NID_sinfo_access +.It Name Constraints Ta Dv NID_name_constraints +.It Certificate Policies Ta Dv NID_certificate_policies +.It Policy Mappings Ta Dv NID_policy_mappings +.It Policy Constraints Ta Dv NID_policy_constraints +.It Inhibit Any Policy Ta Dv NID_inhibit_any_policy +.It IP Address Delegation Ta Dv NID_sbgp_ipAddrBlock +.It Autonomous System Identifier Delegation\ + Ta Dv NID_sbgp_autonomousSysNum +.El +.Ss Netscape Certificate Extensions +The following are (largely obsolete) Netscape certificate extensions. +.Bl -column 30n 30n +.It Netscape Cert Type Ta Dv NID_netscape_cert_type +.It Netscape Base Url Ta Dv NID_netscape_base_url +.It Netscape Revocation Url Ta Dv NID_netscape_revocation_url +.It Netscape CA Revocation Url Ta Dv NID_netscape_ca_revocation_url +.It Netscape Renewal Url Ta Dv NID_netscape_renewal_url +.It Netscape CA Policy Url Ta Dv NID_netscape_ca_policy_url +.It Netscape SSL Server Name Ta Dv NID_netscape_ssl_server_name +.It Netscape Comment Ta Dv NID_netscape_comment +.El +.Ss PKIX CRL Extensions +The following are CRL extensions from PKIX standards such as RFC 5280. +.Bl -column 30n 30n +.It CRL Number Ta Dv NID_crl_number +.It CRL Distribution Points Ta Dv NID_crl_distribution_points +.It Delta CRL Indicator Ta Dv NID_delta_crl +.It Freshest CRL Ta Dv NID_freshest_crl +.It Invalidity Date Ta Dv NID_invalidity_date +.It Issuing Distribution Point Ta Dv NID_issuing_distribution_point +.El +.Pp +The following are CRL entry extensions from PKIX standards such as +RFC 5280. +.Bl -column 30n 30n +.It CRL Reason Code Ta Dv NID_crl_reason +.It Certificate Issuer Ta Dv NID_certificate_issuer +.El +.Ss OCSP Extensions +.Bl -column 30n 30n +.It OCSP Nonce Ta Dv NID_id_pkix_OCSP_Nonce +.It OCSP CRL ID Ta Dv NID_id_pkix_OCSP_CrlID +.It Acceptable OCSP Responses Ta Dv NID_id_pkix_OCSP_acceptableResponses +.It OCSP No Check Ta Dv NID_id_pkix_OCSP_noCheck +.It OCSP Archive Cutoff Ta Dv NID_id_pkix_OCSP_archiveCutoff +.It OCSP Service Locator Ta Dv NID_id_pkix_OCSP_serviceLocator +.It Hold Instruction Code Ta Dv NID_hold_instruction_code +.El +.Sh RETURN VALUES +.Fn X509V3_get_d2i , +.Fn X509V3_EXT_d2i , +.Fn X509_get_ext_d2i , +.Fn X509_CRL_get_ext_d2i , +and +.Fn X509_REVOKED_get_ext_d2i +return a pointer to an extension specific structure or +.Dv NULL +if an error occurs. +.Pp +.Fn X509V3_add1_i2d , +.Fn X509_add1_ext_i2d , +.Fn X509_CRL_add1_ext_i2d , +and +.Fn X509_REVOKED_add1_ext_i2d +return 1 if the operation is successful, 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. +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Pp +The +.Fn X509V3_EXT_i2d +function returns a pointer to an +.Vt X509_EXTENSION +structure if successful; otherwise +.Dv NULL +is returned and an error code can be retrieved with +.Xr ERR_get_error 3 . +.Pp +.Fn X509_get0_extensions , +.Fn X509_CRL_get0_extensions , +and +.Fn X509_REVOKED_get0_extensions +return a stack of extensions, or +.Dv NULL +if no extensions are present. +.Sh SEE ALSO +.Xr d2i_X509 3 , +.Xr d2i_X509_EXTENSION 3 , +.Xr X509_check_purpose 3 , +.Xr X509_CRL_get0_by_serial 3 , +.Xr X509_CRL_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_get_version 3 , +.Xr X509_new 3 , +.Xr X509_REVOKED_new 3 , +.Xr X509V3_EXT_print 3 , +.Xr X509V3_extensions_print 3 +.Sh HISTORY +.Fn X509V3_EXT_d2i +first appeared in OpenSSL 0.9.2b. +.Fn X509V3_EXT_i2d +first appeared in OpenSSL 0.9.3. +Both functions have been available since +.Ox 2.6 . +.Pp +.Fn X509V3_get_d2i , +.Fn X509_get_ext_d2i , +.Fn X509_CRL_get_ext_d2i , +and +.Fn X509_REVOKED_get_ext_d2i +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn X509V3_add1_i2d , +.Fn X509_add1_ext_i2d , +.Fn X509_CRL_add1_ext_i2d , +and +.Fn X509_REVOKED_add1_ext_i2d +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn X509_get0_extensions , +.Fn X509_CRL_get0_extensions , +and +.Fn X509_REVOKED_get0_extensions +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +.Pp +.Fn X509_get0_uids +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.3 . diff --git a/static/openbsd/man3/X509V3_parse_list.3 b/static/openbsd/man3/X509V3_parse_list.3 new file mode 100644 index 00000000..385f8ad9 --- /dev/null +++ b/static/openbsd/man3/X509V3_parse_list.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: X509V3_parse_list.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2024 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 $Mdocdate: June 8 2025 $ +.Dt X509V3_PARSE_LIST 3 +.Os +.Sh NAME +.Nm X509V3_parse_list , +.Nm X509V3_conf_free +.Nd create and destroy CONF_VALUE objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft STACK_OF(CONF_VALUE) * +.Fn X509V3_parse_list "const char *string" +.Ft void +.Fn X509V3_conf_free "CONF_VALUE *conf" +.Sh DESCRIPTION +.Fn X509V3_parse_list +parses the +.Fa string +and allocates an array of +.Vt CONF_VALUE +objects according to the following rules. +.Bl -enum -width 2n +.It +The string is split into fields at comma +.Pq Sq \&, +characters. +.It +If a field contains a colon +.Pq Sq \&: +character, the part before the colon is regarded as a name +and the part after the first colon as the associated value. +Otherwise, the whole field is regarded as the name and +.Dv NULL +is used as the associated value. +.It +For each name and each value, leading and trailing whitespace as defined by +.Xr isspace 3 +is ignored. +.It +Parsing ends when a NUL, carriage return, or newline character +is encountered. +.El +.Pp +A new, empty +.Vt STACK_OF(CONF_VALUE) +is allocated and for each parsed name, one +.Vt CONF_VALUE +structure containing the optional value is pushed onto it. +.Pp +.Fn X509V3_conf_free +releases all memory used by +.Fa conf . +If +.Fa conf +is +.Dv NULL , +no action occurs. +.Pp +The typical way to release the memory returned from +.Fn X509V3_parse_list +is by calling +.Fn sk_CONF_VALUE_pop_free +on it, passing a pointer to the function +.Fn X509V3_conf_free +as the second argument. +.Sh RETURN VALUES +.Fn X509V3_parse_list +returns the new +.Vt STACK_OF(CONF_VALUE) +object or +.Dv NULL +if an error occurs, in particular if there isn't any name, +if the name before a colon or after a comma is empty, +if the value after a colon is empty, +or if memory allocation fails. +.Sh SEE ALSO +.Xr isspace 3 , +.Xr sk_pop_free 3 , +.Xr STACK_OF 3 , +.Xr v2i_ASN1_BIT_STRING 3 +.Sh HISTORY +.Fn X509V3_parse_list +and +.Fn X509V3_conf_free +first appeared in OpenSSL 0.9.2 and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/X509_ALGOR_dup.3 b/static/openbsd/man3/X509_ALGOR_dup.3 new file mode 100644 index 00000000..bc9ba4b7 --- /dev/null +++ b/static/openbsd/man3/X509_ALGOR_dup.3 @@ -0,0 +1,298 @@ +.\" $OpenBSD: X509_ALGOR_dup.3,v 1.24 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 4692340e Jun 7 15:49:08 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" Copyright (c) 2016 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_ALGOR_DUP 3 +.Os +.Sh NAME +.Nm X509_ALGOR_new , +.Nm X509_ALGOR_free , +.Nm X509_ALGOR_dup , +.Nm X509_ALGOR_set0 , +.Nm X509_ALGOR_get0 , +.Nm X509_ALGOR_cmp +.Nd create, change, and inspect algorithm identifiers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_ALGOR * +.Fn X509_ALGOR_new void +.Ft void +.Fn X509_ALGOR_free "X509_ALGOR *alg" +.Ft X509_ALGOR * +.Fo X509_ALGOR_dup +.Fa "X509_ALGOR *alg" +.Fc +.Ft int +.Fo X509_ALGOR_set0 +.Fa "X509_ALGOR *alg" +.Fa "ASN1_OBJECT *aobj" +.Fa "int ptype" +.Fa "void *pval" +.Fc +.Ft void +.Fo X509_ALGOR_get0 +.Fa "const ASN1_OBJECT **paobj" +.Fa "int *pptype" +.Fa "const void **ppval" +.Fa "const X509_ALGOR *alg" +.Fc +.Ft int +.Fo X509_ALGOR_cmp +.Fa "const X509_ALGOR *a" +.Fa "const X509_ALGOR *b" +.Fc +.Sh DESCRIPTION +An +.Vt X509_ALGOR +object represents an ASN.1 +.Vt AlgorithmIdentifier +structure defined in RFC 5280 section 4.1.1.2. +It specifies a cryptographic +.Fa algorithm +by an ASN.1 object identifier (OID) that can be obtained from +.Xr OBJ_nid2obj 3 , +together with optional algorithm-specific +.Fa parameters +of the type +.Vt ASN1_TYPE , +see +.Xr ASN1_TYPE_set 3 . +.Vt X509_ALGOR +objects are used by many other objects, for example certificates, +certificate revocation lists, and certificate requests. +.Pp +.Fn X509_ALGOR_new +allocates a new +.Vt X509_ALGOR +object containing the object that +.Xr OBJ_nid2obj 3 +returns for +.Dv NID_undef +as the +.Fa algorithm +and a +.Dv NULL +pointer as the +.Fa parameters . +.Pp +.Fn X509_ALGOR_free +frees +.Fa alg +and any data contained in it. +If +.Fa alg +is +.Dv NULL , +no action occurs. +.Pp +.Fn X509_ALGOR_dup +creates a deep copy of +.Fa alg . +It is implemented by calling +.Xr ASN1_item_dup 3 +with arguments of +.Dv X509_ALGOR_it +and +.Fa alg , +which is equivalent to calling +.Xr i2d_X509_ALGOR 3 +and +.Xr d2i_X509_ALGOR 3 . +.Pp +.Fn X509_ALGOR_set0 +sets the algorithm OID of +.Fa alg +to +.Fa aobj +and the associated parameter type to +.Fa ptype +with value +.Fa pval . +If +.Fa ptype +is +.Dv V_ASN1_UNDEF , +the parameter is omitted and +.Fa pval +is ignored. +If +.Fa ptype +is zero, +.Fa pval +is ignored and the existing parameter is left unchanged, or if +.Fa alg +does not contain a parameter, a new, empty parameter of type +.Dv V_ASN1_UNDEF +is added. +Otherwise +.Fa ptype +and +.Fa pval +have the same meaning as the +.Fa type +and +.Fa value +parameters to +.Xr ASN1_TYPE_set 3 . +Ownership of +.Fa aobj +and, unless it is ignored, of +.Fa pval +is transferred to +.Fa alg +on success. +.Pp +.Fn X509_ALGOR_get0 +returns +.Fa alg Ns 's +algorithm OID in +.Pf * Fa paobj , +its parameter type in +.Pf * Fa pptype , +and its parameter value in +.Pf * Fa ppval . +Any of +.Fa paobj , +.Fa pptype , +and +.Fa ppval +can be +.Dv NULL . +If +.Fa pptype is +.Dv NULL +or if +.Pf * Fa pptype +is +.Dv V_ASN1_UNDEF +then +.Pf * Fa ppval Ns 's +value is undefined. +.Pp +.Fn X509_ALGOR_cmp +compares +.Fa a +and +.Fa b . +.Sh RETURN VALUES +.Fn X509_ALGOR_new +and +.Fn X509_ALGOR_dup +return a new +.Vt X509_ALGOR +object or +.Dv NULL +if an error occurs. +.Pp +.Fn X509_ALGOR_set0 +returns 1 for success or 0 if +.Fa alg +is +.Dv NULL +or memory allocation fails. +.Pp +.Fn X509_ALGOR_cmp +returns 0 if +.Fa a +and +.Fa b +have identical encodings or non-zero otherwise. +.Sh SEE ALSO +.Xr ASN1_TYPE_set 3 , +.Xr d2i_X509_ALGOR 3 , +.Xr EVP_DigestInit 3 , +.Xr OBJ_nid2obj 3 , +.Xr X509_get0_signature 3 , +.Xr X509_new 3 , +.Xr X509_PUBKEY_get0_param 3 , +.Xr X509_signature_dump 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn X509_ALGOR_new +and +.Fn X509_ALGOR_free +appeared in SSLeay 0.4 or earlier and have been available since +.Ox 2.4 . +.Pp +.Fn X509_ALGOR_dup +first appeared in SSLeay 0.9.1 and has been available since +.Ox 2.6 . +.Pp +.Fn X509_ALGOR_set0 +and +.Fn X509_ALGOR_get0 +first appeared in OpenSSL 0.9.8h and have been available since +.Ox 4.5 . +.Pp +.Fn X509_ALGOR_cmp +first appeared in OpenSSL 0.9.8zd, 1.0.0p, and 1.0.1k +and has been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/X509_ATTRIBUTE_get0_object.3 b/static/openbsd/man3/X509_ATTRIBUTE_get0_object.3 new file mode 100644 index 00000000..b452fcbe --- /dev/null +++ b/static/openbsd/man3/X509_ATTRIBUTE_get0_object.3 @@ -0,0 +1,137 @@ +.\" $OpenBSD: X509_ATTRIBUTE_get0_object.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_ATTRIBUTE_GET0_OBJECT 3 +.Os +.Sh NAME +.Nm X509_ATTRIBUTE_get0_object , +.Nm X509_ATTRIBUTE_count , +.Nm X509_ATTRIBUTE_get0_type , +.Nm X509_ATTRIBUTE_get0_data +.\" In the following line, "X.501" and "Attribute" are not typos. +.\" The "Attribute" type is defined in X.501, not in X.509. +.\" The type is called "Attribute" with capital "A", not "attribute". +.Nd X.501 Attribute read accessors +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft ASN1_OBJECT * +.Fo X509_ATTRIBUTE_get0_object +.Fa "X509_ATTRIBUTE *attr" +.Fc +.Ft int +.Fo X509_ATTRIBUTE_count +.Fa "const X509_ATTRIBUTE *attr" +.Fc +.Ft ASN1_TYPE * +.Fo X509_ATTRIBUTE_get0_type +.Fa "X509_ATTRIBUTE *attr" +.Fa "int index" +.Fc +.Ft void * +.Fo X509_ATTRIBUTE_get0_data +.Fa "X509_ATTRIBUTE *attr" +.Fa "int index" +.Fa "int type" +.Fa "void *data" +.Fc +.Sh DESCRIPTION +These functions provide read access to the X.501 Attribute object +.Fa attr . +.Pp +For +.Fn X509_ATTRIBUTE_get0_data , +the +.Fa type +argument usually is one of the +.Dv V_ASN1_* +constants defined in +.In openssl/asn1.h . +For example, if a return value of the type +.Vt ASN1_OCTET_STRING +is expected, pass +.Dv V_ASN1_OCTET_STRING +as the +.Fa type +argument. +The +.Fa data +argument is ignored; passing +.Dv NULL +is recommended. +.Sh RETURN VALUES +.Fn X509_ATTRIBUTE_get0_object +returns an internal pointer to the type of +.Fa attr +or +.Dv NULL +if +.Fa attr +is +.Dv NULL +or if its type is not set. +.Pp +.Fn X509_ATTRIBUTE_count +returns the number of values stored in +.Fa attr +or 0 if no value or values are set. +.Pp +.Fn X509_ATTRIBUTE_get0_type +returns an internal pointer to the ASN.1 ANY object +representing the value with the given zero-based +.Fa index +or +.Dv NULL +if +.Fa attr +is +.Dv NULL , +if the +.Fa index +is larger than or equal to the number of values stored in +.Fa attr , +or if no value or values are set. +.Pp +.Fn X509_ATTRIBUTE_get0_data +returns an internal pointer to the data +contained in the value with the given zero-based +.Fa index +or +.Dv NULL +if +.Fa attr +is +.Dv NULL , +if the +.Fa index +is larger than or equal to the number of values stored in +.Fa attr , +if no value or values are set, +or if the ASN.1 ANY object representing the value with the given +.Fa index +is not of the requested +.Fa type . +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr ASN1_TYPE_new 3 , +.Xr OPENSSL_sk_new 3 , +.Xr X509_ATTRIBUTE_new 3 , +.Xr X509_ATTRIBUTE_set1_object 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.5 +and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/X509_ATTRIBUTE_new.3 b/static/openbsd/man3/X509_ATTRIBUTE_new.3 new file mode 100644 index 00000000..63a5c581 --- /dev/null +++ b/static/openbsd/man3/X509_ATTRIBUTE_new.3 @@ -0,0 +1,181 @@ +.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.19 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016, 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_ATTRIBUTE_NEW 3 +.Os +.Sh NAME +.Nm X509_ATTRIBUTE_new , +.Nm X509_ATTRIBUTE_create , +.Nm X509_ATTRIBUTE_dup , +.Nm X509_ATTRIBUTE_free +.\" In the following line, "X.501" and "Attribute" are not typos. +.\" The "Attribute" type is defined in X.501, not in X.509. +.\" The type is called "Attribute" with capital "A", not "attribute". +.Nd generic X.501 Attribute +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_ATTRIBUTE * +.Fn X509_ATTRIBUTE_new void +.Ft X509_ATTRIBUTE * +.Fn X509_ATTRIBUTE_create "int nid" "int type" "void *value" +.Ft X509_ATTRIBUTE * +.Fn X509_ATTRIBUTE_dup "X509_ATTRIBUTE *attr" +.Ft void +.Fn X509_ATTRIBUTE_free "X509_ATTRIBUTE *attr" +.Sh DESCRIPTION +In the X.501 standard, an +.Vt Attribute +is the fundamental ASN.1 data type used to represent any kind of +property of any kind of directory entry. +In OpenSSL, very few objects use it directly, most notably the +.Vt X509_REQ_INFO +object used for PKCS#10 certification requests described in +.Xr X509_REQ_new 3 , +the +.Vt PKCS8_PRIV_KEY_INFO +object used for PKCS#8 private key information described in +.Xr PKCS8_PRIV_KEY_INFO_new 3 , +and the +.Vt PKCS12_SAFEBAG +container object described in +.Xr PKCS12_SAFEBAG_new 3 . +.Pp +.Fn X509_ATTRIBUTE_new +allocates and initializes an empty +.Vt X509_ATTRIBUTE +object. +.Pp +.Fn X509_ATTRIBUTE_create +allocates a new multi-valued +.Vt X509_ATTRIBUTE +object of the type +.Fa nid +and initializes its set of values +to contain one new ASN.1 ANY object with the given +.Fa value +and +.Fa type . +The +.Fa type +usually is one of the +.Dv V_ASN1_* +constants defined in +.In openssl/asn1.h ; +it is stored without validating it. +If the function succeeds, ownership of the +.Fa value +is transferred to the new +.Vt X509_ATTRIBUTE +object. +.Pp +Be careful to not confuse the type of the attribute +and the type of the value. +.Pp +.Fn X509_ATTRIBUTE_dup +creates a deep copy of +.Fa attr . +.Pp +.Fn X509_ATTRIBUTE_free +frees +.Fa attr . +.Sh RETURN VALUES +.Fn X509_ATTRIBUTE_new , +.Fn X509_ATTRIBUTE_create , +and +.Fn X509_ATTRIBUTE_dup +return the new +.Vt X509_ATTRIBUTE +object or +.Dv NULL +if an error occurs. +.Pp +In particular, these functions fail if memory allocation fails. +.Fn X509_ATTRIBUTE_create +also fails if +.Xr OBJ_nid2obj 3 +fails on +.Fa nid . +.Sh SEE ALSO +.Xr d2i_X509_ATTRIBUTE 3 , +.Xr OBJ_nid2obj 3 , +.Xr PKCS12_SAFEBAG_new 3 , +.Xr PKCS7_add_attribute 3 , +.Xr PKCS8_pkey_get0_attrs 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 , +.Xr X509_ATTRIBUTE_get0_object 3 , +.Xr X509_ATTRIBUTE_set1_object 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_new 3 , +.Xr X509_REQ_add1_attr 3 , +.Xr X509_REQ_new 3 +.Sh STANDARDS +.Bl -ohang +.It Xo +For the general definition of the +.Vt Attribute +data type: +.Xc +ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: +Information Technology \(en Open Systems Interconnection \(en +The Directory: Models, section 8.2: Overall structure +.It For the specific definition in the context of certification requests: +RFC 2986: PKCS #10: Certification Request Syntax Specification, +section 4.1: CertificationRequestInfo +.It For the specific use in the context of private key information: +RFC 5208: Public-Key Cryptography Standards (PKCS) #8: +Private-Key Information Syntax Specification +.It For the specific definition in the context of PFX: +RFC 7292: PKCS #12: Personal Information Exchange Syntax, +section 4.2: The SafeBag Type +.El +.Sh HISTORY +.Fn X509_ATTRIBUTE_new +and +.Fn X509_ATTRIBUTE_free +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_ATTRIBUTE_create +and +.Fn X509_ATTRIBUTE_dup +first appeared in SSLeay 0.9.1 and have been available since +.Ox 2.6 . +.Sh BUGS +A data type designed to hold arbitrary data is an oxymoron. +.Pp +While it may occasionally be useful for abstract syntax specification +or for generic container objects, using it for the representation +of specific data in a specific data structure feels like dubious +design. +.Pp +Having two distinct data types to hold arbitrary data \(en +in this case, +.Vt X509_ATTRIBUTE +on the X.501 language level and +.Vt X509_EXTENSION +as described in +.Xr X509_EXTENSION_new 3 +on the X.509 language level \(en feels even more questionable, +in particular considering that Attributes in certification requests +can be used to ask for Extensions in certificates. +.Pp +At the very least, the direct use of the low-level generic +.Vt X509_ATTRIBUTE +type in specific data types like certification requests or private +key information looks like a layering violation and appears to put +type safety into jeopardy. diff --git a/static/openbsd/man3/X509_ATTRIBUTE_set1_object.3 b/static/openbsd/man3/X509_ATTRIBUTE_set1_object.3 new file mode 100644 index 00000000..d26e7de4 --- /dev/null +++ b/static/openbsd/man3/X509_ATTRIBUTE_set1_object.3 @@ -0,0 +1,268 @@ +.\" $OpenBSD: X509_ATTRIBUTE_set1_object.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_ATTRIBUTE_SET1_OBJECT 3 +.Os +.Sh NAME +.Nm X509_ATTRIBUTE_set1_object , +.Nm X509_ATTRIBUTE_set1_data , +.Nm X509_ATTRIBUTE_create_by_OBJ , +.Nm X509_ATTRIBUTE_create_by_NID , +.Nm X509_ATTRIBUTE_create_by_txt +.\" In the following line, "X.501" and "Attribute" are not typos. +.\" The "Attribute" type is defined in X.501, not in X.509. +.\" The type is called "Attribute" with capital "A", not "attribute". +.Nd modify an X.501 Attribute +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_ATTRIBUTE_set1_object +.Fa "X509_ATTRIBUTE *attr" +.Fa "const ASN1_OBJECT *obj" +.Fc +.Ft int +.Fo X509_ATTRIBUTE_set1_data +.Fa "X509_ATTRIBUTE *attr" +.Fa "int type" +.Fa "const void *data" +.Fa "int len" +.Fc +.Ft X509_ATTRIBUTE * +.Fo X509_ATTRIBUTE_create_by_OBJ +.Fa "X509_ATTRIBUTE **pattr" +.Fa "const ASN1_OBJECT *obj" +.Fa "int type" +.Fa "const void *data" +.Fa "int len" +.Fc +.Ft X509_ATTRIBUTE * +.Fo X509_ATTRIBUTE_create_by_NID +.Fa "X509_ATTRIBUTE **pattr" +.Fa "int nid" +.Fa "int type" +.Fa "const void *data" +.Fa "int len" +.Fc +.Ft X509_ATTRIBUTE * +.Fo X509_ATTRIBUTE_create_by_txt +.Fa "X509_ATTRIBUTE **pattr" +.Fa "const char *name" +.Fa "int type" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Sh DESCRIPTION +.Fn X509_ATTRIBUTE_set1_object +sets the type of +.Fa attr +to +.Fa obj . +If +.Fa obj +is dynamically allocated, a deep copy is created. +If the type of +.Fa attr +was already set, the old type is freed +as far as it was dynamically allocated. +After calling this function, +.Fa attr +may be in an inconsistent state +because its values may not agree with the new attribute type. +.Pp +.Fn X509_ATTRIBUTE_set1_data +sets +.Fa attr +to be multi-valued and initializes its set of values +to contain a single new ASN.1 ANY object representing the +.Fa data . +.Pp +The interpretation of the +.Fa data +depends on the values of the +.Fa type +and +.Fa len +arguments; there are four different cases. +.Pp +If the +.Fa type +argument has the bit +.Dv MBSTRING_FLAG +set, +.Fa data +is expected to point to a multibyte character string that is +.Fa len +bytes long and uses the encoding specified by the +.Fa type +argument, and it is expected that an attribute type was already assigned to +.Fa attr , +for example by calling +.Fn X509_ATTRIBUTE_set1_object +before calling +.Fn X509_ATTRIBUTE_set1_data . +In this case, an appropriate ASN.1 multibyte string type is chosen and +a new object of that type is allocated and populated to represent the +.Fa data +by calling +.Xr ASN1_STRING_set_by_NID 3 . +The type of that new ASN.1 string object is subsequently used instead of the +.Fa type +argument. +.Pp +If the +.Fa type +argument does not have the bit +.Dv MBSTRING_FLAG +set and the +.Fa len argument +is not \-1, the +.Fa type +argument is expected to be one of the types documented in +.Xr ASN1_STRING_new 3 +and +.Fa data +is expected to point to a buffer of +.Fa len +bytes. +In this case, a new object is allocated with +.Xr ASN1_STRING_type_new 3 +and populated with +.Xr ASN1_STRING_set 3 . +.Pp +If the +.Fa type +argument does not have the bit +.Dv MBSTRING_FLAG +set and the +.Fa len argument +is \-1, +.Fa data +is expected to point to an object of the given +.Fa type +rather than to a buffer. +In this case, a deep copy of the existing object +into the new ASN.1 ANY object is performed with +.Xr ASN1_TYPE_set1 3 . +.Pp +If the +.Fa type +argument is 0, the +.Fa data +and +.Fa len +arguments are ignored and the set of values is left empty +instead of adding a single ASN.1 ANY object to it. +This violates section 8.2 of the X.501 standard, which requires +every attribute to contain at least one value, but some attribute +types used by the library use empty sets of values anyway. +.Pp +.Fn X509_ATTRIBUTE_create_by_OBJ +sets the type of +.Pf ** Fa attr +to +.Fa obj +using +.Fn X509_ATTRIBUTE_set1_object +and copies the +.Fa data +into it using +.Fn X509_ATTRIBUTE_set1_data . +If +.Fa attr +or +.Pf * Fa attr +is +.Dv NULL , +a new +.Vt X509_ATTRIBUTE +object is allocated, populated, and returned. +.Pp +.Fn X509_ATTRIBUTE_create_by_NID +is a wrapper around +.Fn X509_ATTRIBUTE_create_by_OBJ +that obtains the required +.Fa obj +argument by calling +.Xr OBJ_nid2obj 3 +on the +.Fa nid +argument. +.Pp +.Fn X509_ATTRIBUTE_create_by_txt +is a similar wrapper that obtains +.Fa obj +by calling +.Xr OBJ_txt2obj 3 +with the arguments +.Fa name +and 0, which means that long names, short names, and numerical OID +strings are all acceptable. +.Sh RETURN VALUES +.Fn X509_ATTRIBUTE_set1_object +returns 1 if successful or 0 if +.Fa attr +or +.Fa obj +is +.Dv NULL +or if memory allocation fails. +.Pp +.Fn X509_ATTRIBUTE_set1_data +returns 1 if successful or 0 if +.Fa attr +is +.Dv NULL +or if +.Xr ASN1_STRING_set_by_NID 3 , +.Xr ASN1_STRING_set 3 , +.Xr ASN1_TYPE_set1 3 , +or memory allocation fails. +.Pp +.Fn X509_ATTRIBUTE_create_by_OBJ , +.Fn X509_ATTRIBUTE_create_by_NID , +and +.Fn X509_ATTRIBUTE_create_by_txt +return a pointer to the changed or new object or +.Dv NULL +if obtaining +.Fa obj , +allocating memory, or copying fails. +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr ASN1_STRING_new 3 , +.Xr ASN1_STRING_set 3 , +.Xr ASN1_STRING_set_by_NID 3 , +.Xr ASN1_TYPE_new 3 , +.Xr OBJ_nid2obj 3 , +.Xr X509_ATTRIBUTE_get0_object 3 , +.Xr X509_ATTRIBUTE_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.5 +and have been available since +.Ox 2.7 . +.Sh BUGS +If +.Fa attr +already contains one or more values, +.Fn X509_ATTRIBUTE_set1_data , +.Fn X509_ATTRIBUTE_create_by_OBJ , +.Fn X509_ATTRIBUTE_create_by_NID , +and +.Fn X509_ATTRIBUTE_create_by_txt +silently overwrite the pointers to the old values +and leak the memory used for them. diff --git a/static/openbsd/man3/X509_CINF_new.3 b/static/openbsd/man3/X509_CINF_new.3 new file mode 100644 index 00000000..62399c07 --- /dev/null +++ b/static/openbsd/man3/X509_CINF_new.3 @@ -0,0 +1,118 @@ +.\" $OpenBSD: X509_CINF_new.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt X509_CINF_NEW 3 +.Os +.Sh NAME +.Nm X509_CINF_new , +.Nm X509_CINF_free , +.Nm X509_VAL_new , +.Nm X509_VAL_free , +.Nm X509_CERT_AUX_new , +.Nm X509_CERT_AUX_free +.Nd X.509 certificate information objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_CINF * +.Fn X509_CINF_new void +.Ft void +.Fn X509_CINF_free "X509_CINF *inf" +.Ft X509_VAL * +.Fn X509_VAL_new void +.Ft void +.Fn X509_VAL_free "X509_VAL *val" +.Ft X509_CERT_AUX * +.Fn X509_CERT_AUX_new void +.Ft void +.Fn X509_CERT_AUX_free "X509_CERT_AUX *aux" +.Sh DESCRIPTION +.Fn X509_CINF_new +allocates and initializes an empty +.Vt X509_CINF +object, representing an ASN.1 +.Vt TBSCertificate +structure defined in RFC 5280 section 4.1. +It is used inside the +.Vt X509 +object and holds the main information contained in the X.509 +certificate including subject, public key, issuer, serial number, +validity period, and extensions. +.Fn X509_CINF_free +frees +.Fa inf . +.Pp +.Fn X509_VAL_new +allocates and initializes an empty +.Vt X509_VAL +object, representing an ASN.1 +.Vt Validity +structure defined in RFC 5280 section 4.1. +It is used inside the +.Vt X509_CINF +object and holds the validity period of the certificate. +.Fn X509_VAL_free +frees +.Fa val . +.Pp +.Fn X509_CERT_AUX_new +allocates and initializes an empty +.Vt X509_CERT_AUX +structure. +It can be used inside an +.Vt X509 +object to hold optional non-standard auxiliary data appended to a +certificate, for example friendly alias names and trust data. +.Fn X509_CERT_AUX_free +frees +.Fa aux . +.Sh RETURN VALUES +.Fn X509_CINF_new , +.Fn X509_VAL_new , +and +.Fn X509_CERT_AUX_new +return the new +.Vt X509_CINF , +.Vt X509_VAL , +or +.Vt X509_CERT_AUX +object, respectively, or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_X509_CINF 3 , +.Xr X509_add1_trust_object 3 , +.Xr X509_CERT_AUX_print 3 , +.Xr X509_keyid_set1 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn X509_CINF_new , +.Fn X509_CINF_free , +.Fn X509_VAL_new , +and +.Fn X509_VAL_free +appeared in SSLeay 0.4 or earlier and have been available since +.Ox 2.4 . +.Pp +.Fn X509_CERT_AUX_new +and +.Fn X509_CERT_AUX_free +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/X509_CRL_get0_by_serial.3 b/static/openbsd/man3/X509_CRL_get0_by_serial.3 new file mode 100644 index 00000000..5a7d57c3 --- /dev/null +++ b/static/openbsd/man3/X509_CRL_get0_by_serial.3 @@ -0,0 +1,180 @@ +.\" $OpenBSD: X509_CRL_get0_by_serial.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL cdd6c8c5 Mar 20 12:29:37 2017 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_CRL_GET0_BY_SERIAL 3 +.Os +.Sh NAME +.Nm X509_CRL_get0_by_serial , +.Nm X509_CRL_get0_by_cert , +.Nm X509_CRL_get_REVOKED , +.Nm X509_CRL_add0_revoked , +.Nm X509_CRL_sort +.Nd add, sort, and retrieve CRL entries +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_CRL_get0_by_serial +.Fa "X509_CRL *crl" +.Fa "X509_REVOKED **ret" +.Fa "ASN1_INTEGER *serial" +.Fc +.Ft int +.Fo X509_CRL_get0_by_cert +.Fa "X509_CRL *crl" +.Fa "X509_REVOKED **ret" +.Fa "X509 *x" +.Fc +.Ft STACK_OF(X509_REVOKED) * +.Fo X509_CRL_get_REVOKED +.Fa "X509_CRL *crl" +.Fc +.Ft int +.Fo X509_CRL_add0_revoked +.Fa "X509_CRL *crl" +.Fa "X509_REVOKED *rev" +.Fc +.Ft int +.Fo X509_CRL_sort +.Fa "X509_CRL *crl" +.Fc +.Sh DESCRIPTION +.Fn X509_CRL_get0_by_serial +attempts to find a revoked entry in +.Fa crl +for serial number +.Fa serial . +If it is successful, it sets +.Pf * Fa ret +to the internal pointer of the matching entry. +Consequently, +.Pf * Fa ret +must not be freed up after the call. +.Pp +.Fn X509_CRL_get0_by_cert +is similar to +.Fn X509_CRL_get0_by_serial +except that it looks for a revoked entry using the serial number +of certificate +.Fa x . +.Pp +.Fn X509_CRL_get_REVOKED +returns an internal pointer to a stack of all revoked entries for +.Fa crl . +.Pp +.Fn X509_CRL_add0_revoked +appends revoked entry +.Fa rev +to CRL +.Fa crl . +The pointer +.Fa rev +is used internally so it must not be freed up after the call: it is +freed when the parent CRL is freed. +.Pp +.Fn X509_CRL_sort +sorts the revoked entries of +.Fa crl +into ascending serial number order. +.Pp +Applications can determine the number of revoked entries returned by +.Fn X509_CRL_get_revoked +using +.Fn sk_X509_REVOKED_num +and examine each one in turn using +.Fn sk_X509_REVOKED_value , +both defined in +.In openssl/safestack.h . +.Sh RETURN VALUES +.Fn X509_CRL_get0_by_serial +and +.Fn X509_CRL_get0_by_cert +return 0 for failure or 1 for success, except if the revoked entry +has the reason +.Qq removeFromCRL , +in which case 2 is returned. +.Pp +The +.Fn X509_CRL_add0_revoked +function returns 1 if successful; +otherwise 0 is returned and an error code can be retrieved with +.Xr ERR_get_error 3 . +.Pp +.Fn X509_CRL_sort +returns 1 for success or 0 for failure. +The current implementation cannot fail. +.Pp +.Fn X509_CRL_get_REVOKED +returns a STACK of revoked entries. +.Sh SEE ALSO +.Xr d2i_X509_CRL 3 , +.Xr X509_CRL_get_ext 3 , +.Xr X509_CRL_get_issuer 3 , +.Xr X509_CRL_get_version 3 , +.Xr X509_CRL_new 3 , +.Xr X509_REVOKED_new 3 , +.Xr X509V3_get_d2i 3 +.Sh HISTORY +.Fn X509_CRL_get_REVOKED +first appeared in OpenSSL 0.9.2b and has been available since +.Ox 2.6 . +.Pp +.Fn X509_CRL_add0_revoked +and +.Fn X509_CRL_sort +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn X509_CRL_get0_by_serial +and +.Fn X509_CRL_get0_by_cert +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/X509_CRL_new.3 b/static/openbsd/man3/X509_CRL_new.3 new file mode 100644 index 00000000..36a64392 --- /dev/null +++ b/static/openbsd/man3/X509_CRL_new.3 @@ -0,0 +1,144 @@ +.\" $OpenBSD: X509_CRL_new.3,v 1.15 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016, 2018, 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_CRL_NEW 3 +.Os +.Sh NAME +.Nm X509_CRL_new , +.Nm X509_CRL_dup , +.Nm X509_CRL_up_ref , +.Nm X509_CRL_free , +.Nm X509_CRL_INFO_new , +.Nm X509_CRL_INFO_free +.Nd X.509 certificate revocation lists +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_CRL * +.Fn X509_CRL_new void +.Ft X509_CRL * +.Fn X509_CRL_dup "X509_CRL *crl" +.Ft int +.Fn X509_CRL_up_ref "X509_CRL *crl" +.Ft void +.Fn X509_CRL_free "X509_CRL *crl" +.Ft X509_CRL_INFO * +.Fn X509_CRL_INFO_new void +.Ft void +.Fn X509_CRL_INFO_free "X509_CRL_INFO *crl_info" +.Sh DESCRIPTION +.Fn X509_CRL_new +allocates and initializes an empty +.Vt X509_CRL +object, representing an ASN.1 +.Vt CertificateList +structure defined in RFC 5280 section 5.1. +It can hold a pointer to an +.Vt X509_CRL_INFO +object discussed below together with a cryptographic signature +and information about the signature algorithm used. +The reference count is set to 1. +.Pp +.Fn X509_CRL_dup +creates a deep copy of +.Fa crl . +.Pp +.Fn X509_CRL_up_ref +increments the reference count of +.Fa crl +by 1. +.Pp +.Fn X509_CRL_free +decrements the reference count of +.Fa crl +by 1. +If the reference count reaches 0, it frees +.Fa crl . +.Pp +.Fn X509_CRL_INFO_new +allocates and initializes an empty +.Vt X509_CRL_INFO +object, representing an ASN.1 +.Vt TBSCertList +structure defined in RFC 5280 section 5.1. +It is used inside the +.Vt X509_CRL +object and can hold a list of revoked certificates, an issuer name, +the time the list was issued, the time when the next update of the +list is due, and optional extensions. +.Fn X509_CRL_INFO_free +frees +.Fa crl_info . +.Sh RETURN VALUES +.Fn X509_CRL_new , +.Fn X509_CRL_dup , +and +.Fn X509_CRL_INFO_new +return the new +.Vt X509_CRL +or +.Vt X509_CRL_INFO +object, respectively, or +.Dv NULL +if an error occurs. +.Pp +.Fn X509_CRL_up_ref +returns 1 on success or 0 on error. +.Sh SEE ALSO +.Xr ACCESS_DESCRIPTION_new 3 , +.Xr AUTHORITY_KEYID_new 3 , +.Xr d2i_X509_CRL 3 , +.Xr DIST_POINT_new 3 , +.Xr PEM_read_X509_CRL 3 , +.Xr X509_CRL_digest 3 , +.Xr X509_CRL_get0_by_serial 3 , +.Xr X509_CRL_get0_lastUpdate 3 , +.Xr X509_CRL_get0_signature 3 , +.Xr X509_CRL_get_ext 3 , +.Xr X509_CRL_get_ext_d2i 3 , +.Xr X509_CRL_get_issuer 3 , +.Xr X509_CRL_get_version 3 , +.Xr X509_CRL_match 3 , +.Xr X509_CRL_print 3 , +.Xr X509_CRL_sign 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_INFO_new 3 , +.Xr X509_load_crl_file 3 , +.Xr X509_new 3 , +.Xr X509_OBJECT_get0_X509_CRL 3 , +.Xr X509_REVOKED_new 3 , +.Xr X509_STORE_CTX_set0_crls 3 , +.Xr X509_STORE_get1_crls 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, section 5: CRL and CRL +Extensions Profile +.Sh HISTORY +.Fn X509_CRL_new , +.Fn X509_CRL_free , +.Fn X509_CRL_INFO_new , +and +.Fn X509_CRL_INFO_free +first appeared in SSLeay 0.4.4. +.Fn X509_CRL_dup +first appeared in SSLeay 0.5.1. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_CRL_up_ref +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/X509_CRL_print.3 b/static/openbsd/man3/X509_CRL_print.3 new file mode 100644 index 00000000..1f1d2789 --- /dev/null +++ b/static/openbsd/man3/X509_CRL_print.3 @@ -0,0 +1,114 @@ +.\" $OpenBSD: X509_CRL_print.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_CRL_PRINT 3 +.Os +.Sh NAME +.Nm X509_CRL_print , +.Nm X509_CRL_print_fp +.Nd pretty-print a certificate revocation list +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_CRL_print +.Fa "BIO *bio" +.Fa "X509_CRL *crl" +.Fc +.Ft int +.Fo X509_CRL_print_fp +.Fa "FILE *fp" +.Fa "X509_CRL *crl" +.Fc +.Sh DESCRIPTION +.Fn X509_CRL_print +prints information contained in +.Fa crl +to +.Fa bio +in human-readable form, in the following order: +.Bl -bullet +.It +The certificate revocation list version number as defined by +the standard, followed in parentheses by the value contained +in the version field in hexadecimal notation. +See +.Xr X509_CRL_get_version 3 +for details. +.It +The name of the signature algorithm is printed with +.Xr X509_signature_print 3 . +.It +The issuer name as returned by +.Xr X509_CRL_get_issuer 3 . +.It +The times of the last and next updates as returned by +.Xr X509_CRL_get0_lastUpdate 3 +and +.Xr X509_CRL_get0_nextUpdate 3 +are printed with +.Xr ASN1_TIME_print 3 . +.It +All X.509 extensions directly contained +in the certificate revocation list object +.Fa crl +are printed with +.Xr X509V3_extensions_print 3 . +.It +Information about revoked certificates is retrieved with +.Xr X509_CRL_get_REVOKED 3 , +and for each revoked certificate, the following is printed: +.Bl -bullet +.It +The serial number of the certificate is printed with +.Xr i2a_ASN1_INTEGER 3 . +.It +The revocation date is printed with +.Xr ASN1_TIME_print 3 . +.It +All X.509 extensions contained in the revocation entry are printed with +.Xr X509V3_extensions_print 3 . +.El +.It +The signature of +.Fa crl +is printed with +.Xr X509_signature_print 3 . +.El +.Pp +.Fn X509_CRL_print_fp +is similar to +.Fn X509_CRL_print +except that it prints to +.Fa fp . +.Sh RETURN VALUES +These functions are intended to return 1 for success and 0 for error. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr X509_CRL_new 3 , +.Xr X509_print_ex 3 , +.Xr X509_REVOKED_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.2 and have been available since +.Ox 2.6 . +.Sh BUGS +Most I/O errors are silently ignored. +Even if the information printed is incomplete, these functions may +return 1 anyway. +.Pp +If the version number is invalid, no information from the CRL is printed +and the functions fail. diff --git a/static/openbsd/man3/X509_EXTENSION_set_object.3 b/static/openbsd/man3/X509_EXTENSION_set_object.3 new file mode 100644 index 00000000..f1356c35 --- /dev/null +++ b/static/openbsd/man3/X509_EXTENSION_set_object.3 @@ -0,0 +1,349 @@ +.\" $OpenBSD: X509_EXTENSION_set_object.3,v 1.20 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016, 2021, 2024 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_EXTENSION_SET_OBJECT 3 +.Os +.Sh NAME +.Nm X509_EXTENSION_new , +.Nm X509_EXTENSION_dup , +.Nm X509_EXTENSION_free , +.Nm X509_EXTENSION_create_by_NID , +.Nm X509_EXTENSION_create_by_OBJ , +.Nm X509_EXTENSION_set_object , +.Nm X509_EXTENSION_set_critical , +.Nm X509_EXTENSION_set_data , +.Nm X509_EXTENSION_get_object , +.Nm X509_EXTENSION_get_critical , +.Nm X509_EXTENSION_get_data , +.Nm X509_supported_extension +.\" In the next line, the capital "E" is not a typo. +.\" The ASN.1 structure is called "Extension", not "extension". +.Nd create, change, and inspect X.509 Extension objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_EXTENSION * +.Fn X509_EXTENSION_new void +.Ft X509_EXTENSION * +.Fn X509_EXTENSION_dup "X509_EXTENSION *ex" +.Ft void +.Fn X509_EXTENSION_free "X509_EXTENSION *ex" +.Ft X509_EXTENSION * +.Fo X509_EXTENSION_create_by_NID +.Fa "X509_EXTENSION **ex" +.Fa "int nid" +.Fa "int crit" +.Fa "ASN1_OCTET_STRING *data" +.Fc +.Ft X509_EXTENSION * +.Fo X509_EXTENSION_create_by_OBJ +.Fa "X509_EXTENSION **ex" +.Fa "const ASN1_OBJECT *obj" +.Fa "int crit" +.Fa "ASN1_OCTET_STRING *data" +.Fc +.Ft int +.Fo X509_EXTENSION_set_object +.Fa "X509_EXTENSION *ex" +.Fa "const ASN1_OBJECT *obj" +.Fc +.Ft int +.Fo X509_EXTENSION_set_critical +.Fa "X509_EXTENSION *ex" +.Fa "int crit" +.Fc +.Ft int +.Fo X509_EXTENSION_set_data +.Fa "X509_EXTENSION *ex" +.Fa "ASN1_OCTET_STRING *data" +.Fc +.Ft ASN1_OBJECT * +.Fo X509_EXTENSION_get_object +.Fa "X509_EXTENSION *ex" +.Fc +.Ft int +.Fo X509_EXTENSION_get_critical +.Fa "const X509_EXTENSION *ex" +.Fc +.Ft ASN1_OCTET_STRING * +.Fo X509_EXTENSION_get_data +.Fa "X509_EXTENSION *ex" +.Fc +.Ft int +.Fo X509_supported_extension +.Fa "X509_EXTENSION *ex" +.Fc +.Sh DESCRIPTION +.Fn X509_EXTENSION_new +allocates and initializes an empty +.Vt X509_EXTENSION +object, representing an ASN.1 +.Vt Extension +structure defined in RFC 5280 section 4.1. +It is a wrapper object around specific extension objects of different +types and stores an extension type identifier and a criticality +flag in addition to the DER-encoded form of the wrapped object. +.Vt X509_EXTENSION +objects can be used for X.509 v3 certificates inside +.Vt X509_CINF +objects and for X.509 v2 certificate revocation lists inside +.Vt X509_CRL_INFO +and +.Vt X509_REVOKED +objects. +.Pp +.Fn X509_EXTENSION_dup +creates a deep copy of +.Fa ex +using +.Xr ASN1_item_dup 3 . +.Pp +.Fn X509_EXTENSION_free +frees +.Fa ex +and all objects it is using. +.Pp +.Fn X509_EXTENSION_create_by_NID +creates an extension of type +.Fa nid +and criticality +.Fa crit +using data +.Fa data . +The created extension is returned and written to +.Pf * Fa ex +reusing or allocating a new extension if necessary, so +.Pf * Fa ex +should either be +.Dv NULL +or a valid +.Vt X509_EXTENSION +structure. +It must not be an uninitialised pointer. +.Pp +.Fn X509_EXTENSION_create_by_OBJ +is identical to +.Fn X509_EXTENSION_create_by_NID +except that it creates an extension using +.Fa obj +instead of a NID. +.Pp +.Fn X509_EXTENSION_set_object +sets the extension type of +.Fa ex +to +.Fa obj . +The +.Fa obj +pointer is duplicated internally so +.Fa obj +should be freed up after use. +.Pp +.Fn X509_EXTENSION_set_critical +sets the criticality of +.Fa ex +to +.Fa crit . +If +.Fa crit +is zero, the extension in non-critical, otherwise it is critical. +.Pp +.Fn X509_EXTENSION_set_data +sets the data in extension +.Fa ex +to +.Fa data . +The +.Fa data +pointer is duplicated internally. +.Pp +.Fn X509_EXTENSION_get_object +returns the extension type of +.Fa ex +as an +.Vt ASN1_OBJECT +pointer. +The returned pointer is an internal value which must not be freed up. +.Pp +.Fn X509_EXTENSION_get_critical +tests whether +.Fa ex +is critical. +.Pp +.Fn X509_EXTENSION_get_data +returns the data of extension +.Fa ex . +The returned pointer is an internal value which must not be freed up. +.Pp +.Fn X509_supported_extension +checks whether +.Fa ex +is of a type supported by the verifier. +The list of supported extension types is hardcoded into the library. +If an extension is critical but unsupported, +the certificate will normally be rejected. +.Pp +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 +.Xr X509_add1_ext_i2d 3 +and +.Xr X509_get_ext_d2i 3 . +.Pp +The +.Fa data +associated with an extension is the extension encoding in an +.Vt ASN1_OCTET_STRING +structure. +.Sh RETURN VALUES +.Fn X509_EXTENSION_new , +.Fn X509_EXTENSION_dup , +.Fn X509_EXTENSION_create_by_NID , +and +.Fn X509_EXTENSION_create_by_OBJ +return an +.Vt X509_EXTENSION +pointer or +.Dv NULL +if an error occurs. +.Pp +.Fn X509_EXTENSION_set_object , +.Fn X509_EXTENSION_set_critical , +and +.Fn X509_EXTENSION_set_data +return 1 for success or 0 for failure. +.Pp +.Fn X509_EXTENSION_get_object +returns an +.Vt ASN1_OBJECT +pointer. +.Pp +.Fn X509_EXTENSION_get_critical +returns 0 for non-critical or 1 for critical. +.Pp +.Fn X509_EXTENSION_get_data +returns an +.Vt ASN1_OCTET_STRING +pointer. +.Pp +.Fn X509_supported_extension +returns 1 if the type of +.Fa ex +is supported by the verifier or 0 otherwise. +.Sh SEE ALSO +.Xr ACCESS_DESCRIPTION_new 3 , +.Xr AUTHORITY_KEYID_new 3 , +.Xr BASIC_CONSTRAINTS_new 3 , +.Xr d2i_X509_EXTENSION 3 , +.Xr DIST_POINT_new 3 , +.Xr ESS_SIGNING_CERT_new 3 , +.Xr EXTENDED_KEY_USAGE_new 3 , +.Xr GENERAL_NAME_new 3 , +.Xr NAME_CONSTRAINTS_new 3 , +.Xr OCSP_CRLID_new 3 , +.Xr OCSP_SERVICELOC_new 3 , +.Xr PKEY_USAGE_PERIOD_new 3 , +.Xr POLICYINFO_new 3 , +.Xr TS_REQ_new 3 , +.Xr X509_check_ca 3 , +.Xr X509_check_host 3 , +.Xr X509_check_issued 3 , +.Xr X509_get_extension_flags 3 , +.Xr X509_REQ_add_extensions 3 , +.Xr X509V3_EXT_get_nid 3 , +.Xr X509V3_EXT_print 3 , +.Xr X509V3_extensions_print 3 , +.Xr X509V3_get_d2i 3 , +.Xr X509v3_get_ext_by_NID 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn X509_EXTENSION_new +and +.Fn X509_EXTENSION_free +first appeared in SSLeay 0.6.2, +.Fn X509_EXTENSION_dup +in SSLeay 0.6.5, and +.Fn X509_EXTENSION_create_by_NID , +.Fn X509_EXTENSION_create_by_OBJ , +.Fn X509_EXTENSION_set_object , +.Fn X509_EXTENSION_set_critical , +.Fn X509_EXTENSION_set_data , +.Fn X509_EXTENSION_get_object , +.Fn X509_EXTENSION_get_critical , +and +.Fn X509_EXTENSION_get_data +in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_supported_extension +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/X509_INFO_new.3 b/static/openbsd/man3/X509_INFO_new.3 new file mode 100644 index 00000000..38bf6fe5 --- /dev/null +++ b/static/openbsd/man3/X509_INFO_new.3 @@ -0,0 +1,72 @@ +.\" $OpenBSD: X509_INFO_new.3,v 1.5 2025/07/16 17:59:10 schwarze Exp $ +.\" Copyright (c) 2019 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 $Mdocdate: July 16 2025 $ +.Dt X509_INFO_NEW 3 +.Os +.Sh NAME +.Nm X509_INFO_new , +.Nm X509_INFO_free +.Nd X.509 certificate wrapper object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_INFO * +.Fn X509_INFO_new void +.Ft void +.Fn X509_INFO_free "X509_INFO *info" +.Sh DESCRIPTION +.Vt X509_INFO +is a reference-counted wrapper object storing a pointer to an X.509 +certificate together with pointers to the associated private key +and to an associated certificate revocation list. +It is for example used internally by +.Xr X509_load_cert_crl_file 3 . +.Pp +.Fn X509_INFO_new +allocates and initializes an empty +.Vt X509_INFO +object and sets its reference count to 1. +.Pp +.Fn X509_INFO_free +decrements the reference count of +.Fa info +by 1. +If the reference count reaches 0, it frees all referenced objects +as well as the storage needed for +.Fa info +itself. +If +.Fa info +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn X509_INFO_new +returns the newly allocated +.Vt X509_INFO +object or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr PEM_X509_INFO_read_bio 3 , +.Xr X509_CRL_new 3 , +.Xr X509_new 3 +.Sh HISTORY +.Fn X509_INFO_new +and +.Fn X509_INFO_free +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/X509_LOOKUP_hash_dir.3 b/static/openbsd/man3/X509_LOOKUP_hash_dir.3 new file mode 100644 index 00000000..74e3aaed --- /dev/null +++ b/static/openbsd/man3/X509_LOOKUP_hash_dir.3 @@ -0,0 +1,189 @@ +.\" $OpenBSD: X509_LOOKUP_hash_dir.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 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. +.\" +.\" The original file was written by Victor B. Wagner +.\" and Claus Assmann. +.\" Copyright (c) 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_LOOKUP_HASH_DIR 3 +.Os +.Sh NAME +.Nm X509_LOOKUP_hash_dir , +.Nm X509_LOOKUP_file , +.Nm X509_LOOKUP_mem +.Nd certificate lookup methods +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft const X509_LOOKUP_METHOD * +.Fn X509_LOOKUP_hash_dir void +.Ft const X509_LOOKUP_METHOD * +.Fn X509_LOOKUP_file void +.Ft const X509_LOOKUP_METHOD * +.Fn X509_LOOKUP_mem void +.Sh DESCRIPTION +.Fn X509_LOOKUP_hash_dir , +.Fn X509_LOOKUP_file , +and +.Fn X509_LOOKUP_mem +return pointers to static certificate lookup method objects +built into the library, for use with +.Vt X509_STORE . +.Pp +Users of the library typically do not need +to retrieve pointers to these method objects manually. +They are automatically used by the +.Xr X509_STORE_load_locations 3 +or +.Xr SSL_CTX_load_verify_locations 3 +functions. +.Ss File Method +The +.Fn X509_LOOKUP_file +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 +The 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 +.Fa X509_LOOKUP_hash_dir +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 used 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 +.Ar hash . Ns Ar N +for a certificate, or +.Ar hash . Ns Sy r Ns Ar N +for a CRL. +The +.Ar hash +is the value returned by the +.Xr X509_NAME_hash 3 +function applied to the subject name for certificates or issuer +name for CRLs. +The hash can also be obtained via the +.Fl hash +option of the +.Xr openssl 1 +.Cm x509 +or +.Cm crl +commands. +.Pp +The +.Ar N +suffix is a sequence number that starts at zero and is incremented +consecutively for each certificate or CRL with the same +.Ar hash +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 the same subject name hash value. +For example, it is possible to have in the store several certificates +with the same subject or several CRLs with the same issuer (and, for +example, a different validity period). +.Pp +When checking for new CRLs, once one CRL for a 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. +.Ss Memory Method +The +.Fn X509_LOOKUP_mem +method supports loading PEM-encoded certificates and revocation lists +that are already stored in memory, using the function +.Xr X509_LOOKUP_add_mem 3 . +This is particularly useful in processes using +.Xr chroot 2 . +.Sh RETURN VALUES +These functions always return a pointer to a static object. +.Sh SEE ALSO +.Xr SSL_CTX_load_verify_locations 3 , +.Xr X509_LOOKUP_new 3 , +.Xr X509_STORE_load_locations 3 , +.Xr X509_STORE_new 3 +.Sh HISTORY +.Fn X509_LOOKUP_hash_dir +and +.Fn X509_LOOKUP_file +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_LOOKUP_mem +first appeared in +.Ox 5.7 . diff --git a/static/openbsd/man3/X509_LOOKUP_new.3 b/static/openbsd/man3/X509_LOOKUP_new.3 new file mode 100644 index 00000000..5fa9f99d --- /dev/null +++ b/static/openbsd/man3/X509_LOOKUP_new.3 @@ -0,0 +1,461 @@ +.\" $OpenBSD: X509_LOOKUP_new.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_LOOKUP_NEW 3 +.Os +.Sh NAME +.Nm X509_LOOKUP_free , +.Nm X509_LOOKUP_ctrl , +.Nm X509_LOOKUP_add_dir , +.Nm X509_LOOKUP_load_file , +.Nm X509_LOOKUP_add_mem , +.Nm X509_get_default_cert_dir , +.Nm X509_get_default_cert_file , +.Nm X509_get_default_cert_dir_env , +.Nm X509_get_default_cert_file_env +.\" X509_get_default_private_dir is intentionally undocumented +.\" because it appears to be unused by any real-world software +.\" and because it doesn't do much in the first place. +.Nd certificate lookup object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft void +.Fn X509_LOOKUP_free "X509_LOOKUP *lookup" +.Ft int +.Fo X509_LOOKUP_ctrl +.Fa "X509_LOOKUP *lookup" +.Fa "int command" +.Fa "const char *source" +.Fa "long type" +.Fa "char **ret" +.Fc +.Ft int +.Fo X509_LOOKUP_add_dir +.Fa "X509_LOOKUP *lookup" +.Fa "const char *source" +.Fa "long type" +.Fc +.Ft int +.Fo X509_LOOKUP_load_file +.Fa "X509_LOOKUP *lookup" +.Fa "const char *source" +.Fa "long type" +.Fc +.Ft int +.Fo X509_LOOKUP_add_mem +.Fa "X509_LOOKUP *lookup" +.Fa "const struct iovec *source" +.Fa "long type" +.Fc +.In openssl/x509.h +.Ft const char * +.Fn X509_get_default_cert_dir void +.Ft const char * +.Fn X509_get_default_cert_file void +.Ft const char * +.Fn X509_get_default_cert_dir_env void +.Ft const char * +.Fn X509_get_default_cert_file_env void +.Sh DESCRIPTION +.Fn X509_LOOKUP_free +is a deprecated function that +releases the memory used by +.Fa lookup . +It is provided for compatibility only. +If +.Fa lookup +is a +.Dv NULL +pointer, no action occurs. +.Pp +The operation of +.Fn X509_LOOKUP_ctrl +depends on the +.Vt X509_LOOKUP_METHOD +used by +.Fa lookup : +.Bl -tag -width 4n +.It Xr X509_LOOKUP_hash_dir 3 +The +.Fa command +is required to be +.Dv X509_L_ADD_DIR +and the +.Fa source +argument is interpreted +as a colon-separated, NUL-terminated list of directory names. +These directories are added to an internal list of directories to search +for certificate files of the given +.Fa type . +.Pp +If +.Fa type +is +.Dv X509_FILETYPE_DEFAULT , +the +.Fa source +argument is ignored and +.Pa /etc/ssl/certs +and a type of +.Dv X509_FILETYPE_PEM +are used instead. +.Pp +.Fn X509_LOOKUP_add_dir +is a macro that calls +.Fn X509_LOOKUP_ctrl +with a +.Fa command +of +.Dv X509_L_ADD_DIR +and +.Fa ret +set to +.Dv NULL . +.Pp +This lookup method is peculiar in so far as calling +.Fn X509_LOOKUP_ctrl +on a lookup object using it does not yet add any certificates to the associated +.Vt X509_STORE +object. +.It Xr X509_LOOKUP_file 3 +The +.Fa command +is required to be +.Dv X509_L_FILE_LOAD +and the +.Fa source +argument is interpreted as a NUL-terminated file name. +If the +.Fa type +is +.Dv X509_FILETYPE_PEM , +the file is read with +.Xr BIO_new_file 3 +and +.Xr PEM_X509_INFO_read_bio 3 +and the certificates and revocation lists found are added to the +.Vt X509_STORE +object associated with +.Fa lookup +using +.Xr X509_STORE_add_cert 3 +and +.Xr X509_STORE_add_crl 3 . +If +.Fa type +is +.Dv X509_FILETYPE_DEFAULT , +the +.Fa source +argument is ignored and +.Pa /etc/ssl/certs.pem +and a type of +.Dv X509_FILETYPE_PEM +are used instead. +If +.Fa type +is +.Dv X509_FILETYPE_ASN1 , +the file is read with +.Xr d2i_X509_bio 3 +and the single certificate is added to the +.Vt X509_STORE +object associated with +.Fa lookup +using +.Xr X509_STORE_add_cert 3 . +.Pp +.Fn X509_LOOKUP_load_file +is a macro calling +.Fn X509_LOOKUP_ctrl +with a +.Fa command +of +.Dv X509_L_FILE_LOAD +and +.Fa ret +set to +.Dv NULL . +.It Xr X509_LOOKUP_mem 3 +The +.Fa command +and +.Fa type +are required to be +.Dv X509_L_MEM +and +.Dv X509_FILETYPE_PEM , +respectively. +The +.Fa source +argument is interpreted as a pointer to an +.Vt iovec +structure defined in +.In sys/uio.h . +The memory area described by that structure is read with +.Xr BIO_new_mem_buf 3 +and +.Xr PEM_X509_INFO_read_bio 3 +and the certificates and revocation lists found are added to the +.Vt X509_STORE +object associated with +.Fa lookup +using +.Xr X509_STORE_add_cert 3 +and +.Xr X509_STORE_add_crl 3 . +.Pp +.Fn X509_LOOKUP_add_mem +is a macro calling +.Fn X509_LOOKUP_ctrl +with a command of +.Dv X509_L_MEM +and +.Fa ret +set to +.Dv NULL . +.El +.Pp +With LibreSSL, +.Fn X509_LOOKUP_ctrl +always ignores the +.Fa ret +argument. +.Pp +If the +.Fa type +is +.Dv X509_LU_X509 , +it searches the configured directories for files having that name, +with a file name extension that is a small, non-negative decimal integer +starting at +.Qq ".0" . +These files are read with +.Xr X509_load_cert_file 3 . +In each directory, the search is ended once a file with the expected name +and extension does not exists. +.Pp +If the +.Fa type +is +.Dv X509_LU_CRL , +the file name extensions are expected to have a prefix of +.Qq "r" , +i.e. they start with +.Qq ".r0" , +and the files are read with +.Xr X509_load_crl_file 3 . +.Pp +In case of success, the first match is returned in the +.Pf * Fa object +provided by the caller, overwriting any previous content. +.Sh RETURN VALUES +.Fn X509_LOOKUP_ctrl +returns 1 for success or 0 for failure. +With library implementations other than LibreSSL, +it might also return \-1 for internal errors. +.Pp +.Fn X509_get_default_cert_dir +returns a pointer to the constant string +.Qq /etc/ssl/certs , +.Fn X509_get_default_cert_file +to +.Qq /etc/ssl/certs.pem , +.Fn X509_get_default_cert_dir_env +to +.Qq SSL_CERT_DIR , +and +.Fn X509_get_default_cert_file_env +to +.Qq SSL_CERT_FILE . +.Sh ENVIRONMENT +For reasons of security and simplicity, +LibreSSL ignores the environment variables +.Ev SSL_CERT_DIR +and +.Ev SSL_CERT_FILE , +but other library implementations may use their contents instead +of the standard locations for trusted certificates, and a few +third-party application programs also inspect these variables +directly and may pass their values to +.Fn X509_LOOKUP_add_dir +and +.Fn X509_LOOKUP_load_file . +.Sh FILES +.Bl -tag -width /etc/ssl/certs.pem -compact +.It Pa /etc/ssl/certs/ +default directory for storing trusted certificates +.It Pa /etc/ssl/certs.pem +default file for storing trusted certificates +.El +.Sh ERRORS +The following diagnostics can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib" +.Xr d2i_X509_bio 3 +failed in +.Fn X509_LOOKUP_ctrl . +.It Dv X509_R_BAD_X509_FILETYPE Qq "bad x509 filetype" +.Fn X509_LOOKUP_ctrl +was called with an invalid +.Fa type . +.It Dv ERR_R_BUF_LIB Qq "BUF lib" +Memory allocation failed. +.It Dv X509_R_INVALID_DIRECTORY Qq "invalid directory" +The +.Fa source +argument of +.Fn X509_LOOKUP_ctrl +with +.Dv X509_L_ADD_DIR +or +.Fn X509_LOOKUP_add_dir +was +.Dv NULL +or an empty string. +.It Dv X509_R_LOADING_CERT_DIR Qq "loading cert dir" +.Fn X509_LOOKUP_ctrl +with +.Dv X509_L_ADD_DIR +or +.Fn X509_LOOKUP_add_dir +was called with +.Dv X509_FILETYPE_DEFAULT +and adding the default directories failed. +This error is added after and in addition to a more specific diagnostic. +.It Dv X509_R_LOADING_DEFAULTS Qq "loading defaults" +.Fn X509_LOOKUP_ctrl +with +.Dv X509_L_FILE_LOAD +or +.Fn X509_LOOKUP_load_file +was called with +.Dv X509_FILETYPE_DEFAULT +and adding the certificates and revocation lists failed. +This error is added after and in addition to a more specific diagnostic. +.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" +Memory allocation failed. +.It Dv ERR_R_PEM_LIB Qq "PEM lib" +.Xr PEM_X509_INFO_read_bio 3 , +.Xr PEM_read_bio_X509_AUX 3 , +or +.Xr PEM_read_bio_X509_CRL 3 +failed in +.Fn X509_LOOKUP_ctrl . +.It Dv ERR_R_SYS_LIB Qq "system lib" +.Xr BIO_new 3 , +.Xr BIO_new_file 3 , +or +.Xr BIO_read_filename 3 +failed in +.Fn X509_LOOKUP_ctrl . +.It Dv X509_R_WRONG_LOOKUP_TYPE Qq "wrong lookup type" +.Xr X509_STORE_CTX_get_by_subject 3 +was called with an invalid +.Fa type . +.El +.Pp +Passing an invalid +.Fa command +to +.Fn X509_LOOKUP_ctrl +causes failure but provides no diagnostics. +.Sh SEE ALSO +.Xr d2i_X509_bio 3 , +.Xr PEM_read_bio_X509_AUX 3 , +.Xr PEM_X509_INFO_read_bio 3 , +.Xr X509_load_cert_file 3 , +.Xr X509_LOOKUP_hash_dir 3 , +.Xr X509_NAME_hash 3 , +.Xr X509_NAME_new 3 , +.Xr X509_new 3 , +.Xr X509_OBJECT_get_type 3 , +.Xr X509_STORE_add_cert 3 , +.Xr X509_STORE_get_by_subject 3 +.Sh HISTORY +.Fn X509_get_default_cert_dir , +.Fn X509_get_default_cert_file , +.Fn X509_get_default_cert_dir_env , +and +.Fn X509_get_default_cert_file_env +first appeared in SSLeay 0.4.1 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_LOOKUP_add_mem +first appeared in +.Ox 5.7 . +.Pp +The other functions first appeared in SSLeay 0.8.0 +and have been available since +.Ox 2.4 . +.Sh BUGS +If the +.Fa type +is +.Dv X509_FILETYPE_DEFAULT +or +.Dv X509_FILETYPE_PEM , +.Fn X509_LOOKUP_ctrl +with +.Dv X509_L_FILE_LOAD +and +.Fn X509_LOOKUP_load_file +silently ignore failure of +.Xr X509_STORE_add_cert 3 +and +.Xr X509_STORE_add_crl 3 +and indicate success anyway. +.Pp +Handling of a +.Dv NULL +.Fa source +is inconsistent for +.Fn X509_LOOKUP_ctrl +with +.Dv X509_L_FILE_LOAD +and for +.Fn X509_LOOKUP_load_file . +With +.Dv X509_FILETYPE_PEM , +it causes failure, but with +.Dv X509_FILETYPE_ASN1 , +no action occurs and success is indicated. +.Pp +When called on a +.Fa lookup +object using +.Xr X509_LOOKUP_mem 3 , +.Fn X509_LOOKUP_ctrl +raises +.Dv ERR_R_PEM_LIB +when called with an invalid +.Fa command +or +.Fa type , +when +.Xr BIO_new_mem_buf 3 +fails, when +.Fa source +contains zero objects, or when +.Xr X509_STORE_add_cert 3 +fails on the first object encountered, which is all inconsistent +with the behaviour of the other lookup methods. diff --git a/static/openbsd/man3/X509_NAME_ENTRY_get_object.3 b/static/openbsd/man3/X509_NAME_ENTRY_get_object.3 new file mode 100644 index 00000000..4cf40c78 --- /dev/null +++ b/static/openbsd/man3/X509_NAME_ENTRY_get_object.3 @@ -0,0 +1,384 @@ +.\" $OpenBSD: X509_NAME_ENTRY_get_object.3,v 1.18 2025/12/21 09:36:35 tb Exp $ +.\" full merge up to: OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400 +.\" selective merge up to: OpenSSL ca34e08d Dec 12 07:38:07 2018 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016, 2018, 2019, 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2005, 2006, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: December 21 2025 $ +.Dt X509_NAME_ENTRY_GET_OBJECT 3 +.Os +.Sh NAME +.Nm X509_NAME_ENTRY_new , +.Nm X509_NAME_ENTRY_free , +.Nm X509_NAME_ENTRY_get_object , +.Nm X509_NAME_ENTRY_get_data , +.Nm X509_NAME_ENTRY_set , +.Nm X509_NAME_ENTRY_set_object , +.Nm X509_NAME_ENTRY_set_data , +.Nm X509_NAME_ENTRY_create_by_txt , +.Nm X509_NAME_ENTRY_create_by_NID , +.Nm X509_NAME_ENTRY_create_by_OBJ +.\" In the following line, "X.501" is not a typo. +.\" This object defined in X.501, not in X.509. +.Nd X.501 relative distinguished name +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_NAME_ENTRY * +.Fn X509_NAME_ENTRY_new void +.Ft void +.Fo X509_NAME_ENTRY_free +.Fa "X509_NAME_ENTRY* ne" +.Fc +.Ft ASN1_OBJECT * +.Fo X509_NAME_ENTRY_get_object +.Fa "const X509_NAME_ENTRY *ne" +.Fc +.Ft ASN1_STRING * +.Fo X509_NAME_ENTRY_get_data +.Fa "const X509_NAME_ENTRY *ne" +.Fc +.Ft int +.Fo X509_NAME_ENTRY_set +.Fa "const X509_NAME_ENTRY *ne" +.Fc +.Ft int +.Fo X509_NAME_ENTRY_set_object +.Fa "X509_NAME_ENTRY *ne" +.Fa "const ASN1_OBJECT *obj" +.Fc +.Ft int +.Fo X509_NAME_ENTRY_set_data +.Fa "X509_NAME_ENTRY *ne" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_ENTRY_create_by_txt +.Fa "X509_NAME_ENTRY **ne" +.Fa "const char *field" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_ENTRY_create_by_NID +.Fa "X509_NAME_ENTRY **ne" +.Fa "int nid" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_ENTRY_create_by_OBJ +.Fa "X509_NAME_ENTRY **ne" +.Fa "const ASN1_OBJECT *obj" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fc +.Sh DESCRIPTION +An X.501 +.Vt RelativeDistinguishedName +is an ordered set of field type and value pairs. +It is the building block for constructing X.501 +.Vt Name +objects. +The +.Vt X509_NAME_ENTRY +object stores one such pair, containing one field type and one value. +.Pp +.Vt X509_NAME_ENTRY +objects are intended for use by the +.Vt X509_NAME +objects documented in +.Xr X509_NAME_new 3 . +Since part of the information about how several +.Vt X509_NAME_ENTRY +objects combine to form an X.501 +.Vt Name +is stored in the individual +.Vt X509_NAME_ENTRY +objects rather than in the +.Vt X509_NAME +object, any given +.Vt X509_NAME_ENTRY +object can only be used by one +.Vt X509_NAME +object at a time. +.Pp +.Fn X509_NAME_ENTRY_new +allocates and initializes an empty +.Vt X509_NAME_ENTRY +object, representing an ASN.1 +.Vt RelativeDistinguishedName +structure defined in RFC 5280 section 4.1.2.4, but containing not more +than one type-value-pair. +.Pp +.Fn X509_NAME_ENTRY_free +frees +.Fa ne +and the type and value contained in it. +.Pp +.Fn X509_NAME_ENTRY_get_object +retrieves the field type of +.Fa ne +in an +.Vt ASN1_OBJECT +structure. +.Fn X509_NAME_ENTRY_get_data +retrieves the field value of +.Fa ne +in an +.Vt ASN1_STRING +structure. +These two functions can be used to examine an +.Vt X509_NAME_ENTRY +object as returned by +.Xr X509_NAME_get_entry 3 . +.Pp +.Fn X509_NAME_ENTRY_set +retrieves the index of the X.501 +.Vt RelativeDistinguishedName Pq RDN +that +.Fa ne +is part of in the X.501 +.Vt Name +object using it. +The first RDN has index 0. +If an RDN consists of more than one +.Vt X509_NAME_ENTRY +object, they all share the same index. +In practice, RDNs containing more than one type-value-pair are rarely +used, so if an +.Va X509_NAME *name +object uses +.Fa ne , +then +.Fn X509_NAME_ENTRY_set ne +usually agrees with +.Fn sk_X509_NAME_ENTRY_find name->entries ne , +but when multi-pair RDNs are used, it may be smaller. +.Pp +.Fn X509_NAME_ENTRY_set_object +sets the field type of +.Fa ne +to +.Fa obj . +.Pp +.Fn X509_NAME_ENTRY_set_data +sets the field value of +.Fa ne +to the given string +.Fa type +and the value determined by +.Fa bytes +and +.Fa len . +If the +.Fa type +argument is positive and includes the +.Fa MBSTRING_FLAG +bit, +.Xr ASN1_STRING_set_by_NID 3 +is used for setting the value, passing the +.Fa type +as the +.Fa inform +argument and using the +.Fa nid +corresponding to +.Fa ne . +.Pp +.Fn X509_NAME_ENTRY_create_by_txt , +.Fn X509_NAME_ENTRY_create_by_NID , +and +.Fn X509_NAME_ENTRY_create_by_OBJ +create and return an +.Vt X509_NAME_ENTRY +structure. +.Pp +Except for +.Fn X509_NAME_ENTRY_get_object +and +.Fn X509_NAME_ENTRY_get_data , +these functions are rarely used because +.Vt X509_NAME_ENTRY +structures are almost always part of +.Vt X509_NAME +structures and the functions described in +.Xr X509_NAME_add_entry_by_txt 3 +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 described in +.Xr X509_NAME_add_entry_by_txt 3 . +So for example +.Fa type +can be set to +.Dv MBSTRING_ASC , +but in the case of +.Fn X509_NAME_ENTRY_set_data +the field type must be set first so the relevant field information +can be looked up internally. +.Sh RETURN VALUES +The +.Fn X509_NAME_ENTRY_new +function returns a valid +.Vt X509_NAME_ENTRY +structure if successful; otherwise +.Dv NULL +is returned and an error code can be retrieved with +.Xr ERR_get_error 3 . +.Pp +.Fn X509_NAME_ENTRY_get_object +returns a valid +.Vt ASN1_OBJECT +structure if it is set or +.Dv NULL +if an error occurred. +.Pp +.Fn X509_NAME_ENTRY_get_data +returns a valid +.Vt ASN1_STRING +structure if it is set or +.Dv NULL +if an error occurred. +.Pp +.Fn X509_NAME_ENTRY_set +returns the zero-based index of the RDN +.Fa ne +is used in, or 0 if +.Fa ne +is not yet used by any +.Vt X509_NAME +object. +.Pp +The +.Fn X509_NAME_ENTRY_set_object +function returns 1 if successful; +otherwise 0 is returned and an error code can be retrieved with +.Xr ERR_get_error 3 . +.Pp +.Fn X509_NAME_ENTRY_set_data +returns 1 on success or 0 on error. +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Pp +.Fn X509_NAME_ENTRY_create_by_txt , +.Fn X509_NAME_ENTRY_create_by_NID , +and +.Fn X509_NAME_ENTRY_create_by_OBJ +return a valid +.Vt X509_NAME_ENTRY +structure on success or +.Dv NULL +if an error occurred. +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr OBJ_nid2obj 3 , +.Xr X509_NAME_add_entry 3 , +.Xr X509_NAME_get_entry 3 , +.Xr X509_NAME_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Pp +ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: Information +Technology Open Systems Interconnection The Directory: Models, +section 9.3: Relative distinguished name +.Sh HISTORY +.Fn X509_NAME_ENTRY_new +and +.Fn X509_NAME_ENTRY_free +first appeared in SSLeay 0.5.1. +.Fn X509_NAME_ENTRY_get_object , +.Fn X509_NAME_ENTRY_get_data , +.Fn X509_NAME_ENTRY_set_object , +.Fn X509_NAME_ENTRY_set_data , +.Fn X509_NAME_ENTRY_create_by_NID , +and +.Fn X509_NAME_ENTRY_create_by_OBJ +first appeared in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_NAME_ENTRY_create_by_txt +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn X509_NAME_ENTRY_set +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . +.Sh CAVEATS +Despite its name, +.Fn X509_NAME_ENTRY_set +does not set anything. +Something like +.Dq X509_NAME_ENTRY_get_set +would have been a better name. diff --git a/static/openbsd/man3/X509_NAME_add_entry_by_txt.3 b/static/openbsd/man3/X509_NAME_add_entry_by_txt.3 new file mode 100644 index 00000000..e2b78150 --- /dev/null +++ b/static/openbsd/man3/X509_NAME_add_entry_by_txt.3 @@ -0,0 +1,274 @@ +.\" $OpenBSD: X509_NAME_add_entry_by_txt.3,v 1.18 2025/12/21 09:36:35 tb Exp $ +.\" OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2005, 2006, 2013, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: December 21 2025 $ +.Dt X509_NAME_ADD_ENTRY_BY_TXT 3 +.Os +.Sh NAME +.Nm X509_NAME_add_entry_by_txt , +.Nm X509_NAME_add_entry_by_OBJ , +.Nm X509_NAME_add_entry_by_NID , +.Nm X509_NAME_add_entry , +.Nm X509_NAME_delete_entry +.Nd X509_NAME modification functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_NAME_add_entry_by_txt +.Fa "X509_NAME *name" +.Fa "const char *field" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fa "int loc" +.Fa "int set" +.Fc +.Ft int +.Fo X509_NAME_add_entry_by_OBJ +.Fa "X509_NAME *name" +.Fa "const ASN1_OBJECT *obj" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fa "int loc" +.Fa "int set" +.Fc +.Ft int +.Fo X509_NAME_add_entry_by_NID +.Fa "X509_NAME *name" +.Fa "int nid" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fa "int loc" +.Fa "int set" +.Fc +.Ft int +.Fo X509_NAME_add_entry +.Fa "X509_NAME *name" +.Fa "const X509_NAME_ENTRY *ne" +.Fa "int loc" +.Fa "int set" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_delete_entry +.Fa "X509_NAME *name" +.Fa "int loc" +.Fc +.Sh DESCRIPTION +.Fn X509_NAME_add_entry_by_txt , +.Fn X509_NAME_add_entry_by_OBJ , +and +.Fn X509_NAME_add_entry_by_NID +add a field whose name is defined by a string +.Fa field , +an object +.Fa obj +or a NID +.Fa nid , +respectively. +The field value to be added is in +.Fa bytes +of length +.Fa len . +If +.Fa len +is -1 then the field length is calculated internally using +.Fn strlen bytes . +.Pp +The type of field is determined by +.Fa type +which can either be a definition of the type of +.Fa bytes +(such as +.Dv MBSTRING_ASC ) +or a standard ASN.1 type (such as +.Dv V_ASN1_IA5STRING ) . +The new entry is added to a position determined by +.Fa loc +and +.Fa set . +.Pp +.Fn X509_NAME_add_entry +adds a copy of an +.Vt X509_NAME_ENTRY +structure +.Fa ne +to +.Fa name . +The new entry is added to a position determined by +.Fa loc +and +.Fa set . +Since a copy of +.Fa ne +is added, +.Fa ne +must be freed up after the call. +.Pp +.Fn X509_NAME_delete_entry +deletes an entry from +.Fa name +at position +.Fa loc . +The deleted entry is returned and must be freed up. +.Pp +The use of string types such as +.Dv MBSTRING_ASC +or +.Dv MBSTRING_UTF8 +is strongly recommended for the +.Fa type +parameter. +This allows the internal code to correctly determine the type of the +field and to apply length checks according to the relevant standards. +.Pp +If instead an ASN.1 type is used, no checks are performed and the supplied +data in +.Fa bytes +is used directly. +.Pp +In +.Fn X509_NAME_add_entry_by_txt +the +.Fa field +string represents the field name using +.Fn OBJ_txt2obj field 0 . +.Pp +The +.Fa loc +and +.Fa set +parameters determine where a new entry should be added. +For almost all applications, +.Fa loc +can be set to -1 and +.Fa set +to 0. +This adds a new entry to the end of +.Fa name +as a single valued +.Vt RelativeDistinguishedName +(RDN). +.Pp +.Fa loc +actually determines the index where the new entry is inserted: +if it is -1 it is appended. +.Pp +.Fa set +determines how the new type is added. +If it is zero, a new RDN is created. +.Pp +If +.Fa set +is -1 or 1, it is added to the previous or next RDN structure +respectively. +This will then be a multivalued RDN: since multivalue RDNs are very +seldom used, +.Fa set +is almost always set to zero. +.Sh RETURN VALUES +.Fn X509_NAME_add_entry_by_txt , +.Fn X509_NAME_add_entry_by_OBJ , +.Fn X509_NAME_add_entry_by_NID , +and +.Fn X509_NAME_add_entry +return 1 for success or 0 if an error occurred. +.Pp +.Fn X509_NAME_delete_entry +returns either the deleted +.Vt X509_NAME_ENTRY +structure or +.Dv NULL +if an error occurred. +.Pp +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Sh EXAMPLES +Create an +.Vt X509_NAME +structure: +.Bd -literal -offset indent +C=UK, O=Disorganized Organization, CN=Joe Bloggs + +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 */ +.Ed +.Sh SEE ALSO +.Xr d2i_X509_NAME 3 , +.Xr X509_NAME_ENTRY_get_object 3 , +.Xr X509_NAME_get_index_by_NID 3 , +.Xr X509_NAME_new 3 +.Sh HISTORY +.Fn X509_NAME_add_entry +and +.Fn X509_NAME_delete_entry +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_NAME_add_entry_by_txt , +.Fn X509_NAME_add_entry_by_OBJ , +and +.Fn X509_NAME_add_entry_by_NID +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/X509_NAME_get_index_by_NID.3 b/static/openbsd/man3/X509_NAME_get_index_by_NID.3 new file mode 100644 index 00000000..57dd4881 --- /dev/null +++ b/static/openbsd/man3/X509_NAME_get_index_by_NID.3 @@ -0,0 +1,266 @@ +.\" $OpenBSD: X509_NAME_get_index_by_NID.3,v 1.17 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2006, 2014, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_NAME_GET_INDEX_BY_NID 3 +.Os +.Sh NAME +.Nm X509_NAME_get_index_by_NID , +.Nm X509_NAME_get_index_by_OBJ , +.Nm X509_NAME_entry_count , +.Nm X509_NAME_get_entry , +.Nm X509_NAME_get_text_by_NID , +.Nm X509_NAME_get_text_by_OBJ +.Nd X509_NAME lookup and enumeration functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_NAME_get_index_by_NID +.Fa "const X509_NAME *name" +.Fa "int nid" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509_NAME_get_index_by_OBJ +.Fa "const X509_NAME *name" +.Fa "const ASN1_OBJECT *obj" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509_NAME_entry_count +.Fa "const X509_NAME *name" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_get_entry +.Fa "const X509_NAME *name" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_NAME_get_text_by_NID +.Fa "X509_NAME *name" +.Fa "int nid" +.Fa "char *buf" +.Fa "int len" +.Fc +.Ft int +.Fo X509_NAME_get_text_by_OBJ +.Fa "X509_NAME *name" +.Fa "const ASN1_OBJECT *obj" +.Fa "char *buf" +.Fa "int len" +.Fc +.Sh DESCRIPTION +These functions allow an +.Vt X509_NAME +structure to be examined. +The +.Vt X509_NAME +structure is the same as the ASN.1 +.Vt Name +type defined in RFC 2459 (and elsewhere) and used, for example, +in certificate subject and issuer names. +.Pp +.Fn X509_NAME_get_index_by_NID +and +.Fn X509_NAME_get_index_by_OBJ +retrieve the next index matching +.Fa nid +or +.Fa obj +after +.Fa lastpos . +.Fa lastpos +should initially be set to -1. +.Pp +.Fn X509_NAME_get_entry +retrieves the +.Vt X509_NAME_ENTRY +from +.Fa name +corresponding to index +.Fa loc . +Acceptable values for +.Fa loc +run from 0 to +.Fn X509_NAME_entry_count name +- 1. +.Pp +.Fn X509_NAME_get_text_by_NID +and +.Fn X509_NAME_get_text_by_OBJ +retrieve the bytes encoded as UTF-8 from the first entry in +.Fa name +which matches +.Fa nid +or +.Fa obj . +If +.Fa buf +is +.Dv NULL , +nothing is written, but the return value is calculated as usual. +If +.Fa buf +is not +.Dv NULL , +no more than +.Fa len +bytes will be written and the text written to +.Fa buf +will be NUL terminated. +.Pp +If +.Fa len +is not large enough to hold the NUL byte terminated UTF-8 encoding of +the text, or if the UTF-8 encoding of the text would contains a NUL +byte, no data will be written and the call will return failure. +.Pp +All relevant +.Dv NID_* +and +.Dv OBJ_* +codes can be found in the +.In openssl/objects.h +header file. +.Pp +Applications which could pass invalid NIDs to +.Fn X509_NAME_get_index_by_NID +should check for the return value of -2. +Alternatively the NID validity can be determined first by checking that +.Fn OBJ_nid2obj nid +is not +.Dv NULL . +.Sh RETURN VALUES +.Fn X509_NAME_get_index_by_NID +returns the index of the next matching entry, -1 if not found, or -2 if the +.Fa nid +does not correspond to a valid OID. +.Pp +.Fn X509_NAME_get_index_by_OBJ +returns the index of the next matching entry or -1 if not found. +.Pp +.Fn X509_NAME_entry_count +returns the total number of entries in +.Fa name . +.Pp +.Fn X509_NAME_get_entry +returns an internal pointer which must not be freed by the caller or +.Dv NULL +if the index is invalid. +.Pp +.Fn X509_NAME_get_text_by_NID +and +.Fn X509_NAME_get_text_by_OBJ +return the length of the output UTF-8 string written, not counting the +terminating NUL, or -1 in the case of an error or no match being found. +.Pp +In some cases of failure of +.Fn X509_NAME_get_index_by_NID +and +.Fn X509_NAME_get_text_by_NID , +the reason can be determined with +.Xr ERR_get_error 3 . +.Sh EXAMPLES +Process all entries: +.Bd -literal +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 */ +} +.Ed +.Pp +Process all commonName entries: +.Bd -literal +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 */ +} +.Ed +.Sh SEE ALSO +.Xr d2i_X509_NAME 3 , +.Xr X509_NAME_ENTRY_get_object 3 , +.Xr X509_NAME_new 3 +.Sh HISTORY +These functions first appeared in SSLeay 0.8.0 +and have been available since +.Ox 2.4 . +.Sh CAVEATS +.Fn X509_NAME_get_text_by_NID +and +.Fn X509_NAME_get_text_by_OBJ +are legacy functions which 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 +.Vt BMPString +or a +.Vt UTF8String . +.Pp +For a more general solution, +.Fn X509_NAME_get_index_by_NID +or +.Fn X509_NAME_get_index_by_OBJ +should be used, followed by +.Fn X509_NAME_get_entry +on any matching indices and then the various +.Vt X509_NAME_ENTRY +utility functions on the result. diff --git a/static/openbsd/man3/X509_NAME_hash.3 b/static/openbsd/man3/X509_NAME_hash.3 new file mode 100644 index 00000000..2e03f41e --- /dev/null +++ b/static/openbsd/man3/X509_NAME_hash.3 @@ -0,0 +1,98 @@ +.\" $OpenBSD: X509_NAME_hash.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2017, 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_NAME_HASH 3 +.Os +.Sh NAME +.Nm X509_NAME_hash , +.Nm X509_issuer_name_hash , +.Nm X509_subject_name_hash , +.\" X509_issuer_and_serial_hash() is intentionally undocumented +.\" because it uses MD5 only and is unused in real-world code. +.Nm X509_NAME_hash_old , +.Nm X509_issuer_name_hash_old , +.Nm X509_subject_name_hash_old +.\" In the following line, "X.501" and "Name" are not typos. +.\" The "Name" type is defined in X.501, not in X.509. +.\" The type is called "Name" with capital "N", not "name". +.Nd calculate SHA-1 or MD5 hashes of X.501 Name objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft unsigned long +.Fn X509_NAME_hash "X509_NAME *name" +.Ft unsigned long +.Fn X509_issuer_name_hash "X509 *x" +.Ft unsigned long +.Fn X509_subject_name_hash "X509 *x" +.Ft unsigned long +.Fn X509_NAME_hash_old "X509_NAME *name" +.Ft unsigned long +.Fn X509_issuer_name_hash_old "X509 *x" +.Ft unsigned long +.Fn X509_subject_name_hash_old "X509 *x" +.Sh DESCRIPTION +.Fn X509_NAME_hash +calculates an +.Xr SHA1 3 +hash of the DER-encoded form of +.Fa name . +It is for example used by +.Xr X509_LOOKUP_hash_dir 3 +to locate certificate files in the file system. +.Pp +.Fn X509_issuer_name_hash +and +.Fn X509_subject_name_hash +are wrappers to calculate this hash of the issuer or subject name of +.Fa x , +respectively. +.Pp +.Fn X509_NAME_hash_old , +.Fn X509_issuer_name_hash_old , +and +.Fn X509_subject_name_hash_old +are variants that use MD5 instead of SHA-1. +.Sh RETURN VALUES +These functions return the hash value or 0 if an error occurs. +.Sh SEE ALSO +.Xr i2d_X509_NAME 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_LOOKUP_new 3 , +.Xr X509_NAME_digest 3 , +.Xr X509_NAME_new 3 +.Sh HISTORY +.Fn X509_subject_name_hash +first appeared in SSLeay 0.4.0, +.Fn X509_issuer_name_hash +in SSLeay 0.5.1, and +.Fn X509_NAME_hash +in SSLeay 0.8.0. +They were switched to hashing the DER representation of the name +rather than an ASCII rendering in SSLeay 0.9.0 and have all been +available since +.Ox 2.4 . +.Pp +They were switched to using SHA-1 instead of MD5 in OpenSSL 1.0.0 and in +.Ox 4.9 . +.Pp +.Fn X509_NAME_hash_old , +.Fn X509_issuer_name_hash_old , +and +.Fn X509_subject_name_hash_old +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/X509_NAME_new.3 b/static/openbsd/man3/X509_NAME_new.3 new file mode 100644 index 00000000..279df816 --- /dev/null +++ b/static/openbsd/man3/X509_NAME_new.3 @@ -0,0 +1,104 @@ +.\" $OpenBSD: X509_NAME_new.3,v 1.10 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt X509_NAME_NEW 3 +.Os +.Sh NAME +.Nm X509_NAME_new , +.Nm X509_NAME_free +.\" In the following line, "X.501" and "Name" are not typos. +.\" The "Name" type is defined in X.501, not in X.509. +.\" The type in called "Name" with capital "N", not "name". +.Nd X.501 Name object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_NAME * +.Fn X509_NAME_new void +.Ft void +.Fn X509_NAME_free "X509_NAME *name" +.Sh DESCRIPTION +An X.501 +.Vt Name +is an ordered sequence of relative distinguished names. +A relative distinguished name is a set of key-value pairs; see +.Xr X509_NAME_ENTRY_new 3 +for details. +.Pp +Various X.509 structures contain X.501 +.Vt Name +substructures. +They are for example used for the issuers of certificates and +certificate revocation lists and for the subjects of certificates +and certificate requests. +.Pp +.Fn X509_NAME_new +allocates and initializes an empty +.Vt X509_NAME +object, representing an ASN.1 +.Vt Name +structure defined in RFC 5280 section 4.1.2.4. +Data can be added to such objects with the functions described in +.Xr X509_NAME_add_entry_by_txt 3 , +and they can be inspected with the functions described in +.Xr X509_NAME_get_index_by_NID 3 . +.Pp +.Fn X509_NAME_free +frees +.Fa name +and all the +.Vt X509_NAME_ENTRY +objects contained in it. +If +.Fa name +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn X509_NAME_new +returns a new +.Vt X509_NAME +object or +.Dv NULL +if an error occurred. +.Sh SEE ALSO +.Xr d2i_X509_NAME 3 , +.Xr GENERAL_NAME_new 3 , +.Xr NAME_CONSTRAINTS_new 3 , +.Xr SSL_load_client_CA_file 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_NAME_add_entry_by_txt 3 , +.Xr X509_NAME_cmp 3 , +.Xr X509_NAME_digest 3 , +.Xr X509_NAME_ENTRY_new 3 , +.Xr X509_NAME_get_index_by_NID 3 , +.Xr X509_NAME_hash 3 , +.Xr X509_NAME_print_ex 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Pp +ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: +Information Technology \(en Open Systems Interconnection \(en +The Directory: Models, section 9: Names +.Sh HISTORY +.Fn X509_NAME_new +and +.Fn X509_NAME_free +appeared in SSLeay 0.4 or earlier and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/X509_NAME_print_ex.3 b/static/openbsd/man3/X509_NAME_print_ex.3 new file mode 100644 index 00000000..845428b3 --- /dev/null +++ b/static/openbsd/man3/X509_NAME_print_ex.3 @@ -0,0 +1,261 @@ +.\" $OpenBSD: X509_NAME_print_ex.3,v 1.18 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400 +.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2004, 2007, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_NAME_PRINT_EX 3 +.Os +.Sh NAME +.Nm X509_NAME_print_ex , +.Nm X509_NAME_print_ex_fp , +.Nm X509_NAME_oneline +.Nd X509_NAME printing routines +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_NAME_print_ex +.Fa "BIO *out" +.Fa "const X509_NAME *nm" +.Fa "int indent" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo X509_NAME_print_ex_fp +.Fa "FILE *fp" +.Fa "const X509_NAME *nm" +.Fa "int indent" +.Fa "unsigned long flags" +.Fc +.Ft char * +.Fo X509_NAME_oneline +.Fa "const X509_NAME *a" +.Fa "char *buf" +.Fa "int size" +.Fc +.Sh DESCRIPTION +.Fn X509_NAME_print_ex +prints a human readable version of +.Fa nm +to +.Vt BIO +.Fa out . +Each line (for multiline formats) is indented by +.Fa indent +spaces. +The output format can be extensively customised by use of the +.Fa flags +parameter. +.Pp +.Fn X509_NAME_print_ex_fp +is identical to +.Fn X509_NAME_print_ex +except the output is written to the +.Vt FILE +pointer +.Fa fp . +.Pp +.Fn X509_NAME_oneline +prints an ASCII version of +.Fa a +to +.Fa buf . +If +.Fa buf +is +.Dv NULL , +then a buffer is dynamically allocated and returned, and +.Fa size +is ignored. +Otherwise, at most +.Fa size +bytes will be written, including the ending NUL, and +.Fa buf +is returned. +.Pp +.Fn X509_NAME_oneline +is a legacy function which produces a non-standard output form. +It doesn't handle multi-character fields and has various quirks +and inconsistencies. +Its use is strongly discouraged in new applications. +.Pp +Although there are a large number of possible flags, for most purposes +.Dv XN_FLAG_ONELINE , +.Dv XN_FLAG_MULTILINE , +or +.Dv XN_FLAG_RFC2253 +will suffice. +As noted on the +.Xr ASN1_STRING_print_ex 3 +manual page, for UTF-8 terminals the +.Dv ASN1_STRFLGS_ESC_MSB +should be unset: so for example +.Dv XN_FLAG_ONELINE No & Pf ~ Dv ASN1_STRFLGS_ESC_MSB +would be used. +.Pp +The complete set of the flags supported by +.Dv X509_NAME_print_ex +is listed below. +.Pp +Several options can be OR'ed together. +.Pp +The options +.Dv XN_FLAG_SEP_COMMA_PLUS , +.Dv XN_FLAG_SEP_CPLUS_SPC , +.Dv XN_FLAG_SEP_SPLUS_SPC , +and +.Dv XN_FLAG_SEP_MULTILINE +determine the field separators to use. +Two distinct separators are used between distinct +.Vt 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 +.Dv XN_FLAG_SEP_COMMA_PLUS +uses comma and plus as separators. +.Dv XN_FLAG_SEP_CPLUS_SPC +uses comma and plus with spaces: +this is more readable that plain comma and plus. +.Dv XN_FLAG_SEP_SPLUS_SPC +uses spaced semicolon and plus. +.Dv XN_FLAG_SEP_MULTILINE +uses spaced newline and plus respectively. +.Dv XN_FLAG_SEP_MASK +contains the bits used to represent these four options. +.Pp +If +.Dv XN_FLAG_DN_REV +is set, the whole DN is printed in reversed order. +.Pp +The fields +.Dv XN_FLAG_FN_SN , +.Dv XN_FLAG_FN_LN , +.Dv XN_FLAG_FN_OID , +and +.Dv XN_FLAG_FN_NONE +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. +.Dv XN_FLAG_FN_MASK +contains the bits used to represent these four options. +.Pp +If +.Dv XN_FLAG_SPC_EQ +is set, then spaces will be placed around the +.Ql = +character separating field names and values. +.Pp +If +.Dv XN_FLAG_DUMP_UNKNOWN_FIELDS +is set, then the encoding of unknown fields is printed instead of the +values. +.Pp +If +.Dv XN_FLAG_FN_ALIGN +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 +.Xr ASN1_STRING_print_ex 3 +can be used to control how each field value is displayed. +.Pp +In addition a number of options can be set for commonly used formats. +.Pp +.Dv XN_FLAG_RFC2253 +sets options which produce an output compatible with RFC 2253. +It is equivalent to +.Dv ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | +.Dv XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS . +.Pp +.Dv XN_FLAG_ONELINE +is a more readable one line format which is the same as: +.Dv ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | +.Dv XN_FLAG_SPC_EQ | XN_FLAG_FN_SN . +.Pp +.Dv XN_FLAG_MULTILINE +is a multiline format which is the same as: +.Dv ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | +.Dv XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN . +.Pp +.Dv XN_FLAG_COMPAT +uses the traditional non-standard SSLeay format. +.Sh RETURN VALUES +.Fn X509_NAME_print_ex +and +.Fn X509_NAME_print_ex_fp +return 1 on success or 0 on error if +.Dv XN_FLAG_COMPAT +is set in +.Fa flags . +Otherwise, they return the number of printed bytes including the +indentation or \-1 on error. +.Pp +.Fn X509_NAME_oneline +returns a valid string on success or +.Dv NULL +on error. +.Sh SEE ALSO +.Xr ASN1_STRING_print_ex 3 , +.Xr d2i_X509_NAME 3 , +.Xr X509_NAME_get_index_by_NID 3 , +.Xr X509_NAME_new 3 +.Sh HISTORY +.Fn X509_NAME_oneline +first appeared in SSLeay 0.5.1 and has been available since +.Ox 2.4 . +.Pp +.Fn X509_NAME_print_ex +and +.Fn X509_NAME_print_ex_fp +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . diff --git a/static/openbsd/man3/X509_OBJECT_get0_X509.3 b/static/openbsd/man3/X509_OBJECT_get0_X509.3 new file mode 100644 index 00000000..1b0de392 --- /dev/null +++ b/static/openbsd/man3/X509_OBJECT_get0_X509.3 @@ -0,0 +1,253 @@ +.\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.17 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2018, 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_OBJECT_GET0_X509 3 +.Os +.Sh NAME +.Nm X509_OBJECT_get_type , +.Nm X509_OBJECT_new , +.Nm X509_OBJECT_free , +.Nm X509_OBJECT_get0_X509 , +.Nm X509_OBJECT_get0_X509_CRL , +.Nm X509_OBJECT_idx_by_subject , +.Nm X509_OBJECT_retrieve_by_subject , +.Nm X509_OBJECT_retrieve_match +.Nd certificate, CRL, private key, and string wrapper for certificate stores +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft X509_LOOKUP_TYPE +.Fo X509_OBJECT_get_type +.Fa "const X509_OBJECT *obj" +.Fc +.Ft X509_OBJECT * +.Fo X509_OBJECT_new +.Fa void +.Fc +.Ft void +.Fo X509_OBJECT_free +.Fa "X509_OBJECT *obj" +.Fc +.Ft X509 * +.Fo X509_OBJECT_get0_X509 +.Fa "const X509_OBJECT *obj" +.Fc +.Ft X509_CRL * +.Fo X509_OBJECT_get0_X509_CRL +.Fa "X509_OBJECT *obj" +.Fc +.Ft int +.Fo X509_OBJECT_idx_by_subject +.Fa "STACK_OF(X509_OBJECT) *stack" +.Fa "X509_LOOKUP_TYPE type" +.Fa "X509_NAME *name" +.Fc +.Ft X509_OBJECT * +.Fo X509_OBJECT_retrieve_by_subject +.Fa "STACK_OF(X509_OBJECT) *stack" +.Fa "X509_LOOKUP_TYPE type" +.Fa "X509_NAME *name" +.Fc +.Ft X509_OBJECT * +.Fo X509_OBJECT_retrieve_match +.Fa "STACK_OF(X509_OBJECT) *stack" +.Fa "X509_OBJECT *obj" +.Fc +.Sh DESCRIPTION +The +.Vt X509_OBJECT +structure is a shallow wrapper around one +.Vt X509 +certificate object or one +.Vt X509_CRL +certificate revocation list object. +The type of object stored at any given time can be inspected with +.Fn X509_OBJECT_get_type . +.Pp +Each +.Vt X509_STORE +object uses one stack of +.Vt X509_OBJECT +structures as its main storage area. +.Pp +.Fn X509_OBJECT_new +allocates a new +.Vt X509_OBJECT +structure. +It sets the object type to +.Dv X509_LU_NONE +and the pointer to the certificate or CRL to +.Dv NULL . +.Pp +If +.Fa obj +contains an +.Vt X509 +certificate, +.Fn X509_OBJECT_free +calls +.Xr X509_free 3 +on that inner object. +If +.Fa obj +contains an +.Vt X509_CRL +certificate revocation list, it calls +.Xr X509_CRL_free 3 +on that inner list. +.Fn X509_OBJECT_free +then frees the storage used for the +.Fa obj +itself. +.Pp +If +.Fa type +is +.Dv X509_LU_X509 , +.Fn X509_OBJECT_idx_by_subject +and +.Fn X509_OBJECT_retrieve_by_subject +search the given +.Fa stack +for a certificate with the subject +.Fa name . +If +.Fa type +is +.Dv X509_LU_CRL , +they search for a certificate revocation list with the issuer +.Fa name +instead. +.Pp +If +.Fa obj +contains a certificate, +.Fn X509_OBJECT_retrieve_match +searches the given +.Fa stack +for a certificate with a matching subject name; +if it contains a certificate revocation list, it searches for a +certificate revocation list with a matching issuer name instead; +otherwise, it searches for an +.Vt X509_OBJECT +with a matching type. +.Sh RETURN VALUES +.Fn X509_OBJECT_get_type +returns +.Dv X509_LU_X509 +if +.Fa obj +contains a certificate, +.Dv X509_LU_CRL +if it contains a certificate revocation list, or +.Dv X509_LU_NONE +if it contains neither. +.Pp +.Fn X509_OBJECT_new +returns the new object or +.Dv NULL +if memory allocation fails. +.Pp +.Fn X509_OBJECT_get0_X509 +returns an internal pointer to the certificate contained in +.Fa obj +or +.Dv NULL +if +.Fa obj +is +.Dv NULL +or contains no certificate. +.Pp +.Fn X509_OBJECT_get0_X509_CRL +returns an internal pointer to the certificate revocation list contained in +.Fa obj +or +.Dv NULL +if +.Fa obj +is +.Dv NULL +or contains no certificate revocation list. +.Pp +.Fn X509_OBJECT_idx_by_subject +returns the zero-based index of the first matching certificate +or revocation list in the +.Fa stack +or \-1 if +.Fa type +is neither +.Dv X509_LU_X509 +nor +.Dv X509_LU_CRL +or if no match is found. +.Pp +.Fn X509_OBJECT_retrieve_by_subject +returns the first matching certificate or revocation list in the +.Fa stack +or +.Dv NULL +if +.Fa type +is neither +.Dv X509_LU_X509 +nor +.Dv X509_LU_CRL +or if no match is found. +.Pp +.Fn X509_OBJECT_retrieve_match +returns the first matching +.Vt X509_OBJECT +or +.Dv NULL +if +.Fa stack +or +.Fa obj +is +.Dv NULL +or no match is found. +.Sh SEE ALSO +.Xr STACK_OF 3 , +.Xr X509_CRL_new 3 , +.Xr X509_LOOKUP_new 3 , +.Xr X509_NAME_new 3 , +.Xr X509_new 3 , +.Xr X509_STORE_get0_objects 3 , +.Xr X509_STORE_get_by_subject 3 , +.Xr X509_STORE_load_locations 3 , +.Xr X509_STORE_new 3 +.Sh HISTORY +.Fn X509_OBJECT_idx_by_subject , +.Fn X509_OBJECT_retrieve_by_subject , +and +.Fn X509_OBJECT_retrieve_match +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Pp +.Fn X509_OBJECT_get_type , +.Fn X509_OBJECT_get0_X509 , +and +.Fn X509_OBJECT_get0_X509_CRL +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +.Pp +.Fn X509_OBJECT_new +and +.Fn X509_OBJECT_free +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/X509_PUBKEY_new.3 b/static/openbsd/man3/X509_PUBKEY_new.3 new file mode 100644 index 00000000..1ef1afbc --- /dev/null +++ b/static/openbsd/man3/X509_PUBKEY_new.3 @@ -0,0 +1,402 @@ +.\" $OpenBSD: X509_PUBKEY_new.3,v 1.19 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2020, 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_PUBKEY_NEW 3 +.Os +.Sh NAME +.Nm X509_PUBKEY_new , +.Nm X509_PUBKEY_free , +.Nm X509_PUBKEY_set , +.Nm X509_PUBKEY_get0 , +.Nm X509_PUBKEY_get , +.Nm d2i_X509_PUBKEY , +.Nm i2d_X509_PUBKEY , +.Nm d2i_PUBKEY , +.Nm i2d_PUBKEY , +.Nm d2i_PUBKEY_bio , +.Nm d2i_PUBKEY_fp , +.Nm i2d_PUBKEY_fp , +.Nm i2d_PUBKEY_bio , +.Nm X509_PUBKEY_set0_param , +.Nm X509_PUBKEY_get0_param +.Nd X.509 SubjectPublicKeyInfo structure +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_PUBKEY * +.Fn X509_PUBKEY_new void +.Ft void +.Fo X509_PUBKEY_free +.Fa "X509_PUBKEY *a" +.Fc +.Ft int +.Fo X509_PUBKEY_set +.Fa "X509_PUBKEY **x" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft EVP_PKEY * +.Fo X509_PUBKEY_get0 +.Fa "X509_PUBKEY *key" +.Fc +.Ft EVP_PKEY * +.Fo X509_PUBKEY_get +.Fa "X509_PUBKEY *key" +.Fc +.Ft X509_PUBKEY * +.Fo d2i_X509_PUBKEY +.Fa "X509_PUBKEY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_PUBKEY +.Fa "X509_PUBKEY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft EVP_PKEY * +.Fo d2i_PUBKEY +.Fa "EVP_PKEY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PUBKEY +.Fa "EVP_PKEY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft EVP_PKEY * +.Fo d2i_PUBKEY_bio +.Fa "BIO *bp" +.Fa "EVP_PKEY **val_out" +.Fc +.Ft EVP_PKEY * +.Fo d2i_PUBKEY_fp +.Fa "FILE *fp" +.Fa "EVP_PKEY **val_out" +.Fc +.Ft int +.Fo i2d_PUBKEY_fp +.Fa "FILE *fp" +.Fa "EVP_PKEY *val_in" +.Fc +.Ft int +.Fo i2d_PUBKEY_bio +.Fa "BIO *bp" +.Fa "EVP_PKEY *val_in" +.Fc +.Ft int +.Fo X509_PUBKEY_set0_param +.Fa "X509_PUBKEY *pub" +.Fa "ASN1_OBJECT *aobj" +.Fa "int ptype" +.Fa "void *pval" +.Fa "unsigned char *penc" +.Fa "int penclen" +.Fc +.Ft int +.Fo X509_PUBKEY_get0_param +.Fa "ASN1_OBJECT **ppkalg" +.Fa "const unsigned char **pk" +.Fa "int *ppklen" +.Fa "X509_ALGOR **pa" +.Fa "X509_PUBKEY *pub" +.Fc +.Sh DESCRIPTION +The +.Vt X509_PUBKEY +structure represents the ASN.1 +.Vt SubjectPublicKeyInfo +structure defined in RFC 5280 section 4.1 and used in certificates +and certificate requests. +.Pp +.Fn X509_PUBKEY_new +allocates and initializes an +.Vt X509_PUBKEY +structure. +.Pp +.Fn X509_PUBKEY_free +frees up the +.Vt X509_PUBKEY +structure +.Fa a . +If +.Fa a +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn X509_PUBKEY_set +sets the public key in +.Pf * Fa x +to the public key contained in the +.Vt EVP_PKEY +structure +.Fa pkey . +If +.Pf * Fa x +is not +.Dv NULL , +any existing public key structure will be freed. +.Pp +.Fn X509_PUBKEY_get0 +returns the public key contained in +.Fa key . +The returned value is an internal pointer which must not be freed after use. +.Pp +.Fn X509_PUBKEY_get +is similar to +.Fn X509_PUBKEY_get0 +except that the reference +count on the returned key is incremented so it must be freed using +.Xr EVP_PKEY_free 3 +after use. +.Pp +.Fn d2i_X509_PUBKEY , +.Fn i2d_X509_PUBKEY , +.Fn d2i_PUBKEY , +and +.Fn i2d_PUBKEY +decode and encode an ASN.1 +.Vt SubjectPublicKeyInfo +structure using either the +.Vt X509_PUBKEY +or the +.Vt EVP_PKEY +object type, respectively. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Fn d2i_PUBKEY_bio , +.Fn d2i_PUBKEY_fp , +.Fn i2d_PUBKEY_bio +and +.Fn i2d_PUBKEY_fp +are similar to +.Fn d2i_PUBKEY +and +.Fn i2d_PUBKEY +except they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn X509_PUBKEY_set0_param +sets the public key parameters of +.Fa pub . +The OID associated with the algorithm is set to +.Fa aobj . +The type of the algorithm parameters is set to +.Fa ptype +using the structure +.Fa pval . +The encoding of the public key itself is set to the +.Fa penclen +bytes contained in buffer +.Fa penc . +On success ownership of all the supplied parameters is passed to +.Fa pub +so they must not be freed after the call. +.Pp +.Fn X509_PUBKEY_get0_param +retrieves the public key parameters from +.Fa pub , +.Pf * Fa ppkalg +is set to the associated OID and the encoding consists of +.Pf * Fa ppklen +bytes at +.Pf * Fa pk , +and +.Pf * Fa pa +is set to the associated +.Vt AlgorithmIdentifier +for the public key. +If the value of any of these parameters is not required, +it can be set to +.Dv NULL . +All of the retrieved pointers are internal and must not be freed after +the call. +.Sh RETURN VALUES +If the allocation fails, +.Fn X509_PUBKEY_new +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +Otherwise it returns a pointer to the newly allocated structure. +.Pp +.Fn X509_PUBKEY_get0 +returns an internal pointer or +.Dv NULL +if an error occurs. +.Pp +.Fn X509_PUBKEY_get +returns a pointer to an object that had its reference count incremented or +.Dv NULL +if an error occurs. +.Pp +.Fn d2i_X509_PUBKEY , +.Fn d2i_PUBKEY , +.Fn d2i_PUBKEY_bio , +and +.Fn d2i_PUBKEY_fp +return a pointer to a valid object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_X509_PUBKEY +and +.Fn i2d_PUBKEY +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Pp +.Fn X509_PUBKEY_set , +.Fn X509_PUBKEY_set0_param , +.Fn X509_PUBKEY_get0_param , +.Fn i2d_PUBKEY_fp , +and +.Fn i2d_PUBKEY_bio +return 1 for success and 0 if an error occurred. +.Sh ERRORS +After failure of +.Fn X509_PUBKEY_get0 +or +.Fn X509_PUBKEY_get , +one of the following diagnostics can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv X509_R_UNSUPPORTED_ALGORITHM Qq "unsupported algorithm" +The public key uses an algorithm unsupported by +.Xr EVP_PKEY_set_type 3 . +.It X509_R_METHOD_NOT_SUPPORTED Qq "method not supported" +While the algorithm is known to +.Xr EVP_PKEY_set_type 3 , +using it for decoding is not supported. +.It X509_R_PUBLIC_KEY_DECODE_ERROR Qq "public key decode error" +Decoding the public key failed. +.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" +Memory was exhausted when trying to allocate the new +.Vt EVP_PKEY +object. +.El +.Pp +If +.Fa key +is +.Dv NULL +or does not contain a public key, +these functions fail but no error is pushed onto the stack. +.Sh SEE ALSO +.Xr d2i_X509 3 , +.Xr X509_ALGOR_new 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn X509_PUBKEY_new +and +.Fn X509_PUBKEY_free +appeared in SSLeay 0.4 or earlier. +.Fn d2i_X509_PUBKEY +and +.Fn i2d_X509_PUBKEY +first appeared in SSLeay 0.5.1. +.Fn X509_PUBKEY_set +and +.Fn X509_PUBKEY_get +first appeared in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn d2i_PUBKEY +and +.Fn i2d_PUBKEY +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn d2i_PUBKEY_bio , +.Fn d2i_PUBKEY_fp , +.Fn i2d_PUBKEY_fp , +and +.Fn i2d_PUBKEY_bio +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Pp +.Fn X509_PUBKEY_set0_param +and +.Fn X509_PUBKEY_get0_param +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +.Fn X509_PUBKEY_get0 +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/X509_PURPOSE_set.3 b/static/openbsd/man3/X509_PURPOSE_set.3 new file mode 100644 index 00000000..cb955f39 --- /dev/null +++ b/static/openbsd/man3/X509_PURPOSE_set.3 @@ -0,0 +1,296 @@ +.\" $OpenBSD: X509_PURPOSE_set.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_PURPOSE_SET 3 +.Os +.Sh NAME +.Nm X509_PURPOSE_set , +.Nm X509_PURPOSE_get_by_id , +.Nm X509_PURPOSE_add , +.Nm X509_PURPOSE_get_count , +.Nm X509_PURPOSE_cleanup , +.Nm X509_PURPOSE_get0 , +.Nm X509_PURPOSE_get_by_sname , +.Nm X509_PURPOSE_get_id , +.Nm X509_PURPOSE_get0_name , +.Nm X509_PURPOSE_get0_sname , +.Nm X509_PURPOSE_get_trust +.Nd purpose objects, indices, and identifiers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fo X509_PURPOSE_set +.Fa "int *id_out" +.Fa "int id_in" +.Fc +.Ft int +.Fn X509_PURPOSE_get_by_id "int identifier" +.Ft int +.Fo X509_PURPOSE_add +.Fa "int identifier" +.Fa "int trust" +.Fa "int flags" +.Fa "int (*check_purpose)(const X509_PURPOSE *, const X509 *, int)" +.Fa "const char *name" +.Fa "const char *sname" +.Fa "void *usr_data" +.Fc +.Ft int +.Fn X509_PURPOSE_get_count void +.Ft void +.Fn X509_PURPOSE_cleanup void +.Ft X509_PURPOSE * +.Fn X509_PURPOSE_get0 "int index" +.Ft int +.Fn X509_PURPOSE_get_by_sname "const char *sname" +.Ft int +.Fn X509_PURPOSE_get_id "const X509_PURPOSE *object" +.Ft char * +.Fn X509_PURPOSE_get0_name "const X509_PURPOSE *object" +.Ft char * +.Fn X509_PURPOSE_get0_sname "const X509_PURPOSE *object" +.Ft int +.Fn X509_PURPOSE_get_trust "const X509_PURPOSE *object" +.Sh DESCRIPTION +The purposes that an X.509 certificate is intended to be used for +can be identified in three equivalent ways: +.Bl -enum +.It +By purpose identifiers, which are positive integer constants. +Standard purpose identifiers lie in the range from +.Dv X509_PURPOSE_MIN +to +.Dv X509_PURPOSE_MAX , +inclusive, and are listed in the +.Xr X509_check_purpose 3 +manual page. +User defined purpose identifiers are larger than +.Dv X509_PURPOSE_MAX . +.It +By purpose indices, which are non-negative integer constants +but differ from the purpose identifiers for the same purpose. +Standard purpose indices are smaller than +.Dv X509_PURPOSE_MAX . +User defined purpose indices are larger than or equal to +.Dv X509_PURPOSE_MAX . +.It +By purpose objects of the type +.Vt X509_PURPOSE . +Standard purpose objects are available in static storage. +User defined purpose objects can be created with +.Fn X509_PURPOSE_add . +.El +.Pp +Application programmers cannot choose the way to identify purposes +that they like best; depending on the circumstances, all three ways +are needed. +Be warned that the naming of most functions is misleading. +.Pp +Most API functions documented outside the present manual page +use purpose identifiers rather than purpose indices. +.Ss Using purpose identifiers +.Fn X509_PURPOSE_set +validates the purpose identifier +.Fa id_in . +If it is valid, it is copied to +.Pf * Fa id_out . +Otherwise, +.Pf * Fa id_out +remains unchanged. +.Pp +.Fn X509_PURPOSE_get_by_id +converts the purpose +.Fa identifier +to the corresponding purpose index. +To find the corresponding purpose object, pass the result to +.Fn X509_PURPOSE_get0 . +.Pp +.Fn X509_PURPOSE_add +defines a purpose with the given +.Fa identifier +or modifies its properties if it already exists. +The purpose +.Fa identifier , +the +.Fa trust +identifier, the +.Fa flags , +the +.Fa check_purpose +function, the +.Fa name , +the short name +.Fa sname , +and the +.Fa usr_data +pointer are copied into the +.Vt X509_PURPOSE +object. +When modifying an existing purpose object, previous values of fields are +overwritten and previous +.Fa name +and +.Fa sname +strings are freed if they were dynamically allocated. +When creating a new purpose object, +it is added to the global array of user-defined purpose objects. +.Pp +.Dv X509_PURPOSE_DYNAMIC +and +.Dv X509_PURPOSE_DYNAMIC_NAME +are always ignored in the +.Fa flags +argument. +.Dv X509_PURPOSE_DYNAMIC +is automatically set if the object was created by the user. +It is never set for standard objects, not even if they were +modified by the user. +.Dv X509_PURPOSE_DYNAMIC_NAME +is automatically set if the object was created or modified by the user. +It is only unset for unmodified standard objects. +The library does not appear to define any other flags, so the +.Fa flags +argument is probably useless unless users define their own flags +and use them in the +.Fa check_purpose +function. +.Pp +The third and final argument of the +.Fa check_purpose +function is the +.Fa ca +argument documented in +.Xr X509_check_purpose 3 . +.Pp +.Fn X509_PURPOSE_get_count +returns the total number of purposes currently defined, +including both standard and user-defined purposes. +If no user-defined purposes exist, the returned value is +.Dv X509_PURPOSE_MAX . +.Pp +.Fn X509_PURPOSE_cleanup +deletes all user-defined purpose objects +and invalidates their purpose identifiers and purpose indices. +If any of the standard purpose objects were modified by the user, +those changes are +.Em not +reverted. +.Ss Using purpose indices +.Fn X509_PURPOSE_get0 +converts the purpose +.Fa index +to a pointer to the corresponding purpose object. +To find the corresponding purpose identifier, pass the result to +.Fn X509_PURPOSE_get_id . +.Pp +.Fn X509_PURPOSE_get_by_sname +returns the lowest index of a purpose with the given short name. +.Ss Using purpose objects +.Fn X509_PURPOSE_get_id +converts a pointer to a purpose +.Fa object +to the corresponding purpose identifier. +To find the corresponding purpose index, pass the result to +.Fn X509_PURPOSE_get_by_id . +.Pp +.Fn X509_PURPOSE_get0_name , +.Fn X509_PURPOSE_get0_sname , +and +.Fn X509_PURPOSE_get_trust +retrieve the name, short name, and trust identifier from the +.Fa object , +respectively. +.Sh RETURN VALUES +.Fn X509_PURPOSE_set +returns 1 if +.Fa id_in +is valid or 0 otherwise. +.Pp +.Fn X509_PURPOSE_get_by_id +and +.Fn X509_PURPOSE_get_by_sname +return the corresponding purpose index +or \-1 if no matching purpose is found. +.Pp +.Fn X509_PURPOSE_add +returns 1 for success or 0 for failure. +.Pp +.Fn X509_PURPOSE_get_count +returns the total number of purposes currently defined. +.Pp +.Fn X509_PURPOSE_get0 +returns a standard or user-defined purpose object or +.Dv NULL +if the +.Fa index +is invalid. +.Pp +.Fn X509_PURPOSE_get_id +always returns a valid purpose identifier. +.Pp +.Fn X509_PURPOSE_get0_name +and +.Fn X509_PURPOSE_get0_sname +return pointers to storage owned by the +.Fa object . +.Pp +.Fn X509_PURPOSE_get_trust +returns the trust identifier associated with the +.Fa object . +.Sh ERRORS +The following diagnostics can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv X509V3_R_INVALID_PURPOSE Qq "invalid purpose" +.Fn X509_PURPOSE_set +was called with an invalid +.Fa id_in +argument. +.It Dv X509V3_R_INVALID_NULL_ARGUMENT Qq "invalid null argument" +.Fn X509_PURPOSE_add +was called with a +.Fa name +or +.Fa sname +argument of +.Dv NULL . +.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" +.Fn X509_PURPOSE_add +failed to allocate memory. +.El +.Pp +The other functions provide no diagnostics. +.Sh SEE ALSO +.Xr X509_check_purpose 3 , +.Xr X509_new 3 , +.Xr X509_STORE_set_purpose 3 , +.Xr X509_VERIFY_PARAM_set_purpose 3 +.Sh HISTORY +.Fn X509_PURPOSE_set +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Pp +The other functions first appeared in OpenSSL 0.9.5 +and have been available since +.Ox 2.7 . +.Sh CAVEATS +The difference between purpose identifiers and purpose indices provides +an ideal breeding ground for off-by-one bugs. diff --git a/static/openbsd/man3/X509_REQ_add1_attr.3 b/static/openbsd/man3/X509_REQ_add1_attr.3 new file mode 100644 index 00000000..6beb0240 --- /dev/null +++ b/static/openbsd/man3/X509_REQ_add1_attr.3 @@ -0,0 +1,173 @@ +.\" $OpenBSD: X509_REQ_add1_attr.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_REQ_ADD1_ATTR 3 +.Os +.Sh NAME +.Nm X509_REQ_add1_attr , +.Nm X509_REQ_add1_attr_by_OBJ , +.Nm X509_REQ_add1_attr_by_NID , +.Nm X509_REQ_add1_attr_by_txt , +.Nm X509_REQ_delete_attr , +.Nm X509_REQ_get_attr , +.Nm X509_REQ_get_attr_count , +.Nm X509_REQ_get_attr_by_OBJ , +.Nm X509_REQ_get_attr_by_NID +.Nd X.501 Attributes of PKCS#10 certification requests +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_REQ_add1_attr +.Fa "X509_REQ *req" +.Fa "X509_ATTRIBUTE *attr" +.Fc +.Ft int +.Fo X509_REQ_add1_attr_by_OBJ +.Fa "X509_REQ *req" +.Fa "const ASN1_OBJECT *obj" +.Fa "int type" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft int +.Fo X509_REQ_add1_attr_by_NID +.Fa "X509_REQ *req" +.Fa "int nid" +.Fa "int type" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft int +.Fo X509_REQ_add1_attr_by_txt +.Fa "X509_REQ *req" +.Fa "const char *name" +.Fa "int type" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft X509_ATTRIBUTE * +.Fo X509_REQ_delete_attr +.Fa "X509_REQ *req" +.Fa "int index" +.Fc +.Ft X509_ATTRIBUTE * +.Fo X509_REQ_get_attr +.Fa "const X509_REQ *req" +.Fa "int index" +.Fc +.Ft int +.Fo X509_REQ_get_attr_count +.Fa "const X509_REQ *req" +.Fc +.Ft int +.Fo X509_REQ_get_attr_by_OBJ +.Fa "const X509_REQ *req" +.Fa "const ASN1_OBJECT *obj" +.Fa "int start_after" +.Fc +.Ft int +.Fo X509_REQ_get_attr_by_NID +.Fa "const X509_REQ *req" +.Fa "int nid" +.Fa "int start_after" +.Fc +.Sh DESCRIPTION +These functions support associating an array of X.501 Attributes +with a PKCS#10 certification request. +.Pp +.Fn X509_REQ_add1_attr +appends a deep copy of the +.Fa attr , +allocating a new array if necessary. +.Pp +.Fn X509_REQ_add1_attr_by_OBJ , +.Fn X509_REQ_add1_attr_by_NID , +and +.Fn X509_REQ_add1_attr_by_txt +create a new X.501 Attribute object using +.Xr X509_ATTRIBUTE_create_by_OBJ 3 , +.Xr X509_ATTRIBUTE_create_by_NID 3 , +or +.Xr X509_ATTRIBUTE_create_by_txt 3 , +respectively, +allocating a new array if necessary. +.Pp +.Fn X509_REQ_delete_attr +deletes the attribute with the zero-based +.Fa index . +.Pp +.Fn X509_REQ_get_attr +returns the attribute with the zero-based +.Fa index . +.Pp +.Fn X509_REQ_get_attr_count +returns the number of attributes currently associated with +.Fa req . +.Pp +.Fn X509_REQ_get_attr_by_OBJ +and +.Fn X509_REQ_get_attr_by_NID +search for an attribute of the type +.Fa obj +or +.Fa nid . +.Sh RETURN VALUES +.Fn X509_REQ_add1_attr , +.Fn X509_REQ_add1_attr_by_OBJ , +.Fn X509_REQ_add1_attr_by_NID , +and +.Fn X509_REQ_add1_attr_by_txt +return 1 for success or 0 for failure. +.Pp +.Fn X509_REQ_delete_attr +and +.Fn X509_REQ_get_attr +return the deleted or requested attribute or +.Dv NULL +if the requested index is negative or greater than or equal to +the current number of attributes associated with +.Fa req . +.Pp +.Fn X509_REQ_get_attr_count +returns the current number of attributes. +.Pp +.Fn X509_REQ_get_attr_by_OBJ +and +.Fn X509_REQ_get_attr_by_NID +return the index of the first attribute that has an index greater than +.Fa start_after +and a type matching +.Fa obj +or +.Fa nid , +respectively, or \-1 on failure. +In addition, +.Fn X509_REQ_get_attr_by_NID +returns \-2 if +.Xr OBJ_nid2obj 3 +fails on the requested +.Fa nid . +.Sh SEE ALSO +.Xr OBJ_nid2obj 3 , +.Xr X509_ATTRIBUTE_create_by_OBJ 3 , +.Xr X509_ATTRIBUTE_new 3 , +.Xr X509_REQ_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.5 +and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/X509_REQ_add_extensions.3 b/static/openbsd/man3/X509_REQ_add_extensions.3 new file mode 100644 index 00000000..804e7879 --- /dev/null +++ b/static/openbsd/man3/X509_REQ_add_extensions.3 @@ -0,0 +1,114 @@ +.\" $OpenBSD: X509_REQ_add_extensions.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_REQ_ADD_EXTENSIONS 3 +.Os +.Sh NAME +.Nm X509_REQ_add_extensions , +.Nm X509_REQ_add_extensions_nid , +.Nm X509_REQ_get_extensions , +.Nm X509_REQ_extension_nid +.Nd extensions in certification requests +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_REQ_add_extensions +.Fa "X509_REQ *req" +.Fa "STACK_OF(X509_EXTENSION) *extensions" +.Fc +.Ft int +.Fo X509_REQ_add_extensions_nid +.Fa "X509_REQ *req" +.Fa "STACK_OF(X509_EXTENSION) *extensions" +.Fa "int nid" +.Fc +.Ft STACK_OF(X509_EXTENSION) * +.Fn X509_REQ_get_extensions "X509_REQ *req" +.Ft int +.Fn X509_REQ_extension_nid "int nid" +.Sh DESCRIPTION +.Fn X509_REQ_add_extensions +encodes the array of +.Fa extensions +using +.Xr i2d_X509_EXTENSIONS 3 +and adds a new X.501 Attribute object of the type +.Dv NID_ext_req +to +.Fa req +using the equivalent of +.Xr X509_ATTRIBUTE_create_by_NID 3 +with a +.Fa type +of +.Dv V_ASN1_SEQUENCE . +.Pp +.Fn X509_REQ_add_extensions_nid +is identical except that the specified +.Fa nid +is used as the X.501 Attribute type instead of +.Dv NID_ext_req . +.Pp +.Fn X509_REQ_get_extensions +retrieves the first value of the first X.501 Attribute of appropriate type. +By default, the attribute types +.Dv NID_ext_req +and +.Dv NID_ms_ext_req +are considered appropriate. +.Pp +.Fn X509_REQ_extension_nid +checks whether +.Fn X509_REQ_get_extensions +regards the +.Fa nid +argument as a type appropriate for storing extensions. +.Sh RETURN VALUES +.Fn X509_REQ_add_extensions +and +.Fn X509_REQ_add_extensions_nid +returns 1 for success or 0 for failure. +.Pp +.Fn X509_REQ_get_extensions +returns a newly allocated array of ASN.1 +.Vt Extension +objects or +.Dv NULL +if +.Fa req +is +.Dv NULL , +does not contain +.Vt CertificationRequestInfo , +contains no attribute of an appropriate type, +or if decoding or memory allocation fails. +.Pp +.Fn X509_REQ_extension_nid +returns 1 if +.Fa nid +is considered appropriate or 0 otherwise. +.Sh SEE ALSO +.Xr d2i_X509_EXTENSION 3 , +.Xr STACK_OF 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_REQ_new 3 , +.Xr X509V3_extensions_print 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.5 +and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/X509_REQ_new.3 b/static/openbsd/man3/X509_REQ_new.3 new file mode 100644 index 00000000..a62f2c3a --- /dev/null +++ b/static/openbsd/man3/X509_REQ_new.3 @@ -0,0 +1,146 @@ +.\" $OpenBSD: X509_REQ_new.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016, 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_REQ_NEW 3 +.Os +.Sh NAME +.Nm X509_REQ_new , +.Nm X509_REQ_dup , +.Nm X509_to_X509_REQ , +.Nm X509_REQ_free , +.Nm X509_REQ_INFO_new , +.Nm X509_REQ_INFO_free +.Nd PKCS#10 certification requests +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_REQ * +.Fn X509_REQ_new void +.Ft X509_REQ * +.Fn X509_REQ_dup "X509_REQ *req" +.Ft X509_REQ * +.Fn X509_to_X509_REQ "X509 *x" "EVP_PKEY *pkey" "const EVP_MD *md" +.Ft void +.Fn X509_REQ_free "X509_REQ *req" +.Ft X509_REQ_INFO * +.Fn X509_REQ_INFO_new void +.Ft void +.Fn X509_REQ_INFO_free "X509_REQ_INFO *req_info" +.Sh DESCRIPTION +.Fn X509_REQ_new +allocates and initializes an empty +.Vt X509_REQ +object, representing an ASN.1 +.Vt CertificationRequest +structure defined in RFC 2986 section 4.2. +It can hold a pointer to an +.Vt X509_REQ_INFO +object discussed below together with a cryptographic signature and +information about the signature algorithm used. +.Pp +.Fn X509_REQ_dup +creates a deep copy of +.Fa req +using +.Xr ASN1_item_dup 3 , +setting the reference count of the copy to 1. +.Pp +.Fn X509_to_X509_REQ +allocates a new certification request object, copies +the subject name and the public key into it from the certificate +.Fa x , +and sets the version to zero. +Unless +.Fa pkey +is +.Dv NULL , +it also signs the request with +.Xr X509_REQ_sign 3 +using +.Fa pkey +and +.Fa md . +.Pp +.Fn X509_REQ_free +frees +.Fa req . +If +.Fa req +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn X509_REQ_INFO_new +allocates and initializes an empty +.Vt X509_REQ_INFO +object, representing an ASN.1 +.Vt CertificationRequestInfo +structure defined in RFC 2986 section 4.1. +It is used inside the +.Vt X509_REQ +object and can hold the subject and the public key of the requested +certificate and additional attributes. +.Fn X509_REQ_INFO_free +frees +.Fa req_info . +If +.Fa req_info +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn X509_REQ_new , +.Fn X509_REQ_dup , +.Fn X509_to_X509_REQ , +and +.Fn X509_REQ_INFO_new +return the new +.Vt X509_REQ +or +.Vt X509_REQ_INFO +object, respectively, or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_X509_REQ 3 , +.Xr PEM_read_X509_REQ 3 , +.Xr X509_new 3 , +.Xr X509_REQ_add1_attr 3 , +.Xr X509_REQ_add_extensions 3 , +.Xr X509_REQ_check_private_key 3 , +.Xr X509_REQ_digest 3 , +.Xr X509_REQ_get0_signature 3 , +.Xr X509_REQ_get_pubkey 3 , +.Xr X509_REQ_get_subject_name 3 , +.Xr X509_REQ_get_version 3 , +.Xr X509_REQ_print_ex 3 , +.Xr X509_REQ_sign 3 +.Sh STANDARDS +RFC 2986: PKCS #10: Certification Request Syntax Specification +.Sh HISTORY +.Fn X509_REQ_new , +.Fn X509_REQ_free , +.Fn X509_REQ_INFO_new , +and +.Fn X509_REQ_INFO_free +first appeared in SSLeay 0.4.4, +.Fn X509_REQ_dup +in SSLeay 0.5.1, and +.Fn X509_to_X509_REQ +in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/X509_REQ_print_ex.3 b/static/openbsd/man3/X509_REQ_print_ex.3 new file mode 100644 index 00000000..8d87396b --- /dev/null +++ b/static/openbsd/man3/X509_REQ_print_ex.3 @@ -0,0 +1,175 @@ +.\" $OpenBSD: X509_REQ_print_ex.3,v 1.4 2025/06/08 22:30:52 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_REQ_PRINT_EX 3 +.Os +.Sh NAME +.Nm X509_REQ_print_ex , +.Nm X509_REQ_print , +.Nm X509_REQ_print_fp +.Nd pretty-print a PKCS#10 certification request +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_REQ_print_ex +.Fa "BIO *bio" +.Fa "X509_REQ *req" +.Fa "unsigned long nameflags" +.Fa "unsigned long skipflags" +.Fc +.Ft int +.Fo X509_REQ_print +.Fa "BIO *bio" +.Fa "X509_REQ *req" +.Fc +.Ft int +.Fo X509_REQ_print_fp +.Fa "FILE *fp" +.Fa "X509_REQ *req" +.Fc +.Sh DESCRIPTION +.Fn X509_REQ_print_ex +prints information contained in +.Fa req +to +.Fa bio +in human-readable form. +Printing is aborted as soon as any operation fails, with the exception +that failures while attempting to decode or print the public key +are not considered as errors. +.Pp +By default, the following blocks of information +are printed in the following order. +Each block can be skipped by setting the corresponding bit in +.Fa skipflags , +provided in parentheses after each block description. +.Bl -bullet +.It +A pair of lines reading +.Qq Certificate Request:\& +and +.Qq Data:\& +containing no information. +.Pq Dv X509_FLAG_NO_HEADER +.It +The value contained in the version field +in decimal and hexadecimal notation. +.Pq Dv X509_FLAG_NO_VERSION +.It +The subject name is printed with +.Xr X509_NAME_print_ex 3 . +.Pq Dv X509_FLAG_NO_SUBJECT +.It +The public key algorithm is printed with +.Xr i2a_ASN1_OBJECT 3 , +and the public key returned from +.Xr X509_REQ_get_pubkey 3 +with +.Xr EVP_PKEY_print_public 3 . +.Pq Dv X509_FLAG_NO_PUBKEY +.It +For each X.501 attribute that is not a requested extension according to +.Xr X509_REQ_extension_nid 3 , +the object identifier is printed with +.Xr i2a_ASN1_OBJECT 3 , +and all values of the types +.Dv V_ASN1_PRINTABLESTRING , +.Dv V_ASN1_T61STRING , +and +.Dv V_ASN1_IA5STRING +are printed with +.Xr BIO_write 3 . +.Pq Dv X509_FLAG_NO_ATTRIBUTES +.It +The requested extensions are retrieved with +.Xr X509_REQ_get_extensions 3 +and their types and values are printed with +.Xr i2a_ASN1_OBJECT 3 +and +.Xr X509V3_EXT_print 3 , +or, if the latter fails, with +.Xr ASN1_STRING_print 3 . +.Pq Dv X509_FLAG_NO_EXTENSIONS +.It +The signature is printed with +.Xr X509_signature_print 3 . +.Pq Dv X509_FLAG_NO_SIGDUMP +.El +.Pp +The +.Fa nameflags +argument modifies the format for printing X.501 +.Vt Name +objects contained in +.Fa req . +It is passed through to +.Xr X509_NAME_print_ex 3 . +If +.Fa nameflags +is +.Dv X509_FLAG_COMPAT , +the +.Fa indent +argument of +.Xr X509_NAME_print_ex 3 +is set to 16 spaces and the traditional SSLeay format is used. +Otherwise, if the only bit set in +.Dv XN_FLAG_SEP_MASK +is +.Dv XN_FLAG_SEP_MULTILINE , +.Fa indent +is set to 12 spaces. +Otherwise, indent is set to zero. +.Pp +.Fn X509_REQ_print +is a wrapper function setting the +.Fa nameflags +to +.Dv XN_FLAG_COMPAT +and the +.Fa skipflags +to +.Dv X509_FLAG_COMPAT . +.Pp +.Fn X509_REQ_print_fp +is similar to +.Fn X509_REQ_print +except that it prints to +.Fa fp . +.Sh RETURN VALUES +These functions return 1 if all requested information was successfully +printed, even if failures occurred while attempting to decode or +print the public key, or 0 if any operation fails. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr X509_print_ex 3 , +.Xr X509_REQ_new 3 +.Sh HISTORY +.Fn X509_REQ_print +first appeared in SSLeay 0.4.4 and +.Fn X509_REQ_print_fp +in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_REQ_print_ex +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Sh BUGS +Some printing failures are silently ignored while printing extensions, +which may result in incomplete data being printed. diff --git a/static/openbsd/man3/X509_REVOKED_new.3 b/static/openbsd/man3/X509_REVOKED_new.3 new file mode 100644 index 00000000..6dffcfd0 --- /dev/null +++ b/static/openbsd/man3/X509_REVOKED_new.3 @@ -0,0 +1,214 @@ +.\" $OpenBSD: X509_REVOKED_new.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL man3/X509_CRL_get0_by_serial cdd6c8c5 Mar 20 12:29:37 2017 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_REVOKED_NEW 3 +.Os +.Sh NAME +.Nm X509_REVOKED_new , +.Nm X509_REVOKED_dup , +.Nm X509_REVOKED_free , +.Nm X509_REVOKED_get0_serialNumber , +.Nm X509_REVOKED_get0_revocationDate , +.Nm X509_REVOKED_set_serialNumber , +.Nm X509_REVOKED_set_revocationDate +.Nd create, change, and inspect an X.509 CRL revoked entry +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_REVOKED * +.Fn X509_REVOKED_new void +.Ft X509_REVOKED * +.Fo X509_REVOKED_dup +.Fa "X509_REVOKED *r" +.Fc +.Ft void +.Fn X509_REVOKED_free "X509_REVOKED *r" +.Ft const ASN1_INTEGER * +.Fo X509_REVOKED_get0_serialNumber +.Fa "const X509_REVOKED *r" +.Fc +.Ft const ASN1_TIME * +.Fo X509_REVOKED_get0_revocationDate +.Fa "const X509_REVOKED *r" +.Fc +.Ft int +.Fo X509_REVOKED_set_serialNumber +.Fa "X509_REVOKED *r" +.Fa "ASN1_INTEGER *serial" +.Fc +.Ft int +.Fo X509_REVOKED_set_revocationDate +.Fa "X509_REVOKED *r" +.Fa "ASN1_TIME *tm" +.Fc +.Sh DESCRIPTION +.Fn X509_REVOKED_new +allocates and initializes an empty +.Vt X509_REVOKED +object, representing one of the elements of +the revokedCertificates field of the ASN.1 +.Vt TBSCertList +structure defined in RFC 5280 section 5.1. +It is used by +.Vt X509_CRL +objects and can hold information about one revoked certificate +including issuer names, serial number, revocation date, and revocation +reason. +.Pp +.Fn X509_REVOKED_dup +creates a deep copy of +.Fa r . +.Pp +.Fn X509_REVOKED_free +frees +.Fa r . +.Pp +.Fn X509_REVOKED_set_serialNumber +sets the serial number of +.Fa r +to +.Fa serial . +The supplied +.Fa serial +pointer is not used internally so it should be freed up after use. +.Pp +.Fn X509_REVOKED_set_revocationDate +sets the revocation date of +.Fa r +to +.Fa tm . +The supplied +.Fa tm +pointer is not used internally so it should be freed up after use. +.Sh RETURN VALUES +The +.Fn X509_REVOKED_new +function returns the new +.Vt X509_REVOKED +object if successful; otherwise +.Dv NULL +is returned and an error code can be retrieved with +.Xr ERR_get_error 3 . +.Pp +.Fn X509_REVOKED_dup +return the new +.Vt X509_REVOKED +object or +.Dv NULL +if an error occurs. +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Pp +.Fn X509_REVOKED_get0_serialNumber +returns an internal pointer to the serial number of +.Fa r . +.Pp +.Fn X509_REVOKED_get0_revocationDate +returns an internal pointer to the revocation date of +.Fa r . +.Pp +.Fn X509_REVOKED_set_serialNumber +and +.Fn X509_REVOKED_set_revocationDate +return 1 for success or 0 for failure. +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr d2i_X509_CRL 3 , +.Xr PEM_read_X509_CRL 3 , +.Xr X509_CRL_get0_by_serial 3 , +.Xr X509_CRL_new 3 , +.Xr X509_CRL_print 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_REVOKED_get_ext 3 , +.Xr X509_REVOKED_get_ext_d2i 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, section 5.1: CRL Fields +.Sh HISTORY +.Fn X509_REVOKED_new +and +.Fn X509_REVOKED_free +first appeared in SSLeay 0.4.4 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_REVOKED_set_serialNumber +and +.Fn X509_REVOKED_set_revocationDate +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn X509_REVOKED_dup +first appeared in OpenSSL 1.0.2. +.Fn X509_REVOKED_get0_serialNumber +and +.Fn X509_REVOKED_get0_revocationDate +first appeared in OpenSSL 1.1.0. +These functions have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/X509_SIG_get0.3 b/static/openbsd/man3/X509_SIG_get0.3 new file mode 100644 index 00000000..339fcc0c --- /dev/null +++ b/static/openbsd/man3/X509_SIG_get0.3 @@ -0,0 +1,91 @@ +.\" $OpenBSD: X509_SIG_get0.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_SIG_GET0 3 +.Os +.Sh NAME +.Nm X509_SIG_get0 , +.Nm X509_SIG_getm +.Nd DigestInfo functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft void +.Fo X509_SIG_get0 +.Fa "const X509_SIG *sig" +.Fa "const X509_ALGOR **palg" +.Fa "const ASN1_OCTET_STRING **pdigest" +.Fc +.Ft void +.Fo X509_SIG_getm +.Fa "X509_SIG *sig" +.Fa "X509_ALGOR **palg" +.Fa "ASN1_OCTET_STRING **pdigest" +.Fc +.Sh DESCRIPTION +.Fn X509_SIG_get0 +returns pointers to the algorithm identifier and digest value in +.Fa sig . +.Fn X509_SIG_getm +is identical to +.Fn X509_SIG_get0 , +except the pointers returned are not constant and can be modified, +for example to initialise them. +.Sh SEE ALSO +.Xr d2i_X509 3 , +.Xr X509_SIG_new 3 +.Sh HISTORY +.Fn X509_SIG_get0 +and +.Fn X509_SIG_getm +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/X509_SIG_new.3 b/static/openbsd/man3/X509_SIG_new.3 new file mode 100644 index 00000000..8fafc00c --- /dev/null +++ b/static/openbsd/man3/X509_SIG_new.3 @@ -0,0 +1,69 @@ +.\" $OpenBSD: X509_SIG_new.3,v 1.6 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt X509_SIG_NEW 3 +.Os +.Sh NAME +.Nm X509_SIG_new , +.Nm X509_SIG_free +.Nd PKCS#7 digest information +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_SIG * +.Fn X509_SIG_new void +.Ft void +.Fn X509_SIG_free "X509_SIG *sig" +.Sh DESCRIPTION +.Fn X509_SIG_new +allocates and initializes an empty +.Vt X509_SIG +object, representing an ASN.1 +.Vt DigestInfo +structure defined in RFC 2315 section 9.4 +and equivalently in RFC 8017 section 9.2. +It can hold a message digest together with information about +the algorithm used. +.Pp +.Fn X509_SIG_free +frees +.Fa sig . +.Sh RETURN VALUES +.Fn X509_SIG_new +returns the new +.Vt X509_SIG +object or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr d2i_X509_SIG 3 , +.Xr PEM_read_PKCS8 3 , +.Xr RSA_sign 3 , +.Xr X509_new 3 , +.Xr X509_SIG_get0 3 +.Sh STANDARDS +RFC 2315: PKCS #7: Cryptographic Message Syntax, +section 9: Signed-data content type +.Pp +RFC 8017: PKCS #1: RSA Cryptography Specifications, +section 9: Encoding Methods for Signatures +.Sh HISTORY +.Fn X509_SIG_new +and +.Fn X509_SIG_free +appeared in SSLeay 0.4 or earlier and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/X509_STORE_CTX_get_error.3 b/static/openbsd/man3/X509_STORE_CTX_get_error.3 new file mode 100644 index 00000000..5eb2bfe8 --- /dev/null +++ b/static/openbsd/man3/X509_STORE_CTX_get_error.3 @@ -0,0 +1,592 @@ +.\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.29 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL man3/X509_STORE_CTX_get_error 24a535ea Sep 22 13:14:20 2020 +0100 +.\" OpenSSL man3/X509_STORE_CTX_new 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Rich Salz . +.\" Copyright (c) 2009, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_STORE_CTX_GET_ERROR 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_get_error , +.Nm X509_STORE_CTX_set_error , +.Nm X509_STORE_CTX_get_error_depth , +.Nm X509_STORE_CTX_set_error_depth , +.Nm X509_STORE_CTX_get_current_cert , +.Nm X509_STORE_CTX_set_current_cert , +.Nm X509_STORE_CTX_get0_current_issuer , +.Nm X509_STORE_CTX_get0_current_crl , +.Nm X509_STORE_CTX_get0_parent_ctx , +.Nm X509_STORE_CTX_get_num_untrusted , +.Nm X509_STORE_CTX_get0_chain , +.Nm X509_STORE_CTX_get_chain , +.Nm X509_STORE_CTX_get1_chain , +.Nm X509_STORE_CTX_set0_verified_chain , +.Nm X509_verify_cert_error_string +.Nd get or set certificate verification status information +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft int +.Fo X509_STORE_CTX_get_error +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_error +.Fa "X509_STORE_CTX *ctx" +.Fa "int s" +.Fc +.Ft int +.Fo X509_STORE_CTX_get_error_depth +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_error_depth +.Fa "X509_STORE_CTX *ctx" +.Fa "int depth" +.Fc +.Ft X509 * +.Fo X509_STORE_CTX_get_current_cert +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_current_cert +.Fa "X509_STORE_CTX *ctx" +.Fa "X509 *cert" +.Fc +.Ft X509 * +.Fo X509_STORE_CTX_get0_current_issuer +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft X509_CRL * +.Fo X509_STORE_CTX_get0_current_crl +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft X509_STORE_CTX * +.Fo X509_STORE_CTX_get0_parent_ctx +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft int +.Fo X509_STORE_CTX_get_num_untrusted +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft STACK_OF(X509) * +.Fo X509_STORE_CTX_get0_chain +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft STACK_OF(X509) * +.Fo X509_STORE_CTX_get_chain +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft STACK_OF(X509) * +.Fo X509_STORE_CTX_get1_chain +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set0_verified_chain +.Fa "X509_STORE_CTX *ctx" +.Fa "STACK_OF(X509) *chain" +.Fc +.In openssl/x509.h +.Ft const char * +.Fo X509_verify_cert_error_string +.Fa "long n" +.Fc +.Sh DESCRIPTION +Most of these functions are typically called after +.Xr X509_verify_cert 3 +to inspect status information related to certificate verification. +Some may also be called in a verification callback to determine the +nature of an error. +.Pp +.Fn X509_STORE_CTX_get_error +returns the error code of +.Fa ctx . +See the +.Sy ERROR CODES +section for a full description of all error codes. +.Pp +.Fn X509_STORE_CTX_set_error +sets the error code of +.Fa ctx +to +.Fa s . +For example it might be used in a verification callback to set an error +based on additional checks. +.Pp +.Fn X509_STORE_CTX_get_error_depth +returns the depth of the error. +This is a non-negative 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. +.Pp +.Fn X509_STORE_CTX_set_error_depth +sets the error depth. +This can be used in combination with +.Fn X509_STORE_CTX_set_error +to set the depth at which an error condition was detected. +.Pp +.Fn X509_STORE_CTX_get_current_cert +returns the certificate in +.Fa ctx +which caused the error or +.Dv NULL +if no certificate is relevant. +.Pp +.Fn X509_STORE_CTX_set_current_cert +sets the certificate which caused the error in +.Fa ctx +to the given +.Fa cert . +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 +.Xr X509_up_ref 3 . +Once such a saved certificate is no longer needed, it can be freed with +.Xr X509_free 3 . +.Pp +.Fn X509_STORE_CTX_get0_current_issuer +returns the certificate that caused issuer validation to fail or +.Dv NULL +if no CA certificate is relevant. +.Pp +.Fn X509_STORE_CTX_get0_current_crl +returns the certificate revocation list that caused CRL checking to fail or +.Dv NULL +if no CRL is relevant. +.Pp +When, during certification path validation, the need arises to check +the validity of the certification path of a CRL issuer certificate, +the library creates a new, temporary +.Vt X509_STORE_CTX +object. +If +.Fn X509_STORE_CTX_get0_parent_ctx +is called on that temporary object, a pointer to the original +certification path validation context is returned. +This may be useful in callback functions called from +.Xr X509_verify_cert 3 +or from its subroutines to find out whether the callback is called +from the path validation of the target certificate or from the path +validation of a related CRL issuer certificate, and if the latter, +what the target certificate is. +.Pp +.Fn X509_STORE_CTX_get0_chain +returns an internal pointer to a complete validate chain +if a previous call to +.Xr X509_verify_cert 3 +was successful. +If the call to +.Xr X509_verify_cert 3 +was not successful, the returned chain may be incomplete or invalid. +.Fn X509_STORE_CTX_get_chain +is a deprecated alias of +.Fn X509_STORE_CTX_get0_chain . +.Fn X509_STORE_CTX_get1_chain +returns a deep copy of the same chain which persists even after the +.Fa ctx +structure is freed. +When it is no longer needed, it should be freed using +.Fn sk_X509_pop_free chain X509_free . +.Pp +.Fn X509_STORE_CTX_set0_verified_chain +frees the validate chain generated by if a previous call to +.Xr X509_verify_cert 3 , +if any, and replaces it with the given +.Fa chain . +Ownership of the +.Fa chain +is transferred to the +.Fa ctx , +so it should not be freed by the caller. +.Pp +.Fn X509_verify_cert_error_string +returns a human readable error string for verification error +.Fa n . +.Pp +The above functions should be used instead of directly referencing the +fields in the +.Sy X509_VERIFY_CTX +structure. +.Pp +In versions of OpenSSL before 1.0, the current certificate returned by +.Fn X509_STORE_CTX_get_current_cert +was never +.Dv 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 +.Fn X509_verify_cert_error_string , +"Unknown certificate verification error" +is returned. +This should never happen unless an invalid code is passed. +.Sh RETURN VALUES +.Fn X509_STORE_CTX_get_error +returns +.Dv X509_V_OK +or an error code. +.Pp +.Fn X509_STORE_CTX_get_error_depth +returns a non-negative error depth. +.Pp +.Fn X509_STORE_CTX_get_current_cert , +.Fn X509_STORE_CTX_get0_current_issuer , +and +.Fn X509_STORE_CTX_get0_current_crl +return the object which caused the error or +.Dv NULL +if no object of the requested kind is relevant to the error. +.Pp +.Fn X509_STORE_CTX_get0_parent_ctx +returns the parent context or +.Dv NULL +if +.Fa ctx +is not a temporary child context +used for path validation of a CRL issuer certificate. +.Pp +.Fn X509_STORE_CTX_get_num_untrusted +returns the number of untrusted certificates +that were used in building the chain during a call to +.Xr X509_verify_cert 3 . +.Pp +.Fn X509_STORE_CTX_get0_chain , +.Fn X509_STORE_CTX_get_chain , +and +.Fn X509_STORE_CTX_get1_chain +return a pointer to a stack of certificates or +.Dv NULL +if an error occurs. +.Pp +.Fn X509_verify_cert_error_string +returns a human readable error string for verification error +.Fa n . +.Sh 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". +.Bl -tag -width Ds +.It Dv X509_V_OK : No ok +The operation was successful. +.It Dv X509_V_ERR_UNSPECIFIED : \ + No Unspecified certificate verification error +An error was encountered during certificate verification and +the internal routines failed to set a more specific error. +.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT : \ + No 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. +.It Dv X509_V_ERR_UNABLE_TO_GET_CRL : No unable to get certificate CRL +The CRL of a certificate could not be found. +.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE : \ + No 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. +.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE : \ + No 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. +.It Dv X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY : \ + No unable to decode issuer public key +The public key in the certificate +.Vt SubjectPublicKeyInfo +could not be read. +.It Dv X509_V_ERR_CERT_SIGNATURE_FAILURE : No certificate signature failure +The signature of the certificate is invalid. +.It Dv X509_V_ERR_CRL_SIGNATURE_FAILURE : No CRL signature failure +The signature of the CRL is invalid. +.It Dv X509_V_ERR_CERT_NOT_YET_VALID : No certificate is not yet valid +The certificate is not yet valid: the notBefore date is after the +current time. +.It Dv X509_V_ERR_CERT_HAS_EXPIRED : No certificate has expired +The certificate has expired: that is the notAfter date is before the +current time. +.It Dv X509_V_ERR_CRL_NOT_YET_VALID : No CRL is not yet valid +The CRL is not yet valid. +.It Dv X509_V_ERR_CRL_HAS_EXPIRED : No CRL has expired +The CRL has expired. +.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD : \ + No format error in certificate's notBefore field +The certificate notBefore field contains an invalid time. +.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD : \ + No format error in certificate's notAfter field +The certificate notAfter field contains an invalid time. +.It Dv X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD : \ + No format error in CRL's lastUpdate field +The CRL thisUpdate field (sic!) contains an invalid time. +Both the name of the error constant and the text of the error message +give a wrong name for the field that contains the problem. +.It Dv X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD : \ + No format error in CRL's nextUpdate field +The CRL nextUpdate field contains an invalid time. +.It Dv X509_V_ERR_OUT_OF_MEM : No out of memory +An error occurred trying to allocate memory. +This should never happen. +.It Dv X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT : No self signed certificate +The passed certificate is self signed and the same certificate cannot be +found in the list of trusted certificates. +.It Dv X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN : \ + No self signed certificate in certificate chain +The certificate chain could be built up using the untrusted certificates +but the root could not be found locally. +.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY : \ + No 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. +.It Dv X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE : \ + No unable to verify the first certificate +No signatures could be verified because the chain contains only one +certificate and it is not self signed. +.It Dv X509_V_ERR_CERT_CHAIN_TOO_LONG : No certificate chain too long +The certificate chain length is greater than the supplied maximum depth. +.It Dv X509_V_ERR_CERT_REVOKED : No certificate revoked +The certificate has been revoked. +.It Dv X509_V_ERR_INVALID_CA : No invalid CA certificate +A CA certificate is invalid. +Either it is not a CA or its extensions are not consistent with the +supplied purpose. +.It Dv X509_V_ERR_PATH_LENGTH_EXCEEDED : No path length constraint exceeded +The basicConstraints path-length parameter has been exceeded. +.It Dv X509_V_ERR_INVALID_PURPOSE : No unsupported certificate purpose +The supplied certificate cannot be used for the specified purpose. +.It Dv X509_V_ERR_CERT_UNTRUSTED : No certificate not trusted +The root CA is not marked as trusted for the specified purpose. +.It Dv X509_V_ERR_CERT_REJECTED : No certificate rejected +The root CA is marked to reject the specified purpose. +.It Dv X509_V_ERR_SUBJECT_ISSUER_MISMATCH : No subject issuer mismatch +The current candidate issuer certificate was rejected because its +subject name did not match the issuer name of the current certificate. +This is only set if issuer check debugging is enabled; it is used for +status notification and is +.Sy not +in itself an error. +.It Dv X509_V_ERR_AKID_SKID_MISMATCH : \ + No 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. +This is only set if issuer check debugging is enabled; it is used for +status notification and is +.Sy not +in itself an error. +.It Dv X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH : \ + No 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. +This is only set if issuer check debugging is enabled; it is used for +status notification and is +.Sy not +in itself an error. +.It Dv X509_V_ERR_KEYUSAGE_NO_CERTSIGN : \ + No key usage does not include certificate signing +The current candidate issuer certificate was rejected because its +keyUsage extension does not permit certificate signing. +This is only set if issuer check debugging is enabled it is used for +status notification and is +.Sy not +in itself an error. +.It Dv X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER : \ + No unable to get CRL issuer certificate +The CRL's issuer could not be found: +there is no alternative CRL issuer set on +.Ar ctx +and the last certificate in the chain is not self signed. +.It Dv X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION : \ + No unhandled critical extension +The certificate contains a critical extension that is unsupported +by the library. +.It Dv X509_V_ERR_KEYUSAGE_NO_CRL_SIGN : \ + No key usage does not include CRL signing +The CRL issuer has a key usage extension with unset cRLSign bit. +.It Dv X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION : \ + No unhandled critical CRL extension +The CRL contains a critical extension that is unsupported +by the library. +.\" XXX - The following are unreachable (X509_V_ERR_INVALID_NON_CA) or unused. +.\" .It Dv X509_V_ERR_INVALID_NON_CA : \ +.\" No invalid non-CA certificate (has CA markings) +.\" .It Dv X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED : \ +.\" No proxy path length constraint exceeded +.\" .It Dv X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE : \ +.\" No key usage does not include digital signature +.\" .It Dv X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED : \ +.\" No proxy certificates not allowed, please set the appropriate flag +.It Dv X509_V_ERR_INVALID_EXTENSION : \ + No invalid or inconsistent certificate extension +A certificate extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. +.It Dv X509_V_ERR_INVALID_POLICY_EXTENSION : \ + No 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. +.It Dv X509_V_ERR_NO_EXPLICIT_POLICY : No no explicit policy +The verification flags were set to require an explicit policy but none +was present. +.It Dv X509_V_ERR_DIFFERENT_CRL_SCOPE : No different CRL scope +The only CRLs that could be found did not match the scope of the +certificate. +.It Dv X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE : \ + No unsupported extension feature +Some feature of a certificate extension is not supported. +Unused. +.It Dv X509_V_ERR_UNNESTED_RESOURCE : \ + No RFC 3779 resource not subset of parent's resources +When walking up a certificate chain, all resources specified in +RFC 3779 extensions must be contained in the resources delegated in +the issuer's RFC 3779 extensions. +The error indicates that this is not the case or that the trust anchor +has inheritance. +.It Dv X509_V_ERR_PERMITTED_VIOLATION : No permitted subtree violation +A name constraint violation occurred in the permitted subtrees. +.It Dv X509_V_ERR_EXCLUDED_VIOLATION : No excluded subtree violation +A name constraint violation occurred in the excluded subtrees. +.It Dv X509_V_ERR_SUBTREE_MINMAX : \ + No name constraints minimum and maximum not supported +A certificate name constraints extension included a minimum or maximum +field: this is not supported. +.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE : \ + No unsupported name constraint type +An unsupported name constraint type was encountered. +OpenSSL currently only supports directory name, DNS name, email and URI +types. +.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX : \ + No 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 RFC 3280. +This could be caused by a garbage extension or some new feature not +currently supported. +.\" X509_V_ERR_UNSUPPORTED_NAME_SYNTAX : No unsupported or invalid name syntax +.It Dv X509_V_ERR_CRL_PATH_VALIDATION_ERROR : No 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. +.It Dv X509_V_ERR_APPLICATION_VERIFICATION : \ + No application verification failure +An application specific error. +This will never be returned unless explicitly set by an application. +.\" .It Dv X509_V_ERR_HOSTNAME_MISMATCH : No Hostname mismatch +.\" .It Dv X509_V_ERR_EMAIL_MISMATCH : No Email address mismatch +.\" .It Dv X509_V_ERR_IP_ADDRESS_MISMATCH : No IP address mismatch +.\" .It Dv X509_V_ERR_INVALID_CALL : \ +.\" No Invalid certificate verification context +.\" .It Dv X509_V_ERR_STORE_LOOKUP : No Issuer certificate lookup error +.\" .It Dv X509_V_ERR_EE_KEY_TOO_SMALL : No EE certificate key too weak +.\" .It Dv X509_V_ERR_CA_KEY_TOO_SMALL : No CA certificate key too weak +.\" .It Dv X509_V_ERR_CA_MD_TOO_WEAK : \ +.\" No CA signature digest algorithm too weak +.El +.Sh SEE ALSO +.Xr X509_STORE_CTX_new 3 , +.Xr X509_STORE_CTX_set_verify 3 , +.Xr X509_STORE_CTX_set_verify_cb 3 , +.Xr X509_STORE_set_verify_cb 3 , +.Xr X509_up_ref 3 , +.Xr X509_verify_cert 3 +.Sh HISTORY +.Fn X509_STORE_CTX_get_error , +.Fn X509_STORE_CTX_set_error , +.Fn X509_STORE_CTX_get_error_depth , +.Fn X509_STORE_CTX_get_current_cert , +.Fn X509_STORE_CTX_get_chain , +and +.Fn X509_verify_cert_error_string +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_STORE_CTX_get1_chain +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn X509_STORE_CTX_get0_current_issuer , +.Fn X509_STORE_CTX_get0_current_crl , +and +.Fn X509_STORE_CTX_get0_parent_ctx +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +.Fn X509_STORE_CTX_get0_chain +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . +.Pp +.Fn X509_STORE_CTX_set_error_depth , +.Fn X509_STORE_CTX_set_current_cert , +.Fn X509_STORE_CTX_get_num_untrusted , +and +.Fn X509_STORE_CTX_set0_verified_chain +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/X509_STORE_CTX_get_ex_new_index.3 b/static/openbsd/man3/X509_STORE_CTX_get_ex_new_index.3 new file mode 100644 index 00000000..1c34efa9 --- /dev/null +++ b/static/openbsd/man3/X509_STORE_CTX_get_ex_new_index.3 @@ -0,0 +1,154 @@ +.\" $OpenBSD: X509_STORE_CTX_get_ex_new_index.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2009, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_STORE_CTX_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_get_ex_new_index , +.Nm X509_STORE_CTX_set_ex_data , +.Nm X509_STORE_CTX_get_ex_data , +.Nm X509_STORE_CTX_set_app_data , +.Nm X509_STORE_CTX_get_app_data +.Nd add application specific data to X509_STORE_CTX structures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft int +.Fo X509_STORE_CTX_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo X509_STORE_CTX_set_ex_data +.Fa "X509_STORE_CTX *d" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft void * +.Fo X509_STORE_CTX_get_ex_data +.Fa "X509_STORE_CTX *d" +.Fa "int idx" +.Fc +.Ft int +.Fo X509_STORE_CTX_set_app_data +.Fa "X509_STORE_CTX *d" +.Fa "void *arg" +.Fc +.Ft void * +.Fo X509_STORE_CTX_get_app_data +.Fa "X509_STORE_CTX *d" +.Fc +.Sh DESCRIPTION +These functions handle application specific data in +.Vt X509_STORE_CTX +structures. +Their usage is identical to that of +.Xr RSA_get_ex_new_index 3 , +.Xr RSA_set_ex_data 3 , +and +.Xr RSA_get_ex_data 3 . +.Pp +This mechanism is used internally by the +.Xr ssl 3 +library to store the +.Vt SSL +structure associated with a verification operation in an +.Vt X509_STORE_CTX +structure. +.Pp +.Fn X509_STORE_CTX_set_app_data +and +.Fn X509_STORE_CTX_get_app_data +are macros calling +.Fn X509_STORE_CTX_set_ex_data +and +.Fn X509_STORE_CTX_get_ex_data , +respectively, with an +.Fa idx +of 0. +.Sh RETURN VALUES +.Fn X509_STORE_CTX_get_ex_new_index +returns a new index or \-1 on failure. +.Pp +.Fn X509_STORE_CTX_set_ex_data +and +.Fn X509_STORE_CTX_set_app_data +return 1 on success or 0 on failure. +.Pp +.Fn X509_STORE_CTX_get_ex_data +and +.Fn X509_STORE_CTX_get_app_data +return the application data or +.Dv NULL +on failure. +.Dv NULL +may also be valid application data, but currently these functions +can only fail if given an invalid +.Fa idx +argument. +.Sh SEE ALSO +.Xr RSA_get_ex_new_index 3 , +.Xr X509_STORE_CTX_new 3 +.Sh HISTORY +.Fn X509_STORE_CTX_set_app_data +and +.Fn X509_STORE_CTX_get_app_data +first appeared in SSLeay 0.8.0 and +.Fn X509_STORE_CTX_get_ex_new_index , +.Fn X509_STORE_CTX_set_ex_data , +and +.Fn X509_STORE_CTX_get_ex_data +in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/X509_STORE_CTX_new.3 b/static/openbsd/man3/X509_STORE_CTX_new.3 new file mode 100644 index 00000000..4c0f8c58 --- /dev/null +++ b/static/openbsd/man3/X509_STORE_CTX_new.3 @@ -0,0 +1,366 @@ +.\" $OpenBSD: X509_STORE_CTX_new.3,v 1.28 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL aae41f8c Jun 25 09:47:15 2015 +0100 +.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Rich Salz . +.\" Copyright (c) 2009, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_STORE_CTX_NEW 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_new , +.Nm X509_STORE_CTX_init , +.Nm X509_STORE_CTX_cleanup , +.Nm X509_STORE_CTX_free , +.Nm X509_STORE_CTX_get0_store , +.Nm X509_STORE_CTX_set0_trusted_stack , +.Nm X509_STORE_CTX_trusted_stack , +.Nm X509_STORE_CTX_set_cert , +.Nm X509_STORE_CTX_get0_cert , +.\" X509_STORE_CTX_get0_chain moved to X509_STORE_CTX_get_error(3) +.Nm X509_STORE_CTX_set_chain , +.Nm X509_STORE_CTX_set0_untrusted , +.Nm X509_STORE_CTX_get0_untrusted , +.Nm X509_STORE_CTX_set0_crls +.\" X509_STORE_CTX_verify_fn moved to X509_STORE_CTX_set_verify(3) +.\" X509_STORE_CTX_set_verify moved to X509_STORE_CTX_set_verify(3) +.Nd X509_STORE_CTX initialisation +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft X509_STORE_CTX * +.Fn X509_STORE_CTX_new void +.Ft int +.Fo X509_STORE_CTX_init +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_STORE *store" +.Fa "X509 *x" +.Fa "STACK_OF(X509) *untrusted" +.Fc +.Ft void +.Fo X509_STORE_CTX_cleanup +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_free +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft X509_STORE * +.Fo X509_STORE_CTX_get0_store +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set0_trusted_stack +.Fa "X509_STORE_CTX *ctx" +.Fa "STACK_OF(X509) *trusted" +.Fc +.Ft void +.Fo X509_STORE_CTX_trusted_stack +.Fa "X509_STORE_CTX *ctx" +.Fa "STACK_OF(X509) *trusted" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_cert +.Fa "X509_STORE_CTX *ctx" +.Fa "X509 *x" +.Fc +.Ft X509 * +.Fo X509_STORE_CTX_get0_cert +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_chain +.Fa "X509_STORE_CTX *ctx" +.Fa "STACK_OF(X509) *untrusted" +.Fc +.Ft void +.Fo X509_STORE_CTX_set0_untrusted +.Fa "X509_STORE_CTX *ctx" +.Fa "STACK_OF(X509) *untrusted" +.Fc +.Ft STACK_OF(X509) * +.Fo X509_STORE_CTX_get0_untrusted +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set0_crls +.Fa "X509_STORE_CTX *ctx" +.Fa "STACK_OF(X509_CRL) *crls" +.Fc +.Sh DESCRIPTION +These functions set up an +.Vt X509_STORE_CTX +object for subsequent use by +.Xr X509_verify_cert 3 . +.Pp +.Fn X509_STORE_CTX_new +allocates an empty +.Vt X509_STORE_CTX +object not yet containing the subobjects required for normal operation. +.Pp +.Fn X509_STORE_CTX_init +needs to be called on each new +.Fa ctx +before any of the other functions become useful. +It prepares +.Fa ctx +for one single verification operation using +.Xr X509_verify_cert 3 . +The trusted certificate +.Fa store +to be used, the end entity certificate +.Fa x +to be verified, and a set of additional +.Fa untrusted +certificates, to be used for building the chain, +can be supplied, or any or all of them can be set to +.Dv NULL . +The three pointers passed in are stored internally, the three objects +pointed to are not copied, their reference count is not incremented, +and the caller remains responsible for managing their storage and for +not freeing them before +.Fn X509_STORE_CTX_free +is called on +.Fa ctx . +If a +.Fa store +is provided, the verification parameters contained in it are copied using +.Xr X509_VERIFY_PARAM_inherit 3 . +.Pp +.Fn X509_STORE_CTX_cleanup +internally cleans up +.Fa ctx , +returning it to an empty state similar to the one after +.Fn X509_STORE_CTX_new . +It can then be reused with a new call to +.Fn X509_STORE_CTX_init . +.Pp +.Fn X509_STORE_CTX_free +calls +.Fn X509_STORE_CTX_cleanup +and frees the storage pointed to by +.Fa ctx . +If +.Fa ctx +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn X509_STORE_CTX_get0_store +returns the internal pointer to the trusted certificate +.Fa store +that was set with +.Fn X509_STORE_CTX_init . +.Pp +.Fn X509_STORE_CTX_set0_trusted_stack +sets the set of +.Fa trusted +certificates used by +.Fa ctx . +This is an alternative way of specifying trusted certificates instead of +using the +.Fa store . +.Fn X509_STORE_CTX_trusted_stack +is a deprecated alias for +.Fn X509_STORE_CTX_set0_trusted_stack . +.Pp +.Fn X509_STORE_CTX_set_cert +sets the certificate to be verified in +.Fa ctx +to +.Fa x , +overriding the certificate that was set with +.Fn X509_STORE_CTX_init . +Again, the certificate is not copied +and its reference count is not incremented. +.Pp +.Fn X509_STORE_CTX_get0_cert +retrieves the internal pointer to the certificate being verified by +.Fa ctx , +i.e. the last one set using either +.Fn X509_STORE_CTX_init +or +.Fn X509_STORE_CTX_set_cert . +.Pp +.Fn X509_STORE_CTX_set_chain +and +.Fn X509_STORE_CTX_set0_untrusted +are identical and set the additional, +.Fa untrusted +certificates used by +.Fa ctx , +overriding the set of additional, untrusted certificates that was set with +.Fn X509_STORE_CTX_init . +Again, the set and the certificates contained in it are not copied +and their reference counts are not incremented. +.Pp +.Fn X509_STORE_CTX_get0_untrusted +retrieves the internal pointer +to the set of additional, untrusted certificates associated with +.Fa ctx , +i.e. the last one set using either +.Fn X509_STORE_CTX_init , +.Fn X509_STORE_CTX_set_chain , +or +.Fn X509_STORE_CTX_set0_untrusted . +.Pp +.Fn X509_STORE_CTX_set0_crls +sets a set of +.Fa crls +to use during certificate verification. +These CRLs will only be used if CRL verification is enabled in the +associated +.Vt X509_VERIFY_PARAM +structure. +This might be used where additional "useful" CRLs are supplied as part +of a protocol, for example in a PKCS#7 structure. +.Pp +Legacy applications might implicitly use an +.Vt X509_STORE_CTX +like this: +.Bd -literal -offset indent +X509_STORE_CTX ctx; +X509_STORE_CTX_init(&ctx, store, cert, chain); +.Ed +.Pp +This is +.Sy not +recommended in new applications. +They should instead do: +.Bd -literal -offset indent +X509_STORE_CTX *ctx; +ctx = X509_STORE_CTX_new(); +if (ctx == NULL) + /* Bad error */ +X509_STORE_CTX_init(ctx, store, cert, chain); +.Ed +.Sh RETURN VALUES +.Fn X509_STORE_CTX_new +returns a newly allocated context or +.Dv NULL +if an error occurred. +.Pp +.Fn X509_STORE_CTX_init +returns 1 for success or 0 if an error occurred. +.Pp +.Fn X509_STORE_CTX_get0_store +returns the internal pointer to the trusted certificate store or +.Dv NULL +if none was set. +.Pp +.Fn X509_STORE_CTX_get0_cert +returns the internal pointer to the certificate to be verified or +.Dv NULL +if no such certificate was set. +.Pp +.Fn X509_STORE_CTX_get0_untrusted +returns the internal pointer +to the set of additional, untrusted certificates or +.Dv NULL +if no set of additional certificates was provided. +.Sh SEE ALSO +.Xr X509_CRL_new 3 , +.Xr X509_STORE_CTX_get_error 3 , +.Xr X509_STORE_CTX_get_ex_new_index 3 , +.Xr X509_STORE_CTX_set_flags 3 , +.Xr X509_STORE_CTX_set_verify 3 , +.Xr X509_STORE_CTX_set_verify_cb 3 , +.Xr X509_STORE_get_by_subject 3 , +.Xr X509_STORE_new 3 , +.Xr X509_STORE_set1_param 3 , +.Xr X509_STORE_set_verify_cb 3 , +.Xr X509_verify_cert 3 , +.Xr X509_VERIFY_PARAM_inherit 3 , +.Xr X509_VERIFY_PARAM_set_flags 3 +.Sh HISTORY +.Fn X509_STORE_CTX_init , +.Fn X509_STORE_CTX_cleanup , +.Fn X509_STORE_CTX_set_cert , +and +.Fn X509_STORE_CTX_set_chain +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_STORE_CTX_new +and +.Fn X509_STORE_CTX_free +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn X509_STORE_CTX_trusted_stack +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Pp +.Fn X509_STORE_CTX_get0_store +first appeared in OpenSSL 1.0.2. +.Fn X509_STORE_CTX_set0_trusted_stack , +.Fn X509_STORE_CTX_get0_cert , +.Fn X509_STORE_CTX_set0_untrusted , +and +.Fn X509_STORE_CTX_get0_untrusted +first appeared in OpenSSL 1.1.0. +These functions have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/X509_STORE_CTX_set_flags.3 b/static/openbsd/man3/X509_STORE_CTX_set_flags.3 new file mode 100644 index 00000000..028d4da8 --- /dev/null +++ b/static/openbsd/man3/X509_STORE_CTX_set_flags.3 @@ -0,0 +1,325 @@ +.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.9 2025/06/08 22:37:23 schwarze Exp $ +.\" full merge up to: OpenSSL aae41f8c Jun 25 09:47:15 2015 +0100 +.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 Claudio Jeker +.\" Copyright (c) 2021 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 AUTHORS DISCLAIM ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2009 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_STORE_CTX_SET_FLAGS 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_set_flags , +.Nm X509_STORE_CTX_set_time , +.Nm X509_STORE_CTX_set_depth , +.Nm X509_STORE_CTX_set_trust , +.Nm X509_STORE_CTX_set_purpose , +.Nm X509_STORE_CTX_get0_param , +.Nm X509_STORE_CTX_set0_param , +.Nm X509_STORE_CTX_set_default +.Nd X509_STORE_CTX parameter initialisation +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft void +.Fo X509_STORE_CTX_set_flags +.Fa "X509_STORE_CTX *ctx" +.Fa "unsigned long flags" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_time +.Fa "X509_STORE_CTX *ctx" +.Fa "unsigned long dummy" +.Fa "time_t time" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_depth +.Fa "X509_STORE_CTX *ctx" +.Fa "int depth" +.Fc +.Ft int +.Fo X509_STORE_CTX_set_trust +.Fa "X509_STORE_CTX *ctx" +.Fa "int trust" +.Fc +.Ft int +.Fo X509_STORE_CTX_set_purpose +.Fa "X509_STORE_CTX *ctx" +.Fa "int purpose" +.Fc +.Ft X509_VERIFY_PARAM * +.Fo X509_STORE_CTX_get0_param +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set0_param +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_VERIFY_PARAM *param" +.Fc +.Ft int +.Fo X509_STORE_CTX_set_default +.Fa "X509_STORE_CTX *ctx" +.Fa "const char *name" +.Fc +.Sh DESCRIPTION +These functions operate on the +.Vt X509_VERIFY_PARAM +object used by +.Fa ctx . +Usually, +.Xr X509_STORE_CTX_init 3 +is called on +.Fa ctx +before these functions, and +.Xr X509_verify_cert 3 +afterwards. +.Pp +.Fn X509_STORE_CTX_set_flags +sets the internal verification parameter flags to +.Fa flags . +See +.Xr X509_VERIFY_PARAM_set_flags 3 +for a description of the verification flags. +.Pp +.Fn X509_STORE_CTX_set_time +sets the verification +.Fa time +using +.Xr X509_VERIFY_PARAM_set_time 3 . +The +.Fa dummy +argument is ignored. +.Pp +.Fn X509_STORE_CTX_set_depth +sets the maximum verification +.Fa depth +using +.Xr X509_VERIFY_PARAM_set_depth 3 . +That is the maximum number of untrusted CA certificates +that can appear in a chain. +.Pp +.Fn X509_STORE_CTX_set_trust +sets the +.Fa trust +identifier that can also be set using +.Xr X509_VERIFY_PARAM_set_trust 3 . +If the +.Fa trust +argument is 0 or invalid +or the trust identifier is already set to a non-zero value in the +.Vt X509_VERIFY_PARAM +object, no action occurs. +.Pp +.Fn X509_STORE_CTX_set_purpose +sets the +.Fa purpose +identifier that can also be set using +.Xr X509_VERIFY_PARAM_set_purpose 3 . +If the +.Fa purpose +argument is 0 or any failure occurs, nothing is changed. +.Pp +In the following, the trust identifier contained in the +.Vt X509_PURPOSE +object associated with +.Fa purpose +is called the +.Dq associated trust . +.Pp +The function fails if the +.Fa purpose +argument or the associated trust is invalid but not 0; otherwise, +.Fn X509_STORE_CTX_set_purpose +also does the equivalent of calling +.Fn X509_STORE_CTX_set_trust +with the associated trust. +.Pp +If the purpose identifier is already set to a non-zero value in the +.Vt X509_VERIFY_PARAM +object, it is not changed, even if the +.Fa purpose +argument is valid, too. +.Pp +.Fn X509_STORE_CTX_get0_param +retrieves an internal pointer to the verification parameters associated +with +.Fa ctx . +.Pp +.Fn X509_STORE_CTX_set0_param +sets the internal verification parameter pointer to +.Fa param . +After this call +.Fa param +should not be used. +.Pp +.Fn X509_STORE_CTX_set_default +looks up and sets the default verification method to +.Fa name . +This uses the function +.Xr X509_VERIFY_PARAM_lookup 3 +to find an appropriate set of parameters from +.Fa name +and copies them using +.Xr X509_VERIFY_PARAM_inherit 3 . +.Sh RETURN VALUES +.Fn X509_STORE_CTX_set_trust +returns 1 if the +.Fa trust +argument is 0 or valid or 0 if it is invalid but not 0. +A return value of 1 does +.Em not +imply that the trust identifier stored in the +.Vt X509_VERIFY_PARAM +object was changed. +.Pp +.Fn X509_STORE_CTX_set_purpose +returns 1 if both the +.Fa purpose +argument and the associated trust are 0 or valid. +It returns 0 if either the +.Fa purpose +argument or the associated trust is invalid but not 0. +A return value of 1 does not imply that any data was changed. +.Pp +.Fn X509_STORE_CTX_get0_param +returns a pointer to an +.Vt X509_VERIFY_PARAM +structure or +.Dv NULL +if an error occurred. +.Pp +.Fn X509_STORE_CTX_set_default +returns 1 for success or 0 if an error occurred. +.Sh ERRORS +The following diagnostics can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv X509_R_UNKNOWN_TRUST_ID Qq "unknown trust id" +.Fn X509_STORE_CTX_set_trust +was called with a +.Fa trust +argument that is invalid but not 0. +Other implementations may also return this when +.Fn X509_STORE_CTX_set_purpose +is called with a +.Fa purpose +argument with invalid associated trust. +.It Dv X509_R_UNKNOWN_PURPOSE_ID Qq "unknown purpose id" +The +.Fa purpose +argument is invalid but not 0. +.El +.Pp +The other functions provide no diagnostics. +.Sh SEE ALSO +.Xr X509_STORE_CTX_get_error 3 , +.Xr X509_STORE_CTX_new 3 , +.Xr X509_STORE_CTX_set_verify 3 , +.Xr X509_STORE_CTX_set_verify_cb 3 , +.Xr X509_STORE_new 3 , +.Xr X509_STORE_set1_param 3 , +.Xr X509_STORE_set_verify_cb 3 , +.Xr X509_verify_cert 3 , +.Xr X509_VERIFY_PARAM_new 3 , +.Xr X509_VERIFY_PARAM_set_flags 3 +.Sh HISTORY +.Fn X509_STORE_CTX_set_depth +first appeared in OpenSSL 0.9.3 and has been available since +.Ox 2.4 . +.Pp +.Fn X509_STORE_CTX_set_trust +and +.Fn X509_STORE_CTX_set_purpose +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn X509_STORE_CTX_set_flags +and +.Fn X509_STORE_CTX_set_time +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Pp +.Fn X509_STORE_CTX_get0_param , +.Fn X509_STORE_CTX_set0_param , +and +.Fn X509_STORE_CTX_set_default +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Sh CAVEATS +The precise effect of a successful call to +.Fn X509_STORE_CTX_set_trust +and +.Fn X509_STORE_CTX_set_purpose +is unclear unless only one of these functions is used immediately after +.Xr X509_STORE_CTX_init 3 . +It is therefore recommended to use +.Fn X509_STORE_CTX_get0_param , +.Xr X509_VERIFY_PARAM_set_trust 3 , +and +.Xr X509_VERIFY_PARAM_set_purpose 3 +instead. diff --git a/static/openbsd/man3/X509_STORE_CTX_set_verify.3 b/static/openbsd/man3/X509_STORE_CTX_set_verify.3 new file mode 100644 index 00000000..4a319ed8 --- /dev/null +++ b/static/openbsd/man3/X509_STORE_CTX_set_verify.3 @@ -0,0 +1,257 @@ +.\" $OpenBSD: X509_STORE_CTX_set_verify.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021, 2022 Ingo Schwarze +.\" Copyright (c) 2023 Job Snijders +.\" +.\" 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: June 8 2025 $ +.Dt X509_STORE_CTX_SET_VERIFY 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_verify_fn , +.Nm X509_STORE_CTX_set_verify , +.Nm X509_STORE_CTX_get_verify , +.Nm X509_STORE_set_verify , +.Nm X509_STORE_set_verify_func , +.Nm X509_STORE_get_verify , +.Nm X509_STORE_CTX_check_issued_fn , +.Nm X509_STORE_set_check_issued , +.Nm X509_STORE_get_check_issued , +.Nm X509_STORE_CTX_get_check_issued +.Nd user-defined certificate chain verification function +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft typedef int +.Fo (*X509_STORE_CTX_verify_fn) +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_verify +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_STORE_CTX_verify_fn verify" +.Fc +.Ft X509_STORE_CTX_verify_fn +.Fo X509_STORE_CTX_get_verify +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_set_verify +.Fa "X509_STORE *store" +.Fa "X509_STORE_CTX_verify_fn verify" +.Fc +.Ft void +.Fo X509_STORE_set_verify_func +.Fa "X509_STORE *store" +.Fa "X509_STORE_CTX_verify_fn verify" +.Fc +.Ft X509_STORE_CTX_verify_fn +.Fo X509_STORE_get_verify +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft typedef int +.Fo (*X509_STORE_CTX_check_issued_fn) +.Fa "X509_STORE_CTX *ctx" +.Fa "X509 *subject" +.Fa "X509 *issuer" +.Fc +.Ft void +.Fo X509_STORE_set_check_issued +.Fa "X509_STORE *store" +.Fa "X509_STORE_CTX_check_issued_fn check_issued" +.Fc +.Ft X509_STORE_CTX_check_issued_fn +.Fo X509_STORE_get_check_issued +.Fa "X509_STORE *store" +.Fc +.Ft X509_STORE_CTX_check_issued_fn +.Fo X509_STORE_CTX_get_check_issued +.Fa "X509_STORE_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn X509_STORE_CTX_set_verify +configures +.Fa ctx +to use the +.Fa verify +argument as the X.509 certificate chain verification function instead +of the default verification function built into the library when +.Xr X509_verify_cert 3 +is called. +.Pp +The +.Fa verify +function provided by the user is only called if the +.Dv X509_V_FLAG_LEGACY_VERIFY +or +.Dv X509_V_FLAG_NO_ALT_CHAINS +flag was set on +.Fa ctx +using +.Xr X509_STORE_CTX_set_flags 3 +or +.Xr X509_VERIFY_PARAM_set_flags 3 . +Otherwise, it is ignored and a different algorithm is used that does +not support replacing the verification function. +.Pp +.Fn X509_STORE_set_verify +saves the function pointer +.Fa verify +in the given +.Fa store +object. +That pointer will be copied to an +.Vt X509_STORE_CTX +object when +.Fa store +is later passed as an argument to +.Xr X509_STORE_CTX_init 3 . +.Pp +.Fn X509_STORE_set_verify_func +is an alias for +.Fn X509_STORE_set_verify +implemented as a macro. +.Pp +.Fn X509_STORE_set_check_issued +saves the function pointer +.Fa check_issued +in the given +.Fa store +object. +That pointer will be copied to an +.Vt X509_STORE_CTX +object when +.Fa store +is later passed as an argument to +.Fn X509_STORE_CTX_init 3 . +.Pp +The +.Fa check_issued +function provided by the user should check whether a given certificate +.Fa subject +was issued using the CA certificate +.Fa issuer , +and must return 0 on failure and 1 on success. +The default implementation ignores the +.Fa ctx +argument and returns success if and only if +.Xr X509_check_issued 3 +returns +.Dv X509_V_OK . +It is important to pay close attention to the order of the +.Fa issuer +and +.Fa subject +arguments. +In +.Xr X509_check_issued 3 +the +.Fa issuer +precedes the +.Fa subject +while in +.Fn check_issued +the +.Fa subject +comes first. +.Sh RETURN VALUES +.Fn X509_STORE_CTX_verify_fn +is supposed to return 1 to indicate that the chain is valid +or 0 if it is not or if an error occurred. +.Pp +.Fn X509_STORE_CTX_get_verify +returns a function pointer previously set with +.Fn X509_STORE_CTX_set_verify +or +.Xr X509_STORE_CTX_init 3 , +or +.Dv NULL +if +.Fa ctx +is uninitialized. +.Pp +.Fn X509_STORE_get_verify +returns the function pointer previously set with +.Fn X509_STORE_set_verify , +or +.Dv NULL +if that function was not called on the +.Fa store . +.Pp +.Fn X509_STORE_get_check_issued +returns the function pointer previously set with +.Fn X509_STORE_set_check_issued , +or +.Dv NULL +if that function was not called on the +.Fa store . +.Pp +.Fn X509_STORE_CTX_get_check_issued +returns the +.Fn check_issued +function pointer set on the +.Vt X509_STORE_CTX . +This is either the +.Fn check_issued +function inherited from the +.Fa store +used in +.Xr X509_STORE_CTX_init 3 +or the library's default implementation. +.Sh SEE ALSO +.Xr X509_check_issued 3 , +.Xr X509_STORE_CTX_init 3 , +.Xr X509_STORE_CTX_set_error 3 , +.Xr X509_STORE_CTX_set_flags 3 , +.Xr X509_STORE_CTX_set_verify_cb 3 , +.Xr X509_STORE_new 3 , +.Xr X509_STORE_set_flags 3 , +.Xr X509_STORE_set_verify_cb 3 , +.Xr X509_verify_cert 3 , +.Xr X509_VERIFY_PARAM_set_flags 3 +.Sh HISTORY +.Fn X509_STORE_set_verify_func +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . +.Pp +.Fn X509_STORE_CTX_set_verify +and +.Fn X509_STORE_CTX_get_verify +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . +.Pp +.Fn X509_STORE_CTX_verify_fn , +.Fn X509_STORE_set_verify , +and +.Fn X509_STORE_get_verify +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.2 . +.Pp +.Fn X509_STORE_set_check_issued , +.Fn X509_STORE_get_check_issued , +and +.Fn X509_STORE_CTX_get_check_issued +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.3 . +.Sh BUGS +The reversal of order of +.Fa subject +and +.Fa issuer +between +.Fn check_issued +and +.Xr X509_check_issued 3 +is very confusing. +It has led to bugs and will cause many more. diff --git a/static/openbsd/man3/X509_STORE_CTX_set_verify_cb.3 b/static/openbsd/man3/X509_STORE_CTX_set_verify_cb.3 new file mode 100644 index 00000000..29f1e79b --- /dev/null +++ b/static/openbsd/man3/X509_STORE_CTX_set_verify_cb.3 @@ -0,0 +1,310 @@ +.\" $OpenBSD: X509_STORE_CTX_set_verify_cb.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400 +.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2009 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_STORE_CTX_SET_VERIFY_CB 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_verify_cb , +.Nm X509_STORE_CTX_set_verify_cb , +.Nm X509_STORE_CTX_get_verify_cb +.Nd set and retrieve verification callback +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft typedef int +.Fo (*X509_STORE_CTX_verify_cb) +.Fa "int ok" +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_verify_cb +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_STORE_CTX_verify_cb verify_cb" +.Fc +.Ft X509_STORE_CTX_verify_cb +.Fo X509_STORE_CTX_get_verify_cb +.Fa "X509_STORE_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn X509_STORE_CTX_set_verify_cb +sets the verification callback of +.Fa ctx +to +.Fa verify_cb +overwriting any existing callback. +.Pp +The verification callback can be used to modify the operation of +certificate verification, either by overriding error conditions or +logging errors for debugging purposes. +The use of a verification callback is not essential, and should not +be used in security sensitive programs. +.Pp +Do not use this function. +It is extremely fragile and unpredictable. +This callback exposes implementation details of certificate verification, +which change as the library evolves. +Attempting to use it for security checks can introduce vulnerabilities if +making incorrect assumptions about when the callback is called. +Additionally, overriding +.Fa ok +may leave +.Fa ctx +in an inconsistent state and break invariants. +.Pp +Instead, customize certificate verification by configuring options on the +.Vt X509_STORE_CTX +before verification, or applying additional checks after +.Xr X509_verify_cert 3 +completes successfully. +.Pp +The +.Fa ok +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. +As the default behaviour is internal to the verifier, and possibly unknown +to the caller, changing this parameter is inherently dangerous and should not +normally be done except for debugging purposes, and should not be expected to +be consistent if the verifier changes. +If the flag +.Dv X509_V_FLAG_NOTIFY_POLICY +is set, then +.Fa ok +is set to 2 to indicate the policy checking is complete. +.Pp +The +.Fa ctx +parameter to the callback is the +.Vt X509_STORE_CTX +structure that is performing the verification operation. +A callback can examine this structure and receive additional information +about the error, for example by calling +.Xr X509_STORE_CTX_get_current_cert 3 . +Additional application data can be passed to the callback via the +.Sy ex_data +mechanism. +.Pp +The verification callback can be set and inherited from the parent +structure performing the operation. +In some cases (such as S/MIME verification) the +.Vt X509_STORE_CTX +structure is created and destroyed internally and the only way to set a +custom verification callback is by inheriting it from the associated +.Vt X509_STORE . +.Sh RETURN VALUES +.Fn X509_STORE_CTX_get_verify_cb +returns a pointer to the current callback function +used by the specified +.Fa ctx . +If no callback was set using +.Fn X509_STORE_CTX_set_verify_cb , +that is a pointer to a built-in static function +which does nothing except returning the +.Fa ok +argument passed to it. +.Sh EXAMPLES +Default callback operation: +.Bd -literal +int +verify_callback(int ok, X509_STORE_CTX *ctx) +{ + return ok; +} +.Ed +.Pp +This is likely the only safe callback to use. +.Pp +Simple and terrible example that should not be used. +Suppose a certificate in the chain is expired and we +wish to continue after this error: +.Bd -literal +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't override */ + return ok; +} +.Ed +.Pp +While this example is presented for historical purposes, +this is not the correct way to accomplish this. +The verification flag +.Dv X509_V_FLAG_NO_CHECK_TIME +should be set on the +.Vt STORE_CTX +using +.Xr X509_VERIFY_PARAM_set_flags 3 +instead. +.Pp +Full featured debugging logging callback - note that the output and +order that things happen from this can change over time and should not +be parsed or expected to be consistent. +In this case the +.Fa bio_err +is assumed to be a global logging +.Vt BIO , +an alternative would to store a +.Vt BIO +in +.Fa ctx +using +.Sy ex_data . +.Bd -literal +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); +} +.Ed +.Sh SEE ALSO +.Xr X509_STORE_CTX_get_error 3 , +.Xr X509_STORE_CTX_get_ex_new_index 3 , +.Xr X509_STORE_CTX_new 3 , +.Xr X509_STORE_CTX_set_error 3 , +.Xr X509_STORE_CTX_set_flags 3 , +.Xr X509_STORE_CTX_set_verify 3 , +.Xr X509_STORE_set_verify_cb 3 , +.Xr X509_verify_cert 3 , +.Xr X509_VERIFY_PARAM_set_flags 3 +.Sh HISTORY +.Fn X509_STORE_CTX_set_verify_cb +first appeared in OpenSSL 0.9.6c and has been available since +.Ox 3.2 . +.Pp +.Fn X509_STORE_CTX_get_verify_cb +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.1 . +.Pp +.Fn X509_STORE_CTX_verify_cb +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.2 . +.Sh CAVEATS +In general a verification callback should +.Sy NOT +return a changed value of +.Fa ok +because this can allow the verification to appear to succeed +in an unpredictable way. +This can effectively remove all security from the application because +untrusted or invalid certificates may be accepted. +Doing this can possibly make +.Xr X509_verify_cert 3 +return what appears to be a validated chain of certificates that has not +been validated or even had the signatures checked. diff --git a/static/openbsd/man3/X509_STORE_get_by_subject.3 b/static/openbsd/man3/X509_STORE_get_by_subject.3 new file mode 100644 index 00000000..a8379ad5 --- /dev/null +++ b/static/openbsd/man3/X509_STORE_get_by_subject.3 @@ -0,0 +1,247 @@ +.\" $OpenBSD: X509_STORE_get_by_subject.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021, 2023 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 $Mdocdate: June 8 2025 $ +.Dt X509_STORE_GET_BY_SUBJECT 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_get_by_subject , +.Nm X509_STORE_CTX_get_obj_by_subject , +.Nm X509_STORE_CTX_get1_certs , +.Nm X509_STORE_CTX_get1_crls , +.Nm X509_STORE_CTX_get1_issuer , +.Nm X509_STORE_get_by_subject , +.Nm X509_STORE_get1_certs , +.Nm X509_STORE_get1_crls +.Nd retrieve objects from a certificate store +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft int +.Fo X509_STORE_CTX_get_by_subject +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_LOOKUP_TYPE type" +.Fa "X509_NAME *name" +.Fa "X509_OBJECT *object" +.Fc +.Ft X509_OBJECT * +.Fo X509_STORE_CTX_get_obj_by_subject +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_LOOKUP_TYPE type" +.Fa "X509_NAME *name" +.Fc +.Ft STACK_OF(X509) * +.Fo X509_STORE_CTX_get1_certs +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_NAME *name" +.Fc +.Ft STACK_OF(X509_CRL) * +.Fo X509_STORE_CTX_get1_crls +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_NAME *name" +.Fc +.Ft int +.Fo X509_STORE_CTX_get1_issuer +.Fa "X509 **issuer" +.Fa "X509_STORE_CTX *ctx" +.Fa "X509 *certificate" +.Fc +.Ft int +.Fo X509_STORE_get_by_subject +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_LOOKUP_TYPE type" +.Fa "X509_NAME *name" +.Fa "X509_OBJECT *object" +.Fc +.Ft STACK_OF(X509) * +.Fo X509_STORE_get1_certs +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_NAME *name" +.Fc +.Ft STACK_OF(X509_CRL) * +.Fo X509_STORE_get1_crls +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_NAME *name" +.Fc +.Sh DESCRIPTION +.Fn X509_STORE_CTX_get_by_subject +retrieves the first object having a matching +.Fa type +and +.Fa name +from the +.Vt X509_STORE +associated with the +.Fa ctx . +The +.Fa type +can be +.Dv X509_LU_X509 +to retrieve a certificate or +.Dv X509_LU_CRL +to retrieve a revocation list. +.Pp +If the store does not yet contain a matching object or if the type is +.Dv X509_LU_CRL , +a lookup by subject is performed on +.Vt X509_LOOKUP +objects associated with the store until a match is found, +which may add zero or more objects to the store. +.Pp +In case of success, the content of the +.Fa object +provided by the caller is overwritten with a pointer to the first +match, and the reference count of that certificate or revocation +list is incremented by 1. +Avoiding a memory leak by making sure the provided +.Fa object +is empty is the responsibility of the caller. +.Pp +.Fn X509_STORE_CTX_get_obj_by_subject +is similar except that a new object is allocated and returned. +.Pp +.Fn X509_STORE_CTX_get1_certs +retrieves all certificates matching the subject +.Vt name +from the +.Vt X509_STORE +associated with +.Fa ctx . +If there are none yet, +.Fn X509_STORE_CTX_get_by_subject +is called to try and add some. +In case of success, the reference counts of all certificates +added to the returned array are incremented by 1. +.Pp +.Fn X509_STORE_CTX_get1_crls +is similar except that it operates on certificate revocation lists +rather than on certificates and that it always calls +.Fn X509_STORE_CTX_get_by_subject , +even if the +.Vt X509_STORE +already contains a matching revocation list. +.Pp +.Fn X509_STORE_CTX_get1_issuer +retrieves the +.Fa issuer +CA certificate for the given +.Fa certificate +from the +.Vt X509_STORE +associated with +.Fa ctx . +Internally, the issuer name is retrieved with +.Xr X509_get_issuer_name 3 +and the candidate issuer CA certificate with +.Fn X509_STORE_X509_get_by_subject +using that issuer name. +.Xr X509_check_issued 3 +or a user-supplied replacement function is used to check whether the +.Fa certificate +was indeed issued using the +.Fa issuer +CA certificate before returning it. +If verification parameters associated with +.Fa ctx +encourage checking of validity times, CAs with a valid time are +preferred, but if no matching CA has a valid time, one with an +invalid time is accepted anyway. +.Pp +The following are deprecated aliases implemented as macros: +.Bl -column X509_STORE_get_by_subject F X509_STORE_CTX_get_by_subject +.It Fn X509_STORE_get_by_subject Ta for Ta Fn X509_STORE_CTX_get_by_subject +.It Fn X509_STORE_get1_certs Ta for Ta Fn X509_STORE_CTX_get1_certs +.It Fn X509_STORE_get1_crls Ta for Ta Fn X509_STORE_CTX_get1_crls +.El +.Sh RETURN VALUES +.Fn X509_STORE_CTX_get_by_subject +and +.Fn X509_STORE_get_by_subject +return 1 if a match is found or 0 on failure. +In addition to simply not finding a match, +they may also fail due to memory allocation failure. +With library implementations other than LibreSSL, +they might also return negative values for internal errors. +.Pp +.Fn X509_STORE_CTX_get_obj_by_subject +returns the new object or +.Dv NULL +on failure, in particular if no match is found or memory allocation fails. +.Pp +.Fn X509_STORE_CTX_get1_certs +and +.Fn X509_STORE_get1_certs +return a newly allocated and populated array of certificates or +.Dv NULL +on failure. +They fail if no match is found, if +.Fn X509_STORE_CTX_get_by_subject +fails, or if memory allocation fails. +.Pp +.Fn X509_STORE_CTX_get1_crls +and +.Fn X509_STORE_get1_crls +return a newly allocated and populated array of CRLs or +.Dv NULL +on failure. +They fail if +.Fn X509_STORE_CTX_get_by_subject +finds no new match, even if the associated +.Vt X509_STORE +already contains matching CRLs, or if memory allocation fails. +.Pp +.Fn X509_STORE_CTX_get1_issuer +returns 1 if a matching +.Fa issuer +CA certificate is found or 0 otherwise. +With library implementations other than LibreSSL, +it might also return negative values for internal errors. +.Sh SEE ALSO +.Xr STACK_OF 3 , +.Xr X509_check_issued 3 , +.Xr X509_CRL_new 3 , +.Xr X509_get_issuer_name 3 , +.Xr X509_NAME_new 3 , +.Xr X509_new 3 , +.Xr X509_OBJECT_retrieve_by_subject 3 , +.Xr X509_STORE_CTX_new 3 , +.Xr X509_VERIFY_PARAM_set_flags 3 +.Sh HISTORY +.Fn X509_STORE_get_by_subject +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . +.Pp +.Fn X509_STORE_CTX_get1_issuer +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Pp +.Fn X509_STORE_get1_certs +and +.Fn X509_STORE_get1_crls +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +.Fn X509_STORE_CTX_get_by_subject +and +.Fn X509_STORE_CTX_get_obj_by_subject +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . +.Pp +.Fn X509_STORE_CTX_get1_certs +and +.Fn X509_STORE_CTX_get1_crls +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.4 . diff --git a/static/openbsd/man3/X509_STORE_load_locations.3 b/static/openbsd/man3/X509_STORE_load_locations.3 new file mode 100644 index 00000000..d876ef83 --- /dev/null +++ b/static/openbsd/man3/X509_STORE_load_locations.3 @@ -0,0 +1,189 @@ +.\" $OpenBSD: X509_STORE_load_locations.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL X509_STORE_add_cert b0edda11 Mar 20 13:00:17 2018 +0000 +.\" +.\" Copyright (c) 2017, 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_STORE_LOAD_LOCATIONS 3 +.Os +.Sh NAME +.Nm X509_STORE_load_locations , +.Nm X509_STORE_set_default_paths , +.Nm X509_STORE_load_mem , +.Nm X509_STORE_add_lookup +.Nd configure files and directories used by a certificate store +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft int +.Fo X509_STORE_load_locations +.Fa "X509_STORE *store" +.Fa "const char *file" +.Fa "const char *dirs" +.Fc +.Ft int +.Fo X509_STORE_set_default_paths +.Fa "X509_STORE *store" +.Fc +.Ft int +.Fo X509_STORE_load_mem +.Fa "X509_STORE *store" +.Fa "void *buffer" +.Fa "int length" +.Fc +.Ft X509_LOOKUP * +.Fo X509_STORE_add_lookup +.Fa "X509_STORE *store" +.Fa "const X509_LOOKUP_METHOD *method" +.Fc +.Sh DESCRIPTION +.Fn X509_STORE_load_locations +instructs the +.Fa store +to use the PEM +.Fa file +and all the PEM files in the directories +contained in the colon-separated list +.Fa dirs +for looking up certificates, in addition to files and directories +that are already configured. +The certificates in the directories must be in hashed form, as documented in +.Xr X509_LOOKUP_hash_dir 3 . +Directories already in use are not added again. +If +.Dv NULL +is passed for +.Fa file +or +.Fa dirs , +no new file or no new directories are added, respectively. +.Pp +.Fn X509_STORE_load_locations +is identical to +.Xr SSL_CTX_load_verify_locations 3 +except that it operates directly on an +.Vt X509_STORE +object, rather than on the store used by an SSL context. +See that manual page for more information. +.Pp +.Fn X509_STORE_set_default_paths +is similar except that it instructs the +.Fa store +to use the default PEM file and directory +(as documented in +.Sx FILES ) +in addition to what is already configured. +It ignores errors that occur while trying to load the file or to +add the directory, but it may still fail for other reasons, for +example when out of memory while trying to allocate the required +.Vt X509_LOOKUP +objects. +.Pp +.Fn X509_STORE_set_default_paths +is identical to +.Xr SSL_CTX_set_default_verify_paths 3 +except that it operates directly on an +.Vt X509_STORE +object, rather than on the store used by an SSL context. +See that manual page for more information. +.Pp +The above functions are wrappers around +.Xr X509_LOOKUP_load_file 3 +and +.Xr X509_LOOKUP_add_dir 3 . +.Pp +.Fn X509_STORE_load_mem +instructs the +.Fa store +to use the certificates contained in the memory +.Fa buffer +of the given +.Fa length +for certificate lookup. +It is a wrapper around +.Xr X509_LOOKUP_add_mem 3 . +.Pp +.Fn X509_STORE_add_lookup +checks whether the +.Fa store +already contains an +.Vt X509_LOOKUP +object using the given +.Fa method ; +if it does, the existing object is returned and no other action occurs. +Otherwise, a new +.Vt X509_LOOKUP +object is allocated, added, and returned. +This function is used internally by all the functions listed above. +.Sh RETURN VALUES +.Fn X509_STORE_load_locations +returns 1 if all files and directories specified were successfully +added. +It returns 0 for failure. +That can happen if adding the file failed, if adding any of the +directories failed, or if both arguments were +.Dv NULL . +.Pp +.Fn X509_STORE_set_default_paths +returns 0 for some error conditions and 1 otherwise, not just for +success, but also for various cases of failure. +.Pp +.Fn X509_STORE_load_mem +returns 1 for success or 0 for failure. +In particular, parse errors or lack of memory can cause failure. +.Pp +.Fn X509_STORE_add_lookup +returns the existing or new lookup object or +.Dv NULL +on failure. +This is an internal pointer that must not be freed. +With LibreSSL, the only reason for failure is lack of memory. +.Sh FILES +.Bl -tag -width Ds +.It Pa /etc/ssl/cert.pem +default PEM file for +.Fn X509_STORE_set_default_paths +.It Pa /etc/ssl/certs/ +default directory for +.Fn X509_STORE_set_default_paths +.El +.Sh SEE ALSO +.Xr SSL_CTX_load_verify_locations 3 , +.Xr X509_load_cert_file 3 , +.Xr X509_LOOKUP_hash_dir 3 , +.Xr X509_LOOKUP_new 3 , +.Xr X509_STORE_new 3 , +.Xr X509_STORE_set1_param 3 , +.Xr X509_STORE_set_verify_cb 3 +.Sh HISTORY +.Fn X509_STORE_load_locations , +.Fn X509_STORE_set_default_paths , +and +.Fn X509_STORE_add_lookup +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_STORE_load_mem +first appeared in +.Ox 5.7 . +.Sh BUGS +By the time that adding a directory is found to have failed, +the file and some other directories may already have been successfully loaded, +so these functions may change the state of the store even when they fail. +.Pp +.Fn X509_STORE_set_default_paths +clears the error queue, deleting even error information that was +already present when it was called. diff --git a/static/openbsd/man3/X509_STORE_new.3 b/static/openbsd/man3/X509_STORE_new.3 new file mode 100644 index 00000000..e1d146da --- /dev/null +++ b/static/openbsd/man3/X509_STORE_new.3 @@ -0,0 +1,146 @@ +.\" $OpenBSD: X509_STORE_new.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 05ea606a May 20 20:52:46 2016 -0400 +.\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018 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. +.\" +.\" The original file was written by +.\" Alessandro Ghedini . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_STORE_NEW 3 +.Os +.Sh NAME +.Nm X509_STORE_new , +.Nm X509_STORE_up_ref , +.Nm X509_STORE_free +.Nd allocate and free X.509 certificate stores +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft X509_STORE * +.Fn X509_STORE_new void +.Ft int +.Fo X509_STORE_up_ref +.Fa "X509_STORE *store" +.Fc +.Ft void +.Fo X509_STORE_free +.Fa "X509_STORE *store" +.Fc +.Sh DESCRIPTION +.Fn X509_STORE_new +allocates and initializes an empty X.509 certificate store +and sets its reference count to 1. +.Pp +.Fn X509_STORE_up_ref +increments the reference count of +.Fa store +by 1. +.Pp +.Fn X509_STORE_free +decrements the reference count of +.Fa store +by 1. +If the reference count reaches 0, +all resources used by the store, including all certificates +contained in it, are released and +.Fa store +itself is freed. +If +.Fa store +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn X509_STORE_new +returns a newly created +.Vt X509_STORE +object or +.Dv NULL +if an error occurs. +.Pp +.Fn X509_STORE_up_ref +returns 1 for success and 0 for failure. +.Sh SEE ALSO +.Xr PKCS7_verify 3 , +.Xr SSL_CTX_set_cert_store 3 , +.Xr X509_load_cert_file 3 , +.Xr X509_LOOKUP_hash_dir 3 , +.Xr X509_OBJECT_get0_X509 3 , +.Xr X509_STORE_CTX_new 3 , +.Xr X509_STORE_get_ex_new_index 3 , +.Xr X509_STORE_load_locations 3 , +.Xr X509_STORE_set1_param 3 , +.Xr X509_STORE_set_verify_cb 3 , +.Xr X509_verify_cert 3 +.Sh HISTORY +.Fn X509_STORE_new +and +.Fn X509_STORE_free +first appeared in SSLeay 0.8.0 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_STORE_up_ref +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/X509_STORE_set1_param.3 b/static/openbsd/man3/X509_STORE_set1_param.3 new file mode 100644 index 00000000..d96a33a8 --- /dev/null +++ b/static/openbsd/man3/X509_STORE_set1_param.3 @@ -0,0 +1,269 @@ +.\" $OpenBSD: X509_STORE_set1_param.3,v 1.23 2025/06/08 22:40:30 schwarze Exp $ +.\" content checked up to: +.\" OpenSSL man3/X509_STORE_add_cert b0edda11 Mar 20 13:00:17 2018 +0000 +.\" OpenSSL man3/X509_STORE_get0_param e90fc053 Jul 15 09:39:45 2017 -0400 +.\" +.\" Copyright (c) 2018 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 $Mdocdate: June 8 2025 $ +.Dt X509_STORE_SET1_PARAM 3 +.Os +.Sh NAME +.Nm X509_STORE_set1_param , +.Nm X509_STORE_set_flags , +.Nm X509_STORE_set_purpose , +.Nm X509_STORE_set_trust , +.Nm X509_STORE_set_depth , +.Nm X509_STORE_add_cert , +.Nm X509_STORE_add_crl , +.Nm X509_STORE_get0_param , +.Nm X509_STORE_get1_objects , +.Nm X509_STORE_get0_objects , +.Nm X509_STORE_get_ex_new_index , +.Nm X509_STORE_set_ex_data , +.Nm X509_STORE_get_ex_data +.Nd get and set X509_STORE data +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft int +.Fo X509_STORE_set1_param +.Fa "X509_STORE *store" +.Fa "X509_VERIFY_PARAM *pm" +.Fc +.Ft int +.Fo X509_STORE_set_flags +.Fa "X509_STORE *store" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo X509_STORE_set_purpose +.Fa "X509_STORE *store" +.Fa "int purpose" +.Fc +.Ft int +.Fo X509_STORE_set_trust +.Fa "X509_STORE *store" +.Fa "int trust" +.Fc +.Ft int +.Fo X509_STORE_set_depth +.Fa "X509_STORE *store" +.Fa "int depth" +.Fc +.Ft int +.Fo X509_STORE_add_cert +.Fa "X509_STORE *store" +.Fa "X509 *x" +.Fc +.Ft int +.Fo X509_STORE_add_crl +.Fa "X509_STORE *store" +.Fa "X509_CRL *crl" +.Fc +.Ft X509_VERIFY_PARAM * +.Fo X509_STORE_get0_param +.Fa "X509_STORE *store" +.Fc +.Ft STACK_OF(X509_OBJECT) * +.Fo X509_STORE_get1_objects +.Fa "X509_STORE *store" +.Fc +.Ft STACK_OF(X509_OBJECT) * +.Fo X509_STORE_get0_objects +.Fa "X509_STORE *store" +.Fc +.Ft int +.Fo X509_STORE_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo X509_STORE_set_ex_data +.Fa "X509_STORE *store" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft void * +.Fo X509_STORE_get_ex_data +.Fa "X509_STORE *store" +.Fa "int idx" +.Fc +.Sh DESCRIPTION +.Fn X509_STORE_set1_param +copies the verification parameters from +.Fa pm +using +.Xr X509_VERIFY_PARAM_set1 3 +into the verification parameter object contained in the +.Fa store . +.Pp +.Fn X509_VERIFY_PARAM_set_flags , +.Fn X509_STORE_set_purpose , +.Fn X509_STORE_set_trust , +and +.Fn X509_STORE_set_depth +call +.Fn X509_VERIFY_PARAM_set_flags , +.Fn X509_VERIFY_PARAM_set_purpose , +.Fn X509_VERIFY_PARAM_set_trust , +and +.Fn X509_VERIFY_PARAM_set_depth +on the verification parameter object contained in the +.Fa store . +.Pp +.Fn X509_STORE_add_cert +and +.Fn X509_STORE_add_crl +add the certificate +.Fa x +or the certificate revocation list +.Fa crl +to the +.Fa store , +increasing its reference count by 1 in case of success. +Untrusted objects should not be added in this way. +.Pp +.Fn X509_STORE_get_ex_new_index , +.Fn X509_STORE_set_ex_data , +and +.Fn X509_STORE_get_ex_data +handle application specific data in +.Vt X509_STORE +objects. +Their usage is identical to that of +.Xr RSA_get_ex_new_index 3 , +.Xr RSA_set_ex_data 3 , +and +.Xr RSA_get_ex_data 3 . +.Fn X509_STORE_get_ex_new_index +is implemented as a macro. +.Sh RETURN VALUES +.Fn X509_STORE_set1_param , +.Fn X509_STORE_set_purpose , +.Fn X509_STORE_set_trust , +and +.Fn X509_STORE_set_ex_data +return 1 for success or 0 for failure. +.Pp +.Fn X509_STORE_set_flags +and +.Fn X509_STORE_set_depth +always return 1, indicating success. +.Pp +.Fn X509_STORE_add_cert +and +.Fn X509_STORE_add_crl +return 1 for success or 0 for failure. +For example, they fail if +.Fa x +or +.Fa crl +is a +.Dv NULL +pointer, if a certificate with the same subject name as +.Fa x +or a revocation list with the same issuer name as +.Fa crl +are already contained in the +.Fa store , +or if memory allocation fails. +.Pp +.Fn X509_STORE_get0_param +returns an internal pointer to the verification parameter object +contained in the +.Fa store . +The returned pointer must not be freed by the calling application. +.Pp +.Fn X509_STORE_get1_objects +returns a newly allocated stack containing +the certificates, revocation lists, and private keys in +.Fa store , +as well as cached objects added by +.Xr X509_LOOKUP_hash_dir 3 . +The caller must release the result with +.Xr sk_pop_free 3 +and +.Xr X509_OBJECT_free 3 +when done. +.Pp +.Fn X509_STORE_get0_objects +is a deprecated function returning an internal pointer to +the stack of certificates, revocation lists, and private keys contained in +.Fa store . +The returned pointer must not be modified or freed by the calling application. +This function is not thread-safe. +If +.Fa store +is shared across multiple threads, callers cannot safely inspect the result of +this function, because another thread may have concurrently added to it. +In particular, +.Xr X509_LOOKUP_hash_dir 3 +treats this list as a cache and may add to it in the course of certificate +verification. +.Pp +.Fn X509_STORE_get_ex_new_index +returns a new index or \-1 on failure. +.Pp +.Fn X509_STORE_get_ex_data +returns the application data or +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr RSA_get_ex_new_index 3 , +.Xr SSL_set1_param 3 , +.Xr X509_LOOKUP_new 3 , +.Xr X509_OBJECT_get0_X509 3 , +.Xr X509_STORE_CTX_set0_param 3 , +.Xr X509_STORE_load_locations 3 , +.Xr X509_STORE_new 3 , +.Xr X509_VERIFY_PARAM_new 3 , +.Xr X509_VERIFY_PARAM_set_flags 3 +.Sh HISTORY +.Fn X509_STORE_add_cert +first appeared in SSLeay 0.8.0. +.Fn X509_STORE_add_crl +first appeared in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_STORE_set_flags , +.Fn X509_STORE_set_purpose , +and +.Fn X509_STORE_set_trust +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn X509_STORE_set1_param +and +.Fn X509_STORE_set_depth +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn X509_STORE_get0_param , +.Fn X509_STORE_get0_objects , +.Fn X509_STORE_get_ex_new_index , +.Fn X509_STORE_set_ex_data , +and +.Fn X509_STORE_get_ex_data +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.3 . +.Pp +.Fn X509_STORE_get1_objects +first appeared in BoringSSL and has been available since +.Ox 7.5 . diff --git a/static/openbsd/man3/X509_STORE_set_verify_cb_func.3 b/static/openbsd/man3/X509_STORE_set_verify_cb_func.3 new file mode 100644 index 00000000..a09e6741 --- /dev/null +++ b/static/openbsd/man3/X509_STORE_set_verify_cb_func.3 @@ -0,0 +1,122 @@ +.\" $OpenBSD: X509_STORE_set_verify_cb_func.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 05ea606a May 20 20:52:46 2016 -0400 +.\" selective merge up to: OpenSSL 315c47e0 Dec 1 14:22:16 2020 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2009 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_STORE_SET_VERIFY_CB_FUNC 3 +.Os +.Sh NAME +.Nm X509_STORE_set_verify_cb , +.Nm X509_STORE_set_verify_cb_func , +.Nm X509_STORE_get_verify_cb +.Nd set verification callback +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft void +.Fo X509_STORE_set_verify_cb +.Fa "X509_STORE *st" +.Fa "X509_STORE_CTX_verify_cb verify_cb" +.Fc +.Ft void +.Fo X509_STORE_set_verify_cb_func +.Fa "X509_STORE *st" +.Fa "X509_STORE_CTX_verify_cb verify_cb" +.Fc +.Ft X509_STORE_CTX_verify_cb +.Fo X509_STORE_get_verify_cb +.Fa "X509_STORE *st" +.Fc +.Sh DESCRIPTION +.Fn X509_STORE_set_verify_cb +sets the verification callback of +.Sy ctx +to +.Sy verify_cb , +overwriting any existing callback. +.Pp +.Fn X509_STORE_set_verify_cb_func +also sets the verification callback but it is implemented as a macro. +.Pp +The verification callback from an +.Vt X509_STORE +is inherited by the corresponding +.Vt X509_STORE_CTX +structure when it is initialized. +This can be used to set the verification callback when the +.Vt X509_STORE_CTX +is otherwise inaccessible (for example during S/MIME verification). +.Sh RETURN VALUES +.Fn X509_STORE_get_verify_cb +returns the function pointer set with +.Fn X509_STORE_set_verify_cb , +or +.Dv NULL +if that function was not called on +.Fa st . +.Sh SEE ALSO +.Xr X509_STORE_CTX_new 3 , +.Xr X509_STORE_CTX_set_verify 3 , +.Xr X509_STORE_CTX_set_verify_cb 3 , +.Xr X509_STORE_new 3 , +.Xr X509_STORE_set_flags 3 , +.Xr X509_verify_cert 3 +.Sh HISTORY +.Fn X509_STORE_set_verify_cb_func +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . +.Pp +.Fn X509_STORE_set_verify_cb +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Pp +.Fn X509_STORE_get_verify_cb +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.2 . diff --git a/static/openbsd/man3/X509_VERIFY_PARAM_new.3 b/static/openbsd/man3/X509_VERIFY_PARAM_new.3 new file mode 100644 index 00000000..333b3860 --- /dev/null +++ b/static/openbsd/man3/X509_VERIFY_PARAM_new.3 @@ -0,0 +1,307 @@ +.\" $OpenBSD: X509_VERIFY_PARAM_new.3,v 1.6 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2018, 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_VERIFY_PARAM_NEW 3 +.Os +.Sh NAME +.Nm X509_VERIFY_PARAM_new , +.Nm X509_VERIFY_PARAM_inherit , +.Nm X509_VERIFY_PARAM_set1 , +.Nm X509_VERIFY_PARAM_free , +.Nm X509_VERIFY_PARAM_add0_table , +.Nm X509_VERIFY_PARAM_lookup , +.Nm X509_VERIFY_PARAM_get_count , +.Nm X509_VERIFY_PARAM_get0 , +.Nm X509_VERIFY_PARAM_table_cleanup +.\" The following constants defined in the public header +.\" are intentionally undocumented because X509_VERIFY_PARAM is an opaque +.\" struct and LibreSSL provides neither X509_VERIFY_PARAM_set_inh_flags(3) +.\" nor X509_VERIFY_PARAM_get_inh_flags(3): +.\" X509_VP_FLAG_DEFAULT +.\" X509_VP_FLAG_OVERWRITE +.\" X509_VP_FLAG_RESET_FLAGS +.\" X509_VP_FLAG_LOCKED +.\" X509_VP_FLAG_ONCE +.Nd X509 verification parameter objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft X509_VERIFY_PARAM * +.Fo X509_VERIFY_PARAM_new +.Fa void +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_inherit +.Fa "X509_VERIFY_PARAM *destination" +.Fa "const X509_VERIFY_PARAM *source" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set1 +.Fa "X509_VERIFY_PARAM *destination" +.Fa "const X509_VERIFY_PARAM *source" +.Fc +.Ft void +.Fo X509_VERIFY_PARAM_free +.Fa "X509_VERIFY_PARAM *param" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_add0_table +.Fa "X509_VERIFY_PARAM *param" +.Fc +.Ft const X509_VERIFY_PARAM * +.Fo X509_VERIFY_PARAM_lookup +.Fa "const char *name" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_get_count +.Fa void +.Fc +.Ft const X509_VERIFY_PARAM * +.Fo X509_VERIFY_PARAM_get0 +.Fa "int id" +.Fc +.Ft void +.Fo X509_VERIFY_PARAM_table_cleanup +.Fa void +.Fc +.Sh DESCRIPTION +.Fn X509_VERIFY_PARAM_new +allocates and initializes an empty +.Vt X509_VERIFY_PARAM +object. +.Pp +.Fn X509_VERIFY_PARAM_inherit +copies some data from the +.Fa source +object to the +.Fa destination +object. +.Pp +The verification flags set with +.Xr X509_VERIFY_PARAM_set_flags 3 +in the +.Fa source +object are always OR'ed into the verification flags of the +.Fa destination +object. +.Pp +Fields having their default value in the +.Fa source +object are not copied. +.Pp +By default, fields in the +.Fa destination +object already having a non-default value are not overwritten. +However, if at least one of the +.Fa source +or +.Fa destination +objects was created during a call to +.Xr X509_STORE_CTX_init 3 +that did not have a +.Fa store +argument, and if that object was not previously used as the +.Fa destination +in an earlier call to +.Fn X509_VERIFY_PARAM_inherit , +this restriction is waived and even non-default fields in the +.Fa destination +object get overwritten. +If fields overwritten in this way contain pointers to allocated memory, +that memory is freed. +.Pp +As far as permitted by the above rules, the following fields are copied: +.Bl -bullet -width 1n +.It +the verification purpose identifier set with +.Xr X509_VERIFY_PARAM_set_purpose 3 +.It +the trust setting set with +.Xr X509_VERIFY_PARAM_set_trust 3 +.It +the verification time set with +.Xr X509_VERIFY_PARAM_set_time 3 ; +in this case, the only condition is that +.Dv X509_V_FLAG_USE_CHECK_TIME +is not set in the +.Fa destination +object, whereas the time value in the +.Fa destination +object is not inspected before overwriting it +.It +the acceptable policy set with +.Xr X509_VERIFY_PARAM_set1_policies 3 +.It +the maximum verification depth set with +.Xr X509_VERIFY_PARAM_set_depth 3 +.It +flags that were set with +.Xr X509_VERIFY_PARAM_set_hostflags 3 +.It +the list of expected DNS hostnames built with +.Xr X509_VERIFY_PARAM_set1_host 3 +and +.Xr X509_VERIFY_PARAM_add1_host 3 +.It +the expected RFC 822 email address set with +.Xr X509_VERIFY_PARAM_set1_email 3 +.It +the expected IP address set with +.Xr X509_VERIFY_PARAM_set1_ip 3 +or +.Xr X509_VERIFY_PARAM_set1_ip_asc 3 +.El +.Pp +Some data that may be contained in the +.Fa source +object is never copied, for example the subject name of the peer +certificate that can be retrieved with +.Xr X509_VERIFY_PARAM_get0_peername 3 . +.Pp +If +.Fa source +is a +.Dv NULL +pointer, the function has no effect but returns successfully. +.Pp +.Fn X509_VERIFY_PARAM_set1 +is identical to +.Fn X509_VERIFY_PARAM_inherit +except that fields in the +.Fa destination +object are overwritten even if they do not match their default values. +Still, fields having their default value in the +.Fa source +object are not copied. +.Pp +If +.Fn X509_VERIFY_PARAM_inherit +or +.Fn X509_VERIFY_PARAM_set1 +fail, partial copying may have occurred, so all data in the +.Fa destination +object should be regarded as invalid. +.Pp +.Fn X509_VERIFY_PARAM_inherit +is used internally by +.Xr X509_STORE_CTX_init 3 +and by +.Xr X509_STORE_CTX_set_default 3 , +and +.Fn X509_VERIFY_PARAM_set1 +is used internally by +.Xr X509_STORE_set1_param 3 . +.Pp +.Fn X509_VERIFY_PARAM_free +clears all data contained in +.Fa param +and releases all memory used by it. +If +.Fa param +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn X509_VERIFY_PARAM_add0_table +adds +.Fa param +to a static list of +.Vt X509_VERIFY_PARAM +objects maintained by the library. +This function is extremely dangerous because contrary to the name +of the function, if the list already contains an object that happens +to have the same name, that old object is not only silently removed +from the list, but also silently freed, which may silently invalidate +various pointers existing elsewhere in the program. +.Pp +.Fn X509_VERIFY_PARAM_lookup +searches this list for an object of the given +.Fa name . +If no match is found, the predefined objects built-in to the library +are also inspected. +.Pp +.Fn X509_VERIFY_PARAM_get_count +returns the sum of the number of objects on this list and the number +of predefined objects built-in to the library. +Note that this is not necessarily the total number of +.Vt X509_VERIFY_PARAM +objects existing in the program because there may be additional such +objects that were never added to the list. +.Pp +.Fn X509_VERIFY_PARAM_get0 +accesses predefined and user-defined objects using +.Fa id +as an index, useful for looping over objects without knowing their names. +An argument less than the number of predefined objects selects +one of the predefined objects; a higher argument selects an object +from the list. +.Pp +.Fn X509_VERIFY_PARAM_table_cleanup +deletes all objects from this list. +It is extremely dangerous because it also invalidates all data that +was contained in all objects that were on the list and because it +frees all these objects, which may invalidate various pointers +existing elsewhere in the program. +.Sh RETURN VALUES +.Fn X509_VERIFY_PARAM_new +returns a pointer to the new object, or +.Dv NULL +on allocation failure. +.Pp +.Fn X509_VERIFY_PARAM_inherit , +.Fn X509_VERIFY_PARAM_set1 , +and +.Fn X509_VERIFY_PARAM_add0_table +return 1 for success or 0 for failure. +.Pp +.Fn X509_VERIFY_PARAM_lookup +and +.Fn X509_VERIFY_PARAM_get0 +return a pointer to an existing built-in or user-defined object, or +.Dv NULL +if no object with the given +.Fa name +is found, or if +.Fa id +is at least +.Fn X509_VERIFY_PARAM_get_count . +.Pp +.Fn X509_VERIFY_PARAM_get_count +returns a number of objects. +.Sh SEE ALSO +.Xr SSL_set1_param 3 , +.Xr X509_STORE_CTX_set0_param 3 , +.Xr X509_STORE_set1_param 3 , +.Xr X509_verify_cert 3 , +.Xr X509_VERIFY_PARAM_set_flags 3 +.Sh HISTORY +.Fn X509_VERIFY_PARAM_new , +.Fn X509_VERIFY_PARAM_inherit , +.Fn X509_VERIFY_PARAM_set1 , +.Fn X509_VERIFY_PARAM_free , +.Fn X509_VERIFY_PARAM_add0_table , +.Fn X509_VERIFY_PARAM_lookup , +and +.Fn X509_VERIFY_PARAM_table_cleanup +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Pp +.Fn X509_VERIFY_PARAM_get_count +and +.Fn X509_VERIFY_PARAM_get0 +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/X509_VERIFY_PARAM_set_flags.3 b/static/openbsd/man3/X509_VERIFY_PARAM_set_flags.3 new file mode 100644 index 00000000..4c72be02 --- /dev/null +++ b/static/openbsd/man3/X509_VERIFY_PARAM_set_flags.3 @@ -0,0 +1,751 @@ +.\" $OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.32 2025/11/07 19:59:31 schwarze Exp $ +.\" full merge up to: OpenSSL d33def66 Feb 9 14:17:13 2016 -0500 +.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018, 2021, 2022 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. +.\" +.\" The original file was written by Dr. Stephen Henson +.\" and Viktor Dukhovni . +.\" Copyright (c) 2009, 2013, 2014, 2015, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: November 7 2025 $ +.Dt X509_VERIFY_PARAM_SET_FLAGS 3 +.Os +.Sh NAME +.Nm X509_VERIFY_PARAM_get0_name , +.Nm X509_VERIFY_PARAM_set1_name , +.Nm X509_VERIFY_PARAM_set_flags , +.Nm X509_VERIFY_PARAM_clear_flags , +.Nm X509_VERIFY_PARAM_get_flags , +.Nm X509_VERIFY_PARAM_set_purpose , +.Nm X509_VERIFY_PARAM_set_trust , +.Nm X509_VERIFY_PARAM_set_time , +.Nm X509_VERIFY_PARAM_get_time , +.Nm X509_VERIFY_PARAM_add0_policy , +.Nm X509_VERIFY_PARAM_set1_policies , +.Nm X509_VERIFY_PARAM_set_depth , +.Nm X509_VERIFY_PARAM_get_depth , +.Nm X509_VERIFY_PARAM_set_auth_level , +.Nm X509_VERIFY_PARAM_set1_host , +.Nm X509_VERIFY_PARAM_add1_host , +.Nm X509_VERIFY_PARAM_get_hostflags , +.Nm X509_VERIFY_PARAM_set_hostflags , +.Nm X509_VERIFY_PARAM_get0_peername , +.Nm X509_VERIFY_PARAM_set1_email , +.Nm X509_VERIFY_PARAM_set1_ip , +.Nm X509_VERIFY_PARAM_set1_ip_asc +.Nd X509 verification parameters +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft const char * +.Fo X509_VERIFY_PARAM_get0_name +.Fa "const X509_VERIFY_PARAM *param" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set1_name +.Fa "X509_VERIFY_PARAM *param" +.Fa "const char *name" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set_flags +.Fa "X509_VERIFY_PARAM *param" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_clear_flags +.Fa "X509_VERIFY_PARAM *param" +.Fa "unsigned long flags" +.Fc +.Ft unsigned long +.Fo X509_VERIFY_PARAM_get_flags +.Fa "X509_VERIFY_PARAM *param" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set_purpose +.Fa "X509_VERIFY_PARAM *param" +.Fa "int purpose" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set_trust +.Fa "X509_VERIFY_PARAM *param" +.Fa "int trust" +.Fc +.Ft void +.Fo X509_VERIFY_PARAM_set_time +.Fa "X509_VERIFY_PARAM *param" +.Fa "time_t t" +.Fc +.Ft time_t +.Fo X509_VERIFY_PARAM_get_time +.Fa const X509_VERIFY_PARAM *param" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_add0_policy +.Fa "X509_VERIFY_PARAM *param" +.Fa "ASN1_OBJECT *policy" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set1_policies +.Fa "X509_VERIFY_PARAM *param" +.Fa "STACK_OF(ASN1_OBJECT) *policies" +.Fc +.Ft void +.Fo X509_VERIFY_PARAM_set_depth +.Fa "X509_VERIFY_PARAM *param" +.Fa "int depth" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_get_depth +.Fa "const X509_VERIFY_PARAM *param" +.Fc +.Ft void +.Fo X509_VERIFY_PARAM_set_auth_level +.Fa "X509_VERIFY_PARAM *param" +.Fa "int auth_level" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set1_host +.Fa "X509_VERIFY_PARAM *param" +.Fa "const char *name" +.Fa "size_t namelen" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_add1_host +.Fa "X509_VERIFY_PARAM *param" +.Fa "const char *name" +.Fa "size_t namelen" +.Fc +.Ft unsigned int +.Fo X509_VERIFY_PARAM_get_hostflags +.Fa "const X509_VERIFY_PARAM *param" +.Fc +.Ft void +.Fo X509_VERIFY_PARAM_set_hostflags +.Fa "X509_VERIFY_PARAM *param" +.Fa "unsigned int flags" +.Fc +.Ft char * +.Fo X509_VERIFY_PARAM_get0_peername +.Fa "X509_VERIFY_PARAM *param" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set1_email +.Fa "X509_VERIFY_PARAM *param" +.Fa "const char *email" +.Fa "size_t emaillen" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set1_ip +.Fa "X509_VERIFY_PARAM *param" +.Fa "const unsigned char *ip" +.Fa "size_t iplen" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set1_ip_asc +.Fa "X509_VERIFY_PARAM *param" +.Fa "const char *ipasc" +.Fc +.Sh DESCRIPTION +These functions manipulate an +.Vt X509_VERIFY_PARAM +object associated with a certificate verification operation. +.Pp +.Fn X509_VERIFY_PARAM_get0_name +returns the name of the given +.Fa param +object, usually describing its purpose, for example +.Qq default , +.Qq pkcs7 , +.Qq smime_sign , +.Qq ssl_client , +or +.Qq ssl_server . +For user-defined objects, the returned pointer may be +.Dv NULL +even if the object is otherwise valid. +.Pp +.Fn X509_VERIFY_PARAM_set1_name +sets the name of +.Fa param +to a copy of +.Fa name , +or to +.Dv NULL +if +.Fa name +is +.Dv NULL . +.Pp +.Fn X509_VERIFY_PARAM_set_flags +sets the flags in +.Fa param +by OR'ing it with +.Fa flags . +See the +.Sx VERIFICATION FLAGS +section for a complete description of values the +.Fa flags +parameter can take. +.Pp +If the +.Fa flags +argument includes any of the flags contained in +.Dv X509_V_FLAG_POLICY_MASK , +that is, any of +.Dv X509_V_FLAG_POLICY_CHECK , +.Dv X509_V_FLAG_EXPLICIT_POLICY , +.Dv X509_V_FLAG_INHIBIT_ANY , +and +.Dv X509_V_FLAG_INHIBIT_MAP , +then +.Dv X509_V_FLAG_POLICY_CHECK +is set in addition to the flags contained in the +.Fa flags +argument. +.Pp +.Fn X509_VERIFY_PARAM_get_flags +returns the flags in +.Fa param . +.Pp +.Fn X509_VERIFY_PARAM_clear_flags +clears the specified +.Fa flags +in +.Fa param . +.Pp +Calling this function can result in unusual internal states of the +.Fa param +object, for example having a verification time configured but having +.Dv X509_V_FLAG_USE_CHECK_TIME +unset, or having +.Dv X509_V_FLAG_EXPLICIT_POLICY +set but +.Dv X509_V_FLAG_POLICY_CHECK +unset, which may have surprising effects. +.Pp +.Fn X509_VERIFY_PARAM_set_purpose +sets the verification +.Fa purpose +identifier in +.Fa param . +This determines the acceptable purpose of the certificate chain, for example +.Dv X509_PURPOSE_SSL_CLIENT +or +.Dv X509_PURPOSE_SSL_SERVER . +Standard purposes are listed in +.Xr X509_check_purpose 3 , +and additional purposes can be defined with +.Xr X509_PURPOSE_add 3 . +.Pp +.Fn X509_VERIFY_PARAM_set_trust +sets the trust setting in +.Fa param +to +.Fa trust . +.Pp +.Fn X509_VERIFY_PARAM_set_time +sets the flag +.Dv X509_V_FLAG_USE_CHECK_TIME +in +.Fa param +in addition to the flags already set and sets the verification time to +.Fa t . +If this function is not called, the current time is used instead, +or the UNIX Epoch (January 1, 1970) if +.Dv X509_V_FLAG_USE_CHECK_TIME +is manually set using +.Fn X509_VERIFY_PARAM_set_flags . +.Pp +.Fn X509_VERIFY_PARAM_add0_policy +enables policy checking (it is disabled by default) and adds +.Fa policy +to the acceptable policy set. +.Pp +.Fn X509_VERIFY_PARAM_set1_policies +enables policy checking (it is disabled by default) and sets the +acceptable policy set to +.Fa policies . +Any existing policy set is cleared. +The +.Fa policies +parameter can be +.Dv NULL +to clear an existing policy set. +.Pp +.Fn X509_VERIFY_PARAM_set_depth +sets the maximum verification depth to +.Fa depth . +That is the maximum number of untrusted CA certificates that can appear +in a chain. +.Pp +.Fn X509_VERIFY_PARAM_set_auth_level +sets the security level as defined in +.Xr SSL_CTX_set_security_level 3 +for certificate chain validation. +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's trust anchor certificate, which is either directly trusted +or validated by means other than its signature. +.Pp +From the point of view of the X.509 library, +the default security level is 0. +However, the SSL library +uses a different default security level of 1 and calls +.Fn X509_VERIFY_PARAM_set_auth_level +with its own level before validating a certificate chain. +.Pp +.Fn X509_VERIFY_PARAM_set1_host +sets the expected DNS hostname to +.Fa name +clearing any previously specified hostname or names. +If +.Fa name +is +.Dv NULL +or empty, the list of hostnames is cleared, and name checks are not +performed on the peer certificate. +.Fa namelen +should be set to the length of +.Fa name . +For historical compatibility, if +.Fa name +is NUL-terminated, +.Fa namelen +may be specified as zero. +When a hostname is specified, certificate verification automatically +invokes +.Xr X509_check_host 3 +with flags equal to the +.Fa flags +argument given to +.Fn X509_VERIFY_PARAM_set_hostflags +(default zero). +.Fn X509_VERIFY_PARAM_set1_host +will fail if +.Fa name +contains any embedded 0 bytes. +.Pp +.Fn X509_VERIFY_PARAM_add1_host +adds +.Fa name +as an additional reference identifier that can match the peer's +certificate. +Any previous names set via +.Fn X509_VERIFY_PARAM_set1_host +and +.Fn X509_VERIFY_PARAM_add1_host +are retained. +No change is made if +.Fa name +is +.Dv NULL +or empty. +.Fa namelen +should be set to the length of +.Fa name . +For historical compatibility, if +.Fa name +is NUL-terminated, +.Fa namelen +may be specified as zero. +.Fn X509_VERIFY_PARAM_add1_host +will fail if +.Fa name +contains any embedded 0 bytes. +When multiple names are configured, the peer is considered verified when +any name matches. +.Pp +.Fn X509_VERIFY_PARAM_get0_peername +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. +.Pp +.Fn X509_VERIFY_PARAM_set1_email +sets the expected RFC 822 email address to +.Fa email . +.Fa emaillen +should be set to the length of +.Fa email . +For historical compatibility, if +.Fa email +is NUL-terminated, +.Fa emaillen +may be specified as zero, +.Fn X509_VERIFY_PARAM_set1_email +will fail if +.Fa email +is NULL, an empty string, or contains embedded 0 bytes. +When an email address is specified, certificate verification +automatically invokes +.Xr X509_check_email 3 . +.Pp +.Fn X509_VERIFY_PARAM_set1_ip +sets the expected IP address to +.Fa ip . +The +.Fa ip +argument is in binary format, in network byte-order, and +.Fa iplen +must be set to 4 for IPv4 and 16 for IPv6. +.Fn X509_VERIFY_PARAM_set1_ip +will fail if +.Fa ip +is NULL or if +.Fa iplen +is not 4 or 16. +When an IP address is specified, +certificate verification automatically invokes +.Xr X509_check_ip 3 . +.Pp +.Fn X509_VERIFY_PARAM_set1_ip_asc +sets the expected IP address to +.Fa ipasc . +The +.Fa ipasc +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. +.Fn X509_VERIFY_PARAM_set1_ip_asc +will fail if +.Fa ipasc +is unparsable. +.Sh RETURN VALUES +.Fn X509_VERIFY_PARAM_set1_name , +.Fn X509_VERIFY_PARAM_set_flags , +.Fn X509_VERIFY_PARAM_clear_flags , +.Fn X509_VERIFY_PARAM_set_purpose , +.Fn X509_VERIFY_PARAM_set_trust , +.Fn X509_VERIFY_PARAM_add0_policy , +and +.Fn X509_VERIFY_PARAM_set1_policies +return 1 for success or 0 for failure. +.Pp +.Fn X509_VERIFY_PARAM_set1_host , +.Fn X509_VERIFY_PARAM_add1_host , +.Fn X509_VERIFY_PARAM_set1_email , +.Fn X509_VERIFY_PARAM_set1_ip , +and +.Fn X509_VERIFY_PARAM_set1_ip_asc +return 1 for success or 0 for failure. +A failure from these routines will poison +the +.Vt X509_VERIFY_PARAM +object so that future calls to +.Xr X509_verify_cert 3 +using the poisoned object will fail. +.Pp +.Fn X509_VERIFY_PARAM_get_flags +returns the current verification flags. +.Pp +.Fn X509_VERIFY_PARAM_get_time +always returns the configured verification time. +It does so even if the returned time will not be used because the flag +.Dv X509_V_FLAG_USE_CHECK_TIME +is unset. +.Pp +.Fn X509_VERIFY_PARAM_get_depth +returns the current verification depth. +.Pp +.Fn X509_VERIFY_PARAM_get_hostflags +returns the host flags previously set by a call to +.Fn X509_VERIFY_PARAM_set_hostflags +or 0 by default. +.Pp +.Fn X509_VERIFY_PARAM_get0_name +and +.Fn X509_VERIFY_PARAM_get0_peername +return pointers to strings that are only valid +during the lifetime of the given +.Fa param +object and that must not be freed by the application program. +.Sh VERIFICATION FLAGS +The verification flags consists of zero or more of the following +flags OR'ed together. +.Pp +.Dv X509_V_FLAG_CRL_CHECK +enables CRL checking for the certificate chain leaf certificate. +An error occurs if a suitable CRL cannot be found. +.Pp +.Dv X509_V_FLAG_CRL_CHECK_ALL +enables CRL checking for the entire certificate chain. +.Pp +.Dv X509_V_FLAG_IGNORE_CRITICAL +disables critical extension checking. +By default any unhandled critical extensions in certificates or (if +checked) CRLs results in a fatal error. +If this flag is set, unhandled critical extensions are ignored. +.Sy WARNING : +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 +.Dv X509_V_FLAG_X509_STRICT +flag disables workarounds for some broken certificates and makes the +verification strictly apply X509 rules. +.Pp +.Dv X509_V_FLAG_ALLOW_PROXY_CERTS +deprecated flag that used to +enable proxy certificate verification. +In LibreSSL, this flag has no effect. +.Pp +.Dv X509_V_FLAG_POLICY_CHECK +enables certificate policy checking; by default no policy checking is +performed. +Additional information is sent to the verification callback relating to +policy checking. +.Pp +.Dv X509_V_FLAG_EXPLICIT_POLICY , +.Dv X509_V_FLAG_INHIBIT_ANY , +and +.Dv X509_V_FLAG_INHIBIT_MAP +set the +.Dq require explicit policy , +.Dq inhibit any policy , +and +.Dq inhibit policy mapping +flags, respectively, as defined in RFC 3280. +These three flags are ignored unless +.Dv X509_V_FLAG_POLICY_CHECK +is also set. +.Pp +If +.Dv X509_V_FLAG_NOTIFY_POLICY +is set and policy checking is successful, a special status code is +sent to the verification callback. +.Pp +By default some additional features such as indirect CRLs and CRLs +signed by different keys are disabled. +If +.Dv X509_V_FLAG_EXTENDED_CRL_SUPPORT +is set, they are enabled. +.Pp +If +.Dv X509_V_FLAG_USE_DELTAS +is set, delta CRLs (if present) are used to determine certificate +status. +If not set, deltas are ignored. +.Pp +.Dv X509_V_FLAG_CHECK_SS_SIGNATURE +enables checking of the root CA self signed certificate signature. +By default this check is disabled because it doesn't add any additional +security but in some cases applications might want to check the +signature anyway. +A side effect of not checking the root CA signature is that disabled or +unsupported message digests on the root CA are not treated as fatal +errors. +.Pp +The deprecated +.Dv X509_V_FLAG_CB_ISSUER_CHECK +flag used to enable debugging of certificate issuer checks. +It is provided for binary backwards compatibility and has no effect. +.Pp +When +.Dv X509_V_FLAG_TRUSTED_FIRST +is set, construction of the certificate chain in +.Xr X509_verify_cert 3 +will search 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 the trust settings options of the +.Cm x509 +command in +.Xr openssl 1 . +.Pp +The +.Dv X509_V_FLAG_NO_ALT_CHAINS +flag suppresses checking for alternative chains. +By default, unless +.Dv X509_V_FLAG_TRUSTED_FIRST +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. +.Pp +The +.Dv X509_V_FLAG_PARTIAL_CHAIN +flag causes intermediate certificates in the trust store to be treated +as trust-anchors, in the same way as the self-signed root CA +certificates. +This makes it possible to trust certificates issued by an intermediate +CA without having to trust its ancestor root CA. +.Pp +If +.Dv X509_V_FLAG_USE_CHECK_TIME +is set, the validity period of certificates and CRLs is checked. +In this case, +.Dv X509_V_FLAG_NO_CHECK_TIME +is ignored. +If the validation time was set with +.Fn X509_VERIFY_PARAM_set_time , +that time is used. +If +.Fn X509_VERIFY_PARAM_set_time +was not called, the UNIX Epoch (January 1, 1970) is used. +.Pp +If neither +.Dv X509_V_FLAG_USE_CHECK_TIME +nor +.Dv X509_V_FLAG_NO_CHECK_TIME +is set, the validity period of certificates and CRLs is checked +using the current time. +This is the default behaviour. +In this case, if a validation time was set with +.Fn X509_VERIFY_PARAM_set_time +but +.Dv X509_V_FLAG_USE_CHECK_TIME +was later cleared with +.Fn X509_VERIFY_PARAM_clear_flags , +the configured validation time is ignored +and the current time is used anyway. +.Pp +If +.Dv X509_V_FLAG_USE_CHECK_TIME +is not set but +.Dv X509_V_FLAG_NO_CHECK_TIME +is set, the validity period of certificates and CRLs is not checked +at all, and like in the previous case, any configured validation +time is ignored. +.Sh EXAMPLES +Enable CRL checking when performing certificate verification during +SSL connections associated with an +.Vt SSL_CTX +structure +.Fa ctx : +.Bd -literal -offset indent +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); +.Ed +.Sh SEE ALSO +.Xr SSL_set1_host 3 , +.Xr SSL_set1_param 3 , +.Xr X509_check_host 3 , +.Xr X509_STORE_CTX_new 3 , +.Xr X509_STORE_new 3 , +.Xr X509_verify_cert 3 , +.Xr X509_VERIFY_PARAM_new 3 +.Sh HISTORY +.Fn X509_VERIFY_PARAM_set1_name , +.Fn X509_VERIFY_PARAM_set_flags , +.Fn X509_VERIFY_PARAM_set_purpose , +.Fn X509_VERIFY_PARAM_set_trust , +.Fn X509_VERIFY_PARAM_set_time , +.Fn X509_VERIFY_PARAM_add0_policy , +.Fn X509_VERIFY_PARAM_set1_policies , +.Fn X509_VERIFY_PARAM_set_depth , +and +.Fn X509_VERIFY_PARAM_get_depth +first appeared in OpenSSL 0.9.8. +.Fn X509_VERIFY_PARAM_clear_flags +and +.Fn X509_VERIFY_PARAM_get_flags +first appeared in OpenSSL 0.9.8a. +All these functions have been available since +.Ox 4.5 . +.Pp +.Fn X509_VERIFY_PARAM_get0_name , +.Fn X509_VERIFY_PARAM_set1_host , +.Fn X509_VERIFY_PARAM_add1_host , +.Fn X509_VERIFY_PARAM_set_hostflags , +.Fn X509_VERIFY_PARAM_get0_peername , +.Fn X509_VERIFY_PARAM_set1_email , +.Fn X509_VERIFY_PARAM_set1_ip , +and +.Fn X509_VERIFY_PARAM_set1_ip_asc +first appeared in OpenSSL 1.0.2 and have been available since +.Ox 6.3 . +.Pp +.Fn X509_VERIFY_PARAM_set_auth_level +first appeared in OpenSSL 1.1.0 and +.Fn X509_VERIFY_PARAM_get_time +in OpenSSL 1.1.0d. +Both functions have been available since +.Ox 7.2 . +.Pp +.Fn X509_VERIFY_PARAM_get_hostflags +first appeared in OpenSSL 1.1.0i and has been available since +.Ox 7.9 . +.Sh BUGS +Delta CRL checking is currently primitive. +Only a single delta can be used and (partly due to limitations of +.Vt X509_STORE ) +constructed CRLs are not maintained. +.Pp +If CRLs checking is enabled, CRLs are expected to be available in +the corresponding +.Vt X509_STORE +structure. +No attempt is made to download CRLs from the CRL distribution points +extension. diff --git a/static/openbsd/man3/X509_add1_trust_object.3 b/static/openbsd/man3/X509_add1_trust_object.3 new file mode 100644 index 00000000..e1ca67a8 --- /dev/null +++ b/static/openbsd/man3/X509_add1_trust_object.3 @@ -0,0 +1,100 @@ +.\" $OpenBSD: X509_add1_trust_object.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_ADD1_TRUST_OBJECT 3 +.Os +.Sh NAME +.Nm X509_add1_trust_object , +.Nm X509_trust_clear , +.Nm X509_add1_reject_object , +.Nm X509_reject_clear +.Nd mark an X.509 certificate as intended for a specific purpose +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_add1_trust_object +.Fa "X509 *x" +.Fa "const ASN1_OBJECT *purpose" +.Fc +.Ft void +.Fo X509_trust_clear +.Fa "X509 *x" +.Fc +.Ft int +.Fo X509_add1_reject_object +.Fa "X509 *x" +.Fa "const ASN1_OBJECT *purpose" +.Fc +.Ft void +.Fo X509_reject_clear +.Fa "X509 *x" +.Fc +.Sh DESCRIPTION +.Fn X509_add1_trust_object +appends a deep copy of the +.Fa purpose +object to the set of intended purposes that +.Fa x +contains as non-standard auxiliary data. +The function +.Xr OBJ_nid2obj 3 +can be used to create appropriate purpose objects from the +.Dv NID_* +constants mentioned in +.Xr X509_check_purpose 3 , +even though the +.Dv X509_PURPOSE_* +constants listed in that manual page are not intended for use with +.Fn X509_add1_trust_object . +.Pp +.Fn X509_trust_clear +frees and removes all purpose objects from the set of intended +purposes in the non-standard auxiliary data of +.Fa x . +.Pp +.Fn X509_add1_reject_object +and +.Fn X509_reject_clear +are similar except that they operate on a set of unintended purposes. +.Pp +As an alternative to using the functions documented in the present +manual page, X.509 certificate extensions can be used. +At the price of higher complexity, those allow storing the purpose +inside the certificate itself in a standard-conforming way rather than +merely in non-standard auxiliary data associated with the certificate. +See +.Xr EXTENDED_KEY_USAGE_new 3 +for details. +.Sh RETURN VALUES +.Fn X509_add1_trust_object +and +.Fn X509_add1_reject_object +return the new number of purposes in the respective set +or 0 if an error occurs, in particular if memory +allocation fails or if +.Fa x +does not contain a sub-object that can hold non-standard auxiliary data. +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr EXTENDED_KEY_USAGE_new 3 , +.Xr OBJ_nid2obj 3 , +.Xr X509_CERT_AUX_new 3 , +.Xr X509_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.4 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/X509_check_ca.3 b/static/openbsd/man3/X509_check_ca.3 new file mode 100644 index 00000000..2aa496b6 --- /dev/null +++ b/static/openbsd/man3/X509_check_ca.3 @@ -0,0 +1,118 @@ +.\" $OpenBSD: X509_check_ca.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Victor B. Wagner . +.\" Copyright (c) 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_CHECK_CA 3 +.Os +.Sh NAME +.Nm X509_check_ca +.Nd check whether a certificate is a CA certificate +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fo X509_check_ca +.Fa "X509 *cert" +.Fc +.Sh DESCRIPTION +The +.Fn X509_check_ca +function checks whether the given certificate is a CA certificate, +that is, whether it can be used to sign other certificates. +.Sh RETURN VALUES +If +.Fa cert +is a CA certificate, a non-zero value is returned; 0 otherwise. +.Pp +The following return values identify specific kinds of CA certificates: +.Bl -tag -width 2n +.It 1 +an X.509 v3 CA certificate with +.Sy basicConstraints +extension CA:TRUE +.It 3 +a self-signed X.509 v1 certificate +.It 4 +a certificate with +.Sy keyUsage +extension with bit +.Sy keyCertSign +set, but without +.Sy basicConstraints +.It 5 +a certificate with an outdated Netscape Certificate Type extension telling +that it is a CA certificate +.El +.Sh SEE ALSO +.Xr BASIC_CONSTRAINTS_new 3 , +.Xr EXTENDED_KEY_USAGE_new 3 , +.Xr X509_check_issued 3 , +.Xr X509_check_purpose 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_new 3 , +.Xr X509_verify_cert 3 +.Sh HISTORY +.Fn X509_check_ca +first appeared in OpenSSL 0.9.7f and has been available since +.Ox 3.8 . +.Sh BUGS +If +.Fn X509_check_ca +fails to cache X509v3 extension values, the return value may +be incorrect. +An application should +call +.Xr X509_check_purpose 3 +with a +.Fa purpose +argument of \-1, +ensuring that the X509v3 extensions are cached, +before calling +.Fn X509_check_ca . diff --git a/static/openbsd/man3/X509_check_host.3 b/static/openbsd/man3/X509_check_host.3 new file mode 100644 index 00000000..be3190b2 --- /dev/null +++ b/static/openbsd/man3/X509_check_host.3 @@ -0,0 +1,247 @@ +.\" $OpenBSD: X509_check_host.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL a09e4d24 Jun 12 01:56:31 2014 -0400 +.\" selective merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 +.\" +.\" This file was written by Florian Weimer and +.\" Viktor Dukhovni . +.\" Copyright (c) 2012, 2014, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_CHECK_HOST 3 +.Os +.Sh NAME +.Nm X509_check_host , +.Nm X509_check_email , +.Nm X509_check_ip , +.Nm X509_check_ip_asc +.Nd X.509 certificate matching +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fo X509_check_host +.Fa "X509 *x" +.Fa "const char *name" +.Fa "size_t namelen" +.Fa "unsigned int flags" +.Fa "char **peername" +.Fc +.Ft int +.Fo X509_check_email +.Fa "X509 *x" +.Fa "const char *address" +.Fa "size_t addresslen" +.Fa "unsigned int flags" +.Fc +.Ft int +.Fo X509_check_ip +.Fa "X509 *x" +.Fa "const unsigned char *address" +.Fa "size_t addresslen" +.Fa "unsigned int flags" +.Fc +.Ft int +.Fo X509_check_ip_asc +.Fa "X509 *x" +.Fa "const char *address" +.Fa "unsigned int flags" +.Fc +.Sh 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 +.Fn X509_check_host +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; they may match part of that label with an +explicit prefix or suffix. +For example, by default, the host +.Fa name +.Qq www.example.com +would match a certificate with a SAN or CN value of +.Qq *.example.com , +.Qq w*.example.com +or +.Qq *w.example.com . +.Pp +Per section 6.4.2 of RFC 6125, +.Fa name +values representing international domain names must be given in A-label +form. +The +.Fa namelen +argument must be the number of characters in the name string or zero, in +which case the length is calculated with +.Fn strlen name . +When +.Fa name +starts with a dot (e.g.\& +.Qq .example.com ) , +it will be matched by a certificate valid for any sub-domain of +.Fa name ; +see also +.Fa X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS +below. +.Pp +When the certificate is matched and +.Fa peername +is not +.Dv NULL , +a pointer to a copy of the matching SAN or CN from the peer +certificate is stored at the address passed in +.Fa peername . +The application is responsible for freeing the peername via +.Xr free 3 +when it is no longer needed. +.Pp +.Fn X509_check_email +checks if the certificate matches the specified email +.Fa address . +Only the mailbox syntax of RFC 822 is supported. +Comments are not allowed, +and no attempt is made to normalize quoted characters. +The +.Fa addresslen +argument must be the number of characters in the address string or zero, +in which case the length is calculated with +.Fn strlen address . +.Pp +.Fn X509_check_ip +checks if the certificate matches a specified IPv4 or IPv6 address. +The +.Fa address +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. +.Pp +.Fn X509_check_ip_asc +is similar, except that the NUL-terminated string +.Fa address +is first converted to the internal representation. +.Pp +The +.Fa flags +argument is usually 0, but it can be the bitwise OR of the following +flags. +.Pp +The +.Dv X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT +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 remaining flags are only meaningful for +.Fn X509_check_host . +.Pp +The +.Dv X509_CHECK_FLAG_NO_WILDCARDS +flag disables wildcard expansion. +.Pp +The +.Dv X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS +flag suppresses support for +.Qq * +as a wildcard pattern in labels that have a +prefix or suffix, such as +.Qq www* +or +.Qq *www . +.Pp +The +.Dv X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS +flag allows a +.Qq * +that constitutes the complete label of a DNS name (e.g.\& +.Qq *.example.com ) +to match more than one label in +.Fa name . +.Pp +The +.Dv X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS +flag restricts +.Fa name +values which start with +.Qq \&. , +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 +.Fa name +of +.Qq .example.com +would match a peer certificate with a DNS name of +.Qq www.example.com , +but would not match a peer certificate with a DNS name of +.Qq www.sub.example.com . +.Sh 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, +.Fn X509_check_host +returns -2 if the provided +.Fa name +contains embedded NUL bytes. +.Sh SEE ALSO +.Xr SSL_set1_host 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_get1_email 3 , +.Xr X509_new 3 , +.Xr X509_VERIFY_PARAM_set1_host 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.2 +and have been available since +.Ox 6.1 . diff --git a/static/openbsd/man3/X509_check_issued.3 b/static/openbsd/man3/X509_check_issued.3 new file mode 100644 index 00000000..24457674 --- /dev/null +++ b/static/openbsd/man3/X509_check_issued.3 @@ -0,0 +1,110 @@ +.\" $OpenBSD: X509_check_issued.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Victor B. Wagner . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_CHECK_ISSUED 3 +.Os +.Sh NAME +.Nm X509_check_issued +.Nd check whether a certificate was issued using a given CA certificate +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fo X509_check_issued +.Fa "X509 *issuer" +.Fa "X509 *subject" +.Fc +.Sh DESCRIPTION +This function checks whether the certificate +.Fa subject +was issued using the CA certificate +.Fa issuer . +It does the following checks: +.Bl -bullet +.It +match the issuer field of +.Fa subject +against the subject field of +.Fa issuer +.It +if +.Sy authorityKeyIdentifier +is present in the +.Fa subject +certificate, +compare it to the +.Sy subjectKeyIdentifier +of +.Fa issuer +.It +check the +.Sy keyUsage +field of +.Fa issuer . +.El +.Sh RETURN VALUES +This function returns +.Dv X509_V_OK +if the certificate +.Fa subject +is issued by +.Fa issuer , +or some +.Dv X509_V_ERR* +constant to indicate an error. +.Sh SEE ALSO +.Xr X509_check_ca 3 , +.Xr X509_new 3 , +.Xr X509_verify_cert 3 +.Sh HISTORY +.Fn X509_check_issued +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . diff --git a/static/openbsd/man3/X509_check_private_key.3 b/static/openbsd/man3/X509_check_private_key.3 new file mode 100644 index 00000000..61ff0917 --- /dev/null +++ b/static/openbsd/man3/X509_check_private_key.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: X509_check_private_key.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL X509_check_private_key.pod 09ddb878 Jun 5 03:56:07 2017 +0800 +.\" +.\" Copyright (c) 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 $Mdocdate: June 8 2025 $ +.Dt X509_CHECK_PRIVATE_KEY 3 +.Os +.Sh NAME +.Nm X509_check_private_key , +.Nm X509_REQ_check_private_key +.Nd compare public key components +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_check_private_key +.Fa "const X509 *x" +.Fa "const EVP_PKEY *k" +.Fc +.Ft int +.Fo X509_REQ_check_private_key +.Fa "X509_REQ *x" +.Fa "EVP_PKEY *k" +.Fc +.Sh DESCRIPTION +These functions are seriously misnamed. +.Fn X509_check_private_key +compares the +.Em public +key components (e.g. exponent and modulus of an RSA key) +and parameters (e.g. EC params of an EC key) of +.Fa k +with the corresponding properties of +.Fa x . +Despite the name, it neither checks whether +.Fa k +contains private key components at all, nor, if any are present, +whether they are consistent with the public key components. +.Pp +.Fn X509_REQ_check_private_key +is equivalent to +.Fn X509_check_private_key +except that it compares to the public key +contained in a certificate request. +.Sh RETURN VALUES +These functions return 1 if the public key components and parameters +match, or 0 if they do not or if an error occurs. +On error or mismatch, a reason code can be obtained using +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr SSL_check_private_key 3 , +.Xr X509_new 3 , +.Xr X509_REQ_new 3 +.Sh HISTORY +.Fn X509_check_private_key +first appeared in SSLeay 0.6.5 and has been available since +.Ox 2.4 . +.Pp +.Fn X509_REQ_check_private_key +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/X509_check_purpose.3 b/static/openbsd/man3/X509_check_purpose.3 new file mode 100644 index 00000000..86ee53f5 --- /dev/null +++ b/static/openbsd/man3/X509_check_purpose.3 @@ -0,0 +1,432 @@ +.\" $OpenBSD: X509_check_purpose.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2019, 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_CHECK_PURPOSE 3 +.Os +.Sh NAME +.Nm X509_check_purpose +.Nd check intended usage of a public key +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fo X509_check_purpose +.Fa "X509 *certificate" +.Fa "int purpose" +.Fa "int ca" +.Fc +.Sh DESCRIPTION +If the +.Fa purpose +argument is \-1, +.Fn X509_check_purpose +ignores the +.Fa ca +argument and checks that all the extensions of the +.Fa certificate +can be parsed and pass minimal sanity checks, ensuring that +no extension occurs more than once. +It also makes sure that all extensions are cached in the +.Vt X509 +object. +.Pp +If the +.Fa purpose +argument is not \-1 and the +.Fa ca +flag is 0, +.Fn X509_check_purpose +also checks whether the public key contained in the +.Fa certificate +is intended to be used for the given +.Fa purpose , +which can be one of the following integer constants. +The check succeeds if none of the conditions given in the list below +are violated. +It always fails if parsing fails for any extension contained in the +.Fa certificate . +.Bl -tag -width 1n +.It Dv X509_PURPOSE_SSL_CLIENT +.Bl -dash -width 1n -compact +.It +If the +.Fa certificate +contains an Extended Key Usage extension, it contains the RFC 5280 +.Dq TLS WWW client authentication +purpose +.Pq Dv NID_client_auth . +.It +If the +.Fa certificate +contains a Key Usage extension, the +.Dv digitalSignature +bit is set. +.It +If the +.Fa certificate +contains a Netscape Cert Type extension, the +.Dq SSL client certificate +bit is set +.Pq Dv NS_SSL_CLIENT . +.El +.It Dv X509_PURPOSE_SSL_SERVER +.Bl -dash -width 1n -compact +.It +If the +.Fa certificate +contains an Extended Key Usage extension, it contains the RFC 5280 +.Dq TLS WWW server authentication +purpose +.Pq Dv NID_server_auth +or the private +.Dq Netscape Server Gated Crypto +.Pq Dv NID_ns_sgc +or +.Dq Microsoft Server Gated Crypto +.Pq Dv NID_ms_sgc +purpose. +.It +If the +.Fa certificate +contains a Key Usage extension, at least one of the +.Dv digitalSignature +and +.Dv keyEncipherment +bits is set. +.It +If the +.Fa certificate +contains a Netscape Cert Type extension, the +.Dq SSL server certificate +bit is set +.Pq Dv NS_SSL_SERVER +.El +.It Dv X509_PURPOSE_NS_SSL_SERVER +.\" check_purpose_ns_ssl_server, "Netscape SSL server" +This does the same checks as +.Dv X509_PURPOSE_SSL_SERVER +and additionally requires that a Key Usage extension, if present, +has the +.Dv keyEncipherment +bit set. +.It Dv X509_PURPOSE_SMIME_SIGN +.\" check_purpose_smime_sign, "S/MIME signing" +.Bl -dash -width 1n -compact +.It +If the +.Fa certificate +contains an Extended Key Usage extension, it contains the RFC 5280 +.Dq Email protection +purpose +.Pq Dv NID_email_protect . +.It +If the +.Fa certificate +contains a Key Usage extension, at least one of the +.Dv digitalSignature +and +.Dv nonRepudiation +bits is set. +.It +If the +.Fa certificate +contains a Netscape Cert Type extension, it has the +.Dq S/MIME certificate +bit set. +If the +.Dq SSL client certificate +bit is set but the +.Dq S/MIME certificate +bit is not, no decision is made. +.El +.It Dv X509_PURPOSE_SMIME_ENCRYPT +.\" check_purpose_smime_encrypt, "S/MIME encryption" +.Bl -dash -width 1n -compact +.It +If the +.Fa certificate +contains an Extended Key Usage extension, it contains the RFC 5280 +.Dq Email protection +purpose +.Pq Dv NID_email_protect . +.It +If the +.Fa certificate +contains a Key Usage extension, the +.Dv keyEncipherment +bit is set. +.It +If the +.Fa certificate +contains a Netscape Cert Type extension, it has the +.Dq S/MIME certificate +bit set. +If the +.Dq SSL client certificate +bit is set but the +.Dq S/MIME certificate +bit is not, no decision is made. +.El +.It Dv X509_PURPOSE_CRL_SIGN +.\" check_purpose_crl_sign, "CRL signing" +.Bl -dash -width 1n -compact +.It +If the +.Fa certificate +contains a Key Usage extension, the +.Dv cRLSign +bit is set. +.El +.It Dv X509_PURPOSE_ANY +Nothing is required except that, if any extensions are present, +parsing them needs to succeed. +.It Dv X509_PURPOSE_OCSP_HELPER +.\" ocsp_helper, "OCSP helper" +Nothing is required except that, if any extensions are present, +parsing them needs to succeed. +The application program is expected +to do the actual checking by other means. +.It Dv X509_PURPOSE_TIMESTAMP_SIGN +.\" check_purpose_timestamp_sign, "Time Stamp signing" +.Bl -dash -width 1n -compact +.It +The +.Fa certificate +contains an Extended Key Usage extension containing the RFC 5280 +.Dq Time Stamping +purpose and no other purpose. +This extension is marked as critical. +.It +If the +.Fa certificate +contains a Key Usage extension, at least one of the +.Dv digitalSignature +and +.Dv nonRepudiation +bits is set, and no other bits are set. +.El +.El +.Pp +If the +.Fa purpose +argument is not \-1 and the +.Fa ca +flag is non-zero, +.Fn X509_check_purpose +instead checks, in addition to the minimal sanity checks, whether the +.Fa certificate +can be used as a certificate authority certificate +in the context of the given +.Fa purpose . +To succeed, the check always requires that none of the following +conditions are violated: +.Pp +.Bl -dash -width 1n -compact +.It +If the +.Fa certificate +contains any extensions, parsing them succeeds. +.It +If the +.Fa certificate +contains a Key Usage extension, the +.Dv keyCertSign +bit is set. +.It +If the +.Fa certificate +contains a Basic Constraints extension, the +.Fa cA +field is set. +.It +If the +.Fa certificate +is a version 1 certificate, the subject name matches the issuer name +and the certificate is self signed. +.El +.Pp +The check succeeds if none of the additional conditions given in +the list below are violated. +.Bl -tag -width 1n +.It Dv X509_PURPOSE_SSL_CLIENT +.Bl -dash -width 1n -compact +.It +If the +.Fa certificate +contains an Extended Key Usage extension, it contains the RFC 5280 +.Dq TLS WWW client authentication +purpose +.Pq Dv NID_client_auth . +.It +If the +.Fa certificate +is not a version 1 certificate and does not contain a Basic Constraints +extension, it contains a Key Usage extension with the +.Dv keyCertSign +bit set or a Netscape Cert Type extension with the +.Dq SSL CA certificate +bit set. +.El +.It Dv X509_PURPOSE_SSL_SERVER No or Dv X509_PURPOSE_NS_SSL_SERVER +.Bl -dash -width 1n -compact +.It +If the +.Fa certificate +contains an Extended Key Usage extension, it contains the RFC 5280 +.Dq TLS WWW server authentication +purpose +.Pq Dv NID_server_auth +or the private +.Dq Netscape Server Gated Crypto +.Pq Dv NID_ns_sgc +or +.Dq Microsoft Server Gated Crypto +.Pq Dv NID_ms_sgc +purpose. +.It +If the +.Fa certificate +is not a version 1 certificate and does not contain a Basic Constraints +extension, it contains a Key Usage extension with the +.Dv keyCertSign +bit set or a Netscape Cert Type extension with the +.Dq SSL CA certificate +bit set. +.El +.It Dv X509_PURPOSE_SMIME_SIGN No or Dv X509_PURPOSE_SMIME_ENCRYPT +.Bl -dash -width 1n -compact +.It +If the +.Fa certificate +contains an Extended Key Usage extension, it contains the RFC 5280 +.Dq Email protection +purpose +.Pq Dv NID_email_protect . +.It +If the +.Fa certificate +is not a version 1 certificate and does not contain a Basic Constraints +extension, it contains a Key Usage extension with the +.Dv keyCertSign +bit set or a Netscape Cert Type extension with the +.Dq S/MIME CA certificate +bit set. +.El +.It Xo +.Dv X509_PURPOSE_CRL_SIGN , +.Dv X509_PURPOSE_OCSP_HELPER , +or +.Dv X509_PURPOSE_TIMESTAMP_SIGN +.Xc +.Bl -dash -width 1n -compact +.It +If the +.Fa certificate +is not a version 1 certificate and does not contain a Basic Constraints +extension, it contains a Key Usage extension with the +.Dv keyCertSign +bit set or a Netscape Cert Type extension with at least one of the +.Dq SSL CA certificate , +.Dq S/MIME CA certificate , +or +.Dq Object-signing CA certificate +bits set. +.El +.It Dv X509_PURPOSE_ANY +Nothing is required except that, if any extensions are present, +parsing them needs to succeed. +The check even succeeds if the three other common conditions +cited above this list are violated. +.El +.Pp +If the function +.Xr X509_PURPOSE_add 3 +was called before +.Fn X509_check_purpose , +it may have installed different, user-supplied checking functions +for some of the standard purposes listed above, or it may have +installed additional, user-supplied checking functions for user-defined +.Fa purpose +identifiers not listed above. +.Sh RETURN VALUES +If the parsing of certificate extensions fails, sanity checks fail or the +.Fa purpose +is invalid, +.Fn X509_check_purpose +returns \-1 to indicate the error. +.Pp +If the +.Fa purpose +argument is \-1 and parsing and minimal sanity checks succeed, +.Fn X509_check_purpose +returns 1 to indicate success. +.Pp +Otherwise, it returns the following values: +.Pp +If +.Fa ca +is 0: +.Bl -column -1 Failure -compact +.It 0 Ta Failure Ta The +.Fa certificate +cannot be used for the +.Fa purpose . +.It 1 Ta Success Ta The +.Fa certificate +can be used for the +.Fa purpose . +.It 2 Ta Unknown Ta \&No decision can be made. +.El +.Pp +If +.Fa ca +is non-zero: +.Bl -column -1 Failure -compact +.It 0 Ta Failure Ta The +.Fa certificate +cannot be used as a CA for the +.Fa purpose . +.It 1 Ta Success Ta The +.Fa certificate +can be used as a CA for the +.Fa purpose . +.It 3 Ta Success Ta The Fa certificate No is a version 1 CA . +.It 4 Ta Success Ta The Key Usage allows Dv keyCertSign . +.It 5 Ta Success Ta A Netscape Cert Type allows usage as a CA. +.El +.Sh SEE ALSO +.Xr BASIC_CONSTRAINTS_new 3 , +.Xr EXTENDED_KEY_USAGE_new 3 , +.Xr X509_new 3 , +.Xr X509_PURPOSE_set 3 , +.Xr X509V3_get_d2i 3 , +.Xr x509v3.cnf 5 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Bl -dash -offset indent -compact +.It +section 4.2.1.3: Key Usage +.It +section 4.2.1.9: Basic Constraints +.It +section 4.2.1.12: Extended Key Usage +.El +.Sh HISTORY +.Fn X509_check_purpose +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/X509_cmp.3 b/static/openbsd/man3/X509_cmp.3 new file mode 100644 index 00000000..e025f5c8 --- /dev/null +++ b/static/openbsd/man3/X509_cmp.3 @@ -0,0 +1,233 @@ +.\" $OpenBSD: X509_cmp.3,v 1.5 2025/06/08 22:37:23 schwarze Exp $ +.\" full merge up to: OpenSSL ea5d4b89 Jun 6 11:42:02 2019 +0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 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. +.\" +.\" The original file was written by Paul Yang . +.\" Copyright (c) 2019 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_CMP 3 +.Os +.Sh NAME +.Nm X509_cmp , +.Nm X509_NAME_cmp , +.\" The alias X509_name_cmp(3) is intentionally undocumented +.\" because it is almost unused in real-world code. +.Nm X509_issuer_and_serial_cmp , +.Nm X509_issuer_name_cmp , +.Nm X509_subject_name_cmp , +.Nm X509_CRL_cmp , +.Nm X509_CRL_match +.Nd compare X.509 certificates and related values +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_cmp +.Fa "const X509 *a" +.Fa "const X509 *b" +.Fc +.Ft int +.Fo X509_NAME_cmp +.Fa "const X509_NAME *a" +.Fa "const X509_NAME *b" +.Fc +.Ft int +.Fo X509_issuer_and_serial_cmp +.Fa "const X509 *a" +.Fa "const X509 *b" +.Fc +.Ft int +.Fo X509_issuer_name_cmp +.Fa "const X509 *a" +.Fa "const X509 *b" +.Fc +.Ft int +.Fo X509_subject_name_cmp +.Fa "const X509 *a" +.Fa "const X509 *b" +.Fc +.Ft int +.Fo X509_CRL_cmp +.Fa "const X509_CRL *a" +.Fa "const X509_CRL *b" +.Fc +.Ft int +.Fo X509_CRL_match +.Fa "const X509_CRL *a" +.Fa "const X509_CRL *b" +.Fc +.Sh DESCRIPTION +.Fn X509_cmp +compares two X.509 certificates using +.Xr memcmp 3 +on the hashes of their canonical (DER) representations as generated with +.Xr X509_digest 3 . +The digest function is implementation-specific: LibreSSL uses SHA-512, other +implementations use SHA-1. +.Pp +.Fn X509_NAME_cmp +compares two X.501 +.Vt Name +objects using their canonical (DER) representations generated with +.Xr i2d_X509_NAME 3 . +.Pp +.Fn X509_issuer_and_serial_cmp +compares the +.Fa issuer +and +.Fa serialNumber +fields of two +.Vt TBSCertificate +structures, using +.Fn X509_NAME_cmp +for the +.Fa issuer +fields. +.Pp +.Fn X509_issuer_name_cmp +compares the +.Fa issuer +fields of two +.Vt TBSCertificate +structures using +.Fn X509_NAME_cmp . +.Pp +.Fn X509_subject_name_cmp +compares the +.Fa subject +fields of two +.Vt TBSCertificate +structures using +.Fn X509_NAME_cmp . +.Pp +.Fn X509_CRL_cmp +is misnamed; it only compares the +.Fa issuer +fields of two +.Vt TBSCertList +structures using +.Fn X509_NAME_cmp . +.Pp +.Fn X509_CRL_match +compares two certificate revocation lists using +.Xr memcmp 3 +on the hashes of their canonical (DER) representations as generated with +.Xr X509_CRL_digest 3 . +The digest function is implementation-specific: LibreSSL uses SHA-512, other +implementations use SHA-1. +.Sh RETURN VALUES +All these functions return 0 to indicate a match or a non-zero value +to indicate a mismatch. +.Pp +.Fn X509_NAME_cmp , +.Fn X509_issuer_and_serial_cmp , +.Fn X509_issuer_name_cmp , +.Fn X509_subject_name_cmp +and +.Fn X509_CRL_cmp +may return -2 to indicate an error. +.Sh SEE ALSO +.Xr i2d_X509_NAME 3 , +.Xr X509_CRL_new 3 , +.Xr X509_digest 3 , +.Xr X509_NAME_new 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate +and Certificate Revocation List (CRL) Profile +.Bl -dash -compact -offset indent +.It +section 4.1: Basic Certificate Fields +.It +section 5.1: CRL Fields +.El +.Sh HISTORY +.Fn X509_issuer_and_serial_cmp , +.Fn X509_issuer_name_cmp , +and +.Fn X509_subject_name_cmp +first appeared in SSLeay 0.5.1 and +.Fn X509_NAME_cmp +and +.Fn X509_CRL_cmp +in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_cmp +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn X509_CRL_match +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Sh BUGS +For +.Fn X509_NAME_cmp , +.Fn X509_issuer_and_serial_cmp , +.Fn X509_issuer_name_cmp , +.Fn X509_subject_name_cmp +and +.Fn X509_CRL_cmp , +the return value -2 sometimes indicates a mismatch and sometimes an error. diff --git a/static/openbsd/man3/X509_cmp_time.3 b/static/openbsd/man3/X509_cmp_time.3 new file mode 100644 index 00000000..2ac584ad --- /dev/null +++ b/static/openbsd/man3/X509_cmp_time.3 @@ -0,0 +1,201 @@ +.\" $OpenBSD: X509_cmp_time.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2017, 2021 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. +.\" +.\" The original file was written by Emilia Kasper +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_CMP_TIME 3 +.Os +.Sh NAME +.Nm X509_cmp_time , +.Nm X509_cmp_current_time , +.Nm X509_time_adj_ex , +.Nm X509_time_adj , +.Nm X509_gmtime_adj +.Nd ASN.1 Time utilities +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_cmp_time +.Fa "const ASN1_TIME *asn1_time" +.Fa "time_t *cmp_time" +.Fc +.Ft int +.Fo X509_cmp_current_time +.Fa "const ASN1_TIME *asn1_time" +.Fc +.Ft ASN1_TIME * +.Fo X509_time_adj_ex +.Fa "ASN1_TIME *out_time" +.Fa "int offset_day" +.Fa "long offset_sec" +.Fa "time_t *in_time" +.Fc +.Ft ASN1_TIME * +.Fo X509_time_adj +.Fa "ASN1_TIME *out_time" +.Fa "long offset_sec" +.Fa "time_t *in_time" +.Fc +.Ft ASN1_TIME * +.Fo X509_gmtime_adj +.Fa "ASN1_TIME *out_time" +.Fa "long offset_sec" +.Fc +.Sh DESCRIPTION +.Fn X509_cmp_time +parses +.Fa asn1_time +and compares it to +.Fa cmp_time , +or to the current time if +.Fa cmp_time +is +.Dv NULL . +.Fn X509_cmp_current_time +compares it to the current time. +.Pp +.Fn X509_time_adj_ex +sets +.Fa out_time +to a time +.Fa offset_day +and +.Fa offset_sec +later than +.Fa in_time . +The values of +.Fa offset_day +and +.Fa offset_sec +can be negative to set a time before +.Fa in_time . +The +.Fa offset_sec +value can also exceed the number of seconds in a day. +If +.Fa in_time +is +.Dv NULL , +the current time is used instead. +If +.Fa out_time +is +.Dv NULL , +a new +.Vt ASN1_TIME +structure is allocated and returned. +.Pp +.Fn X509_time_adj +does the same with a 0 day offset. +.Pp +.Fn X509_gmtime_adj +does the same using the current time instead of +.Fa in_time , +that is, it sets +.Fa out_time +to a time +.Fa offset_sec +seconds later than the current time. +.Sh RETURN VALUES +.Fn X509_cmp_time +and +.Fn X509_cmp_current_time +return -1 if +.Fa asn1_time +is earlier than or equal to +.Fa cmp_time , +1 if it is later, or 0 on error. +.Pp +.Fn X509_time_adj_ex , +.Fn X509_time_adj , +and +.Fn X509_gmtime_adj +return a pointer to the updated or newly allocated +.Vt ASN1_TIME +structure or +.Dv NULL +on error. +.Sh SEE ALSO +.Xr ASN1_TIME_new 3 , +.Xr ASN1_TIME_set 3 , +.Xr time 3 +.Sh HISTORY +.Fn X509_cmp_current_time +and +.Fn X509_gmtime_adj +first appeared in SSLeay 0.6.0 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_cmp_time +and +.Fn X509_time_adj +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Pp +.Fn X509_time_adj_ex +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/X509_digest.3 b/static/openbsd/man3/X509_digest.3 new file mode 100644 index 00000000..991d1990 --- /dev/null +++ b/static/openbsd/man3/X509_digest.3 @@ -0,0 +1,156 @@ +.\" $OpenBSD: X509_digest.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100 +.\" +.\" This file was written by Rich Salz +.\" Copyright (c) 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_DIGEST 3 +.Os +.Sh NAME +.Nm X509_digest , +.Nm X509_CRL_digest , +.Nm X509_pubkey_digest , +.Nm X509_NAME_digest , +.Nm X509_REQ_digest , +.Nm PKCS7_ISSUER_AND_SERIAL_digest +.Nd get digests of various objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_digest +.Fa "const X509 *data" +.Fa "const EVP_MD *type" +.Fa "unsigned char *md" +.Fa "unsigned int *len" +.Fc +.Ft int +.Fo X509_CRL_digest +.Fa "const X509_CRL *data" +.Fa "const EVP_MD *type" +.Fa "unsigned char *md" +.Fa "unsigned int *len" +.Fc +.Ft int +.Fo X509_pubkey_digest +.Fa "const X509 *data" +.Fa "const EVP_MD *type" +.Fa "unsigned char *md" +.Fa "unsigned int *len" +.Fc +.Ft int +.Fo X509_REQ_digest +.Fa "const X509_REQ *data" +.Fa "const EVP_MD *type" +.Fa "unsigned char *md" +.Fa "unsigned int *len" +.Fc +.Ft int +.Fo X509_NAME_digest +.Fa "const X509_NAME *data" +.Fa "const EVP_MD *type" +.Fa "unsigned char *md" +.Fa "unsigned int *len" +.Fc +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_ISSUER_AND_SERIAL_digest +.Fa "PKCS7_ISSUER_AND_SERIAL *data" +.Fa "const EVP_MD *type" +.Fa "unsigned char *md" +.Fa "unsigned int *len" +.Fc +.Sh DESCRIPTION +.Fn X509_pubkey_digest +returns a digest of the DER representation of the public key contained in +.Fa data . +All other functions described here return a digest of the DER +representation of their entire +.Fa data +object. +.Pp +The +.Fa type +parameter specifies the digest to be used, such as +.Xr EVP_sha1 3 . +.Fa md +is a pointer to the buffer where the digest will be copied and is +assumed to be large enough; a size of at least +.Dv EVP_MAX_MD_SIZE +bytes is suggested. +The +.Fa len +parameter, if not +.Dv NULL , +points to a place where the digest size will be stored. +.Sh RETURN VALUES +These functions return 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr EVP_get_digestbyname 3 , +.Xr X509_cmp 3 , +.Xr X509_CRL_new 3 , +.Xr X509_NAME_new 3 , +.Xr X509_new 3 , +.Xr X509_REQ_new 3 +.Sh HISTORY +.Fn X509_digest , +.Fn X509_NAME_digest , +and +.Fn PKCS7_ISSUER_AND_SERIAL_digest +first appeared in SSLeay 0.6.5 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_CRL_digest +and +.Fn X509_REQ_digest +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Pp +.Fn X509_pubkey_digest +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/X509_find_by_subject.3 b/static/openbsd/man3/X509_find_by_subject.3 new file mode 100644 index 00000000..962eb808 --- /dev/null +++ b/static/openbsd/man3/X509_find_by_subject.3 @@ -0,0 +1,70 @@ +.\" $OpenBSD: X509_find_by_subject.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_FIND_BY_SUBJECT 3 +.Os +.Sh NAME +.Nm X509_find_by_subject , +.Nm X509_find_by_issuer_and_serial +.Nd search an array of X.509 certificates +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509 * +.Fo X509_find_by_subject +.Fa "STACK_OF(X509) *sk" +.Fa "X509_NAME *subject" +.Fc +.Ft X509 * +.Fo X509_find_by_issuer_and_serial +.Fa "STACK_OF(X509) *sk" +.Fa "X509_NAME *issuer" +.Fa "ASN1_INTEGER *serial" +.Fc +.Sh DESCRIPTION +.Fn X509_find_by_subject +searches the variable-sized array +.Fa sk +for a certificate with a matching +.Fa subject +name. +.Pp +.Fn X509_find_by_issuer_and_serial +searches the array for a certificate where both the +.Fa issuer +name and the +.Fa serial +number match the arguments. +.Sh RETURN VALUES +These functions return a pointer to the first matching certificate or +.Dv NULL +if +.Fa sk +is +.Dv NULL +or does not contain a matching certificate. +.Sh SEE ALSO +.Xr ASN1_INTEGER_new 3 , +.Xr STACK_OF 3 , +.Xr X509_cmp 3 , +.Xr X509_get_serialNumber 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_NAME_new 3 , +.Xr X509_new 3 +.Sh HISTORY +These functions first appeared in SSLeay 0.8.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/X509_get0_notBefore.3 b/static/openbsd/man3/X509_get0_notBefore.3 new file mode 100644 index 00000000..5ac075fe --- /dev/null +++ b/static/openbsd/man3/X509_get0_notBefore.3 @@ -0,0 +1,265 @@ +.\" $OpenBSD: X509_get0_notBefore.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $ +.\" content checked up to: OpenSSL 27b138e9 May 19 00:16:38 2017 +0000 +.\" +.\" Copyright (c) 2018, 2020 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 $Mdocdate: June 8 2025 $ +.Dt X509_GET0_NOTBEFORE 3 +.Os +.Sh NAME +.Nm X509_get0_notBefore , +.Nm X509_get0_notAfter , +.Nm X509_getm_notBefore , +.Nm X509_getm_notAfter , +.Nm X509_get_notBefore , +.Nm X509_get_notAfter , +.Nm X509_CRL_get0_lastUpdate , +.Nm X509_CRL_get0_nextUpdate , +.Nm X509_CRL_get_lastUpdate , +.Nm X509_CRL_get_nextUpdate , +.Nm X509_set1_notBefore , +.Nm X509_set1_notAfter , +.Nm X509_set_notBefore , +.Nm X509_set_notAfter , +.Nm X509_CRL_set1_lastUpdate , +.Nm X509_CRL_set1_nextUpdate , +.Nm X509_CRL_set_lastUpdate , +.Nm X509_CRL_set_nextUpdate +.Nd get and set certificate and CRL validity dates +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft const ASN1_TIME * +.Fo X509_get0_notBefore +.Fa "const X509 *x" +.Fc +.Ft const ASN1_TIME * +.Fo X509_get0_notAfter +.Fa "const X509 *x" +.Fc +.Ft ASN1_TIME * +.Fo X509_getm_notBefore +.Fa "const X509 *x" +.Fc +.Ft ASN1_TIME * +.Fo X509_getm_notAfter +.Fa "const X509 *x" +.Fc +.Ft ASN1_TIME * +.Fo X509_get_notBefore +.Fa "const X509 *x" +.Fc +.Ft ASN1_TIME * +.Fo X509_get_notAfter +.Fa "const X509 *x" +.Fc +.Ft const ASN1_TIME * +.Fo X509_CRL_get0_lastUpdate +.Fa "const X509_CRL *crl" +.Fc +.Ft const ASN1_TIME * +.Fo X509_CRL_get0_nextUpdate +.Fa "const X509_CRL *crl" +.Fc +.Ft ASN1_TIME * +.Fo X509_CRL_get_lastUpdate +.Fa "X509_CRL *crl" +.Fc +.Ft ASN1_TIME * +.Fo X509_CRL_get_nextUpdate +.Fa "X509_CRL *crl" +.Fc +.Ft int +.Fo X509_set1_notBefore +.Fa "X509 *x" +.Fa "const ASN1_TIME *tm" +.Fc +.Ft int +.Fo X509_set1_notAfter +.Fa "X509 *x" +.Fa "const ASN1_TIME *tm" +.Fc +.Ft int +.Fo X509_set_notBefore +.Fa "X509 *x" +.Fa "const ASN1_TIME *tm" +.Fc +.Ft int +.Fo X509_set_notAfter +.Fa "X509 *x" +.Fa "const ASN1_TIME *tm" +.Fc +.Ft int +.Fo X509_CRL_set1_lastUpdate +.Fa "X509_CRL *crl" +.Fa "const ASN1_TIME *tm" +.Fc +.Ft int +.Fo X509_CRL_set1_nextUpdate +.Fa "X509_CRL *crl" +.Fa "const ASN1_TIME *tm" +.Fc +.Ft int +.Fo X509_CRL_set_lastUpdate +.Fa "X509_CRL *crl" +.Fa "const ASN1_TIME *tm" +.Fc +.Ft int +.Fo X509_CRL_set_nextUpdate +.Fa "X509_CRL *crl" +.Fa "const ASN1_TIME *tm" +.Fc +.Sh DESCRIPTION +.Fn X509_getm_notBefore +and +.Fn X509_getm_notAfter +return pointers to the +.Fa notBefore +and +.Fa notAfter +fields of the validity period of the certificate +.Fa x , +respectively. +.Fn X509_get_notBefore +and +.Fn X509_get_notAfter +are deprecated aliases implemented as macros. +.Pp +.Fn X509_get0_notBefore +and +.Fn X509_get0_notAfter +are identical except for the const qualifier on the return type. +.Pp +.Fn X509_CRL_get0_lastUpdate +is misnamed in a confusing way: it returns a pointer to the +.Fa thisUpdate +field of the +.Fa crl , +indicating the time when this +.Fa crl +was issued. +.Pp +.Fn X509_CRL_get0_nextUpdate +returns a pointer to the +.Fa nextUpdate +field of the +.Fa crl , +indicating the time when issuing the subsequent CRL will be due. +.Pp +.Fn X509_CRL_get_lastUpdate +and +.Fn X509_CRL_get_nextUpdate +are deprecated and identical except for the const qualifier +on the argument and on the return type. +.Pp +.Fn X509_set1_notBefore , +.Fn X509_set1_notAfter , +.Fn X509_CRL_set1_lastUpdate , +and +.Fn X509_CRL_set1_nextUpdate +set the +.Fa notBefore , +.Fa notAfter , +.Fa thisUpdate Pq sic!\& , +or +.Fa nextUpdate +field of +.Fa x +or +.Fa crl , +respectively, to a deep copy of +.Fa tm +and free the +.Vt ASN1_TIME +value that they replace. +.Pp +.Fn X509_set_notBefore , +.Fn X509_set_notAfter , +.Fn X509_CRL_set_lastUpdate , +and +.Fn X509_CRL_set_nextUpdate +are deprecated aliases. +.Sh RETURN VALUES +The +.Sy get +functions return internal pointers +which must not be freed by the application, or +.Dv NULL +if the requested field is not available. +They may crash with a +.Dv NULL +pointer access if +.Fa x +or +.Fa crl +is +.Dv NULL . +.Pp +The +.Sy set +functions return 1 on success or 0 on failure. +They fail if +.Fa x +is +.Dv NULL +or does not contain a +.Fa validity +substructure, if +.Fa crl +is +.Dv NULL , +or if +.Xr ASN1_STRING_dup 3 +fails. +.Pp +Except for some cases of +.Xr ASN1_STRING_dup 3 +failure, these functions do not support +determining reasons for failure with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ASN1_TIME_set 3 , +.Xr X509_cmp_time 3 , +.Xr X509_CRL_get0_by_serial 3 , +.Xr X509_CRL_new 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_new 3 , +.Xr X509_sign 3 , +.Xr X509_VAL_new 3 , +.Xr X509_verify_cert 3 +.Sh HISTORY +.Fn X509_get_notBefore , +.Fn X509_get_notAfter , +.Fn X509_set_notBefore , +and +.Fn X509_set_notAfter +first appeared in SSLeay 0.6.5 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_CRL_get_lastUpdate +and +.Fn X509_CRL_get_nextUpdate +first appeared in OpenSSL 0.9.2 and have been available since +.Ox 2.6 . +.Pp +.Fn X509_CRL_set_lastUpdate +and +.Fn X509_CRL_set_nextUpdate +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +The remaining functions first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/X509_get0_signature.3 b/static/openbsd/man3/X509_get0_signature.3 new file mode 100644 index 00000000..6cebb94e --- /dev/null +++ b/static/openbsd/man3/X509_get0_signature.3 @@ -0,0 +1,288 @@ +.\" $OpenBSD: X509_get0_signature.3,v 1.12 2025/07/06 09:32:08 tb Exp $ +.\" selective merge up to: +.\" OpenSSL man3/X509_get0_signature 2f7a2520 Apr 25 17:28:08 2017 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2020 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: July 6 2025 $ +.Dt X509_GET0_SIGNATURE 3 +.Os +.Sh NAME +.Nm X509_get0_signature , +.Nm X509_REQ_get0_signature , +.Nm X509_CRL_get0_signature , +.Nm X509_get0_tbs_sigalg , +.Nm X509_CRL_get0_tbs_sigalg , +.Nm X509_get_signature_type , +.Nm X509_get_signature_nid , +.Nm X509_REQ_get_signature_nid , +.Nm X509_CRL_get_signature_nid , +.Nm X509_get_signature_info +.Nd signature information +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft void +.Fo X509_get0_signature +.Fa "const ASN1_BIT_STRING **psig" +.Fa "const X509_ALGOR **palg" +.Fa "const X509 *x" +.Fc +.Ft void +.Fo X509_REQ_get0_signature +.Fa "const X509_REQ *req" +.Fa "const ASN1_BIT_STRING **psig" +.Fa "const X509_ALGOR **palg" +.Fc +.Ft void +.Fo X509_CRL_get0_signature +.Fa "const X509_CRL *crl" +.Fa "const ASN1_BIT_STRING **psig" +.Fa "const X509_ALGOR **palg" +.Fc +.Ft const X509_ALGOR * +.Fo X509_get0_tbs_sigalg +.Fa "const X509 *x" +.Fc +.Ft const X509_ALGOR * +.Fo X509_CRL_get0_tbs_sigalg +.Fa "const X509_CRL *crl" +.Fc +.Ft int +.Fo X509_get_signature_type +.Fa "const X509 *x" +.Fc +.Ft int +.Fo X509_get_signature_nid +.Fa "const X509 *x" +.Fc +.Ft int +.Fo X509_REQ_get_signature_nid +.Fa "const X509_REQ *req" +.Fc +.Ft int +.Fo X509_CRL_get_signature_nid +.Fa "const X509_CRL *crl" +.Fc +.Ft int +.Fo X509_get_signature_info +.Fa "X509 *x" +.Fa "int *md_nid" +.Fa "int *pkey_nid" +.Fa "int *security_bits" +.Fa "uint32_t *flags" +.Fc +.Sh DESCRIPTION +.Fn X509_get0_signature , +.Fn X509_REQ_get0_signature , +and +.Fn X509_CRL_get0_signature +set +.Pf * Fa psig +to the signature and +.Pf * Fa palg +to the signature algorithm of +.Fa x , +.Fa req , +or +.Fa crl , +respectively. +.Fn X509_get0_tbs_sigalg +and +.Fn X509_CRL_get0_tbs_sigalg +return the signature algorithm in the signed portion of +.Fa x +or +.Fa crl , +respectively. +The values returned are internal pointers +that must not be freed by the caller. +.Pp +.Fn X509_get_signature_type +returns the base NID corresponding to the signature algorithm of +.Fa x +just like +.Xr EVP_PKEY_base_id 3 +does. +.Pp +.Fn X509_get_signature_nid , +.Fn X509_REQ_get_signature_nid , +and +.Fn X509_CRL_get_signature_nid +return the NID corresponding to the signature algorithm of +.Fa x , +.Fa req , +or +.Fa crl , +respectively, just like +.Xr EVP_PKEY_id 3 +does. +.Pp +.Fn X509_get_signature_info +retrieves information about the signature of certificate +.Fa x . +The NID of the digest algorithm is written to +.Pf * Fa md_nid , +the public key algorithm to +.Pf * Fa pkey_nid , +the effective security bits to +.Pf * Fa security_bits , +and flag details to +.Pf * Fa flags . +Any of the output parameters can be set to +.Dv NULL +if the information is not required. +If +.Fa flags +is not a +.Dv NULL +pointer, +.Pf * Fa flags +is set to the bitwise OR of: +.Bl -tag -width 1n -offset 3n +.It Dv X509_SIG_INFO_VALID +No error occurred. +This flag is set if +.Fn X509_get_signature_info +returns 1. +.It Dv X509_SIG_INFO_TLS +The signature algorithm is appropriate for use in TLS. +For a supported EdDSA algorithm (in LibreSSL this is Ed25519) +this flag is always set. +For an RSASSA-PSS PSS algorithm this flag is set if +the parameters are DER encoded, +the digest algorithm is one of SHA-256, SHA-384, or SHA-512, +the same digest algorithm is used in the mask generation function, +and the salt length is equal to the digest algorithm's output length. +For all other signature algorithms this flag is set if the digest +algorithm is one of SHA-1, SHA-256, SHA-384, or SHA-512. +.El +.Pp +.Fn X509_get_signature_info +returns 1 on success and 0 on failure. +Failure conditions include unsupported signature algorithms, +certificate parsing errors and memory allocation failure. +.Pp +These functions provide lower level access to the signature +for cases where an application wishes to analyse or generate a +signature in a form where +.Xr X509_sign 3 +is not appropriate, for example in a non-standard or unsupported format. +.Sh SEE ALSO +.Xr EVP_PKEY_base_id 3 , +.Xr OBJ_obj2nid 3 , +.Xr X509_ALGOR_new 3 , +.Xr X509_CRL_get0_by_serial 3 , +.Xr X509_CRL_new 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_get_version 3 , +.Xr X509_new 3 , +.Xr X509_REQ_new 3 , +.Xr X509_sign 3 , +.Xr X509_signature_dump 3 , +.Xr X509_verify_cert 3 +.Sh HISTORY +.Fn X509_get_signature_type +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . +.Pp +.Fn X509_get0_signature +and +.Fn X509_get_signature_nid +first appeared in OpenSSL 1.0.2. +.Fn X509_REQ_get0_signature , +.Fn X509_CRL_get0_signature , +.Fn X509_get0_tbs_sigalg , +.Fn X509_REQ_get_signature_nid , +and +.Fn X509_CRL_get_signature_nid +first appeared in OpenSSL 1.1.0. +All these functions have been available since +.Ox 6.3 . +.Pp +.Fn X509_CRL_get0_tbs_sigalg +first appeared in LibreSSL 3.7.1 and has been available since +.Ox 7.3 . +.Pp +.Fn X509_get_signature_info +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 7.6 . +.Sh CAVEATS +The security bits returned by +.Fn X509_get_signature_info +refer to the information available from the certificate signature +(such as the signing digest). +In some cases the actual security of the signature is smaller +because the signing key is less secure. +For example in a certificate signed using SHA-512 +and a 1024-bit RSA key. +.Sh BUGS +The signatures of +.Fn X509_get0_signature , +.Fn X509_REQ_get0_signature , +and +.Fn X509_CRL_get0_signature +are inconsistent. diff --git a/static/openbsd/man3/X509_get1_email.3 b/static/openbsd/man3/X509_get1_email.3 new file mode 100644 index 00000000..020708d2 --- /dev/null +++ b/static/openbsd/man3/X509_get1_email.3 @@ -0,0 +1,124 @@ +.\" $OpenBSD: X509_get1_email.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2019 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 $Mdocdate: June 8 2025 $ +.Dt X509_GET1_EMAIL 3 +.Os +.Sh NAME +.Nm X509_get1_email , +.Nm X509_get1_ocsp , +.Nm X509_email_free +.Nd utilities for stacks of strings +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Vt typedef char *OPENSSL_STRING ; +.Ft STACK_OF(OPENSSL_STRING) * +.Fo X509_get1_email +.Fa "X509 *certificate" +.Fc +.Ft STACK_OF(OPENSSL_STRING) * +.Fo X509_get1_ocsp +.Fa "X509 *certificate" +.Fc +.Ft void +.Fo X509_email_free +.Fa "STACK_OF(OPENSSL_STRING) *stack" +.Fc +.Sh DESCRIPTION +.Fn X509_get1_email +retrieves all email addresses from the +.Fa subject +field and from any +Subject Alternative Name extension of the +.Fa certificate . +.Pp +.Fn X509_get1_ocsp +retrieves all uniform resource identifiers +from all +.Vt AccessDescription +objects having an +.Fa accessMethod +of OCSP which are contained in the Authority Information Access extension +of the +.Fa certificate . +.Pp +.Fn X509_email_free +frees all strings stored in the +.Fa stack +as well as the stack itself. +If +.Fa stack +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn X509_REQ_get1_email +and +.Fn X509_get1_ocsp +return newly allocated stacks of +.Vt char * +containing copies of the addresses in question, or +.Dv NULL +if there are no addresses or if an error occurs. +.Sh SEE ALSO +.Xr OCSP_sendreq_new 3 , +.Xr OCSP_SERVICELOC_new 3 , +.Xr OPENSSL_sk_new 3 , +.Xr STACK_OF 3 , +.Xr X509_check_email 3 , +.Xr X509_get_ext_d2i 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_new 3 , +.Xr x509v3.cnf 5 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Bl -dash -offset indent -compact +.It +section 4.1: Basic Certificate Fields +.It +section 4.1.2.6: Subject +.It +section 4.2.1.6: Subject Alternative Name +.It +section 4.2.2.1: Authority Information Access +.El +.Pp +RFC 2985: PKCS #9: Selected Object Classes and Attribute Types +.Bl -dash -offset indent -compact +.It +section 5.2.1: Electronic-mail address +.It +appendix B.3.5: emailAddress +.El +.Sh HISTORY +.Fn X509_get1_email +and +.Fn X509_email_free +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Pp +.Fn X509_get1_ocsp +first appeared in OpenSSL 0.9.8h and has been available since +.Ox 4.5 . +.Sh BUGS +.Fn X509_email_free +is utterly misnamed. +It does not operate on any +.Vt X509 +object, nor is it in any way restricted to email addresses; +instead, it simply frees a stack of strings. diff --git a/static/openbsd/man3/X509_get_extension_flags.3 b/static/openbsd/man3/X509_get_extension_flags.3 new file mode 100644 index 00000000..1d15be40 --- /dev/null +++ b/static/openbsd/man3/X509_get_extension_flags.3 @@ -0,0 +1,235 @@ +.\" $OpenBSD: X509_get_extension_flags.3,v 1.6 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 361136f4 Sep 1 18:56:58 2015 +0100 +.\" selective merge up to: OpenSSL 2b2e3106f Feb 16 15:04:45 2021 +0000 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_GET_EXTENSION_FLAGS 3 +.Os +.Sh NAME +.Nm X509_get_extension_flags , +.Nm X509_get_key_usage , +.Nm X509_get_extended_key_usage +.Nd retrieve certificate extension data +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft uint32_t +.Fo X509_get_extension_flags +.Fa "X509 *x" +.Fc +.Ft uint32_t +.Fo X509_get_key_usage +.Fa "X509 *x" +.Fc +.Ft uint32_t +.Fo X509_get_extended_key_usage +.Fa "X509 *x" +.Fc +.Sh DESCRIPTION +These functions retrieve information related to commonly used +certificate extensions. +.Pp +.Fn X509_get_extension_flags +retrieves general information about a certificate. +It returns one or more of the following flags OR'ed together. +.Bl -tag -width Ds +.It Dv EXFLAG_V1 +The certificate is an obsolete version 1 certificate. +.It Dv EXFLAG_BCONS +The certificate contains a basic constraints extension. +.It Dv EXFLAG_CA +The certificate contains basic constraints and asserts the CA flag. +.It Dv EXFLAG_PROXY +The certificate is a valid proxy certificate. +In LibreSSL this flag is never set. +.It Dv EXFLAG_SI +The certificate is self issued (that is subject and issuer names match). +.It Dv EXFLAG_SS +The subject and issuer names match and extension values imply it is self +signed. +.It Dv EXFLAG_FRESHEST +The freshest CRL extension is present in the certificate. +.It Dv EXFLAG_CRITICAL +The certificate contains an unhandled critical extension. +.It Dv 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. +.\" EXFLAG_NO_FINGERPRINT is not available in LibreSSL. Do we need +.\" https://github.com/openssl/openssl/issues/13698 and the fix it fixes? +.\".It Dv EXFLAG_NO_FINGERPRINT +.\" Failed to compute the internal SHA-1 hash value of the certificate. +.\" This may be due to malloc failure or because no SHA-1 implementation was +.\" found. +.It Dv EXFLAG_INVALID_POLICY +The +.Dv 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. +.It Dv EXFLAG_KUSAGE +The certificate contains a key usage extension. +The value can be retrieved using +.Fn X509_get_key_usage . +.It Dv EXFLAG_XKUSAGE +The certificate contains an extended key usage extension. +The value can be retrieved using +.Fn X509_get_extended_key_usage . +.El +.Pp +.Fn X509_get_key_usage +returns the value of the key usage extension. +If key usage is present, it returns zero or more of these flags: +.Dv KU_DIGITAL_SIGNATURE , +.Dv KU_NON_REPUDIATION , +.Dv KU_KEY_ENCIPHERMENT , +.Dv KU_DATA_ENCIPHERMENT , +.Dv KU_KEY_AGREEMENT , +.Dv KU_KEY_CERT_SIGN , +.Dv KU_CRL_SIGN , +.Dv KU_ENCIPHER_ONLY , +or +.Dv KU_DECIPHER_ONLY , +corresponding to individual key usage bits. +If key usage is absent, +.Dv UINT32_MAX +is returned. +.Pp +The following aliases for these flags are defined in +.In openssl/x509.h : +.Dv X509v3_KU_DIGITAL_SIGNATURE , +.Dv X509v3_KU_NON_REPUDIATION , +.Dv X509v3_KU_KEY_ENCIPHERMENT , +.Dv X509v3_KU_DATA_ENCIPHERMENT , +.Dv X509v3_KU_KEY_AGREEMENT , +.Dv X509v3_KU_KEY_CERT_SIGN , +.Dv X509v3_KU_CRL_SIGN , +.Dv X509v3_KU_ENCIPHER_ONLY , +and +.Dv X509v3_KU_DECIPHER_ONLY . +.\" X509v3_KU_UNDEF is intentionally undocumented because nothing uses it. +.Pp +.Fn X509_get_extended_key_usage +returns the value of the extended key usage extension. +If extended key usage is present, it returns zero or more of these +flags: +.Dv XKU_SSL_SERVER , +.Dv XKU_SSL_CLIENT , +.Dv XKU_SMIME , +.Dv XKU_CODE_SIGN +.Dv XKU_OCSP_SIGN , +.Dv XKU_TIMESTAMP , +.Dv XKU_DVCS , +or +.Dv XKU_ANYEKU . +These correspond to the OIDs +.Qq id-kp-serverAuth , +.Qq id-kp-clientAuth , +.Qq id-kp-emailProtection , +.Qq id-kp-codeSigning , +.Qq id-kp-OCSPSigning , +.Qq id-kp-timeStamping , +.Qq id-kp-dvcs , +and +.Qq anyExtendedKeyUsage , +respectively. +Additionally, +.Dv XKU_SGC +is set if either Netscape or Microsoft SGC OIDs are present. +.Pp +The value of the flags correspond to extension values which are cached +in the +.Vt X509 +structure. +If the flags returned do not provide sufficient information, +an application should examine extension values directly, +for example using +.Xr X509_get_ext_d2i 3 . +.Pp +If the key usage or extended key usage extension is absent then +typically usage is unrestricted. +For this reason +.Fn X509_get_key_usage +and +.Fn X509_get_extended_key_usage +return +.Dv UINT32_MAX +when the corresponding extension is absent. +Applications can additionally check the return value of +.Fn X509_get_extension_flags +and take appropriate action if an extension is absent. +.Sh RETURN VALUES +.Fn X509_get_extension_flags , +.Fn X509_get_key_usage +and +.Fn X509_get_extended_key_usage +return sets of flags corresponding to the certificate extension values. +.Sh SEE ALSO +.Xr BASIC_CONSTRAINTS_new 3 , +.Xr EXTENDED_KEY_USAGE_new 3 , +.Xr POLICYINFO_new 3 , +.Xr X509_check_ca 3 , +.Xr X509_check_purpose 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_get_ext_d2i 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_get_version 3 , +.Xr X509_new 3 +.Sh HISTORY +.Nm X509_get_extension_flags , +.Nm X509_get_key_usage , +and +.Nm X509_get_extended_key_usage +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/X509_get_pubkey.3 b/static/openbsd/man3/X509_get_pubkey.3 new file mode 100644 index 00000000..9af6f49a --- /dev/null +++ b/static/openbsd/man3/X509_get_pubkey.3 @@ -0,0 +1,297 @@ +.\" $OpenBSD: X509_get_pubkey.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2020, 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_GET_PUBKEY 3 +.Os +.Sh NAME +.Nm X509_get_pubkey , +.Nm X509_get0_pubkey , +.Nm X509_set_pubkey , +.Nm X509_get_X509_PUBKEY , +.Nm X509_get0_pubkey_bitstr , +.Nm X509_REQ_get_pubkey , +.Nm X509_REQ_get0_pubkey , +.Nm X509_REQ_set_pubkey , +.Nm X509_extract_key , +.Nm X509_REQ_extract_key +.Nd get or set certificate or certificate request public key +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft EVP_PKEY * +.Fo X509_get_pubkey +.Fa "X509 *x" +.Fc +.Ft EVP_PKEY * +.Fo X509_get0_pubkey +.Fa "const X509 *x" +.Fc +.Ft int +.Fo X509_set_pubkey +.Fa "X509 *x" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft X509_PUBKEY * +.Fo X509_get_X509_PUBKEY +.Fa "const X509 *x" +.Fc +.Ft ASN1_BIT_STRING * +.Fo X509_get0_pubkey_bitstr +.Fa "const X509 *x" +.Fc +.Ft EVP_PKEY * +.Fo X509_REQ_get_pubkey +.Fa "X509_REQ *req" +.Fc +.Ft EVP_PKEY * +.Fo X509_REQ_get0_pubkey +.Fa "X509_REQ *req" +.Fc +.Ft int +.Fo X509_REQ_set_pubkey +.Fa "X509_REQ *x" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft EVP_PKEY * +.Fo X509_extract_key +.Fa "X509 *x" +.Fc +.Ft EVP_PKEY * +.Fo X509_REQ_extract_key +.Fa "X509_REQ *req" +.Fc +.Sh DESCRIPTION +.Fn X509_get_pubkey +attempts to decode the public key for certificate +.Fa x . +If successful, it returns the public key as an +.Vt EVP_PKEY +pointer with its reference count incremented: this means the returned +key must be freed up after use. +.Fn X509_get0_pubkey +is similar except that it does not increment the reference count +of the returned +.Vt EVP_PKEY , +so it must not be freed up after use. +.Pp +.Fn X509_get_X509_PUBKEY +returns an internal pointer to the +.Vt SubjectPublicKeyInfo +structure contained in +.Fa x . +The returned value must not be freed up after use. +.Pp +.Fn X509_get0_pubkey_bitstr +returns an internal pointer to just the public key contained in this +.Vt SubjectPublicKeyInfo +structure, without the information about the algorithm used. +.Pp +.Fn X509_set_pubkey +attempts to set the public key for certificate +.Fa x +to +.Fa pkey . +The key +.Fa pkey +should be freed up after use. +.Pp +.Fn X509_REQ_get_pubkey , +.Fn X509_REQ_get0_pubkey , +and +.Fn X509_REQ_set_pubkey +are similar but operate on certificate request +.Fa req . +.Pp +The first time a public key is decoded, the +.Vt EVP_PKEY +structure is cached in the certificate or certificate request itself. +Subsequent calls return the cached structure with its reference count +incremented to improve performance. +.Pp +.Fn X509_extract_key +and +.Fn X509_REQ_extract_key +are deprecated aliases for +.Fn X509_get_pubkey +and +.Fn X509_REQ_get_pubkey , +respectively, implemented as macros. +.Sh RETURN VALUES +.Fn X509_get_pubkey , +.Fn X509_get0_pubkey , +.Fn X509_get_X509_PUBKEY , +.Fn X509_get0_pubkey_bitstr , +.Fn X509_REQ_get_pubkey , +.Fn X509_REQ_get0_pubkey , +.Fn X509_extract_key , +and +.Fn X509_REQ_extract_key +return a public key or +.Dv NULL +if an error occurred. +.Pp +.Fn X509_set_pubkey +and +.Fn X509_REQ_set_pubkey +return 1 for success or 0 for failure. +.Pp +In some cases of failure of +.Fn X509_get0_pubkey , +.Fn X509_set_pubkey , +.Fn X509_REQ_get_pubkey , +.Fn X509_REQ_get0_pubkey , +and +.Fn X509_REQ_set_pubkey , +the reason can be determined with +.Xr ERR_get_error 3 . +.Sh ERRORS +.Fn X509_get_pubkey , +.Fn X509_get0_pubkey , +.Fn X509_REQ_get_pubkey , +.Fn X509_extract_key , +and +.Fn X509_REQ_extract_key +provide diagnostics as documented for +.Xr X509_PUBKEY_get 3 . +If +.Fa x +or +.Fa req +is +.Dv NULL +or contains no certificate information, +they fail without pushing an error onto the stack. +.Pp +.Fn X509_get_X509_PUBKEY +provides no diagnostics and crashes by accessing a +.Dv NULL +pointer if +.Fa x +is +.Dv NULL +or contains no certificate information, +.Pp +.Fn X509_get0_pubkey_bitstr +provides no diagnostics +and fails without pushing an error onto the stack if +.Fa x +is +.Dv NULL , +but it crashes by accessing a +.Dv NULL +pointer if +.Fa x +contains no certificate information. +.Sh SEE ALSO +.Xr d2i_X509 3 , +.Xr X509_CRL_get0_by_serial 3 , +.Xr X509_NAME_add_entry_by_txt 3 , +.Xr X509_NAME_ENTRY_get_object 3 , +.Xr X509_NAME_get_index_by_NID 3 , +.Xr X509_NAME_print_ex 3 , +.Xr X509_new 3 , +.Xr X509_PUBKEY_new 3 , +.Xr X509_REQ_new 3 , +.Xr X509_sign 3 , +.Xr X509_verify_cert 3 , +.Xr X509V3_get_d2i 3 +.Sh STANDARDS +RFC 5280, Internet X.509 Public Key Infrastructure Certificate +and Certificate Revocation List (CRL) Profile, +section 4.1 Basic Certificate Fields +.Pp +RFC 2986: PKCS #10: Certification Request Syntax Specification, +section 4.1 CertificationRequestInfo +.Sh HISTORY +.Fn X509_extract_key +and +.Fn X509_REQ_extract_key +first appeared in SSLeay 0.5.1 but returned a pointer to an +.Vt RSA +object before SSLeay 0.6.0. +.Fn X509_get_pubkey , +.Fn X509_set_pubkey , +.Fn X509_REQ_get_pubkey , +and +.Fn X509_REQ_set_pubkey +first appeared in SSLeay 0.6.5. +.Fn X509_get_X509_PUBKEY +first appeared in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_get0_pubkey_bitstr +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.4 . +.Pp +.Fn X509_get0_pubkey +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . +.Fn X509_REQ_get0_pubkey +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/X509_get_pubkey_parameters.3 b/static/openbsd/man3/X509_get_pubkey_parameters.3 new file mode 100644 index 00000000..b2611210 --- /dev/null +++ b/static/openbsd/man3/X509_get_pubkey_parameters.3 @@ -0,0 +1,100 @@ +.\" $OpenBSD: X509_get_pubkey_parameters.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_GET_PUBKEY_PARAMETERS 3 +.Os +.Sh NAME +.Nm X509_get_pubkey_parameters +.Nd copy public key parameters from a chain +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_get_pubkey_parameters +.Fa "EVP_PKEY *pkey" +.Fa "STACK_OF(X509) *chain" +.Fc +.Sh DESCRIPTION +.Fn X509_get_pubkey_parameters +copies public key parameters from the first appropriate certificate in the +.Fa chain . +.Pp +If +.Fa pkey +is not +.Dv NULL +and already contains complete public key parameters or uses an +algorithm that does not use any parameters, no action occurs and +the function indicates success without inspecting the existing +parameters, without inspecting the +.Fa chain , +and without comparing any parameters. +.Pp +Otherwise, all public key parameters are copied +from the first certificate in the +.Fa chain +that contains complete public key parameters +to each certificate preceding it in the +.Fa chain . +Unless +.Fa pkey +is a +.Dv NULL +pointer, the same parameters are also copied to +.Fa pkey . +.Sh RETURN VALUES +.Fn X509_get_pubkey_parameters +returns 1 for success or 0 for failure. +.Sh ERRORS +The following diagnostics can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv X509_R_UNABLE_TO_GET_CERTS_PUBLIC_KEY Qq unable to get certs public key +Retrieving the public key from a certificate in the +.Fa chain +failed before a certificate containing complete public key parameters +could be found. +.It Xo +.Dv X509_R_UNABLE_TO_FIND_PARAMETERS_IN_CHAIN +.Qq unable to find parameters in chain +.Xc +None of the certificates in the chain +contain complete public key parameters. +.El +.Sh SEE ALSO +.Xr EVP_PKEY_copy_parameters 3 , +.Xr EVP_PKEY_new 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_new 3 +.Sh HISTORY +.Fn X509_get_pubkey_parameters +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . +.Sh CAVEATS +If +.Fn X509_get_pubkey_parameters +fails and returns 0, a part of the parameters may or may not have +been copied before the failure was detected, whereas other parts of +.Fa pkey +and +.Fa chain +may remain unchanged. +So in case of failure, the state of the arguments may change +and possibly become inconsistent. diff --git a/static/openbsd/man3/X509_get_serialNumber.3 b/static/openbsd/man3/X509_get_serialNumber.3 new file mode 100644 index 00000000..56f108f3 --- /dev/null +++ b/static/openbsd/man3/X509_get_serialNumber.3 @@ -0,0 +1,130 @@ +.\" $OpenBSD: X509_get_serialNumber.3,v 1.6 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_GET_SERIALNUMBER 3 +.Os +.Sh NAME +.Nm X509_get_serialNumber , +.Nm X509_get0_serialNumber , +.Nm X509_set_serialNumber +.Nd get or set certificate serial number +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft ASN1_INTEGER * +.Fo X509_get_serialNumber +.Fa "X509 *x" +.Fc +.Ft const ASN1_INTEGER * +.Fo X509_get0_serialNumber +.Fa "const X509 *x" +.Fc +.Ft int +.Fo X509_set_serialNumber +.Fa "X509 *x" +.Fa "ASN1_INTEGER *serial" +.Fc +.Sh DESCRIPTION +.Fn X509_get_serialNumber +returns the serial number of certificate +.Fa x +as an +.Vt ASN1_INTEGER +structure which can be examined or initialised. +The value returned is an internal pointer which must not be freed +up after the call. +.Pp +.Fn X509_get0_serialNumber +does the same except that it accepts a constant argument +and returns a constant result. +.Pp +.Fn X509_set_serialNumber +sets the serial number of certificate +.Fa x +to +.Fa serial . +A copy of the serial number is used internally so +.Fa serial +should be freed up after use. +.Sh RETURN VALUES +.Fn X509_get_serialNumber +and +.Fn X509_get0_serialNumber +return a pointer to an +.Vt ASN1_INTEGER +structure. +.Pp +.Fn X509_set_serialNumber +returns 1 for success or 0 for failure. +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr d2i_X509 3 , +.Xr X509_CRL_get0_by_serial 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_NAME_add_entry_by_txt 3 , +.Xr X509_NAME_ENTRY_get_object 3 , +.Xr X509_NAME_get_index_by_NID 3 , +.Xr X509_NAME_print_ex 3 , +.Xr X509_new 3 , +.Xr X509_sign 3 , +.Xr X509_verify_cert 3 , +.Xr X509V3_get_d2i 3 +.Sh HISTORY +.Fn X509_get_serialNumber +and +.Fn X509_set_serialNumber +first appeared in SSLeay 0.6.5 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_get0_serialNumber +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.4 . diff --git a/static/openbsd/man3/X509_get_subject_name.3 b/static/openbsd/man3/X509_get_subject_name.3 new file mode 100644 index 00000000..8dc19080 --- /dev/null +++ b/static/openbsd/man3/X509_get_subject_name.3 @@ -0,0 +1,190 @@ +.\" $OpenBSD: X509_get_subject_name.3,v 1.11 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_GET_SUBJECT_NAME 3 +.Os +.Sh NAME +.Nm X509_get_subject_name , +.Nm X509_set_subject_name , +.Nm X509_get_issuer_name , +.Nm X509_set_issuer_name , +.Nm X509_REQ_get_subject_name , +.Nm X509_REQ_set_subject_name , +.Nm X509_CRL_get_issuer , +.Nm X509_CRL_set_issuer_name +.Nd get and set issuer or subject names +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_NAME * +.Fo X509_get_subject_name +.Fa "const X509 *x" +.Fc +.Ft int +.Fo X509_set_subject_name +.Fa "X509 *x" +.Fa "X509_NAME *name" +.Fc +.Ft X509_NAME * +.Fo X509_get_issuer_name +.Fa "const X509 *x" +.Fc +.Ft int +.Fo X509_set_issuer_name +.Fa "X509 *x" +.Fa "X509_NAME *name" +.Fc +.Ft X509_NAME * +.Fo X509_REQ_get_subject_name +.Fa "const X509_REQ *req" +.Fc +.Ft int +.Fo X509_REQ_set_subject_name +.Fa "X509_REQ *req" +.Fa "X509_NAME *name" +.Fc +.Ft X509_NAME * +.Fo X509_CRL_get_issuer +.Fa "const X509_CRL *crl" +.Fc +.Ft int +.Fo X509_CRL_set_issuer_name +.Fa "X509_CRL *x" +.Fa "X509_NAME *name" +.Fc +.Sh DESCRIPTION +.Fn X509_get_subject_name +returns the subject name of certificate +.Fa x . +The returned value is an internal pointer which must not be freed. +.Pp +.Fn X509_set_subject_name +sets the issuer name of certificate +.Fa x +to +.Fa name . +The +.Fa name +parameter is copied internally and should be freed up when it is no +longer needed. +.Pp +.Fn X509_get_issuer_name +and +.Fn X509_set_issuer_name +are identical to +.Fn X509_get_subject_name +and +.Fn X509_set_subject_name +except that they get and set the issuer name of +.Fa x . +.Pp +Similarly +.Fn X509_REQ_get_subject_name , +.Fn X509_REQ_set_subject_name , +.Fn X509_CRL_get_issuer , +and +.Fn X509_CRL_set_issuer_name +get or set the subject or issuer names of certificate requests +of CRLs, respectively. +.Sh RETURN VALUES +.Fn X509_get_subject_name , +.Fn X509_get_issuer_name , +.Fn X509_REQ_get_subject_name , +and +.Fn X509_CRL_get_issuer +return a pointer to an +.Vt X509_NAME +object. +.Pp +.Fn X509_set_subject_name , +.Fn X509_set_issuer_name , +.Fn X509_REQ_set_subject_name , +and +.Fn X509_CRL_set_issuer_name +return 1 for success or 0 for failure. +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr d2i_X509_NAME 3 , +.Xr X509_CRL_get0_by_serial 3 , +.Xr X509_CRL_new 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_NAME_add_entry_by_txt 3 , +.Xr X509_NAME_ENTRY_get_object 3 , +.Xr X509_NAME_get_index_by_NID 3 , +.Xr X509_NAME_new 3 , +.Xr X509_NAME_print_ex 3 , +.Xr X509_new 3 , +.Xr X509_REQ_new 3 , +.Xr X509_sign 3 , +.Xr X509_verify_cert 3 , +.Xr X509V3_get_d2i 3 +.Sh HISTORY +.Fn X509_get_subject_name +and +.Fn X509_get_issuer_name +appeared in SSLeay 0.4 or earlier. +.Fn X509_set_subject_name , +.Fn X509_set_issuer_name , +.Fn X509_REQ_get_subject_name , +and +.Fn X509_REQ_set_subject_name +first appeared in SSLeay 0.6.5. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_CRL_get_issuer +first appeared in OpenSSL 0.9.2b and has been available since +.Ox 2.6 . +.Pp +.Fn X509_CRL_set_issuer_name +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/X509_get_version.3 b/static/openbsd/man3/X509_get_version.3 new file mode 100644 index 00000000..d539053d --- /dev/null +++ b/static/openbsd/man3/X509_get_version.3 @@ -0,0 +1,163 @@ +.\" $OpenBSD: X509_get_version.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_GET_VERSION 3 +.Os +.Sh NAME +.Nm X509_get_version , +.Nm X509_set_version , +.Nm X509_REQ_get_version , +.Nm X509_REQ_set_version , +.Nm X509_CRL_get_version , +.Nm X509_CRL_set_version +.Nd get or set certificate, certificate request, or CRL version +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft long +.Fo X509_get_version +.Fa "const X509 *x" +.Fc +.Ft int +.Fo X509_set_version +.Fa "X509 *x" +.Fa "long version" +.Fc +.Ft long +.Fo X509_REQ_get_version +.Fa "const X509_REQ *req" +.Fc +.Ft int +.Fo X509_REQ_set_version +.Fa "X509_REQ *x" +.Fa "long version" +.Fc +.Ft long +.Fo X509_CRL_get_version +.Fa "const X509_CRL *crl" +.Fc +.Ft int +.Fo X509_CRL_set_version +.Fa "X509_CRL *x" +.Fa "long version" +.Fc +.Sh DESCRIPTION +.Fn X509_get_version +returns the numerical value of the version field of certificate +.Fa x . +Note: this is defined by standards (X.509 et al.) to be one less +than the certificate version. +So a version 3 certificate will return 2 and a version 1 certificate +will return 0. +.Pp +.Fn X509_set_version +sets the numerical value of the version field of certificate +.Fa x +to +.Fa version . +.Pp +Similarly +.Fn X509_REQ_get_version , +.Fn X509_REQ_set_version , +.Fn X509_CRL_get_version , +and +.Fn X509_CRL_set_version +get and set the version number of certificate requests and CRLs. +.Pp +The version field of certificates, certificate requests, and CRLs +has a DEFAULT value of v1(0) meaning the field should be omitted +for version 1. +This is handled transparently by these functions. +.Sh RETURN VALUES +.Fn X509_get_version , +.Fn X509_REQ_get_version , +and +.Fn X509_CRL_get_version +return the numerical value of the version field. +.Pp +.Fn X509_set_version , +.Fn X509_REQ_set_version , +and +.Fn X509_CRL_set_version +return 1 for success or 0 for failure. +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr d2i_X509 3 , +.Xr X509_CRL_get0_by_serial 3 , +.Xr X509_CRL_new 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_NAME_add_entry_by_txt 3 , +.Xr X509_NAME_ENTRY_get_object 3 , +.Xr X509_NAME_get_index_by_NID 3 , +.Xr X509_NAME_print_ex 3 , +.Xr X509_new 3 , +.Xr X509_REQ_new 3 , +.Xr X509_sign 3 , +.Xr X509_verify_cert 3 , +.Xr X509V3_get_d2i 3 +.Sh HISTORY +.Fn X509_get_version , +.Fn X509_set_version , +.Fn X509_REQ_get_version , +and +.Fn X509_REQ_set_version +first appeared in SSLeay 0.6.5 and have been available since +.Ox 2.4 . +.Pp +.Fn X509_CRL_get_version +first appeared in OpenSSL 0.9.2b and has been available since +.Ox 2.6 . +.Pp +.Fn X509_CRL_set_version +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/X509_keyid_set1.3 b/static/openbsd/man3/X509_keyid_set1.3 new file mode 100644 index 00000000..e1668f97 --- /dev/null +++ b/static/openbsd/man3/X509_keyid_set1.3 @@ -0,0 +1,172 @@ +.\" $OpenBSD: X509_keyid_set1.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_KEYID_SET1 3 +.Os +.Sh NAME +.Nm X509_keyid_set1 , +.Nm X509_keyid_get0 , +.Nm X509_alias_set1 , +.Nm X509_alias_get0 +.Nd auxiliary certificate data for PKCS#12 +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_keyid_set1 +.Fa "X509 *x" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft unsigned char * +.Fo X509_keyid_get0 +.Fa "X509 *x" +.Fa "int *plen" +.Fc +.Ft int +.Fo X509_alias_set1 +.Fa "X509 *x" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft unsigned char * +.Fo X509_alias_get0 +.Fa "X509 *x" +.Fa "int *plen" +.Fc +.Sh DESCRIPTION +These functions store non-standard auxiliary data in +.Fa x +and retrieve it. +.Pp +The +.Fa len +bytes of +.Fa data +stored using +.Fn X509_keyid_set1 +will be written to the +.Sy localKeyID +attribute of the PKCS#12 structure if +.Xr PKCS12_create 3 +is later called on +.Fa x , +and the +.Fa data +stored using +.Fn X509_alias_set1 +will be written to the +.Sy friendlyName +attribute. +If +.Fa data +points to a NUL-terminated string, \-1 can be passed as the +.Fa len +argument to let +.Fa len +be calculated internally using +.Xr strlen 3 . +If a +.Dv NULL +pointer is passed as the +.Fa data +argument, the respective auxiliary data stored in +.Fa x , +if any, is removed from +.Fa x +and freed. +.Pp +Conversely, +.Xr PKCS12_parse 3 +retrieves these attributes from a PKCS#12 structure such that they can +subsequently be accessed with +.Fn X509_keyid_get0 +and +.Fn X509_alias_get0 . +Unless +.Dv NULL +is passed for the +.Fa plen +argument, these functions store the size of the returned buffer in bytes in +.Pf * Fa plen . +After the call, the returned buffer is not necessarily NUL-terminated, +but it may contain internal NUL bytes. +.Pp +API design is very incomplete; given the complexity of PKCS#12, +that's probably an asset rather than a defect. +The PKCS#12 standard defines many attributes that cannot be stored in +.Vt X509 +objects. +.Pp +To associate certificates with alternative names and key identifiers, +X.509 certificate extensions are more commonly used than PKCS#12 +attributes, for example using +.Xr X509_EXTENSION_create_by_NID 3 +with +.Dv NID_subject_alt_name +or +.Dv NID_subject_key_identifier . +.Sh RETURN VALUES +.Fn X509_keyid_set1 +and +.Fn X509_alias_set1 +return 1 if +.Fa data +is +.Dv NULL +or if the input +.Fa data +was successfully copied into +.Fa x , +or 0 if +.Fa data +is not +.Dv NULL +but could not be copied because +.Fa x +is +.Dv NULL +or memory allocation failed. +.Pp +.Fn X509_keyid_get0 +and +.Fn X509_alias_get0 +return an internal pointer to an array of bytes or +.Dv NULL +if +.Fa x +does not contain auxiliary data of the requested kind. +.Sh SEE ALSO +.Xr ASN1_STRING_set 3 , +.Xr X509_CERT_AUX_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_new 3 , +.Xr X509V3_get_d2i 3 +.Sh HISTORY +.Fn X509_alias_set1 +and +.Fn X509_alias_get0 +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn X509_keyid_set1 +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Pp +.Fn X509_keyid_get0 +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/X509_load_cert_file.3 b/static/openbsd/man3/X509_load_cert_file.3 new file mode 100644 index 00000000..04a666da --- /dev/null +++ b/static/openbsd/man3/X509_load_cert_file.3 @@ -0,0 +1,134 @@ +.\" $OpenBSD: X509_load_cert_file.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_LOAD_CERT_FILE 3 +.Os +.Sh NAME +.Nm X509_load_cert_file , +.Nm X509_load_crl_file , +.Nm X509_load_cert_crl_file +.Nd read, decode, and cache certificates and CRLs +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509_vfy.h +.Ft int +.Fo X509_load_cert_file +.Fa "X509_LOOKUP *ctx" +.Fa "const char *file" +.Fa "int type" +.Fc +.Ft int +.Fo X509_load_crl_file +.Fa "X509_LOOKUP *ctx" +.Fa "const char *file" +.Fa "int type" +.Fc +.Ft int +.Fo X509_load_cert_crl_file +.Fa "X509_LOOKUP *ctx" +.Fa "const char *file" +.Fa "int type" +.Fc +.Sh DESCRIPTION +.Fn X509_load_cert_file +with a +.Fa type +of +.Dv X509_FILETYPE_PEM +reads one or more certificates in PEM format from the given +.Fa file +using +.Xr PEM_read_bio_X509_AUX 3 ; +with a type of +.Dv X509_FILETYPE_ASN1 , +if reads one certificate in DER format using +.Xr d2i_X509_bio 3 . +The certificates read are added to the +.Vt X509_STORE +memory cache object associated with the given +.Fa ctx +using +.Xr X509_STORE_add_cert 3 . +.Pp +.Fn X509_load_crl_file +with a +.Fa type +of +.Dv X509_FILETYPE_PEM +reads one or more certificate revocation lists in PEM format from the given +.Fa file +using +.Xr PEM_read_bio_X509_CRL 3 ; +with a type of +.Dv X509_FILETYPE_ASN1 , +if reads one certificate revocation lists in DER format using +.Xr d2i_X509_CRL_bio 3 . +The certificate revocation lists read are added to the +.Vt X509_STORE +memory cache object associated with the given +.Fa ctx +using +.Xr X509_STORE_add_crl 3 . +.Pp +.Fn X509_load_cert_crl_file +with a +.Fa type +of +.Dv X509_FILETYPE_PEM +read one or more certificates and/or certificate revocation lists +in PEM format from the given +.Fa file +using +.Xr PEM_X509_INFO_read_bio 3 +and adds them to the +.Vt X509_STORE +memory cache object associated with the given +.Fa ctx +using +.Xr X509_STORE_add_cert 3 +and +.Xr X509_STORE_add_crl 3 , +respectively. +.Pp +.Fn X509_load_cert_crl_file +with a +.Fa type +of +.Dv X509_FILETYPE_ASN1 +is equivalent to +.Fn X509_load_cert_file +and cannot be used to read a certificate revocation list. +.Sh RETURN VALUES +These functions return the number of objects loaded or 0 on error. +.Sh SEE ALSO +.Xr d2i_X509_bio 3 , +.Xr PEM_read_PrivateKey 3 , +.Xr X509_LOOKUP_new 3 , +.Xr X509_OBJECT_get0_X509 3 , +.Xr X509_STORE_load_locations 3 , +.Xr X509_STORE_new 3 +.Sh HISTORY +.Fn X509_load_cert_file +first appeared in SSLeay 0.8.0 and +.Fn X509_load_crl_file +in SSLeay 0.9.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_load_cert_crl_file +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/X509_new.3 b/static/openbsd/man3/X509_new.3 new file mode 100644 index 00000000..b6140b24 --- /dev/null +++ b/static/openbsd/man3/X509_new.3 @@ -0,0 +1,279 @@ +.\" $OpenBSD: X509_new.3,v 1.47 2025/07/16 17:59:10 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016, 2018, 2019, 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2006, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: July 16 2025 $ +.Dt X509_NEW 3 +.Os +.Sh NAME +.Nm X509_new , +.Nm X509_dup , +.Nm X509_REQ_to_X509 , +.Nm X509_free , +.Nm X509_up_ref , +.Nm X509_chain_up_ref +.Nd X.509 certificate object +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509 * +.Fn X509_new void +.Ft X509 * +.Fo X509_dup +.Fa "X509 *a" +.Fc +.Ft X509 * +.Fo X509_REQ_to_X509 +.Fa "X509_REQ *req" +.Fa "int days" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft void +.Fo X509_free +.Fa "X509 *a" +.Fc +.Ft int +.Fo X509_up_ref +.Fa "X509 *a" +.Fc +.Ft STACK_OF(X509) * +.Fo X509_chain_up_ref +.Fa "STACK_OF(X509) *chain" +.Fc +.Sh DESCRIPTION +.Fn X509_new +allocates and initializes an empty +.Vt X509 +object with reference count 1. +It represents an ASN.1 +.Vt Certificate +structure defined in RFC 5280 section 4.1. +It can hold a public key together with information about the person, +organization, device, or function the associated private key belongs to. +.Pp +.Fn X509_dup +creates a deep copy of +.Fa a +using +.Xr ASN1_item_dup 3 , +setting the reference count of the copy to 1. +.Pp +.Fn X509_REQ_to_X509 +allocates a new certificate object, copies the public key from +.Fa req +into it, copies the subject name of +.Fa req +to both the subject and issuer names of the new certificate, sets the +.Fa notBefore +field to the current time and the +.Fa notAfter +field to the given number of +.Fa days +in the future, and signs the new certificate with +.Xr X509_sign 3 +using +.Fa pkey +and the MD5 algorithm. +If +.Fa req +contains at least one attribute, +the version of the new certificate is set to 2. +.Pp +.Fn X509_free +decrements the reference count of the +.Vt X509 +structure +.Fa a +and frees it up if the reference count reaches 0. +If +.Fa a +is a +.Dv NULL +pointer, no action occurs. +.Pp +.Fn X509_up_ref +increments the reference count of +.Fa a +by 1. +This function is 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 +.Fn X509_chain_up_ref +performs a shallow copy of the given +.Fa chain +using +.Fn sk_X509_dup +and increments the reference count of each contained certificate +by 1. +Its purpose is similar to +.Fn X509_up_ref : +The returned chain persists after the original is freed. +.Sh RETURN VALUES +.Fn X509_new , +.Fn X509_dup , +and +.Fn X509_REQ_to_X509 +return a pointer to the newly allocated object or +.Dv NULL +if an error occurs; an error code can be obtained by +.Xr ERR_get_error 3 . +.Pp +.Fn X509_up_ref +returns 1 for success or 0 for failure. +.Pp +.Fn X509_chain_up_ref +returns the copy of the +.Fa chain +or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr ASIdentifiers_new 3 , +.Xr ASRange_new 3 , +.Xr AUTHORITY_KEYID_new 3 , +.Xr BASIC_CONSTRAINTS_new 3 , +.Xr crypto 3 , +.Xr d2i_X509 3 , +.Xr IPAddressRange_new 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 , +.Xr X509_ALGOR_new 3 , +.Xr X509_ATTRIBUTE_new 3 , +.Xr X509_check_ca 3 , +.Xr X509_check_host 3 , +.Xr X509_check_issued 3 , +.Xr X509_check_private_key 3 , +.Xr X509_check_purpose 3 , +.Xr X509_CINF_new 3 , +.Xr X509_cmp 3 , +.Xr X509_CRL_new 3 , +.Xr X509_digest 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_find_by_subject 3 , +.Xr X509_get0_notBefore 3 , +.Xr X509_get0_signature 3 , +.Xr X509_get1_email 3 , +.Xr X509_get_ex_new_index 3 , +.Xr X509_get_extension_flags 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_get_pubkey_parameters 3 , +.Xr X509_get_serialNumber 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_get_version 3 , +.Xr X509_INFO_new 3 , +.Xr X509_load_cert_file 3 , +.Xr X509_LOOKUP_hash_dir 3 , +.Xr X509_LOOKUP_new 3 , +.Xr X509_NAME_new 3 , +.Xr X509_OBJECT_new 3 , +.Xr X509_print_ex 3 , +.Xr X509_PUBKEY_new 3 , +.Xr X509_PURPOSE_set 3 , +.Xr X509_REQ_new 3 , +.Xr X509_SIG_new 3 , +.Xr X509_sign 3 , +.Xr X509_STORE_CTX_new 3 , +.Xr X509_STORE_get_by_subject 3 , +.Xr X509_STORE_new 3 , +.Xr X509v3_addr_add_inherit 3 , +.Xr X509v3_addr_get_range 3 , +.Xr X509v3_addr_inherits 3 , +.Xr X509v3_addr_subset 3 , +.Xr X509v3_addr_validate_path 3 , +.Xr X509v3_asid_add_id_or_range 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn X509_new +and +.Fn X509_free +appeared in SSLeay 0.4 or earlier, +.Fn X509_dup +in SSLeay 0.4.4, and +.Fn X509_REQ_to_X509 +in SSLeay 0.6.0 . +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_up_ref +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.1 . +.Pp +.Fn X509_chain_up_ref +first appeared in OpenSSL 1.0.2 and has been available since +.Ox 6.3 . +.Sh BUGS +The X.509 public key infrastructure and its data types contain too +many design bugs to list them. +For lots of examples, see the classic +.Lk https://www.cs.auckland.ac.nz/~pgut001/pubs/x509guide.txt\ + "X.509 Style Guide" +that +.An Peter Gutmann +published in 2000. diff --git a/static/openbsd/man3/X509_ocspid_print.3 b/static/openbsd/man3/X509_ocspid_print.3 new file mode 100644 index 00000000..7b0493c6 --- /dev/null +++ b/static/openbsd/man3/X509_ocspid_print.3 @@ -0,0 +1,59 @@ +.\" $OpenBSD: X509_ocspid_print.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_OCSPID_PRINT 3 +.Os +.Sh NAME +.Nm X509_ocspid_print +.Nd pretty-print hashes of subject name and public key +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_ocspid_print +.Fa "BIO *bio" +.Fa "X509 *issuer" +.Fc +.Sh DESCRIPTION +.Fn X509_ocspid_print +produces human-readable output to +.Fa bio +containing hexadecimal representations of SHA-1 hashes of the +DER-encoded forms of the subject name and the public key of the +.Fa issuer +certificate, as these hashes appear in OCSP requests. +.Sh RETURN VALUES +.Fn X509_ocspid_print +returns 1 for success or 0 for failure. +.Sh EXAMPLES +This function is used by the +.Fl ocspid +flag of the +.Xr openssl 1 +.Cm x509 +command. +.Sh SEE ALSO +.Xr EVP_sha1 3 , +.Xr i2d_X509_NAME 3 , +.Xr OCSP_cert_to_id 3 , +.Xr OCSP_REQUEST_new 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_get_subject_name 3 +.Sh HISTORY +.Fn X509_ocspid_print +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/X509_print_ex.3 b/static/openbsd/man3/X509_print_ex.3 new file mode 100644 index 00000000..627ef25a --- /dev/null +++ b/static/openbsd/man3/X509_print_ex.3 @@ -0,0 +1,285 @@ +.\" $OpenBSD: X509_print_ex.3,v 1.7 2025/07/01 06:47:56 tb Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: July 1 2025 $ +.Dt X509_PRINT_EX 3 +.Os +.Sh NAME +.Nm X509_print_ex , +.Nm X509_CERT_AUX_print , +.Nm X509_print_ex_fp , +.Nm X509_print , +.Nm X509_print_fp +.Nd pretty-print an X.509 certificate +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_print_ex +.Fa "BIO *bio" +.Fa "X509 *x" +.Fa "unsigned long nameflags" +.Fa "unsigned long skipflags" +.Fc +.Ft int +.Fo X509_CERT_AUX_print +.Fa "BIO *bio" +.Fa "X509_CERT_AUX *aux" +.Fa "int indent" +.Fc +.Ft int +.Fo X509_print_ex_fp +.Fa "FILE *fp" +.Fa "X509 *x" +.Fa "unsigned long nameflags" +.Fa "unsigned long skipflags" +.Fc +.Ft int +.Fo X509_print +.Fa "BIO *bio" +.Fa "X509 *x" +.Fc +.Ft int +.Fo X509_print_fp +.Fa "FILE *fp" +.Fa "X509 *x" +.Fc +.Sh DESCRIPTION +.Fn X509_print_ex +prints information contained in +.Fa x +to +.Fa bio +in human-readable form. +Printing is aborted as soon as any operation fails, with the exception +that failures while attempting to decode or print the public key, +the X.509 version 3 extensions, or non-standard auxiliary data are +not considered as errors. +.Pp +By default, the following blocks of information are printed +in the following order. +Each block can be skipped by setting the corresponding bit in +.Fa skipflags , +provided in parentheses after each block description. +.Bl -bullet +.It +A pair of lines reading +.Qq Certificate:\& +and +.Qq Data:\& +containing no information. +.Pq Dv X509_FLAG_NO_HEADER +.It +The certificate version number as defined by the standard, +followed in parentheses by the value contained in the version field +in hexadecimal notation. +See +.Xr X509_get_version 3 +for details. +.Pq Dv X509_FLAG_NO_VERSION +.It +The serial number of the certificate as returned by +.Xr X509_get_serialNumber 3 . +If it is not \-1 and converting it to +.Vt long +succeeds, it is printed in both decimal and hexadecimal format. +If it is \-1, too wide to fit in +.Vt long , +or conversion fails, it is printed byte-by-byte in hexadecimal notation. +.Pq Dv X509_FLAG_NO_SERIAL +.It +The name of the signature algorithm is printed with +.Xr X509_signature_print 3 . +.Pq Dv X509_FLAG_NO_SIGNAME +.It +The issuer name returned by +.Xr X509_get_issuer_name 3 +is printed with +.Xr X509_NAME_print_ex 3 . +.Pq Dv X509_FLAG_NO_ISSUER +.It +The validity period from +.Xr X509_get_notBefore 3 +to +.Xr X509_get_notAfter 3 +is printed using +.Xr ASN1_TIME_print 3 . +.Pq Dv X509_FLAG_NO_VALIDITY +.It +The subject name returned from +.Xr X509_get_subject_name 3 +is printed with +.Xr X509_NAME_print_ex 3 . +.Pq Dv X509_FLAG_NO_SUBJECT +.It +The public key algorithm is printed with +.Xr i2a_ASN1_OBJECT 3 , +and the public key returned from +.Xr X509_get_pubkey 3 +with +.Xr EVP_PKEY_print_public 3 . +.Pq Dv X509_FLAG_NO_PUBKEY +.It +If an issuer or a subject unique identifier is present, its hex dump +is printed with +.Xr X509_signature_dump 3 . +.Pq Dv X509_FLAG_NO_IDS +.It +All X.509 extensions contained in the certificate are printed with +.Xr X509V3_extensions_print 3 . +.Pq Dv X509_FLAG_NO_EXTENSIONS +.It +The signature is printed with +.Xr X509_signature_print 3 . +.Pq Dv X509_FLAG_NO_SIGDUMP +.It +Non-standard auxiliary data associated with the certificate is printed +using the function +.Fn X509_CERT_AUX_print +documented below. +.Pq Dv X509_FLAG_NO_AUX +.El +.Pp +The +.Fa nameflags +argument modifies the format for printing X.501 +.Vt Name +objects contained in +.Fa x . +It is passed through to +.Xr X509_NAME_print_ex 3 . +If +.Fa nameflags +is +.Dv X509_FLAG_COMPAT , +the +.Fa indent +argument of +.Xr X509_NAME_print_ex 3 +is set to 16 spaces and the traditional SSLeay format is used. +Otherwise, if the only bit set in +.Dv XN_FLAG_SEP_MASK +is +.Dv XN_FLAG_SEP_MULTILINE , +.Fa indent +is set to 12 spaces. +Otherwise, +.Fa indent +is set to zero. +.Pp +.Fn X509_CERT_AUX_print +prints information contained in +.Fa aux +to +.Fa bio +in human-readable form with a left margin of +.Fa indent +spaces. +If +.Fa aux +is +.Dv NULL , +it prints nothing. +.Pp +Information is printed in the following order: +.Bl -bullet +.It +Purposes the certificate is intended to be used for as set with +.Xr X509_add1_trust_object 3 , +each printed with +.Xr OBJ_obj2txt 3 . +.It +Purposes the certificate is explicitly +.Em not +intended to be used for as set with +.Xr X509_add1_reject_object 3 , +again each printed with +.Xr OBJ_obj2txt 3 . +.It +If +.Fa aux +contains data set with +.Xr X509_alias_set1 3 , +the raw bytes are printed in unencoded form. +.It +If +.Fa aux +contains data set with +.Xr X509_keyid_set1 3 , +the bytes are printed in hexadecimal notation with colons in between. +.El +.Pp +.Fn X509_print_ex_fp +is similar to +.Fn X509_print_ex +except that it prints to +.Fa fp . +.Pp +.Fn X509_print +and +.Fn X509_print_fp +are wrapper functions setting the +.Fa nameflags +to +.Dv XN_FLAG_COMPAT +and the +.Fa skipflags +to +.Dv X509_FLAG_COMPAT . +.Sh RETURN VALUES +.Fn X509_print_ex , +.Fn X509_print_ex_fp , +.Fn X509_print , +and +.Fn X509_print_fp +return 1 if all requested information was successfully printed, +even if failures occurred while attempting to decode or print the +public key or X.509 version 3 extensions, or 0 if any other operation +failed. +.Pp +.Fn X509_CERT_AUX_print +always returns 1 and silently ignores write errors. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr X509_CERT_AUX_new 3 , +.Xr X509_CRL_print 3 , +.Xr X509_new 3 , +.Xr X509_REQ_print_ex 3 +.Sh HISTORY +.Fn X509_print +first appeared in SSLeay 0.5.1 and was changed to print to a +.Vt BIO +in SSLeay 0.6.0. +.Fn X509_print_fp +first appeared in SSLeay 0.6.0. +Both functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_CERT_AUX_print +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn X509_print_ex +and +.Fn X509_print_ex_fp +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Sh BUGS +If arbitrary data was stored into +.Fa x +using +.Xr X509_alias_set1 3 , +these functions may print binary data and even NUL bytes. diff --git a/static/openbsd/man3/X509_sign.3 b/static/openbsd/man3/X509_sign.3 new file mode 100644 index 00000000..9e9df1e9 --- /dev/null +++ b/static/openbsd/man3/X509_sign.3 @@ -0,0 +1,210 @@ +.\" $OpenBSD: X509_sign.3,v 1.13 2025/07/11 18:42:51 tb Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: July 11 2025 $ +.Dt X509_SIGN 3 +.Os +.Sh NAME +.Nm X509_sign , +.Nm X509_sign_ctx , +.Nm X509_verify , +.Nm X509_REQ_sign , +.Nm X509_REQ_sign_ctx , +.Nm X509_REQ_verify , +.Nm X509_CRL_sign , +.Nm X509_CRL_sign_ctx , +.Nm X509_CRL_verify +.Nd sign or verify certificate, certificate request, or CRL signature +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_sign +.Fa "X509 *x" +.Fa "EVP_PKEY *pkey" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo X509_sign_ctx +.Fa "X509 *x" +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft int +.Fo X509_verify +.Fa "X509 *x" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo X509_REQ_sign +.Fa "X509_REQ *x" +.Fa "EVP_PKEY *pkey" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo X509_REQ_sign_ctx +.Fa "X509_REQ *x" +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft int +.Fo X509_REQ_verify +.Fa "X509_REQ *x" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo X509_CRL_sign +.Fa "X509_CRL *x" +.Fa "EVP_PKEY *pkey" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo X509_CRL_sign_ctx +.Fa "X509_CRL *x" +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft int +.Fo X509_CRL_verify +.Fa "X509_CRL *x" +.Fa "EVP_PKEY *pkey" +.Fc +.Sh DESCRIPTION +.Fn X509_sign +signs the certificate +.Fa x +using the private key +.Fa pkey +and the message digest +.Fa md +and sets the signature in +.Fa x . +.Fn X509_sign_ctx +also signs the certificate +.Fa x +but uses the parameters contained in digest context +.Fa ctx . +.Pp +.Fn X509_verify +verifies the signature of certificate +.Fa x +using the public key +.Fa pkey . +Only the signature is checked: no other checks (such as certificate +chain validity) are performed. +.Pp +.Fn X509_REQ_sign , +.Fn X509_REQ_sign_ctx , +.Fn X509_REQ_verify , +.Fn X509_CRL_sign , +.Fn X509_CRL_sign_ctx , +and +.Fn X509_CRL_verify +sign and verify certificate requests and CRLs, respectively. +.Pp +.Fn X509_sign_ctx +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. +.Sh RETURN VALUES +.Fn X509_sign , +.Fn X509_sign_ctx , +.Fn X509_REQ_sign , +.Fn X509_REQ_sign_ctx , +.Fn X509_CRL_sign , +and +.Fn X509_CRL_sign_ctx +return the size of the signature in bytes for success or 0 for failure. +.Pp +.Fn X509_verify , +.Fn X509_REQ_verify , +and +.Fn X509_CRL_verify +return 1 if the signature is valid or 0 if the signature check fails. +If the signature could not be checked at all because it was invalid or +some other error occurred, then -1 is returned. +.Pp +In some cases of failure, the reason can be determined with +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr d2i_X509 3 , +.Xr EVP_DigestInit 3 , +.Xr X509_CRL_get0_by_serial 3 , +.Xr X509_CRL_new 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_get_version 3 , +.Xr X509_NAME_add_entry_by_txt 3 , +.Xr X509_NAME_ENTRY_get_object 3 , +.Xr X509_NAME_get_index_by_NID 3 , +.Xr X509_NAME_print_ex 3 , +.Xr X509_new 3 , +.Xr X509_REQ_new 3 , +.Xr X509_verify_cert 3 , +.Xr X509V3_get_d2i 3 +.Sh HISTORY +.Fn X509_verify +appeared in SSLeay 0.4 or earlier. +.Fn X509_sign +and +.Fn X509_REQ_sign +first appeared in SSLeay 0.4.4. +.Fn X509_REQ_verify +and +.Fn X509_CRL_verify +first appeared in SSLeay 0.4.5b. +.Fn X509_CRL_sign +first appeared in SSLeay 0.5.1. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_sign_ctx , +.Fn X509_REQ_sign_ctx , +and +.Fn X509_CRL_sign_ctx +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/X509_signature_dump.3 b/static/openbsd/man3/X509_signature_dump.3 new file mode 100644 index 00000000..c5b9277e --- /dev/null +++ b/static/openbsd/man3/X509_signature_dump.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: X509_signature_dump.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt X509_SIGNATURE_DUMP 3 +.Os +.Sh NAME +.Nm X509_signature_dump , +.Nm X509_signature_print +.Nd pretty-print ASN.1 strings +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_signature_dump +.Fa "BIO *bio" +.Fa "const ASN1_STRING *signature" +.Fa "int indent" +.Fc +.Ft int +.Fo X509_signature_print +.Fa "BIO *bio" +.Fa "const X509_ALGOR *algorithm" +.Fa "const ASN1_STRING *signature" +.Fc +.Sh DESCRIPTION +.Fn X509_signature_dump +writes the data bytes contained in the +.Fa signature +to +.Fa bio +in hexadecimal format with colons between bytes, +18 bytes per output line, each line indented with +.Fa indent +space characters. +.Pp +.Fn X509_signature_print +writes the name of the signature +.Fa algorithm , +or, if no name for it is known, its object identifier (OID) to +.Fa bio +using +.Xr i2a_ASN1_OBJECT 3 . +After that, if a method object for the algorithm can be retrieved with +.Xr EVP_PKEY_asn1_find 3 +and if that object defines a printing method, that printing method is +used to print the +.Fa signature . +Otherwise, unless the +.Fa signature +is +.Dv NULL , +it is printed using +.Fn X509_signature_dump . +.Sh RETURN VALUES +These functions return 1 on success or 0 on failure. +They fail and return as soon as any write operation fails. +.Sh SEE ALSO +.Xr ASN1_STRING_new 3 , +.Xr ASN1_STRING_print_ex 3 , +.Xr BIO_new 3 , +.Xr EVP_PKEY_asn1_find 3 , +.Xr OBJ_find_sigid_algs 3 , +.Xr X509_ALGOR_new 3 , +.Xr X509_get0_signature 3 +.Sh HISTORY +.Fn X509_signature_print +first appeared in OpenSSL 0.9.7 and has been available since +.Ox 3.2 . +.Pp +.Fn X509_signature_dump +first appeared in OpenSSL 1.0.1 and has been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/X509_verify_cert.3 b/static/openbsd/man3/X509_verify_cert.3 new file mode 100644 index 00000000..7897e09f --- /dev/null +++ b/static/openbsd/man3/X509_verify_cert.3 @@ -0,0 +1,94 @@ +.\" $OpenBSD: X509_verify_cert.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2009, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509_VERIFY_CERT 3 +.Os +.Sh NAME +.Nm X509_verify_cert +.Nd discover and verify X509 certificate chain +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509_verify_cert +.Fa "X509_STORE_CTX *ctx" +.Fc +.Sh DESCRIPTION +The +.Fn X509_verify_cert +function attempts to discover and validate a certificate chain based on +parameters in +.Fa ctx . +.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. +.Sh RETURN VALUES +If a complete chain can be built and validated this function returns 1, +otherwise it returns a value <= 0 indicating failure. +.Pp +Additional error information can be obtained by examining +.Fa ctx , +using +.Xr X509_STORE_CTX_get_error 3 . +.Sh SEE ALSO +.Xr openssl 1 , +.Xr X509_STORE_CTX_get_error 3 , +.Xr X509_STORE_CTX_new 3 +.Sh HISTORY +.Fn X509_verify_cert +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . +.Sh BUGS +This function uses the header +.In openssl/x509.h +as opposed to most chain verification functions which use +.In openssl/x509_vfy.h . diff --git a/static/openbsd/man3/X509v3_addr_add_inherit.3 b/static/openbsd/man3/X509v3_addr_add_inherit.3 new file mode 100644 index 00000000..d33de1f6 --- /dev/null +++ b/static/openbsd/man3/X509v3_addr_add_inherit.3 @@ -0,0 +1,476 @@ +.\" $OpenBSD: X509v3_addr_add_inherit.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: June 8 2025 $ +.Dt X509V3_ADDR_ADD_INHERIT 3 +.Os +.Sh NAME +.Nm X509v3_addr_add_inherit , +.Nm X509v3_addr_add_prefix , +.Nm X509v3_addr_add_range , +.Nm X509v3_addr_canonize , +.Nm X509v3_addr_is_canonical +.Nd RFC 3779 IP address delegation extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fo X509v3_addr_add_inherit +.Fa "IPAddrBlocks *addrblocks" +.Fa "const unsigned afi" +.Fa "const unsigned *safi" +.Fc +.Ft int +.Fo X509v3_addr_add_prefix +.Fa "IPAddrBlocks *addrblocks" +.Fa "const unsigned afi" +.Fa "const unsigned *safi" +.Fa "unsigned char *prefix" +.Fa "const int prefixlen" +.Fc +.Ft int +.Fo X509v3_addr_add_range +.Fa "IPAddrBlocks *addrblocks" +.Fa "const unsigned afi" +.Fa "const unsigned *safi" +.Fa "unsigned char *min" +.Fa "unsigned char *max" +.Fc +.Ft int +.Fo X509v3_addr_canonize +.Fa "IPAddrBlocks *addrblocks" +.Fc +.Ft int +.Fo X509v3_addr_is_canonical +.Fa "IPAddrBlocks *addrblocks" +.Fc +.Sh DESCRIPTION +An +.Vt IPAddrBlocks +object represents the content of +an IP address delegation extension +as defined in RFC 3779, section 2.2.3.1. +It holds lists of IP address prefixes and IP address ranges +delegated from the issuer to the subject of the certificate. +It can be instantiated as explained in the EXAMPLES section +and its internals are documented in +.Xr IPAddressRange_new 3 . +.Pp +Each list in a well-formed +.Vt IPAddrBlocks +object is uniquely identified by +an address family identifier (AFI) and +an optional subsequent address family identifier (SAFI). +Lists can be absent or can contain an +.Dq inherit +marker to indicate that the resources are to be inherited +from the corresponding list of the issuer certificate. +.Pp +Per specification, an AFI is an unsigned 16-bit integer and +a SAFI is an unsigned 8-bit integer. +For IPv4 and IPv6 there are the predefined constants +.Dv IANA_AFI_IPV4 +and +.Dv IANA_AFI_IPV6 , +which should be the only values used for +.Fa afi +in this API. +In practice, +.Fa safi +is always NULL. +.Fa afi +is generally silently truncated to its lowest 16 bits and, if +.Fa safi +is non-NULL, +only the lowest 8 bits of the value pointed at are used. +.Pp +.Fn X509v3_addr_add_inherit +adds a list with an +.Dq inherit +marker to +.Fa addrblocks . +If a list corresponding to +.Fa afi +and +.Fa safi +already exists, no action occurs if it is marked +.Dq inherit , +otherwise the call fails. +.Pp +.Fn X509v3_addr_add_prefix +adds a newly allocated internal representation of the +.Fa prefix +of length +.Fa prefixlen +to the list corresponding to +.Fa afi +and the optional +.Fa safi +in +.Fa addrblocks . +If no such list exists, it is created first. +If the list exists and is marked +.Dq inherit , +the call fails. +.Fa prefix +is expected to be a byte array in network byte order. +It should point at enough memory to accommodate +.Fa prefixlen +bits and it is recommended that all the bits not covered by the +.Fa prefixlen +be set to 0. +It is the caller's responsibility to ensure that the +.Fa prefix +has no address in common with any of +the prefixes or ranges already in the list. +If +.Fa afi +is +.Dv IANA_AFI_IPV4 , +.Fa prefixlen +should be between 0 and 32 (inclusive) and if +.Fa afi +is +.Dv IANA_AFI_IPV6 , +.Fa prefixlen +should be between 0 and 128 (inclusive). +.Pp +.Fn X509v3_addr_add_range +is similar to +.Fn X509v3_addr_add_prefix +for the closed interval of IP addresses between +.Fa min +and +.Fa max +in network presentation. +If +.Fa afi +is +.Dv IANA_AFI_IPV4 , +.Fa min +and +.Fa max +should point at 4 bytes of memory +and if +.Fa afi +is +.Dv IANA_AFI_IPV6 , +.Fa min +and +.Fa max +should point at 16 bytes of memory. +In case the range of IP addresses between +.Fa min +and +.Fa max +is a prefix, a prefix will be added instead of a range. +It is the caller's responsibility to ensure that +.Fa min +is less than or equal to +.Fa max +and that it does not contain any address already present +in the list. +Failure to do so will result in a subsequent failure of +.Fn X509v3_addr_canonize . +.Pp +.Fn X509v3_addr_canonize +attempts to bring the +.Pf non- Dv NULL +.Fa addrblocks +into canonical form. +An +.Vt IPAddrBlocks +object is said to be in canonical form if it conforms +to the ordering specified in RFC 3779: +section 2.2.3.3 requires that +the list of lists be sorted first by increasing +.Fa afi +and then by increasing +.Fa safi , +where NULL is the minimal SAFI; +section 2.2.3.6 requires that each list be in minimal form and sorted. +The minimality requirement is that all adjacent prefixes +and ranges must be merged into a single range and that each +range must be expressed as a prefix, if possible. +In particular, any given address can be in at most one list entry. +The order is by increasing minimal IP address in network byte order. +.Pp +.Fn X509v3_addr_is_canonical +indicates whether +.Fa addrblocks +is in canonical form. +.Sh RETURN VALUES +All these functions return 1 on success and 0 on failure. +Memory allocation failure is one possible reason for all of them. +Sometimes an error code can be obtained by +.Xr ERR_get_error 3 . +.Pp +.Fn X509v3_addr_add_inherit +fails if the list corresponding to +.Fa afi +and the optional +.Fa safi +already exists and is not marked +.Dq inherit . +.Pp +.Fn X509v3_addr_add_prefix +and +.Fn X509v3_addr_add_range +fail if a list corresponding to +.Fa afi +and the optional +.Fa safi +already exists and is marked +.Dq inherit , +or if +.Fa prefixlen +is outside the interval [0,32] for IPv4 addresses +or [0,128] for IPv6 addresses. +.Pp +.Fn X509v3_addr_canonize +fails if one of the lists in +.Fa addrblocks +is malformed, +in particular if it contains corrupt, overlapping, +or duplicate entries. +Corruption includes ranges where +.Fa max +is strictly smaller than +.Fa min . +The error conditions are generally indistinguishable. +.Pp +.Fn X509v3_addr_is_canonical +returns 1 if +.Fa addrblocks +is in canonical form. +A return value of 0 can indicate non-canonical form or a corrupted list. +.Sh EXAMPLES +Construct the first extension from RFC 3779, Appendix B. +.Bd -literal +#include +#include + +#include +#include +#include + +#include +#include +#include +#include + +const char *prefixes[] = { + "10.0.32/20", "10.0.64/24", "10.1/16", + "10.2.48/20", "10.2.64/24", "10.3/16", +}; +#define N_PREFIXES (sizeof(prefixes) / sizeof(prefixes[0])) + +static void +hexdump(const unsigned char *buf, size_t len) +{ + size_t i; + + for (i = 1; i <= len; i++) + printf(" 0x%02x,%s", buf[i \- 1], i % 8 ? "" : "\en"); + if (len % 8) + printf("\en"); +} + +int +main(void) +{ + IPAddrBlocks *addrblocks; + X509_EXTENSION *ext; + unsigned char *der; + int der_len; + size_t i; + + if (pledge("stdio", NULL) == \-1) + err(1, "pledge"); + + /* + * Somebody forgot to implement IPAddrBlocks_new(). IPAddrBlocks + * is the same as STACK_OF(IPAddressFamily). As such, it should + * have IPAddressFamily_cmp() as its comparison function. It is + * not possible to call sk_new(3) because IPAddressFamily_cmp() + * is not part of the public API. The correct comparison function + * can be installed as a side-effect of X509v3_addr_canonize(3). + */ + if ((addrblocks = sk_IPAddressFamily_new_null()) == NULL) + err(1, "sk_IPAddressFamily_new_null"); + if (!X509v3_addr_canonize(addrblocks)) + errx(1, "X509v3_addr_canonize"); + + /* Add the prefixes as IPv4 unicast. */ + for (i = 0; i < N_PREFIXES; i++) { + unsigned char addr[16] = {0}; + int len; + int unicast = 1; /* SAFI for unicast forwarding. */ + + len = inet_net_pton(AF_INET, prefixes[i], addr, + sizeof(addr)); + if (len == \-1) + errx(1, "inet_net_pton(%s)", prefixes[i]); + if (!X509v3_addr_add_prefix(addrblocks, IANA_AFI_IPV4, + &unicast, addr, len)) + errx(1, "X509v3_addr_add_prefix(%s)", prefixes[i]); + } + if (!X509v3_addr_add_inherit(addrblocks, IANA_AFI_IPV6, NULL)) + errx(1, "X509v3_addr_add_inherit"); + + /* + * Ensure the extension is in canonical form. Otherwise the two + * adjacent prefixes 10.2.48/20 and 10.2.64/24 are not merged into + * the range 10.2.48.0--10.2.64.255. This results in invalid DER + * encoding from X509V3_EXT_i2d(3) and i2d_X509_EXTENSION(3). + */ + if (!X509v3_addr_canonize(addrblocks)) + errx(1, "X509v3_addr_canonize"); + + /* Create the extension with the correct OID; mark it critical. */ + ext = X509V3_EXT_i2d(NID_sbgp_ipAddrBlock, 1, addrblocks); + if (ext == NULL) + errx(1, "X509V3_EXT_i2d"); + + der = NULL; + if ((der_len = i2d_X509_EXTENSION(ext, &der)) <= 0) + errx(1, "i2d_X509_EXTENSION"); + + hexdump(der, der_len); + + /* One way of implementing IPAddrBlocks_free(). */ + sk_IPAddressFamily_pop_free(addrblocks, IPAddressFamily_free); + X509_EXTENSION_free(ext); + free(der); + + return 0; +} +.Ed +.Pp +Implement the missing public API +.Fn d2i_IPAddrBlocks +and +.Fn i2d_IPAddrBlocks +using +.Xr ASN1_item_d2i 3 : +.Bd -literal +IPAddrBlocks * +d2i_IPAddrBlocks(IPAddrBlocks **addrblocks, const unsigned char **in, + long len) +{ + const X509V3_EXT_METHOD *v3_addr; + + if ((v3_addr = X509V3_EXT_get_nid(NID_sbgp_ipAddrBlock)) == NULL) + return NULL; + return (IPAddrBlocks *)ASN1_item_d2i((ASN1_VALUE **)addrblocks, + in, len, ASN1_ITEM_ptr(v3_addr\->it)); +} + +int +i2d_IPAddrBlocks(IPAddrBlocks *addrblocks, unsigned char **out) +{ + const X509V3_EXT_METHOD *v3_addr; + + if ((v3_addr = X509V3_EXT_get_nid(NID_sbgp_ipAddrBlock)) == NULL) + return \-1; + return ASN1_item_i2d((ASN1_VALUE *)addrblocks, out, + ASN1_ITEM_ptr(v3_addr\->it)); +} +.Ed +.Pp +The use of the undocumented macro +.Dv ASN1_ITEM_ptr() +is necessary if compatibility with modern versions of other implementations +is desired. +.Sh SEE ALSO +.Xr ASIdentifiers_new 3 , +.Xr crypto 3 , +.Xr inet_net_ntop 3 , +.Xr inet_ntop 3 , +.Xr IPAddressRange_new 3 , +.Xr X509_new 3 , +.Xr X509v3_addr_get_range 3 , +.Xr X509v3_addr_validate_path 3 , +.Xr X509v3_asid_add_id_or_range 3 +.Sh STANDARDS +RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: +.Bl -dash -compact +.It +section 2: IP Address delegation extension +.El +.Pp +RFC 7020: The Internet Numbers Registry System +.Pp +RFC 7249: Internet Number Registries +.Pp +.Rs +.%T Address Family Numbers +.%U https://www.iana.org/assignments/address\-family\-numbers +.Re +.Pp +.Rs +.%T Subsequent Address Family Identifiers (SAFI) Parameters +.%U https://www.iana.org/assignments/safi\-namespace +.Re +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . +.Sh BUGS +.Fn IPAddrBlocks_new , +.Fn IPAddrBlocks_free , +.Fn d2i_IPAddrBlocks , +and +.Fn i2d_IPAddrBlocks +do not exist and +.Fa IPAddrBlocks_it +is not public. +The above examples show how to implement the four missing functions +with public API. +.Pp +.Fn X509v3_addr_add_range +should check for inverted range bounds and overlaps +on insertion and fail instead of creating a nonsensical +.Fa addrblocks +that fails to be canonized by +.Fn X509v3_addr_canonize . +.Pp +If +.Dv NULL +is passed to +.Xr X509v3_asid_canonize 3 , +it succeeds. +.Fn X509v3_addr_is_canonical +considers +.Dv NULL +to be a canonical +.Vt IPAddrBlocks . +In contrast, +.Fn X509v3_addr_canonize +crashes with a +.Dv NULL +dereference. +.Pp +The code only supports the IPv4 and IPv6 AFIs. +This is not consistently enforced across implementations. +.Pp +.Fn X509v3_addr_add_range +fails to clear the unused bits set to 1 in the last octet of +the +.Vt ASN1_BIT_STRING +representation of +.Fa max . +This confuses some software. diff --git a/static/openbsd/man3/X509v3_addr_get_range.3 b/static/openbsd/man3/X509v3_addr_get_range.3 new file mode 100644 index 00000000..7ad279d7 --- /dev/null +++ b/static/openbsd/man3/X509v3_addr_get_range.3 @@ -0,0 +1,133 @@ +.\" $OpenBSD: X509v3_addr_get_range.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: June 8 2025 $ +.Dt X509V3_ADDR_GET_RANGE 3 +.Os +.Sh NAME +.Nm X509v3_addr_get_afi , +.Nm X509v3_addr_get_range +.Nd parse helpers for the IP address delegation extension +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft unsigned +.Fn X509v3_addr_get_afi "const IPAddressFamily *af" +.Ft int +.Fo X509v3_addr_get_range +.Fa "IPAddressOrRange *aor" +.Fa "const unsigned afi" +.Fa "unsigned char *min" +.Fa "unsigned char *max" +.Fa "const int length" +.Fc +.Sh DESCRIPTION +.Fn X509v3_addr_get_afi +returns the address family identifier (AFI) of +.Fa af . +.Pp +.Fn X509v3_addr_get_range +converts the minimum and maximum addresses in +the address prefix or range +.Fa aor +from internal encoding to IP addresses in network byte order +and places copies in the arrays +.Fa min +and +.Fa max , +of size +.Fa length . +The +.Fa length +must be large enough to accommodate an address for +.Fa afi , +which is at least 4 for +.Dv IANA_AFI_IPV4 +and at least 16 for +.Dv IANA_AFI_IPV6 . +.Sh RETURN VALUES +.Fn X509v3_addr_get_afi +returns the AFI encoded in +.Fa af +or 0 if +.Fa af +does not contain a valid AFI, or if the AFI is not IPv4 or IPv6. +.Pp +.Fn X509v3_addr_get_range +returns the number of bytes copied into +.Fa min +and +.Fa max +or 0 on error. +An error occurs if +.Fa aor +is malformed, if +.Fa afi +is not +.Dv IANA_AFI_IPV4 +or +.Dv IANA_AFI_IPV6 , +if either +.Fa min +or +.Fa max +is +.Dv NULL , +or if +.Fa length +is smaller than 4 or 16, respectively. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr inet_ntop 3 , +.Xr IPAddressRange_new 3 , +.Xr X509_new 3 , +.Xr X509v3_addr_add_inherit 3 +.Sh STANDARDS +RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: +.Bl -dash -compact +.It +section 2: IP Address delegation extension +.It +section 2.2.3.3: Element addressFamily +.It +section 2.2.3.7: Type IPAddressOrRange +.It +section 2.2.3.8: Element addressPrefix and Type IPAddress +.El +.Pp +.Rs +.%T Address Family Numbers +.%U https://www.iana.org/assignments/address-family-numbers +.Re +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . +.Sh BUGS +There is no accessor for the SAFI of +.Fa af . +.Pp +An error from +.Fn X509v3_addr_get_afi +is indistinguishable from the reserved AFI 0 being set on +.Fa af . +.Pp +It is not entirely clear how a caller is supposed to obtain an +.Vt IPAddressFamily +object or an +.Vt IPAddressOrRange +object without reaching into various structs documented in +.Xr IPAddressRange_new 3 . diff --git a/static/openbsd/man3/X509v3_addr_inherits.3 b/static/openbsd/man3/X509v3_addr_inherits.3 new file mode 100644 index 00000000..0da24ad1 --- /dev/null +++ b/static/openbsd/man3/X509v3_addr_inherits.3 @@ -0,0 +1,105 @@ +.\" $OpenBSD: X509v3_addr_inherits.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: June 8 2025 $ +.Dt X509V3_ADDR_INHERITS 3 +.Os +.Sh NAME +.Nm X509v3_addr_inherits , +.Nm X509v3_asid_inherits +.Nd RFC 3779 inheritance +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fn X509v3_addr_inherits "IPAddrBlocks *addrblocks" +.Ft int +.Fn X509v3_asid_inherits "ASIdentifiers *asids" +.Sh DESCRIPTION +.Fn X509v3_addr_inherits +determines if there is at least one address family in +.Fa addrblocks +that uses inheritance. +.Pp +.Fn X509v3_asid_inherits +is intended to determine if at least one of +the list of autonomous system numbers or +the list of routing domain identifiers +uses inheritance. +.Sh RETURN VALUES +.Fn X509v3_addr_inherits +returns 1 if and only if +.Fa addrblocks +contains at least one +.Fa IPAddressFamily +object that is correctly marked +.Dq inherit : +its +.Fa IPAddressChoice +is of +.Fa type +.Dv IPAddressChoice_inherit +and its +.Fa inherit +element is present. +Otherwise it returns 0. +.Pp +.Fn X509v3_asid_inherits +returns 1 if and only if +at least one of the +.Fa asnum +or the +.Fa rdi +lists has +.Fa type +.Dv ASIdentifierChoice_inherit . +Otherwise it returns 0. +.Sh SEE ALSO +.Xr ASIdentifiers_new 3 , +.Xr ASRange_new 3 , +.Xr crypto 3 , +.Xr IPAddressRange_new 3 , +.Xr X509_new 3 , +.Xr X509v3_addr_add_inherit 3 , +.Xr X509v3_asid_add_inherit 3 +.Sh STANDARDS +RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: +.Bl -dash -compact +.It +section 2: IP Address delegation extension +.It +section 2.2.3.5: Element inherit +.It +section 3: AS identifiers delegation extension +.It +section 3.2.3.3: Element inherit +.El +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . +.Sh BUGS +.Fn X509v3_asid_inherits +ignores whether the +.Fa inherit +element is present or absent in the list that is considered to use inheritance. +.Pp +There is no API that determines whether all lists contained in an +.Vt ASIdentifiers +or an +.Vt IPAddrBlocks +object inherit. +See RFC 9287, 5.1.2 for an example where this is relevant. diff --git a/static/openbsd/man3/X509v3_addr_subset.3 b/static/openbsd/man3/X509v3_addr_subset.3 new file mode 100644 index 00000000..5629d9c3 --- /dev/null +++ b/static/openbsd/man3/X509v3_addr_subset.3 @@ -0,0 +1,177 @@ +.\" $OpenBSD: X509v3_addr_subset.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: June 8 2025 $ +.Dt X509V3_ADDR_SUBSET 3 +.Os +.Sh NAME +.Nm X509v3_addr_subset , +.Nm X509v3_asid_subset +.Nd RFC 3779 subset relationship +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fn X509v3_addr_subset "IPAddrBlocks *child" "IPAddrBlocks *parent" +.Ft int +.Fn X509v3_asid_subset "ASIdentifiers *child" "ASIdentifiers *parent" +.Sh DESCRIPTION +.Fn X509v3_addr_subset +determines if all IP address resources present in +.Fa child +are contained in the corresponding resources in +.Fa parent . +.Pp +The implementation assumes but does not ensure that both +.Fa child +and +.Fa parent +are in canonical form as described in +.Xr X509v3_addr_is_canonical 3 . +In particular, both +.Fa child +and +.Fa parent +are sorted appropriately and they contain at most one +.Vt IPAddressFamily +object per address family identifier (AFI) and optional +subsequent address family identifier (SAFI). +.Pp +The checks are, in order: +.Bl -enum +.It +If +.Fa child +is +.Dv NULL +or identical to +.Fa parent +then +.Fa child +is a subset of +.Fa parent . +In particular, a +.Dv NULL +.Fa parent +is allowed for a +.Dv NULL +.Fa child . +.It +If +.Fa parent +is +.Dv NULL +then +.Fa child +is not a subset of +.Fa parent . +.It +If +.Xr X509v3_addr_inherits 3 +determines that +.Fa child +inherits or that +.Fa parent +inherits +then +.Fa child +is not a subset of +.Fa parent . +.It +Each address prefix or range in +.Fa child +must be a subset of an address prefix or range in the +.Fa parent , +taking AFI and optional SAFI into account: +.Bl -bullet -compact +.It +For each +.Vt IPAddressFamily +of +.Fa child +there must be an +.Vt IPAddressFamily +of +.Fa parent +with the same AFI and optional SAFI. +.It +Since the address prefixes and ranges in corresponding +.Vt IPAddressFamily +objects in +.Fa child +and +.Fa parent +are sorted in ascending order, +and do not overlap, +they can be traversed simultaneously in linear time. +For each prefix or range in +.Fa child +there must be a prefix or range in +.Fa parent +whose minimal address is smaller +and whose maximal address is larger. +.El +If any of these steps fails, +.Fa child +is not a subset of +.Fa parent . +.El +.Pp +.Fn X509v3_asid_subset +determines if all AS identifier resources in +.Fa child +are contained in the corresponding resources in +.Fa parent . +.Pp +The description for +.Fn X509v3_addr_subset +applies mutatis mutandis. +In particular, +.Fa child +and +.Fa parent +must be in canonical form per +.Xr X509v3_asid_is_canonical 3 , +but this is not enforced. +.Sh RETURN VALUES +.Fn X509v3_addr_subset +and +.Fn X509v3_asid_subset +return 1 if and only if +.Fa child +is a subset of +.Fa parent , +otherwise they return 0. +If both +.Fa child +and +.Fa parent +are in canonical form, +these functions cannot fail. +.Sh SEE ALSO +.Xr ASIdentifiers_new 3 , +.Xr ASRange_new 3 , +.Xr crypto 3 , +.Xr IPAddressRange_new 3 , +.Xr X509_new 3 , +.Xr X509v3_addr_add_inherit 3 , +.Xr X509v3_asid_add_inherit 3 +.Sh STANDARDS +RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers. +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/X509v3_addr_validate_path.3 b/static/openbsd/man3/X509v3_addr_validate_path.3 new file mode 100644 index 00000000..5bafc6eb --- /dev/null +++ b/static/openbsd/man3/X509v3_addr_validate_path.3 @@ -0,0 +1,204 @@ +.\" $OpenBSD: X509v3_addr_validate_path.3,v 1.6 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: June 8 2025 $ +.Dt X509V3_ADDR_VALIDATE_PATH 3 +.Os +.Sh NAME +.Nm X509v3_addr_validate_path , +.Nm X509v3_addr_validate_resource_set , +.Nm X509v3_asid_validate_path , +.Nm X509v3_asid_validate_resource_set +.Nd RFC 3779 path validation for IP address and AS number delegation +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fn X509v3_addr_validate_path "X509_STORE_CTX *ctx" +.Ft int +.Fo X509v3_addr_validate_resource_set +.Fa "STACK_OF(X509) *chain" +.Fa "IPAddrBlocks *addrblocks" +.Fa "int allow_inherit" +.Fc +.Ft int +.Fn X509v3_asid_validate_path "X509_STORE_CTX *ctx" +.Ft int +.Fo X509v3_asid_validate_resource_set +.Fa "STACK_OF(X509) *chain" +.Fa "ASIdentifiers *asid" +.Fa "int allow_inherit" +.Fc +.Sh DESCRIPTION +Both RFC 3779 extensions require additional checking in the certification +path validation. +.Bl -enum +.It +The initial set of allowed IP address and AS number resources is defined in +the trust anchor, where inheritance is not allowed. +.It +An issuer may only delegate subsets of resources present in its +RFC 3779 extensions or subsets of resources inherited from its issuer. +.It +If an RFC 3779 extension is present in a certificate, +the same type of extension must also be present in its issuer. +.It +All RFC 3779 extensions +appearing in the validation path must be in canonical form +according to +.Xr X509v3_addr_is_canonical 3 +and +.Xr X509v3_asid_is_canonical 3 . +.El +.Pp +.Fn X509v3_addr_validate_path +and +.Fn X509v3_asid_validate_path +are called from +.Xr X509_verify_cert 3 +as part of the verification chain building. +On encountering an error or a violation of the above rules, +.Fa error , +.Fa error_depth , +and +.Fa current_cert +are set on +.Fa ctx +and the verify callback is called with +.Fa ok +set to 0. +.Dv X509_V_ERR_INVALID_EXTENSION +indicates a non-canonical resource, +.Dv X509_V_ERR_UNNESTED_RESOURCE +indicates a violation of the other rules above. +In rare circumstances, the error can be +.Dv X509_V_ERR_UNSPECIFIED +and for IP address resources +.Dv X509_V_ERR_OUT_OF_MEM +is also possible. +.Pp +.Fn X509v3_addr_validate_resource_set +validates the resources in +.Fa addrblocks +against a specific certificate +.Fa chain . +After checking that +.Fa addrblocks +is canonical, its IP addresses are checked to be covered in +the certificate at depth 0, +then the chain is walked all the way to the trust anchor +until an error or a violation of the above rules is encountered. +.Fa addrblocks +is allowed to use inheritance according to +.Xr X509v3_addr_inherits 3 +if and only if +.Fa allow_inherit +is non-zero. +.Pp +.Fn X509v3_asid_validate_resource_set +performs similar checks as +.Fn X509v3_addr_validate_resource_set +for +.Fa asid . +.Sh RETURN VALUES +All these functions return 1 on successful validation and 0 otherwise. +.Pp +For +.Fn X509v3_addr_validate_path +and +.Fn X509v3_asid_validate_path +a non-empty +.Fa chain +and a +.Fa verify_cb +must be present on +.Fa ctx , +otherwise they fail and set the +.Fa error +on +.Fa ctx +to +.Dv X509_V_ERR_UNSPECIFIED . +The +.Fa verify_cb +is called with the error codes described above +on most errors encountered during validation. +Some malformed extensions can lead to an error +that cannot be intercepted by the callback. +With the exception of an allocation error, +no error codes are set on the error stack. +.Pp +.Fn X509v3_addr_validate_resource_set +accepts a +.Dv NULL +.Fa addrblocks +and +.Fn X509v3_asid_validate_resource_set +accepts a +.Dv NULL +.Fa asid +as valid. +They fail if +.Fa chain +is +.Dv NULL +or empty. +If +.Fa allow_inherit +is 0, +.Fa addrblocks +or +.Fa asid +is checked for inheritance with +.Xr X509v3_addr_inherits 3 +or +.Xr X509v3_asid_inherits 3 . +The remaining failure cases are the same as for +.Fn X509v3_addr_validate_path +and +.Fn X509v3_asid_validate_path . +They cannot and do not attempt to communicate +the cause of the error to the caller. +.Sh SEE ALSO +.Xr ASIdentifiers_new 3 , +.Xr crypto 3 , +.Xr IPAddressRange_new 3 , +.Xr X509_new 3 , +.Xr X509_STORE_CTX_get_error 3 , +.Xr X509_verify_cert 3 , +.Xr X509v3_addr_add_inherit 3 , +.Xr X509v3_addr_inherits 3 , +.Xr X509v3_asid_add_id_or_range 3 +.Sh STANDARDS +RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: +.Bl -dash -compact +.It +section 2.3: IP Address Delegation Extension Certification Path Validation +.It +section 3.3: Autonomous System Identifier Delegation Extension Certification +Path Validation +.El +.Pp +RFC 5280: Internet X.509 Public Key Infrastructure Certificate +and Certificate Revocation List (CRL) Profile +.Bl -dash -compact +.It +section 6: Certification Path Validation +.El +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/X509v3_asid_add_id_or_range.3 b/static/openbsd/man3/X509v3_asid_add_id_or_range.3 new file mode 100644 index 00000000..6378f45a --- /dev/null +++ b/static/openbsd/man3/X509v3_asid_add_id_or_range.3 @@ -0,0 +1,328 @@ +.\" $OpenBSD: X509v3_asid_add_id_or_range.3,v 1.10 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: June 8 2025 $ +.Dt X509V3_ASID_ADD_ID_OR_RANGE 3 +.Os +.Sh NAME +.Nm X509v3_asid_add_id_or_range , +.Nm X509v3_asid_add_inherit , +.Nm X509v3_asid_canonize , +.Nm X509v3_asid_is_canonical +.Nd RFC 3779 autonomous system identifier delegation extension +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fo X509v3_asid_add_id_or_range +.Fa "ASIdentifiers *asid" +.Fa "int type" +.Fa "ASN1_INTEGER *min" +.Fa "ASN1_INTEGER *max" +.Fc +.Ft int +.Fo X509v3_asid_add_inherit +.Fa "ASIdentifiers *asid" +.Fa "int type" +.Fc +.Ft int +.Fo X509v3_asid_canonize +.Fa "ASIdentifiers *asid" +.Fc +.Ft int +.Fo X509v3_asid_is_canonical +.Fa "ASIdentifiers *asid" +.Fc +.Sh DESCRIPTION +An +.Vt ASIdentifiers +object represents the content of the certificate extension +defined in RFC 3779, section 3.2.3.1. +It can be instantiated with +.Xr ASIdentifiers_new 3 +and its internals are documented in +.Xr ASRange_new 3 . +.Pp +An autonomous system is identified by an unsigned 32-bit integer, +called an AS identifier or AS number. +An +.Vt ASIdentifiers +object can hold two lists: +a list of +.Fa type +.Dv V3_ASID_ASNUM +containing individual AS identifiers and ranges of AS identifiers, +and an obsolete list of +.Fa type +.Dv V3_ASID_RDI +containing routing domain identifiers (RDIs). +Either of these lists may be absent, or it may contain nothing +but a special +.Dq inherit +marker that indicates that the list is inherited from the issuer +of the certificate. +.Pp +.Fn X509v3_asid_add_id_or_range +adds an individual identifier or a range of identifiers to the list of +.Fa type +(either +.Dv V3_ASID_ASNUM +or +.Dv V3_ASID_RDI ) +in +.Fa asid . +If no such list exists, it is created first. +If a list of +.Fa type +already exists and contains the +.Dq inherit +marker, the call fails. +.Fa min +must be a +.Pf non- Dv NULL +.Vt ASN1_INTEGER . +If +.Fa max +is +.Dv NULL , +.Fa min +is added as an individual identifier. +Ownership of +.Fa min +and +.Fa max +is transferred to +.Fa asid +on success. +It is the responsibility of the caller to ensure that +the resulting +.Fa asid +does not contain lists with overlapping ranges and that +.Fa min +is strictly less than +.Fa max +if both are +.Pf non- Dv NULL . +The caller should also ensure that the AS identifiers are +32-bit integers. +Failure to do so may result in an +.Fa asid +that cannot be brought into canonical form by +.Fn X509v3_asid_canonize . +.Pp +.Fn X509v3_asid_add_inherit +adds the list of +.Fa type +(either +.Dv V3_ASID_ASNUM +or +.Dv V3_ASID_RDI ) +in +.Fa asid +if necessary and marks it +.Dq inherit . +This fails if +.Fa asid +already contains a list of +.Fa type +that is not marked +.Dq inherit . +.Pp +.Fn X509v3_asid_canonize +attempts to bring both lists in +.Fa asid +into canonical form. +If +.Fa asid +is +.Dv NULL +the call succeeds and no action occurs. +A list is in canonical form if it is either one of +.Bl -dash -compact +.It +absent, +.It +marked +.Dq inherit , +.It +non-empty and all identifiers and ranges are listed in increasing order. +Ranges must not overlap, +.\" the following is not currently specified and leads to ambiguity: +.\" contain at least two elements, +and adjacent ranges must be fully merged. +.El +.Pp +.Fn X509v3_asid_canonize +merges adjacent ranges +but refuses to merge overlapping ranges or to discard duplicates. +For example, the adjacent ranges [a,b] and [b+1,c] are merged +into the single range [a,c], but if both [a,b] and [b,c] appear in a list, +this results in an error since they are considered overlapping. +Likewise, the identifier a is absorbed into the adjacent +range [a+1,b] to yield [a,b]. +.Fn X509v3_asid_canonize +errors if the minimum of any range is larger than the maximum. +In contrast, minimum and maximum of a range may be equal. +.Pp +.Fn X509v3_asid_is_canonical +checks whether +.Fa asid +is in canonical form. +Once +.Fn X509v3_asid_canonize +is called successfully on +.Fa asid , +all subsequent calls to +.Fn X509v3_asid_is_canonical +succeed on an unmodified +.Fa asid +unless memory allocation fails. +.Sh RETURN VALUES +All these functions return 1 on success and 0 on failure. +.Pp +.Fn X509v3_asid_add_id_or_range +and +.Fn X509v3_asid_add_inherit +fail if +.Fa asid +is +.Dv NULL +or if +.Fa type +is distinct from +.Dv V3_ASID_ASNUM +and +.Dv V3_ASID_RDI , +or on memory allocation failure. +In addition, +.Fn X509v3_asid_add_id_or_range +fails if +.Fa asid +contains a list of +.Fa type +that is marked +.Dq inherit , +and +.Fn X509v3_asid_add_inherit +fails if +.Fa asid +contains a list of +.Fa type +that is not marked +.Dq inherit . +.Pp +.Fn X509v3_asid_canonize +fails if either list is empty and not marked +.Dq inherit , +or if it is malformed, or if memory allocation fails. +Malformed lists include lists containing duplicate, overlapping, +or malformed elements, for example AS ranges where the minimum is +larger than the maximum. +Some of these failure modes result in an error being pushed onto the +error stack. +.Pp +.Fn X509v3_asid_is_canonical +returns 1 if +.Fa asid +is canonical and 0 if it is not canonical or on memory allocation +failure. +.Sh SEE ALSO +.Xr ASIdentifiers_new 3 , +.Xr crypto 3 , +.Xr s2i_ASN1_INTEGER 3 , +.Xr X509_new 3 , +.Xr X509v3_addr_add_inherit 3 , +.Xr X509v3_addr_validate_path 3 +.Sh STANDARDS +RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers, +.Bl -dash -compact +.It +section 3: Autonomous System Delegation Extension +.El +.Pp +.Rs +.%T Autonomous System (AS) Numbers +.%U https://www.iana.org/assignments/as-numbers +.Re +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . +.Sh BUGS +.Fn X509v3_asid_add_id_or_range +does not check for inverted range bounds and overlaps +on insertion. +It is very easy to create an +.Fa asid +that fails to be canonized by +.Fn X509v3_asid_canonize +and it is very hard to diagnose why. +.Pp +Both +.Fn X509v3_asid_add_id_or_range +and +.Fn X509v3_asid_add_inherit +can leave +.Fa asid +in a corrupted state if memory allocation fails during their execution. +In addition, +.Fn X509v3_asid_add_id_or_range +may already have freed the +.Fa min +and +.Fa max +arguments on failure. +.Pp +RFC 3779 does not explicitly disallow ranges where the minimum +is equal to the maximum. +The isolated AS identifier +.Fa min +and the AS range +.Bq Fa min , Ns Fa min +where the minimum and the maximum are equal to +.Fa min +have the same semantics. +.Fn X509v3_asid_is_canonical +accepts both representations as valid and +.Fn X509v3_asid_canonize +does not prefer either representation over the other. +The encodings of the two representations produced by +.Xr i2d_ASIdentifiers 3 +are distinct. +.Pp +.Fn X509v3_asid_is_canonical +does not fully check inheriting lists to be well formed. +It only checks the +.Fa type +to be +.Dv ASIdentifierChoice_inherit +and ignores the presence or absence of the +.Fa inherit +element. +.Fn X509v3_asid_canonize +does not fix that up. +This can lead to incorrect or unexpected DER encoding of +.Dq canonical +.Vt ASIdentifiers +objects. +In particular, it is possible to construct an +.Vt ASIdentifiers +object for which both +.Fn X509v3_asid_is_canonical +and +.Xr X509v3_asid_inherits 3 +return 1, and after a round trip through DER the latter +returns 0. diff --git a/static/openbsd/man3/X509v3_get_ext_by_NID.3 b/static/openbsd/man3/X509v3_get_ext_by_NID.3 new file mode 100644 index 00000000..63f81801 --- /dev/null +++ b/static/openbsd/man3/X509v3_get_ext_by_NID.3 @@ -0,0 +1,409 @@ +.\" $OpenBSD: X509v3_get_ext_by_NID.3,v 1.16 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL fd38836b Jun 20 15:25:43 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt X509V3_GET_EXT_BY_NID 3 +.Os +.Sh NAME +.Nm X509v3_get_ext_count , +.Nm X509v3_get_ext , +.Nm X509v3_get_ext_by_NID , +.Nm X509v3_get_ext_by_OBJ , +.Nm X509v3_get_ext_by_critical , +.Nm X509v3_delete_ext , +.Nm X509v3_add_ext , +.Nm X509_get_ext_count , +.Nm X509_get_ext , +.Nm X509_get_ext_by_NID , +.Nm X509_get_ext_by_OBJ , +.Nm X509_get_ext_by_critical , +.Nm X509_delete_ext , +.Nm X509_add_ext , +.Nm X509_CRL_get_ext_count , +.Nm X509_CRL_get_ext , +.Nm X509_CRL_get_ext_by_NID , +.Nm X509_CRL_get_ext_by_OBJ , +.Nm X509_CRL_get_ext_by_critical , +.Nm X509_CRL_delete_ext , +.Nm X509_CRL_add_ext , +.Nm X509_REVOKED_get_ext_count , +.Nm X509_REVOKED_get_ext , +.Nm X509_REVOKED_get_ext_by_NID , +.Nm X509_REVOKED_get_ext_by_OBJ , +.Nm X509_REVOKED_get_ext_by_critical , +.Nm X509_REVOKED_delete_ext , +.Nm X509_REVOKED_add_ext +.Nd extension stack utility functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft int +.Fo X509v3_get_ext_count +.Fa "const STACK_OF(X509_EXTENSION) *x" +.Fc +.Ft X509_EXTENSION * +.Fo X509v3_get_ext +.Fa "const STACK_OF(X509_EXTENSION) *x" +.Fa "int loc" +.Fc +.Ft int +.Fo X509v3_get_ext_by_NID +.Fa "const STACK_OF(X509_EXTENSION) *x" +.Fa "int nid" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509v3_get_ext_by_OBJ +.Fa "const STACK_OF(X509_EXTENSION) *x" +.Fa "const ASN1_OBJECT *obj" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509v3_get_ext_by_critical +.Fa "const STACK_OF(X509_EXTENSION) *x" +.Fa "int crit" +.Fa "int lastpos" +.Fc +.Ft X509_EXTENSION * +.Fo X509v3_delete_ext +.Fa "STACK_OF(X509_EXTENSION) *x" +.Fa "int loc" +.Fc +.Ft STACK_OF(X509_EXTENSION) * +.Fo X509v3_add_ext +.Fa "STACK_OF(X509_EXTENSION) **x" +.Fa "X509_EXTENSION *ex" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_get_ext_count +.Fa "const X509 *x" +.Fc +.Ft X509_EXTENSION * +.Fo X509_get_ext +.Fa "const X509 *x" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_get_ext_by_NID +.Fa "const X509 *x" +.Fa "int nid" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509_get_ext_by_OBJ +.Fa "const X509 *x" +.Fa "const ASN1_OBJECT *obj" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509_get_ext_by_critical +.Fa "const X509 *x" +.Fa "int crit" +.Fa "int lastpos" +.Fc +.Ft X509_EXTENSION * +.Fo X509_delete_ext +.Fa "X509 *x" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_add_ext +.Fa "X509 *x" +.Fa "X509_EXTENSION *ex" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_CRL_get_ext_count +.Fa "const X509_CRL *x" +.Fc +.Ft X509_EXTENSION * +.Fo X509_CRL_get_ext +.Fa "const X509_CRL *x" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_CRL_get_ext_by_NID +.Fa "const X509_CRL *x" +.Fa "int nid" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509_CRL_get_ext_by_OBJ +.Fa "const X509_CRL *x" +.Fa "const ASN1_OBJECT *obj" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509_CRL_get_ext_by_critical +.Fa "const X509_CRL *x" +.Fa "int crit" +.Fa "int lastpos" +.Fc +.Ft X509_EXTENSION * +.Fo X509_CRL_delete_ext +.Fa "X509_CRL *x" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_CRL_add_ext +.Fa "X509_CRL *x" +.Fa "X509_EXTENSION *ex" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_REVOKED_get_ext_count +.Fa "const X509_REVOKED *x" +.Fc +.Ft X509_EXTENSION * +.Fo X509_REVOKED_get_ext +.Fa "const X509_REVOKED *x" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_REVOKED_get_ext_by_NID +.Fa "const X509_REVOKED *x" +.Fa "int nid" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509_REVOKED_get_ext_by_OBJ +.Fa "const X509_REVOKED *x" +.Fa "const ASN1_OBJECT *obj" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509_REVOKED_get_ext_by_critical +.Fa "const X509_REVOKED *x" +.Fa "int crit" +.Fa "int lastpos" +.Fc +.Ft X509_EXTENSION * +.Fo X509_REVOKED_delete_ext +.Fa "X509_REVOKED *x" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_REVOKED_add_ext +.Fa "X509_REVOKED *x" +.Fa "X509_EXTENSION *ex" +.Fa "int loc" +.Fc +.Sh DESCRIPTION +.Fn X509v3_get_ext_count +retrieves the number of extensions in +.Fa x . +.Pp +.Fn X509v3_get_ext +retrieves extension +.Fa loc +from +.Fa x . +The index +.Fa loc +can take any value from 0 to +.Fn X509_get_ext_count x No \- 1 . +The returned extension is an internal pointer which must not be +freed up by the application. +.Pp +.Fn X509v3_get_ext_by_NID +and +.Fn X509v3_get_ext_by_OBJ +look for an extension with +.Fa nid +or +.Fa obj +from extension stack +.Fa x . +The search starts from the extension after +.Fa lastpos +or from the beginning if +.Fa lastpos +is \-1. +If the extension is found, its index is returned; otherwise, a negative +value is returned. +.Pp +.Fn X509v3_get_ext_by_critical +is similar to +.Fn X509v3_get_ext_by_NID +except that it looks for an extension of criticality +.Fa crit . +A zero value for +.Fa crit +looks for a non-critical extension; a non-zero value looks for a +critical extension. +.Pp +.Fn X509v3_delete_ext +deletes the extension with index +.Fa loc +from +.Fa x . +The deleted extension is returned and must be freed by the caller. +If +.Fa loc +is an invalid index value, +.Dv NULL +is returned. +.Pp +.Fn X509v3_add_ext +adds the extension +.Fa ex +to the stack +.Pf * Fa x +at position +.Fa loc . +If +.Fa loc +is \-1, the new extension is added to the end. +If +.Pf * Fa x +is +.Dv NULL , +a new stack will be allocated. +The passed extension +.Fa ex +is duplicated internally so it must be freed after use. +.Pp +.Fn X509_get_ext_count , +.Fn X509_get_ext , +.Fn X509_get_ext_by_NID , +.Fn X509_get_ext_by_OBJ , +.Fn X509_get_ext_by_critical , +.Fn X509_delete_ext , +and +.Fn X509_add_ext +operate on the extensions of certificate +.Fa x . +They are otherwise identical to the X509v3 functions. +.Pp +.Fn X509_CRL_get_ext_count , +.Fn X509_CRL_get_ext , +.Fn X509_CRL_get_ext_by_NID , +.Fn X509_CRL_get_ext_by_OBJ , +.Fn X509_CRL_get_ext_by_critical , +.Fn X509_CRL_delete_ext , +and +.Fn X509_CRL_add_ext +operate on the extensions of the CRL +.Fa x . +They are otherwise identical to the X509v3 functions. +.Pp +.Fn X509_REVOKED_get_ext_count , +.Fn X509_REVOKED_get_ext , +.Fn X509_REVOKED_get_ext_by_NID , +.Fn X509_REVOKED_get_ext_by_OBJ , +.Fn X509_REVOKED_get_ext_by_critical , +.Fn X509_REVOKED_delete_ext , +and +.Fn X509_REVOKED_add_ext +operate on the extensions of the CRL entry +.Fa x . +They are otherwise identical to the X509v3 functions. +.Pp +These functions are used to examine stacks of extensions directly. +Many applications will want to parse or encode and add an extension: +they should use the extension encode and decode functions instead +such as +.Xr X509_get_ext_d2i 3 . +.Pp +Extension indices start from zero, so a zero index return value is +not an error. +These search functions start from the extension +.Em after +the +.Fa lastpos +parameter, so it should initially be set to \-1. +If it is set to 0, the initial extension will not be checked. +.Sh RETURN VALUES +.Fn X509v3_get_ext_count +returns the extension count. +.Pp +.Fn X509v3_get_ext , +.Fn X509v3_delete_ext , +and +.Fn X509_delete_ext +return an +.Vt X509_EXTENSION +pointer or +.Dv NULL +if an error occurs. +.Pp +.Fn X509v3_get_ext_by_NID , +.Fn X509v3_get_ext_by_OBJ , +and +.Fn X509v3_get_ext_by_critical +return the extension index or \-1 if an error occurs. +In addition, +.Fn X509v3_get_ext_by_NID +returns \-2 if +.Xr OBJ_nid2obj 3 +fails on the requested +.Fa nid . +.Pp +.Fn X509v3_add_ext +returns a stack of extensions or +.Dv NULL +on error. +.Pp +.Fn X509_add_ext +returns 1 on success or 0 on error. +.Sh SEE ALSO +.Xr OBJ_nid2obj 3 , +.Xr X509_CRL_new 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509_new 3 , +.Xr X509_REVOKED_new 3 , +.Xr X509V3_EXT_print 3 , +.Xr X509V3_extensions_print 3 , +.Xr X509V3_get_d2i 3 +.Sh HISTORY +These functions first appeared in SSLeay 0.8.0 +and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/__fpending.3 b/static/openbsd/man3/__fpending.3 new file mode 100644 index 00000000..530b2e13 --- /dev/null +++ b/static/openbsd/man3/__fpending.3 @@ -0,0 +1,129 @@ +.\" $OpenBSD: __fpending.3,v 1.3 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2024 Philip Guenther +.\" +.\" 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: June 13 2025 $ +.Dt __FPENDING 3 +.Os +.Sh NAME +.Nm __fpending , +.Nm __freadahead , +.Nm __freading , +.Nm __freadptr , +.Nm __freadptrinc , +.Nm __fseterr , +.Nm __fwriting +.Nd stream extension functions +.Sh SYNOPSIS +.In stdio_ext.h +.Ft size_t +.Fn __fpending "FILE *stream" +.Ft size_t +.Fn __freadahead "FILE *stream" +.Ft int +.Fn __freading "FILE *stream" +.Ft const char * +.Fn __freadptr "FILE *stream" "size_t *sizep" +.Ft void +.Fn __freadptrinc "FILE *stream" "size_t increment" +.Ft void +.Fn __fseterr "FILE *stream" +.Ft int +.Fn __fwriting "FILE *stream" +.Sh DESCRIPTION +The +.Fn __fpending +function returns the number of bytes of output data currently +buffered on +.Fa stream . +.Pp +The +.Fn __freadahead +function returns the number of bytes of input data currently +buffered on +.Fa stream . +.Pp +The +.Fn __freading +function returns non-zero if +.Fa stream +either was opened read-only or if the last operation on the stream +was a read or push-back operation. +.Pp +The +.Fn __freadptr +function returns either a pointer to the next byte of buffered input +data on +.Fa stream +and stores the number of consecutive bytes of buffered data available +to the location pointed to by +.Fa sizep , +or return +.Dv NULL +if there's no buffered input data. +The value returned via +.Fa sizep +may differ from the value that would be returned by +.Fn __freadahead . +.Pp +The +.Fn __freadptrinc +function consumes +.Fa increment +bytes of buffered input data on +.Fa stream . +This is only valid immediately after a non-NULL return from +.Fn __freadptr +and +.Fa increment +must not be greater than the size value from that call. +.Pp +The +.Fn __fseterr +function sets the error indicator for +.Fa stream . +.Pp +The +.Fn __fwriting +function returns non-zero if +.Fa stream +either was opened write-only or append-only or if the last operation +on the stream was a write operation. +.Sh ERRORS +These functions should not fail and do not set the external +variable +.Va errno . +.Sh SEE ALSO +.Xr fflush 3 +.Sh HISTORY +The +.Fn __fpending , +.Fn __freadahead , +.Fn __freading , +.Fn __freadptr , +.Fn __freadptrinc , +.Fn __fseterr , +and +.Fn __fwriting +functions appeared in +.Ox 7.6 . +.Sh BUGS +These functions are under-specified and non-portable. +They exist to permit a particular +.Dq portability +library to function without direct manipulation of stdio structures; +everyone else should either implement their own stdio layer, +do the work of defining and standardizing the required functionality, +or reconsider their life decisions. diff --git a/static/openbsd/man3/__tfork_thread.3 b/static/openbsd/man3/__tfork_thread.3 new file mode 100644 index 00000000..714895fa --- /dev/null +++ b/static/openbsd/man3/__tfork_thread.3 @@ -0,0 +1,142 @@ +.\" $OpenBSD: __tfork_thread.3,v 1.4 2016/05/11 21:52:49 deraadt Exp $ +.\" +.\" Copyright (c) 2011 Philip Guenther +.\" +.\" 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 11 2016 $ +.Dt __TFORK_THREAD 3 +.Os +.Sh NAME +.Nm __tfork_thread , +.Nm __tfork +.Nd create a new kernel thread in the current process +.Sh SYNOPSIS +.In unistd.h +.Bd -literal +struct __tfork { + void *tf_tcb; /* TCB address for new thread */ + pid_t *tf_tid; /* where to write child's thread ID */ + void *tf_stack; /* stack address for new thread */ +}; +.Ed +.Pp +.Ft pid_t +.Fn __tfork_thread "const struct __tfork *params" "size_t psize" "void (*startfunc)(void *)" "void *startarg" +.Ft pid_t +.Fn __tfork "const struct __tfork *params" "size_t psize" +.Sh DESCRIPTION +The +.Fn __tfork_thread +function creates a new kernel thread in the current process. +The new thread starts by calling +.Fa startfunc , +passing +.Fa startarg +as the only argument. +If +.Fa startfunc +returns, the thread will exit. +.Pp +The +.Fa params +argument provides parameters used by the kernel during thread creation. +The new thread's thread control block (TCB) address is set to +.Em tf_tcb . +If +.Em tf_tid +is not NULL, the new thread's thread ID is returned to the user at that +address, with the guarantee that this is done before returning to +userspace in either the calling thread or the new thread. +If +.Em tf_stack +is not NULL, the new thread's stack is initialized to start at that address. +On hppa that is the lowest address used; +on other architectures that is the address after the highest address used. +.Pp +The +.Fa psize +argument provides the size of the +.Vt "struct __tfork" +passed via the +.Fa params +argument. +.Pp +The underlying system call used to create the thread is +.Fn __tfork . +Because the new thread returns without a stack frame, +the syscall cannot be directly used from C and is therefore not +provided as a function. +However, the syscall may show up in the output of +.Xr kdump 1 . +.Sh RETURN VALUES +Upon successful completion, +.Fn __tfork_thread +returns in the calling thread the thread ID of new thread. +The +.Fn __tfork +syscall itself, on success, returns a value of 0 in the new thread +and returns the thread ID of the new thread to the calling thread. +Otherwise, a value of -1 is returned, no thread is created, and the +global variable +.Va errno +is set to indicate an error. +.Sh ERRORS +.Fn __tfork_thread +and +.Fn __tfork +will fail and no thread will be created if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Cannot allocate memory. +The new process image required more memory than was allowed by the hardware or +by system-imposed memory management constraints. +A lack of swap space is normally temporary; however, a lack of core is not. +Soft limits may be increased to their corresponding hard limits. +.It Bq Er EINVAL +Invalid argument. +Some invalid argument was supplied. +.It Bq Er EAGAIN +Resource temporarily unavailable. +The system-imposed limit on the total +number of threads under execution would be exceeded. +This limit is configuration-dependent. +.It Bq Er EAGAIN +Resource temporarily unavailable. +The system-imposed limit +.Dv MAXUPRC +on the total number of threads under execution by a single user would be +exceeded. +.Dv MAXUPRC +is currently defined in +.In sys/param.h +as +.Dv CHILD_MAX , +which is currently defined as 80 in +.In sys/syslimits.h . +.El +.Sh STANDARDS +The +.Fn __tfork_thread +function and +.Fn __tfork +syscall are specific to +.Ox +and should not be used in portable applications. +.Sh HISTORY +The +.Fn __tfork_thread +function and +.Fn __tfork +syscall appeared in +.Ox 5.1 . diff --git a/static/openbsd/man3/a2d_ASN1_OBJECT.3 b/static/openbsd/man3/a2d_ASN1_OBJECT.3 new file mode 100644 index 00000000..ed5e7b21 --- /dev/null +++ b/static/openbsd/man3/a2d_ASN1_OBJECT.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: a2d_ASN1_OBJECT.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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 $Mdocdate: June 8 2025 $ +.Dt A2D_ASN1_OBJECT 3 +.Os +.Sh NAME +.Nm a2d_ASN1_OBJECT +.Nd DER content octets of an ASN.1 object identifier +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo a2d_ASN1_OBJECT +.Fa "unsigned char *der_out" +.Fa "int olen" +.Fa "const char *val_in" +.Fa "int ilen" +.Fc +.Sh DESCRIPTION +.Fn a2d_ASN1_OBJECT +accepts an ASCII string +.Fa val_in +of +.Fa ilen +bytes and interprets it as the numerical form of an ASN.1 object identifier. +It writes the content octets of the DER encoding of the object identifier +to the buffer +.Fa der_out +which is +.Fa olen +bytes long. +The identifier and length octets of the DER encoding are not written. +.Pp +If +.Fa ilen +is \-1, the +.Xr strlen 3 +of +.Fa val_in +is used instead. +.Pp +If +.Fa der_out +is a +.Dv NULL +pointer, writing the content octets is skipped +and only the return value is calculated. +.Sh RETURN VALUES +.Fn a2d_ASN1_OBJECT +returns the number of content octets that were or would be written or 0 if +.Fa ilen +is 0, if +.Fa val_in +is not a valid representation of an object identifier, +if memory allocation fails, or if the number of content octets +would be larger than +.Fa olen . +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr i2d_ASN1_OBJECT 3 , +.Xr OBJ_create 3 +.Sh STANDARDS +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules: +Specification of Basic Encoding Rules (BER), Canonical Encoding +Rules (CER) and Distinguished Encoding Rules (DER), +section 8.19: Encoding of an object identifier value +.Sh HISTORY +.Fn a2d_ASN1_OBJECT +first appeared in SSLeay 0.8.0 and has been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/a2i_ipadd.3 b/static/openbsd/man3/a2i_ipadd.3 new file mode 100644 index 00000000..1fea5e1a --- /dev/null +++ b/static/openbsd/man3/a2i_ipadd.3 @@ -0,0 +1,137 @@ +.\" $OpenBSD: a2i_ipadd.3,v 1.2 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2024 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 $Mdocdate: June 8 2025 $ +.Dt A2I_IPADD 3 +.Os +.Sh NAME +.Nm a2i_ipadd , +.Nm a2i_IPADDRESS , +.Nm a2i_IPADDRESS_NC +.Nd parse Internet Protocol addresses into ASN.1 OCTET STRINGs for X.509 +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft int +.Fo a2i_ipadd +.Fa "unsigned char *ipout" +.Fa "const char *ipasc" +.Fc +.Ft ASN1_OCTET_STRING * +.Fo a2i_IPADDRESS +.Fa "const char *ipasc" +.Fc +.Ft ASN1_OCTET_STRING * +.Fo a2i_IPADDRESS_NC +.Fa "const char *ipasc" +.Fc +.Sh DESCRIPTION +.Fn a2i_ipadd +and +.Fn a2i_IPADDRESS +parse the string +.Fa ipasc +containing an IPv4 or IPv6 address +in one of the following formats: +.Bd -literal -offset indent +d.d.d.d +x:x:x:x:x:x:x:x (exactly 8 words) +(x:)*x::x(:x)* (less than 8 words) +(x:)*x:: (less than 8 words) +::x(:x)* (less than 8 words) +:: +(x:)*d.d.d.d (up to 6 hexadecimal words, :: can be used) +.Ed +.Pp +where each +.Ar d +represents a non-negative decimal number less than 256 +with one, two or three digits and each +.Ar x +represents a non-negative hexadecimal number +with one, two, three, or four digits. +Both the lower case letters a-f and the upper case letters A-F can be used. +.Pp +.Fn a2i_ipadd +stores the bytes of the address in network byte order (big endian) starting at +.Fa ipout . +The caller is responsible for providing sufficient space; +always providing a buffer of at least 16 bytes is recommended, +even if an IPv4 address is expected, to avoid buffer overruns in case +.Fa ipasc +is malformed. +.Pp +.Fn a2i_IPADDRESS +stores the address in a newly allocated ASN.1 +.Vt OCTET STRING . +.Pp +.Fn a2i_IPADDRESS_NC +expects +.Fa ipasc +to contain two addresses of the same address family in the above form, +separated by a slash +.Pq Sq / +character, and stores the concatenation of both addresses +in a newly allocated ASN.1 +.Vt OCTET STRING , +which is typically used for address/mask pairs +in name constraint extensions of CA certificates. +.Sh RETURN VALUES +.Fn a2i_ipadd +returns the number of bytes written to +.Fa ipout +in case of success, i.e. 4 for an IPv4 or 16 for an IPv6 address, +or 0 if parsing failed. +.Pp +.Fn a2i_IPADDRESS +and +.Fn a2i_IPADDRESS_NC +return the new object or +.Dv NULL +if parsing or memory allocation failed. +.Sh SEE ALSO +.Xr a2i_ASN1_STRING 3 , +.Xr ASN1_OCTET_STRING_new 3 , +.Xr ASN1_OCTET_STRING_set 3 , +.Xr GENERAL_NAME_new 3 , +.Xr IPAddressRange_new 3 , +.Xr NAME_CONSTRAINTS_new 3 , +.Xr s2i_ASN1_OCTET_STRING 3 , +.Xr X509_EXTENSION_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Bl -dash -width 1n -compact +.It +section 4.2.1.6: Subject Alternative Name +.It +section 4.2.1.10: Name Constraints +.El +.Sh HISTORY +.Fn a2i_IPADDRESS +and +.Fn a2i_IPADDRESS_NC +first appeared in OpenSSL 0.9.8 and +.Fn a2i_ipadd +in OpenSSL 0.9.8e. +They have been available since +.Ox 4.5 . +.Sh CAVEATS +While some syntax errors are caught, only minimal validation takes place, +and these functions often return objects that make no sense, in particular +in the context of IPv6. +For example, the trailing :d.d.d.d syntax can be appended +to a hexadecimal part that results in twelve arbitrary bytes. diff --git a/static/openbsd/man3/a64l.3 b/static/openbsd/man3/a64l.3 new file mode 100644 index 00000000..c34af99c --- /dev/null +++ b/static/openbsd/man3/a64l.3 @@ -0,0 +1,133 @@ +.\" $OpenBSD: a64l.3,v 1.13 2019/01/25 00:19:25 millert Exp $ +.\" +.\" Copyright (c) 1997 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. +.\" +.Dd $Mdocdate: January 25 2019 $ +.Dt A64L 3 +.Os +.Sh NAME +.Nm a64l , +.Nm l64a +.Nd convert between 32-bit integer and radix-64 ASCII string +.Sh SYNOPSIS +.In stdlib.h +.Ft long +.Fn a64l "const char *s" +.Ft char * +.Fn l64a "long l" +.Sh DESCRIPTION +The +.Fn a64l +and +.Fn l64a +functions are used to maintain numbers stored in radix-64 +.Tn ASCII +characters. +This is a notation by which 32-bit integers +can be represented by up to six characters; each character represents a +.Dq digit +in a radix-64 notation. +.Pp +The characters used to represent digits are +.Ql \&. +for 0, +.Ql / +for 1, +.Ql 0 +through +.Ql 9 +for 2-11, +.Ql A +through +.Ql Z +for 12-37, and +.Ql a +through +.Ql z +for 38-63. +.Pp +The +.Fn a64l +function takes a pointer to a NUL-terminated radix-64 representation +and returns a corresponding 32-bit value. +If the string pointed to by +.Fa s +contains more than six characters, +.Fn a64l +will use the first six. +.Fn a64l +scans the character string from left to right, decoding +each character as a 6-bit radix-64 number. +If a long integer is +larger than 32 bits, the return value will be sign-extended. +.Pp +.Fn l64a +takes a long integer argument +.Fa l +and returns a pointer to the corresponding radix-64 representation. +.Sh RETURN VALUES +On success, +.Fn a64l +returns a 32-bit representation of +.Fa s . +If +.Fa s +is a null pointer or if it contains digits other than those described above, +.Fn a64l +returns \-1 and sets the global variable +.Va errno +to +.Er EINVAL . +.Pp +On success, +.Fn l64a +returns a pointer to a string containing the radix-64 representation of +.Fa l . +If +.Fa l +is 0, +.Fn l64a +returns a pointer to the empty string. +If +.Fa l +is negative, +.Fn l64a +returns a null pointer and sets the global variable +.Va errno +to +.Er EINVAL . +.Sh STANDARDS +The +.Fn a64l +and +.Fn l64a +functions conform to +.St -xpg4.2 . +.Sh CAVEATS +The value returned by +.Fn l64a +is a pointer into a static buffer, the contents of which +will be overwritten by subsequent calls. +.Pp +The value returned by +.Fn a64l +may be incorrect if the value is too large; for that reason, only strings +that resulted from a call to +.Fn l64a +should be used to call +.Fn a64l . +.Pp +If a long integer is larger than 32 bits, only the low-order +32 bits are used. diff --git a/static/openbsd/man3/abort.3 b/static/openbsd/man3/abort.3 new file mode 100644 index 00000000..2f15cd82 --- /dev/null +++ b/static/openbsd/man3/abort.3 @@ -0,0 +1,77 @@ +.\" 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. +.\" +.\" $OpenBSD: abort.3,v 1.11 2014/05/14 21:54:20 tedu Exp $ +.\" +.Dd $Mdocdate: May 14 2014 $ +.Dt ABORT 3 +.Os +.Sh NAME +.Nm abort +.Nd cause abnormal program termination +.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 +Some implementations may flush output streams before terminating. +This implementation does not. +.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 -p1003.1-90 . +.Sh HISTORY +The +.Fn abort +function first appeared in +.At v5 . +.Pp +Historically, previous standards required +.Fn abort +to flush and close output streams, but this conflicted with the requirement +that +.Fn abort +be async signal safe. +As a result, the flushing requirement was dropped. diff --git a/static/openbsd/man3/abs.3 b/static/openbsd/man3/abs.3 new file mode 100644 index 00000000..afacc985 --- /dev/null +++ b/static/openbsd/man3/abs.3 @@ -0,0 +1,75 @@ +.\" 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. +.\" +.\" $OpenBSD: abs.3,v 1.12 2019/01/18 07:32:17 schwarze Exp $ +.\" +.Dd $Mdocdate: January 18 2019 $ +.Dt ABS 3 +.Os +.Sh NAME +.Nm abs +.Nd integer absolute value function +.Sh SYNOPSIS +.In limits.h +.In stdlib.h +.Ft int +.Fn abs "int j" +.Sh DESCRIPTION +The +.Fn abs +function computes the absolute value of the integer +.Fa j . +.Sh RETURN VALUES +The +.Fn abs +function returns the absolute value. +.Sh SEE ALSO +.Xr cabs 3 , +.Xr floor 3 , +.Xr hypot 3 , +.Xr imaxabs 3 , +.Xr labs 3 +.Sh STANDARDS +The +.Fn abs +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn abs +function first appeared in +.At v6 . +.Sh CAVEATS +The result of applying +.Fn abs +to +.Dv INT_MIN +is undefined. diff --git a/static/openbsd/man3/acos.3 b/static/openbsd/man3/acos.3 new file mode 100644 index 00000000..8ec2c36b --- /dev/null +++ b/static/openbsd/man3/acos.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: acos.3,v 1.18 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ACOS 3 +.Os +.Sh NAME +.Nm acos , +.Nm acosf , +.Nm acosl +.Nd arc cosine functions +.Sh SYNOPSIS +.Lb libm +.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 +function computes the principal value of the arc cosine of +.Fa x +in the range +.Bq 0 , pi . +The +.Fn acosf +function is a single precision version of +.Fn acos . +The +.Fn acosl +function is an extended precision version of +.Fn acos . +.Sh RETURN VALUES +If |x|>1, +.Fn acos "x" , +.Fn acosf "x" +and +.Fn acosl "x" +set the global variable +.Va errno +to +.Er EDOM . +.Sh SEE ALSO +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 diff --git a/static/openbsd/man3/acosh.3 b/static/openbsd/man3/acosh.3 new file mode 100644 index 00000000..f3678c44 --- /dev/null +++ b/static/openbsd/man3/acosh.3 @@ -0,0 +1,83 @@ +.\" $OpenBSD: acosh.3,v 1.19 2025/06/07 10:33:06 schwarze 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. +.\" +.\" from: @(#)acosh.3 5.2 (Berkeley) 5/6/91 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ACOSH 3 +.Os +.Sh NAME +.Nm acosh , +.Nm acoshf , +.Nm acoshl +.Nd inverse hyperbolic cosine functions +.Sh SYNOPSIS +.Lb libm +.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 +function computes the inverse hyperbolic cosine +of the real +argument +.Fa x . +The +.Fn acoshf +function is a single precision version of +.Fn acosh . +The +.Fn acoshl +function is an extended precision version of +.Fn acosh . +.Sh RETURN VALUES +If +.Fa 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 . +.Sh SEE ALSO +.Xr asinh 3 , +.Xr atanh 3 , +.Xr exp 3 +.Sh HISTORY +The +.Fn acosh +function appeared in +.Bx 4.3 . diff --git a/static/openbsd/man3/agentx.3 b/static/openbsd/man3/agentx.3 new file mode 100644 index 00000000..db991285 --- /dev/null +++ b/static/openbsd/man3/agentx.3 @@ -0,0 +1,661 @@ +.\" $OpenBSD: agentx.3,v 1.11 2025/06/05 18:43:07 schwarze Exp $ +.\" +.\" Copyright (c) 2020 Martijn van Duren +.\" +.\" 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: June 5 2025 $ +.Dt AGENTX 3 +.Os +.Sh NAME +.Nm agentx_log_fatal , +.Nm agentx_log_warn , +.Nm agentx_log_info , +.Nm agentx_log_debug , +.Nm agentx , +.Nm agentx_connect , +.Nm agentx_retry , +.Nm agentx_read , +.Nm agentx_write , +.Nm agentx_wantwrite , +.Nm agentx_free , +.Nm agentx_session , +.Nm agentx_session_free , +.Nm agentx_context , +.Nm agentx_context_object_find , +.Nm agentx_context_object_nfind , +.Nm agentx_context_uptime , +.Nm agentx_context_free , +.Nm agentx_region , +.Nm agentx_region_free , +.Nm agentx_agentcaps , +.Nm agentx_agentcaps_free , +.Nm agentx_index_integer_new , +.Nm agentx_index_integer_any , +.Nm agentx_index_integer_value , +.Nm agentx_index_integer_dynamic , +.Nm agentx_index_string_dynamic , +.Nm agentx_index_nstring_dynamic , +.Nm agentx_index_oid_dynamic , +.Nm agentx_index_noid_dynamic , +.Nm agentx_index_ipaddress_dynamic , +.Nm agentx_index_free , +.Nm agentx_object , +.Nm agentx_object_free , +.Nm agentx_varbind_integer , +.Nm agentx_varbind_string , +.Nm agentx_varbind_nstring , +.Nm agentx_varbind_printf , +.Nm agentx_varbind_null , +.Nm agentx_varbind_oid , +.Nm agentx_varbind_object , +.Nm agentx_varbind_index , +.Nm agentx_varbind_ipaddress , +.Nm agentx_varbind_counter32 , +.Nm agentx_varbind_gauge32 , +.Nm agentx_varbind_unsigned32 , +.Nm agentx_varbind_timeticks , +.Nm agentx_varbind_opaque , +.Nm agentx_varbind_counter64 , +.Nm agentx_varbind_notfound , +.Nm agentx_varbind_error , +.Nm agentx_varbind_request , +.Nm agentx_varbind_get_index_integer , +.Nm agentx_varbind_get_index_string , +.Nm agentx_varbind_get_index_oid , +.Nm agentx_varbind_get_index_ipaddress , +.Nm agentx_varbind_set_index_integer , +.Nm agentx_varbind_set_index_string , +.Nm agentx_varbind_set_index_nstring , +.Nm agentx_varbind_set_index_oid , +.Nm agentx_varbind_set_index_object , +.Nm agentx_varbind_set_index_ipaddress +.Nd manage an interface to an agentx master +.Sh SYNOPSIS +.Lb libagentx +.In agentx.h +.Ft extern void +.Fn (*agentx_log_fatal) "const char *fmt" ... +.Ft extern void +.Fn (*agentx_log_warn) "const char *fmt" ... +.Ft extern void +.Fn (*agentx_log_info) "const char *fmt" ... +.Ft extern void +.Fn (*agentx_log_debug) "const char *fmt" ... +.Ft struct agentx * +.Fn agentx "void (*nofd)(struct agentx *, void *, int)" "void *cookie" +.Ft void +.Fn agentx_connect "struct agentx *sa" "int fd" +.Ft void +.Fn agentx_retry "struct agentx *sa" +.Ft void +.Fn agentx_read "struct agentx *sa" +.Ft void +.Fn agentx_write "struct agentx *sa" +.Ft extern void +.Fn (*agentx_wantwrite) "struct agentx *sa" "int fd" +.Ft void +.Fn agentx_free "struct agentx *sa" +.Ft struct agentx_session * +.Fo agentx_session +.Fa "struct agentx *sa" "uint32_t oid[]" "size_t oidlen" +.Fa "const char *descr" "uint8_t timeout" +.Fc +.Ft void +.Fn agentx_session_free "struct agentx_session *sas" +.Ft struct agentx_context * +.Fn agentx_context "struct agentx_session *sas" "const char *name" +.Ft struct agentx_object * +.Fo agentx_context_object_find +.Fa "struct agentx_context *sac" "const uint32_t oid[]" "size_t oidlen" +.Fa "int active" "int instance" +.Fc +.Ft struct agentx_object * +.Fo agentx_context_object_nfind +.Fa "struct agentx_context *" "const uint32_t oid[]" "size_t oidlen" +.Fa "int active" "int inclusive" +.Fc +.Ft uint32_t +.Fn agentx_context_uptime "struct agentx_context *sac" +.Ft void +.Fn agentx_context_free "struct agentx_context *sac" +.Ft struct agentx_agentcaps * +.Fo agentx_agentcaps +.Fa "struct agentx_context *sac" "uint32_t oid[]" "size_t oidlen" +.Fa "const char *descr" +.Fc +.Ft void +.Fn agentx_agentcaps_free "struct agentx_agentcaps *saa" +.Ft struct agentx_region * +.Fo agentx_region +.Fa "struct agentx_context *sac" "uint32_t oid[]" +.Fa "size_t oidlen" "uint8_t timeout" +.Fc +.Ft void +.Fn agentx_region_free "struct agentx_region *sar" +.Ft struct agentx_index * +.Fo agentx_index_integer_new +.Fa "struct agentx_region *sar" "uint32_t oid[]" "size_t oidlen" +.Fc +.Ft struct agentx_index * +.Fo agentx_index_integer_any +.Fa "struct agentx_region *sar" "uint32_t oid[]" "size_t oidlen" +.Fc +.Ft struct agentx_index * +.Fo agentx_index_integer_value +.Fa "struct agentx_region *sar" "uint32_t oid[]" "size_t oidlen" +.Fa "int32_t value" +.Fc +.Ft struct agentx_index * +.Fo agentx_index_integer_dynamic +.Fa "struct agentx_region *sar" "uint32_t oid[] "size_t oidlen" +.Fc +.Ft struct agentx_index * +.Fo agentx_index_string_dynamic +.Fa "struct agentx_region *sar" "uint32_t oid[]" "size_t oidlen" +.Fc +.Ft struct agentx_index * +.Fo agentx_index_nstring_dynamic +.Fa "struct agentx_region *sar" "uint32_t oid[]" "size_t oidlen" +.Fa "size_t slen" +.Fc +.Ft struct agentx_index * +.Fo agentx_index_oid_dynamic +.Fa "struct agentx_region *sar" "uint32_t oid[]" "size_t oidlen" +.Fc +.Ft struct agentx_index * +.Fo agentx_index_noid_dynamic +.Fa "struct agentx_region *sar" "uint32_t oid[]" "size_t oidlen" +.Fa "size_t vlen" +.Fc +.Ft struct agentx_index * +.Fo agentx_index_ipaddress_dynamic +.Fa "struct agentx_region *sar" "uint32_t oid[]" "size_t oidlen" +.Fc +.Ft void +.Fn agentx_index_free "struct agentx_index *sai" +.Ft struct agentx_object * +.Fo agentx_object +.Fa "struct agentx_region *sar" "uint32_t oid[]" "size_t oidlen" +.Fa "struct agentx_index *index[]" "size_t indexlen" "int implied" +.Fa "void (*getcb)(struct agentx_varbind *)" +.Fc +.Ft void +.Fn agentx_object_free "struct agentx_object *sao" +.Ft void +.Fn agentx_varbind_integer "struct agentx_varbind *sav" "int32_t value" +.Ft void +.Fn agentx_varbind_string "struct agentx_varbind *sav" "const char *value" +.Ft void +.Fo agentx_varbind_nstring +.Fa "struct agentx_varbind *sav" "const char *value" "size_t slen" +.Fc +.Ft void +.Fo agentx_varbind_printf +.Fa "struct agentx_varbind *sav" "const char *fmt" ... +.Fc +.Ft void +.Fn agentx_varbind_null "struct agentx_varbind *sav" +.Ft void +.Fo agentx_varbind_oid +.Fa "struct agentx_varbind *sav" "const uint32_t oid[]" "size_t oidlen" +.Fc +.Ft void +.Fo agentx_varbind_object +.Fa "struct agentx_varbind *sav" "struct agentx_object *sao" +.Fc +.Ft void +.Fo agentx_varbind_index +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" +.Fc +.Ft void +.Fo agentx_varbind_ipaddress +.Fa "struct agentx_varbind *sav" "const struct in_addr *addr" +.Fc +.Ft void +.Fn agentx_varbind_counter32 "struct agentx_varbind *sav" "uint32_t value" +.Ft void +.Fn agentx_varbind_gauge32 "struct agentx_varbind *sav" "uint32_t value" +.Ft void +.Fn agentx_varbind_unsigned32 "struct agentx_varbind *sav" "uint32_t value" +.Ft void +.Fo agentx_varbind_timeticks +.Fa "struct agentx_varbind *sav" "uint32_t value" +.Fc +.Ft void +.Fo agentx_varbind_opaque +.Fa "struct agentx_varbind *sav" "const char *value" "size_t slen" +.Fc +.Ft void +.Fn agentx_varbind_counter64 "struct agentx_varbind *sav" "uint64_t value" +.Ft void +.Fn agentx_varbind_notfound "struct agentx_varbind *sav" +.Ft void +.Fn agentx_varbind_error "struct agentx_varbind *sav" +.Ft enum agentx_request_type +.Fn agentx_varbind_request "struct agentx_varbind *sav" +.Ft int32_t +.Fo agentx_varbind_get_index_integer +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" +.Fc +.Ft const unsigned char * +.Fo agentx_varbind_get_index_string +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" "size_t *slen" +.Fa "int *implied" +.Fc +.Ft const uint32_t * +.Fo agentx_varbind_get_index_oid +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" +.Fa "size_t *oidlen" "int *implied" +.Fc +.Ft const struct in_addr * +.Fo agentx_varbind_get_index_ipaddress +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" +.Fc +.Ft void +.Fo agentx_varbind_set_index_integer +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" +.Fa "int32_t value" +.Fc +.Ft void +.Fo agentx_varbind_set_index_string +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" +.Fa "const unsigned char *value" +.Fc +.Ft void +.Fo agentx_varbind_set_index_nstring +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" +.Fa "const unsigned char *value" "size_t slen" +.Fc +.Ft void +.Fo agentx_varbind_set_index_oid +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" +.Fa "const uint32_t *oid" "size_t oidlen" +.Fc +.Ft void +.Fo agentx_varbind_set_index_object +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" +.Fa "struct agentx_object *sao" +.Fc +.Ft void +.Fo agentx_varbind_set_index_ipaddress +.Fa "struct agentx_varbind *sav" "struct agentx_index *sai" +.Fa "const struct in_addr *addr" +.Fc +.Bd -literal +enum agentx_request_type { + AGENTX_REQUEST_TYPE_GET, + AGENTX_REQUEST_TYPE_GETNEXT, + AGENTX_REQUEST_TYPE_GETNEXTINCLUSIVE +}; +.Ed +.Fd #define AGENTX_MASTER_PATH \(dq/var/agentx/master\(dq +.Fd #define AGENTX_OID_MAX_LEN 128 +.Fd #define AGENTX_OID_INDEX_MAX_LEN 10 +.Fd #define AGENTX_OID(...) +.Fd #define AGENTX_MIB2 1, 3, 6, 1, 2, 1 +.Fd #define AGENTX_ENTERPRISES 1, 3, 6, 1, 4, 1 +.Sh DESCRIPTION +The +.Nm agentx +functions allow an application to describe their MIB layout and provide an +.Fa fd +based interface to control the internal agentx state. +.Nm agentx +is not thread safe. +.Ss DESCRIBING THE MIB +.Nm agentx +is a framework to abstract away the agentx protocol from the application. +For the framework to report information to the administrator, the +.Fn agentx_log_fatal , +.Fn agentx_log_warn , +.Fn agentx_log_info +and +.Fn agentx_log_debug +functions must be set. +.Pp +When +.Fa sa +is created by +.Fn agentx +or when +.Fa sa +detects that there is no connection to the agentx master, it calls out to +.Fa nofd +with itself, +.Fa cookie +and an integer +.Fa close +as arguments. +If +.Fa close +is not set, +.Fn nofd +is expected to set up a new +.Fa fd +to the agentx master. +This one can usually be found at +.Dv AGENTX_MASTER_PATH . +This +.Fa fd +can be returned to +.Fa sa +at any moment via +.Fn agentx_connect , +but must always be done as a result of a call to +.Fn nofd . +Once +.Fn agentx_connect +has been called, +the application is responsible for retrieving data when available +on +.Fa fd +by calling +.Fn agentx_read . +If nonblocking writes are desirable, the +.Fn agentx_wantwrite +pointer can be set to an application function and will be called as soon as +there's data available to be written out. +Once +.Fa fd +is ready for a write, the function +.Fn agentx_write +should be called. +.Pp +If any of the session, agentcaps, region, index, or objects failed to enable +correctly +.Pq as can be seen by the admin through the logs +they can be retried through +.Fn agentx_retry . +.Pp +.Fa sa +can be freed via +.Fn agentx_free . +It will close all active sessions and free all derived objects. +Once freed, no new objects can be derived from the freed objects. +Once all sessions are closed, it will call out to +.Fn nofd +with +.Fa close +set, indicating that the application can clean up any context related to +.Fa sa . +.Pp +On top of the +.Fa sa +connection a +.Vt agentx_session +must be set up. +Normally there's only a single session per +.Fa sa . +The +.Fa timeout +argument specifies the maximum time in seconds the master should wait for a +reply before determining we're gone. +If set to 0, the agentx master determines the timeout. +The +.Fa oid +and +.Fa oidlen +combination identifies the subagent and will be visible through the +agentxSessionObjectID object on the agentx master. +The +.Fa descr +is a short displaystring description of the agent and will be visible through +the agentxSessionDescr object on the agentx master. +.Pp +The +.Vt agentx_context +is the SNMPv3 context in which the objects operate and is built on top of +agentx_session +.Fa sas . +If the default context is requested, +.Fa name +must be NULL. +.Pp +.Fn agentx_agentcaps +registers an entry in the agentx master's sysORTable. +The +.Fa oid , +.Fa oidlen +combination should point to an AGENT-CAPABILITIES object which describes the +capabilities of the subagent. +.Fa descr +should be a textual description of the capabilities. +If no AGENT-CAPABILITIES object is defined, this function can be omitted. +.Pp +A +.Vt agentx_region +indicates a region inside the object-tree for which get- and set-requests will +be queried. +If the OID has already been claimed by another subagent, it will try to claim it +on a lower priority. +The +.Fa timeout +parameter overrules its +.Vt agentx_session +counterpart. +.Pp +For objects in a table one or more +.Ft agentx_index +elements must be supplied. +.Fn agentx_index_integer_new , +.Fn agentx_index_integer_any +and +.Fn agentx_index_integer_value +register an integer index at the agentx master. +Of these +.Fn agentx_index_integer_new +registers a new, previously unused, index; +.Fn agentx_index_integer_any +registers the first available index; +and +.Fn agentx_index_integer_value +tries to register a specific value. +If the registration of an index fails, an error will be logged and all objects +using it will remain disabled. +The OID where the index should be registered is documented by the MIB. +These registered indices are usually used for tables where multiple subagents +are registered. +.Pp +For dynamic indices the agentx_index_*_dynamic functions can be used, based +on the data type of the object. +The data type should match the data type in the MIB at the +.Fa oid +object. +Indices of data type string or oid with a fixed length should be created via +.Fn agentx_index_nstring_dynamic +and +.Fn agentx_index_noid_dynamic +respectively. +.Pp +.Vt agentx_object +is an object as described in the MIB. +For scalar objects +.Pq without indices +the final zero must be omitted. +For table entries a list of 1 or more indices must be added via +.Fa index +and +.Fa indexlen . +The list of indices must match the INDEX list on the ENTRY object in the MIB. +The total length of the OID, including indices, can't be more than +.Dv AGENTX_OID_MAX_LEN +and indexlen can't be more than +.Dv AGENTX_OID_INDEX_MAX_LEN . +If +.Fa implied +is set, the final index must be of type OID or string and will omit the leading +length indicator. +This value must only be set if specified in the MIB. +.Fn getcb +will be called for each varbind in a GET, GETNEXT or GETBULK request that +matches the object. +.Ss HANDLING GET REQUESTS +A call to +.Fn getcb +must eventually result in a call to one of the following functions: +.Bl -tag -width agentx_varbind_counter32() +.It Fn agentx_varbind_integer +Set the return value to an int32_t value. +.It Fn agentx_varbind_string +A C string wrapper around +.Fn agentx_varbind_nstring . +.It Fn agentx_varbind_nstring +Set the return value to an octetstring. +.It Fn agentx_varbind_printf +A printf wrapper around +.Fn agentx_varbind_nstring . +.It Fn agentx_varbind_null +Set the return value to null. +.It Fn agentx_varbind_oid +Set the return value to an OID value. +.It Fn agentx_varbind_object +An agentx_object wrapper around +.Fn agentx_varbind_oid . +.It Fn agentx_varbind_index +An agentx_index wrapper around +.Fn agentx_varbind_oid . +.It Fn agentx_varbind_ipaddress +Set the return value to ipaddress. +.It Fn agentx_varbind_counter32 +Set the return value to an uint32_t of type counter32. +.It Fn agentx_varbind_gauge32 +Set the return value to an uint32_t of type gauge32. +.It Fn agentx_varbind_unsigned32 +A wrapper around agentx_varbind_gauge32. +.It Fn agentx_varbind_timeticks +Set the return value to an uint32_t of type timeticks. +.It Fn agentx_varbind_opaque +Set the return value to an opaque value. +.It Fn agentx_varbind_counter64 +Set the return value to an uint64_t of type counter64. +.It Fn agentx_varbind_notfound +When the request is of type GET, return a nosuchinstance error. +When the request is of type GETNEXT or GETBULK, return an endofmibview error. +On endofmibview the next object is queried. +This function can only be called on objects that contain one or more *_dynamic +indices. +.It Fn agentx_varbind_error +Returns a GENERR error to the client. +.El +.Pp +For objects containing *_dynamic indices the following support functions are to +be used: +.Bl -tag -width Ds +.It Fn agentx_varbind_request +Returns whether the request is of type GET, GETNEXT or GETNEXTINCLUSIVE. +.It Fn agentx_varbind_get_index_integer +Retrieve a single int32_t index value. +.It Fn agentx_varbind_get_index_string +Retrieve an octetstring index value. +.Fa slen +is the length of the string and +.Fa implied +indicates if the next value for this index should be length sorted before +alphabetically sorted. +.It Fn agentx_varbind_get_index_oid +Retrieve an oid index value. +.Fa oidlen +is the length of the oid and +.Fa implied +indicates if the next value for this index should be length sorted before +alphabetically sorted. +.It Fn agentx_varbind_get_index_ipaddress +Retrieve an ipaddress index value. +.It Fn agentx_varbind_set_index_integer +Sets a single int32_t index value. +.It Fn agentx_varbind_set_index_string +A C string wrapper around +.Fn agentx_varbind_set_index_nstring . +.It Fn agentx_varbind_set_index_nstring +Set an octetstring index value. +.It Fn agentx_varbind_set_index_oid +Set an oid index value. +.It Fn agentx_varbind_set_index_object +A agentx_object wrapper around +.Fn agentx_varbind_set_index_oid . +.It Fn agentx_varbind_set_index_ipaddress +Set an ipaddress index value. +.El +.Pp +For these functions +.Fa sai +must be part of the object the request is performed on. +The function type must also match the data type of +.Fa sai . +.Pp +Other functions that can retrieve information from the agentx context are: +.Bl -tag -width Ds +.It Fn agentx_context_object_find +Find an agentx_object created inside agentx_context +.Fa sac +based on +.Fa oid +and +.Fa oidlen . +If +.Fa active +is set the object must be reachable from the agentx master, else NULL is +returned. +If +.Fa oid +can be an instance, find its parent object. +.It Fn agentx_context_object_nfind +Find the next agentx_object created inside agentx_context +.Fa sac +based on +.Fa oid +and +.Fa oidlen . +If +.Fa active +is set the object must be reachable from the agentx master, else NULL is +returned. +If +.Fa inclusive +is set, the object returned may also exactly match +.Fa oid . +.It Fn agentx_context_uptime +Returns the sysuptime in seconds for +.Fa sac +in timeticks. +.El +.Sh SEE ALSO +.Xr snmp 1 , +.Xr snmpd 8 +.Sh STANDARDS +.Rs +.%A M. Daniele +.%A B. Wijnen +.%A M. Ellison, Ed. +.%A D. Francisco, Ed. +.%D January 2000 +.%R RFC 2741 +.%T Agent Extensibility (AgentX) Protocol Version 1 +.Re +.Pp +.Rs +.%A L. Heintz +.%A S. Gudur +.%A M. Ellison, Ed. +.%D January 2000 +.%R RFC 2742 +.%T Definitions of Managed Objects for Extensible SNMP Agents +.Re +.Sh HISTORY +The +.Nm agentx +API first appeared in +.Ox 6.9 . +.Sh AUTHORS +.An Martijn van Duren Aq Mt martijn@openbsd.org diff --git a/static/openbsd/man3/alarm.3 b/static/openbsd/man3/alarm.3 new file mode 100644 index 00000000..b4aa10bf --- /dev/null +++ b/static/openbsd/man3/alarm.3 @@ -0,0 +1,108 @@ +.\" $OpenBSD: alarm.3,v 1.17 2022/08/02 01:23:23 jsg 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. +.\" +.Dd $Mdocdate: August 2 2022 $ +.Dt ALARM 3 +.Os +.Sh NAME +.Nm alarm +.Nd schedule SIGALRM delivery +.Sh SYNOPSIS +.In unistd.h +.Ft unsigned int +.Fn alarm "unsigned int seconds" +.Sh DESCRIPTION +.Bf -symbolic +This is a simplified interface to +.Xr setitimer 2 . +.Ef +.Pp +The +.Fn alarm +function schedules the +.Dv SIGALRM +signal for delivery to the calling process after the given number of +.Fa seconds +have elapsed. +.Pp +If an alarm is already pending, +another call to +.Fn alarm +will supersede the prior call. +.Pp +If +.Fa seconds +is zero, +any pending alarm is cancelled. +.Sh RETURN VALUES +.Fn alarm +returns the number of seconds remaining until the pending alarm would have +expired. +If the alarm has already expired, +the alarm was cancelled, +or no alarm was ever scheduled, +.Fn alarm +returns zero. +.Sh SEE ALSO +.Xr setitimer 2 , +.Xr sigaction 2 , +.Xr sigsuspend 2 , +.Xr signal 3 , +.Xr sleep 3 , +.Xr ualarm 3 +.Sh STANDARDS +The +.Fn alarm +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +An +.Fn alarm +system call first appeared outside of Bell Labs in the +.Dq 50 changes +tape for +.At v6 . +It was first officially released with PWB/UNIX 1.0. +For +.Bx 4.1c , +it was reimplemented as a wrapper around the +.Xr setitimer 2 +system call. +.Sh CAVEATS +The +.Fn alarm +function is implemented with the per-process +.Dv ITIMER_REAL +timer described in +.Xr setitimer 2 . +Use of both +.Fn alarm +and +.Xr setitimer 2 +in the same program may yield confusing behavior. diff --git a/static/openbsd/man3/alloca.3 b/static/openbsd/man3/alloca.3 new file mode 100644 index 00000000..5252ba58 --- /dev/null +++ b/static/openbsd/man3/alloca.3 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1980, 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. +.\" +.\" $OpenBSD: alloca.3,v 1.14 2015/01/17 18:01:43 tedu Exp $ +.\" +.Dd $Mdocdate: January 17 2015 $ +.Dt ALLOCA 3 +.Os +.Sh NAME +.Nm alloca +.Nd memory allocator +.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. +.Sh SEE ALSO +.Xr pagesize 1 , +.Xr brk 2 , +.Xr malloc 3 +.\" .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... +.Sh CAVEATS +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. +Avoid +.Fn alloca +with large unbounded allocations. diff --git a/static/openbsd/man3/arc4random.3 b/static/openbsd/man3/arc4random.3 new file mode 100644 index 00000000..411860c2 --- /dev/null +++ b/static/openbsd/man3/arc4random.3 @@ -0,0 +1,116 @@ +.\" $OpenBSD: arc4random.3,v 1.37 2019/09/29 16:30:35 jmc Exp $ +.\" +.\" Copyright 1997 Niels Provos +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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 Niels Provos. +.\" 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. +.\" +.\" Manual page, using -mandoc macros +.\" +.Dd $Mdocdate: September 29 2019 $ +.Dt ARC4RANDOM 3 +.Os +.Sh NAME +.Nm arc4random , +.Nm arc4random_buf , +.Nm arc4random_uniform +.Nd random number generator +.Sh SYNOPSIS +.In stdlib.h +.Ft uint32_t +.Fn arc4random "void" +.Ft void +.Fn arc4random_buf "void *buf" "size_t nbytes" +.Ft uint32_t +.Fn arc4random_uniform "uint32_t upper_bound" +.Sh DESCRIPTION +This family of functions provides higher quality data than those +described in +.Xr rand 3 , +.Xr random 3 , +and +.Xr rand48 3 . +.Pp +Use of these functions is encouraged for almost all random number +consumption because the other interfaces are deficient in either +quality, portability, standardization, or availability. +These functions can be called in almost all coding environments, +including +.Xr pthreads 3 +and +.Xr chroot 2 . +.Pp +High quality 32-bit pseudo-random numbers are generated very quickly. +On each call, a cryptographic pseudo-random number generator is used +to generate a new result. +One data pool is used for all consumers in a process, so that consumption +under program flow can act as additional stirring. +The subsystem is re-seeded from the kernel +.Xr random 4 +subsystem using +.Xr getentropy 2 +on a regular basis, and also upon +.Xr fork 2 . +.Pp +The +.Fn arc4random +function returns a single 32-bit value. +.Pp +.Fn arc4random_buf +fills the region +.Fa buf +of length +.Fa nbytes +with random data. +.Pp +.Fn arc4random_uniform +will return a single 32-bit value, uniformly distributed but less than +.Fa upper_bound . +This is recommended over constructions like +.Dq Li arc4random() % upper_bound +as it avoids "modulo bias" when the upper bound is not a power of two. +In the worst case, this function may consume multiple iterations +to ensure uniformity; see the source code to understand the problem +and solution. +.Sh RETURN VALUES +These functions are always successful, and no return value is +reserved to indicate an error. +.Sh SEE ALSO +.Xr rand 3 , +.Xr rand48 3 , +.Xr random 3 +.Sh HISTORY +These functions first appeared in +.Ox 2.1 . +.Pp +The original version of this random number generator used the +RC4 (also known as ARC4) algorithm. +In +.Ox 5.5 +it was replaced with the ChaCha20 cipher, and it may be replaced +again in the future as cryptographic techniques advance. +A good mnemonic is +.Dq A Replacement Call for Random . diff --git a/static/openbsd/man3/asin.3 b/static/openbsd/man3/asin.3 new file mode 100644 index 00000000..bdf577b8 --- /dev/null +++ b/static/openbsd/man3/asin.3 @@ -0,0 +1,84 @@ +.\" $OpenBSD: asin.3,v 1.18 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ASIN 3 +.Os +.Sh NAME +.Nm asin , +.Nm asinf , +.Nm asinl +.Nd arc sine functions +.Sh SYNOPSIS +.Lb libm +.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 +function computes the principal value of the arc sine of +.Fa x +in the range +.Bk -words +.Bq -pi/2, +pi/2 . +.Ek +The +.Fn asinf +function is a single precision version of +.Fn asin . +The +.Fn asinl +function is an extended precision version of +.Fn asin . +.Sh RETURN VALUES +If |x|>1, +.Fn asin "x" , +.Fn asinf "x" +and +.Fn asinl "x" +return NaN and set the global variable +.Va errno +to +.Er EDOM . +.Sh SEE ALSO +.Xr acos 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 diff --git a/static/openbsd/man3/asinh.3 b/static/openbsd/man3/asinh.3 new file mode 100644 index 00000000..21bec477 --- /dev/null +++ b/static/openbsd/man3/asinh.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: asinh.3,v 1.17 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ASINH 3 +.Os +.Sh NAME +.Nm asinh , +.Nm asinhf , +.Nm asinhl +.Nd inverse hyperbolic sine functions +.Sh SYNOPSIS +.Lb libm +.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 +function computes the inverse hyperbolic sine +of the real argument. +The +.Fn asinhf +function is a single precision version of +.Fn asinh . +The +.Fn asinhl +function is an extended precision version of +.Fn asinh . +.Sh RETURN VALUES +The +.Fn asinh , +.Fn asinhf +and +.Fn asinhl +functions return the inverse hyperbolic sine of +.Fa x . +.Sh SEE ALSO +.Xr acosh 3 , +.Xr atanh 3 , +.Xr exp 3 +.Sh HISTORY +The +.Fn asinh +function appeared in +.Bx 4.3 . diff --git a/static/openbsd/man3/asr_run.3 b/static/openbsd/man3/asr_run.3 new file mode 100644 index 00000000..d9b3282f --- /dev/null +++ b/static/openbsd/man3/asr_run.3 @@ -0,0 +1,335 @@ +.\" $OpenBSD: asr_run.3,v 1.5 2022/03/31 17:27:15 naddy Exp $ +.\" +.\" Copyright (c) 2012-2014, Eric Faurot +.\" +.\" 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: March 31 2022 $ +.Dt ASR_RUN 3 +.Os +.Sh NAME +.Nm asr_run , +.Nm asr_run_sync , +.Nm asr_abort , +.Nm asr_resolver_from_string , +.Nm asr_resolver_free , +.Nm res_send_async , +.Nm res_query_async , +.Nm res_search_async , +.Nm getrrsetbyname_async , +.Nm gethostbyname_async , +.Nm gethostbyname2_async , +.Nm gethostbyaddr_async , +.Nm getnetbyname_async , +.Nm getnetbyaddr_async , +.Nm getaddrinfo_async , +.Nm getnameinfo_async +.Nd asynchronous resolver functions +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netdb.h +.In asr.h +.Ft int +.Fn asr_run "struct asr_query *aq" "struct asr_result *ar" +.Ft int +.Fn asr_run_sync "struct asr_query *aq" "struct asr_result *ar" +.Ft void +.Fn asr_abort "struct asr_query *aq" +.Ft void * +.Fn asr_resolver_from_string "const char *str" +.Ft void +.Fn asr_resolver_free "void *asr" +.Ft struct asr_query * +.Fn res_send_async "const unsigned char *pkt" "int pktlen" "void *asr" +.Ft struct asr_query * +.Fn res_query_async "const char *name" "int class" "int type" "void *asr" +.Ft struct asr_query * +.Fn res_search_async "const char *name" "int class" "int type" "void *asr" +.Ft struct asr_query * +.Fn getrrsetbyname_async "const char *hostname" "unsigned int rdclass" "unsigned int rdtype" "unsigned int flags" "void *asr" +.Ft struct asr_query * +.Fn gethostbyname_async "const char *name" "void *asr" +.Ft struct asr_query * +.Fn gethostbyname2_async "const char *name" "int af" "void *asr" +.Ft struct asr_query * +.Fn gethostbyaddr_async "const void *addr" "socklen_t len" "int af" "void *asr" +.Ft struct asr_query * +.Fn getnetbyname_async "const char *name" "void *asr" +.Ft struct asr_query * +.Fn getnetbyaddr_async "in_addr_t net" "int type" "void *asr" +.Ft struct asr_query * +.Fn getaddrinfo_async "const char *hostname" "const char *servname" "const struct addrinfo *hints" "void *asr" +.Ft struct asr_query * +.Fn getnameinfo_async "const struct sockaddr *sa" "socklen_t salen" "char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags" "void *asr" +.Sh DESCRIPTION +The +.Nm asr +functions provide a simple interface for asynchronous address +resolution and nameserver querying. +They should be used in place of the classical resolver functions +of libc when blocking is not desirable. +.Pp +The principle of operation is as follows: +All async requests are made against an +.Nm asr +context which basically defines a list of sources to query and a +strategy to do so. +The user creates a query through one of the dedicated functions, and +gets a handle representing the internal query. +A query is a state-machine that can be run to try to fulfill a +particular request. +This is done by calling in a generic API that performs the state +transitions until it needs to give the control back to the user, +either because a result is available, or because the next transition +implies a blocking call (a file descriptor needs to be read from or +written to). +The user is responsible for dealing with the situation: either get +the result, or wait until the fd conditions are met, and then call +back into the resolving machinery when it is ready to proceed. +.Pp +The +.Fn asr_run +function drives the resolving process. +It runs the asynchronous query represented by the +.Fa aq +handle until a result is available, or until it cannot continue +without blocking. +The results are returned to the user through the +.Fa ar +parameter, which must be a valid pointer to user allocated memory. +.Fa ar +is defined as: +.Bd -literal +struct asr_result { + + /* Fields set if the query is not done yet (asr_run returns 0) */ + int ar_cond; /* ASR_WANT_READ or ASR_WANT_WRITE */ + int ar_fd; /* the fd waiting for io condition */ + int ar_timeout; /* time to wait for in milliseconds */ + + /* Error fields. Depends on the query type. */ + int ar_errno; + int ar_h_errno; + int ar_gai_errno; + int ar_rrset_errno; + + /* Result for res_*_async() calls */ + int ar_count; /* number of answers in the dns reply */ + int ar_rcode; /* response code in the dns reply */ + void *ar_data; /* raw reply packet (must be freed) */ + int ar_datalen; /* reply packet length */ + struct sockaddr_storage ar_ns; /* nameserver that responded */ + + /* Result for other calls. Must be freed properly. */ + struct addrinfo *ar_addrinfo; + struct rrsetinfo *ar_rrsetinfo; + struct hostent *ar_hostent; + struct netent *ar_netent; +}; +.Ed +.Pp +The function returns one of the following values: +.Bl -tag -width "0 " -offset indent +.It 0 +The query cannot be processed further until a specific condition on a +file descriptor becomes true. +The following members of the +.Fa ar +structure are filled: +.Pp +.Bl -tag -width "ar_timeout " -compact +.It Fa ar_cond +one of ASR_WANT_READ or ASR_WANT_WRITE, +.It Fa ar_fd +the file descriptor waiting for an IO operation, +.It Fa ar_timeout +the amount of time to wait for in milliseconds. +.El +.Pp +The caller is expected to call +.Fn asr_run +again once the condition holds or the timeout expires. +.It 1 +The query is completed. +The members relevant to the actual async query type are set accordingly, +including error conditions. +In any case, the query is cleared and its handle is invalidated. +.El +.Pp +Note that although the query itself may fail (the error being properly reported +in the +.Fa ar +structure), the +.Fn asr_run +function itself cannot fail and it always preserves errno. +.Pp +The +.Fn asr_run_sync +function is a wrapper around +.Fn asr_run +that handles the read/write conditions, thus falling back to a blocking +interface. +It only returns 1. +It also preserves errno. +.Pp +The +.Fn asr_abort +function clears a running query. +It can be called when the query is waiting on a file descriptor. +Note that a completed query is already cleared when +.Fn asr_run +returns, so +.Fn asr_abort +must not be called in this case. +.Pp +The +.Fn asr_resolver_from_string +function constructs an asr context from a string that conforms to the +.Xr resolv.conf 5 +file format. +.Fn asr_resolver_free +frees an asr context obtained from +.Fn asr_resolver_from_string . +.Pp +The remaining functions are used to initiate different kinds of query +on the +.Fa asr +resolver context. +The specific operational details for each of them are described below. +All functions return a handle to an internal query, or NULL if they could +not allocate the necessary resources to initiate the query. +All other errors (especially invalid parameters) are reported when calling +.Fn asr_run . +They usually have the same interface as an existing resolver function, with +an additional +.Ar asr +argument, which specifies the context to use for this request. +An +.Ar asr +argument of NULL will use the default context for the current thread. +This is constructed from +.Pa /etc/resolv.conf +and takes care of reloading the file when it changes. +.Pp +The +.Fn res_send_async , +.Fn res_query_async +and +.Fn res_search_async +functions are asynchronous versions of the standard libc resolver routines. +Their interface is very similar, except that the response buffer is always +allocated internally. +The return value is found upon completion in the +.Fa ar_datalen +member of the response structure. +In addition, the +.Fa ar_ns +structure contains the address of the DNS server that sent the response, +.Fa ar_rcode +contains the code returned by the server in the DNS response packet, and +.Fa ar_count +contains the number of answers in the packet. +If a response is received, it is placed in a newly allocated buffer +and returned as +.Fa ar_data +member. +This buffer must be freed by the caller. +On error, the +.Fa ar_errno +and +.Fa ar_h_errno +members are set accordingly. +.Pp +The +.Fn getrrsetbyname_async +function is an asynchronous version of +.Xr getrrsetbyname 3 . +Upon completion, the return code is found in +.Fa ar_rrset_errno +and the address to the newly allocated result set is set in +.Fa ar_rrsetinfo . +As for the blocking function, it must be freed by calling +.Xr freerrset 3 . +.Pp +The +.Fn gethostbyname_async , +.Fn gethostbyname2_async +and +.Fn gethostbyaddr_async +functions provide an asynchronous version of the network host entry functions. +Upon completion, +.Ar ar_h_errno +is set and the resulting hostent address, if found, is set +in the +.Ar ar_hostent +field. +Note that unlike their blocking counterparts, these functions always return a +pointer to newly allocated memory, which must be released by the caller using +.Xr free 3 . +.Pp +Similarly, the +.Fn getnetbyname_async +and +.Fn getnetbyaddr_async +functions provide an asynchronous version of the network entry functions. +Upon completion, +.Ar ar_h_errno +is set and the resulting netent address, if found, is set +in the +.Ar ar_netent +field. +The memory there is also allocated for the request, and it must be freed by +.Xr free 3 . +.Pp +The +.Fn getaddrinfo_async +function is an asynchronous version of the +.Xr getaddrinfo 3 +call. +It provides a chain of addrinfo structures with all valid combinations of +socket address for the given +.Fa hostname , +.Fa servname +and +.Fa hints . +Those three parameters have the same meaning as for the blocking counterpart. +Upon completion the return code is set in +.Fa ar_gai_errno . +The +.Fa ar_errno +member may also be set. +On success, the +.Fa ar_addrinfo +member points to a newly allocated list of addrinfo. +This list must be freed with +.Xr freeaddrinfo 3 . +.Sh WORKING WITH THREADS +This implementation of the asynchronous resolver interface is thread-safe +and lock-free internally, but the following restriction applies: +Two different threads must not create queries on the same context or +run queries originating from the same context at the same time. +If they want to do that, all calls must be protected by a mutex around +that context. +.Pp +It is generally not a problem since the main point of the asynchronous +resolver is to multiplex queries within a single thread of control, +so sharing a resolver among threads is not useful. +.Sh SEE ALSO +.Xr getaddrinfo 3 , +.Xr gethostbyname 3 , +.Xr getnameinfo 3 , +.Xr getnetbyname 3 , +.Xr getrrsetbyname 3 , +.Xr res_send 3 , +.Xr resolv.conf 5 diff --git a/static/openbsd/man3/atan.3 b/static/openbsd/man3/atan.3 new file mode 100644 index 00000000..de6ecbf3 --- /dev/null +++ b/static/openbsd/man3/atan.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: atan.3,v 1.15 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ATAN 3 +.Os +.Sh NAME +.Nm atan , +.Nm atanf , +.Nm atanl +.Nd arc tangent functions of one variable +.Sh SYNOPSIS +.Lb libm +.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 +function computes the principal value of the arc tangent of +.Fa x +in the range +.Bk -words +.Bq -pi/2 , +pi/2 . +.Ek +The +.Fn atanf +function is a single precision version of +.Fn atan . +The +.Fn atanl +function is an extended precision version of +.Fn atan . +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 diff --git a/static/openbsd/man3/atan2.3 b/static/openbsd/man3/atan2.3 new file mode 100644 index 00000000..ae33786d --- /dev/null +++ b/static/openbsd/man3/atan2.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: atan2.3,v 1.21 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ATAN2 3 +.Os +.Sh NAME +.Nm atan2 , +.Nm atan2f , +.Nm atan2l +.Nd arc tangent functions of two variables +.Sh SYNOPSIS +.Lb libm +.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 +function computes the principal value of the arc tangent of +.Fa y Ns / Ns Fa x , +using the signs of both arguments to determine the quadrant of +the return value. +The +.Fn atan2f +function is a single precision version of +.Fn atan2 . +The +.Fn atan2l +function is an extended precision version of +.Fn atan2 . +.Sh RETURN VALUES +The +.Fn atan2 , +.Fn atan2f +and +.Fn atan2l +functions, if successful, +return the arc tangent of +.Fa y Ns / Ns Fa x +in the range +.Bk -words +.Bq \&- Ns pi , \&+ Ns pi +.Ek +radians. +If both +.Fa x +and +.Fa y +are zero, the global variable +.Va errno +is set to +.Er EDOM . +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 +.Sh STANDARDS +The +.Fn atan2 +function conforms to +.St -ansiC . diff --git a/static/openbsd/man3/atanh.3 b/static/openbsd/man3/atanh.3 new file mode 100644 index 00000000..cbfe86d9 --- /dev/null +++ b/static/openbsd/man3/atanh.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: atanh.3,v 1.20 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ATANH 3 +.Os +.Sh NAME +.Nm atanh , +.Nm atanhf , +.Nm atanhl +.Nd inverse hyperbolic tangent functions +.Sh SYNOPSIS +.Lb libm +.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 +function computes the inverse hyperbolic tangent +of the real +argument +.Fa x . +The +.Fn atanhf +function is a single precision version of +.Fn atanh . +The +.Fn atanhl +function is an extended precision version of +.Fn atanh . +.Sh RETURN VALUES +If |x|>=1, +.Fn atanh "x" , +.Fn atanhf "x" +and +.Fn atanhl "x" +return +infinity, -infinity or NaN, and set the global variable +.Va errno +to +.Er EDOM . +.Sh SEE ALSO +.Xr acosh 3 , +.Xr asinh 3 , +.Xr exp 3 , +.Xr fpclassify 3 +.Sh HISTORY +The +.Fn atanh +function appeared in +.Bx 4.3 . diff --git a/static/openbsd/man3/atexit.3 b/static/openbsd/man3/atexit.3 new file mode 100644 index 00000000..3a7e0d97 --- /dev/null +++ b/static/openbsd/man3/atexit.3 @@ -0,0 +1,97 @@ +.\" 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. +.\" +.\" $OpenBSD: atexit.3,v 1.13 2022/02/06 00:29:02 jsg Exp $ +.\" +.Dd $Mdocdate: February 6 2022 $ +.Dt ATEXIT 3 +.Os +.Sh NAME +.Nm atexit +.Nd register a function to be called on exit +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn atexit "void (*function)(void)" +.Sh DESCRIPTION +The +.Fn atexit +function registers the given +.Fa function +to be called at program exit, whether via +.Xr exit 3 +or via return from the program's +.Fn 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. +.Pp +If a shared object is unloaded from process memory using +.Xr dlclose 3 , +then any functions registered by calling +.Fn atexit +from that shared object will be called in reverse order and unregistered. +Note that it is the source of the call to +.Fn atexit +that matters, not the source of the function that was registered. +.Pp +.Fn atexit +is very difficult to use correctly without creating +.Xr exit 3 Ns -time +races. +Unless absolutely necessary, avoid using it. +.Sh RETURN VALUES +The +.Nm +function returns the value 0 if successful; otherwise a non-zero +value is returned and the global variable +.Va errno +is set to indicate the error. +.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 dlclose 3 , +.Xr exit 3 +.Sh STANDARDS +The +.Fn atexit +function conforms to +.St -ansiC . +.Pp +Setting +.Va errno +on error and the behavior when a shared object is unloaded +are extensions to that standard. diff --git a/static/openbsd/man3/atof.3 b/static/openbsd/man3/atof.3 new file mode 100644 index 00000000..7d1f09d1 --- /dev/null +++ b/static/openbsd/man3/atof.3 @@ -0,0 +1,81 @@ +.\" 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. +.\" +.\" $OpenBSD: atof.3,v 1.10 2022/09/11 06:38:11 jmc Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ATOF 3 +.Os +.Sh NAME +.Nm atof +.Nd convert ASCII string to double +.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 +.Fa nptr +to +.Vt 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 . +.Sh HISTORY +An +.Fn atof +function first appeared in +.At v1 . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_NUMERIC +.Xr locale 1 +category can cause parsing failures; see CAVEATS in +.Xr setlocale 3 +for details. diff --git a/static/openbsd/man3/atoi.3 b/static/openbsd/man3/atoi.3 new file mode 100644 index 00000000..92d8de93 --- /dev/null +++ b/static/openbsd/man3/atoi.3 @@ -0,0 +1,89 @@ +.\" 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. +.\" +.\" $OpenBSD: atoi.3,v 1.13 2022/09/11 06:38:11 jmc Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ATOI 3 +.Os +.Sh NAME +.Nm atoi +.Nd convert ASCII string to integer +.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 +.Fa nptr +to +.Vt integer +representation. +.Pp +It is equivalent to: +.Bd -literal -offset indent +(int)strtol(nptr, (char **)NULL, 10); +.Ed +.Sh SEE ALSO +.Xr atof 3 , +.Xr atol 3 , +.Xr strtod 3 , +.Xr strtol 3 , +.Xr strtonum 3 , +.Xr strtoul 3 +.Sh STANDARDS +The +.Fn atoi +function conforms to +.St -ansiC . +.Sh HISTORY +An +.Fn atoi +function first appeared in +.At v1 . +.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, +but +.Xr strtonum 3 +can be used to convert numbers from strings much more safely +and easily. diff --git a/static/openbsd/man3/atol.3 b/static/openbsd/man3/atol.3 new file mode 100644 index 00000000..f67ca7da --- /dev/null +++ b/static/openbsd/man3/atol.3 @@ -0,0 +1,68 @@ +.\" 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. +.\" +.\" $OpenBSD: atol.3,v 1.11 2022/09/11 06:38:11 jmc Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ATOL 3 +.Os +.Sh NAME +.Nm atol +.Nd convert ASCII string to long integer +.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 +.Fa nptr +to +.Vt 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 atoll 3 , +.Xr strtod 3 , +.Xr strtol 3 , +.Xr strtoul 3 +.Sh STANDARDS +The +.Fn atol +function conforms to +.St -isoC-99 . diff --git a/static/openbsd/man3/atoll.3 b/static/openbsd/man3/atoll.3 new file mode 100644 index 00000000..c2b606dd --- /dev/null +++ b/static/openbsd/man3/atoll.3 @@ -0,0 +1,68 @@ +.\" 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. +.\" +.\" $OpenBSD: atoll.3,v 1.9 2022/09/11 06:38:11 jmc Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ATOLL 3 +.Os +.Sh NAME +.Nm atoll +.Nd convert ASCII string to long long integer +.Sh SYNOPSIS +.In stdlib.h +.Ft long long +.Fn atoll "const char *nptr" +.Sh DESCRIPTION +The +.Fn atoll +function converts the initial portion of the string pointed to by +.Fa nptr +to +.Vt 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 strtoul 3 +.Sh STANDARDS +The +.Fn atoll +function conforms to +.St -isoC-99 . diff --git a/static/openbsd/man3/auth_subr.3 b/static/openbsd/man3/auth_subr.3 new file mode 100644 index 00000000..d36c0ac9 --- /dev/null +++ b/static/openbsd/man3/auth_subr.3 @@ -0,0 +1,538 @@ +.\" $OpenBSD: auth_subr.3,v 1.27 2023/02/19 21:33:38 aisha Exp $ +.\" +.\" Copyright (c) 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 $From: auth_subr.3,v 2.5 2000/03/30 19:11:27 polk Exp $ +.Dd $Mdocdate: February 19 2023 $ +.Dt AUTH_OPEN 3 +.Os +.Sh NAME +.Nm auth_open , +.Nm auth_call , +.Nm auth_challenge , +.Nm auth_check_change , +.Nm auth_check_expire , +.Nm auth_clean , +.Nm auth_close , +.Nm auth_clrenv , +.Nm auth_clroption , +.Nm auth_clroptions , +.Nm auth_getitem , +.Nm auth_getpwd , +.Nm auth_getstate , +.Nm auth_getvalue , +.Nm auth_set_va_list , +.Nm auth_setdata , +.Nm auth_setenv , +.Nm auth_setitem , +.Nm auth_setoption , +.Nm auth_setpwd , +.Nm auth_setstate +.Nd interface to the BSD Authentication system +.Sh SYNOPSIS +.In sys/types.h +.In login_cap.h +.In bsd_auth.h +.Ft auth_session_t * +.Fn auth_open "void" +.Ft int +.Fn auth_close "auth_session_t *as" +.Ft int +.Fn auth_call "auth_session_t *as" "char *path" "..." +.Ft char * +.Fn auth_challenge "auth_session_t *as" +.Ft quad_t +.Fn auth_check_change "auth_session_t *as" +.Ft quad_t +.Fn auth_check_expire "auth_session_t *as" +.Ft void +.Fn auth_clean "auth_session_t *as" +.Ft void +.Fn auth_clrenv "auth_session_t *as" +.Ft void +.Fn auth_clroption "auth_session_t * as" "char *name" +.Ft void +.Fn auth_clroptions "auth_session_t *as" +.Ft char * +.Fn auth_getitem "auth_session_t *as" "auth_item_t item" +.Ft struct passwd * +.Fn auth_getpwd "auth_session_t *as" +.Ft int +.Fn auth_getstate "auth_session_t *as" +.Ft char * +.Fn auth_getvalue "auth_session_t *as" "char *what" +.Ft void +.Fn auth_set_va_list "auth_session_t *as" "va_list ap" +.Ft int +.Fn auth_setdata "auth_session_t *as" "void *ptr" "size_t len" +.Ft void +.Fn auth_setenv "auth_session_t *as" +.Ft int +.Fn auth_setitem "auth_session_t *as" "auth_item_t item" "char *value" +.Ft int +.Fn auth_setoption "auth_session_t *as" "char *name" "char *value" +.Ft int +.Fn auth_setpwd "auth_session_t *as" "struct passwd *pwd" +.Ft void +.Fn auth_setstate "auth_session_t *as" "int state" +.Sh DESCRIPTION +These functions provide the lower level interface to the +.Bx +Authentication system. +They all operate on a +.Bx +Authentication session pointer, +.Fa as , +which is returned by +.Fn auth_open . +The session pointer +must be passed to all other +.Bx +Authentication functions called. +The +.Fn auth_open +function returns +.Dv NULL +if it was unable to allocate memory for the session. +The session is terminated by the +.Fn auth_close +function, +which also sets any environment variables requested by the login script +(assuming the user was not rejected) or removes files created by the +login script if the authentication was not successful. +It returns the final state of the authentication request. +A return value of 0 implies the user was not authenticated. +A non-zero return value is made up of 1 or more of the following values +ORed together: +.Bl -tag -width AUTH_ROOTOKAYXX +.It Dv AUTH_OKAY +The user was authenticated. +.It Dv AUTH_ROOTOKAY +The user was authenticated with a root instance. +.It Dv AUTH_SECURE +The user was authenticated via a mechanism which is not subject to +eavesdropping attacks (such as provided by token cards). +.El +.Pp +The full state of the session is returned by the +.Fn auth_getstate +function. +In addition to the values above, it also may contain the bits: +.Bl -tag -width AUTH_ROOTOKAYXX +.It Dv AUTH_SILENT +Do not report an error, the user was not authenticated for access and +was not expected to be. +This is returned by login scripts that allow changing of the user's password, +for instance. +This value is stripped off for normal returns. +.It Dv AUTH_CHALLENGE +The user was not authenticated for access and a challenge was issued. +The challenge should be displayed to the user, a response retrieved, +and the result verified. +This value is stripped off for normal returns. +.It Dv AUTH_EXPIRED +The user's account has expired. +.It Dv AUTH_PWEXPIRED +The user's password has expired and needs to be changed. +.El +.Pp +A session may be cleaned +by calling +.Fn auth_clean . +This function removes any files created by a login script in this +session and clears all state associated with this session, with the +exception of the option settings. +It is not necessary to call +.Fn auth_clean +if +.Fn auth_close +is called. +.Pp +The remaining functions are described in alphabetical order. +.Pp +The fundamental function for doing +.Bx +Authentication is +.Fn auth_call . +In addition to the pointer to the +.Bx +Authentication session, it takes +the following parameters: +.Bl -tag -width indent +.It Ar path +The full path name of the login script to run. +.It Ar ... +The remaining arguments, which should be of type +.Vt char * +and terminated with a +.Dv NULL , +are passed to the login script at the end of the command line. +Non-optional arguments such as user should be prefixed by a +.Qq -- +argument so that +.Xr getopt 3 +will not attempt to interpret them as optional flags. +.El +.Pp +The +.Fn auth_call +function, after verifying the +.Ar path , +creates a bi-directional pipe (socketpair) which is located on +file descriptor 3 for the child (the login script). +This is known as the +.Dq back channel . +The actual command line passed to the child is made up of +3 parts. +The parameters passed to +.Fn auth_call +following +.Ar path +have appended to them any arguments specified by the +.Fn auth_set_va_list +function. +These are typically the variable arguments passed to the function +that calls +.Fn auth_call . +Any option values set by the +.Fn auth_setoption +function are inserted between the first argument (the command +name) and the second argument with a preceding +.Fl v +flag. +The name and value are separated by an +.Sq = : +.Pp +.D1 Fl v Ar name=value +.Pp +Once the login script has been spawned, any data specified by the +.Fn auth_setdata +is written to the back channel. +Multiple blocks of data may have been specified and they will be sent +in the same order they were specified. +As the data is sent, the storage for the data is zeroed out and then freed +(the data is zeroed out since it may contain sensitive information, +such as a password). +Once any data is written out, +.Fn auth_call +reads up to 8192 bytes of data from the back channel. +The state of the session is determined from this data (see +.Xr login.conf 5 +for details). +If the login script exits with a 0 and does not specify any return state +on the back channel, the state prior to the call to +.Fn auth_call +is retained. +.Pp +Note that while +.Fn auth_call +will zero out the copies it makes of sensitive information, such as plain text +passwords, after it is sent, it is the responsibility of the +caller to zero out the original copies of this sensitive information. +Due to the mechanics of the +.Fn auth_call +function, this data must be zeroed +.Em before +.Fn auth_call +is called. +The safest place to zero out sensitive information is immediately +after it has been passed to +.Fn auth_setdata . +.Pp +The back channel data may also contain a file descriptor passed back +from the login script. +If this is the case, the login script will first send back the string +.Dq fd +to indicate that a file descriptor will be the next data item. +The file descriptor will be passed back to the next invocation of +the login script with a number specified by the +.Fl v Ar fd +option. +This is used to implement stateful challenge/response schemes that require +a persistent connection during the challenge and response. +The copy of the descriptor in the parent process is closed when the +child is running to prevent deadlock when file locking is used. +The descriptor is also closed by a call to +.Fn auth_close +or +.Fn auth_clean . +.Pp +The data read from the back channel is also used by the +.Fn auth_getvalue +and +.Fn auth_close +functions. +Subsequent calls to +.Fn auth_call +will cause this data to be lost and overwritten with the new data read +from the new call. +.Pp +The environment passed to the login script by +.Fn auth_call +only contains two values: +.Ev PATH +and +.Ev SHELL . +The +.Ev PATH +is set to the default path +.Pa ( /bin +and +.Pa /usr/bin ) +while the +.Ev SHELL +is set to the default system shell +.Pq Pa /bin/sh . +.Pp +The +.Fn auth_challenge +function queries the login script defined by the current +.Ar style +for a challenge for the user specified by +.Ar name . +(See below for the setting of the +.Ar style +and +.Ar name ) . +It internally uses the +.Fn auth_call +function. +The generated challenge is returned. +.Dv NULL +is returned on error or if no challenge was generated. +.Pp +The +.Fn auth_check_change +and +.Fn auth_check_expire +functions check the password expiration (change) and account expiration +times. +They return 0 if no change or expiration time is set for the account. +They return a negative value of how many seconds have passed since +the password or account expired. +In this case the state of the session is marked with either +.Li AUTH_PWEXPIRED +or +.Li AUTH_EXPIRED +as well as clearing any bits which would indicate the authentication was +successful. +If the password or account has not expired, they return the number of +seconds left until the account does expire. +The return value of -1 can either indicate the password or account +just expired or that no password entry was set for the current session. +.Pp +The +.Fn auth_clrenv +function clears any requests set by a login script for +environment variables to be set. +.Pp +The +.Fn auth_clroption +function clears the previously set option +.Fa name . +.Pp +The +.Fn auth_clroptions +function clears all previously set options. +.Pp +The +.Fn auth_getitem +function returns the value of +.Fa item . +The +.Fa item +may be one of: +.Bl -tag -width AUTH_INTERACTIVE +.It Dv AUTH_CHALLENGE +The latest challenge, if any, set for the session. +.It Dv AUTH_CLASS +The class of the user, as defined by the +.Pa /etc/login.conf +file. +This value is not directly used by +.Bx +Authentication, rather, it is +passed to the login scripts for their possible use. +.It Dv AUTH_INTERACTIVE +If set to any value, then the session is tagged as interactive. +If not set, the session is not interactive. +When the value is requested, it is always either +.Dv NULL +or +.Dq True . +The auth subroutines may choose to provide additional information to +standard output or standard error when the session is interactive. +There is no functional change in the operation of the subroutines. +.It Dv AUTH_NAME +The name of the user being authenticated. +The name should include the instance, if any, that is being requested. +.It Dv AUTH_SERVICE +The service requesting the authentication. +Initially it is set to the default service which provides the traditional +interactive service. +.It Dv AUTH_STYLE +The style of authentication being performed, as defined by the +.Pa /etc/login.conf +file. +The style determines which login script should actually be used. +.El +.Pp +The value returned points to private memory and should not be +freed by the caller. +.Pp +The +.Fn auth_getvalue +function returns the value, if any, associated with the specified internal +variable +.Ar what . +These variables are set by login scripts. +When a new login script is run +(by the +.Fn auth_call +function), +the values from the previous login script are lost. +(See +.Xr login.conf 5 +for details on internal variables.) +.Pp +The +.Fn auth_set_va_list +function establishes a variable argument list to be used by the +.Fn auth_call +function. +It is intended to be used by functions which need to call +.Fn auth_call +but take a variable number of arguments themselves. +Since the arguments are not copied, the call to +.Fn auth_call +must be placed within the scope of +.Fa ap . +The +.Fn auth_call +function will call +.Xr va_end 3 +on +.Fa ap . +.Pp +The +.Fn auth_setdata +function makes a copy of +.Fa len +bytes of data pointed to by +.Fa ptr +for use by +.Fn auth_call . +The data will be passed on the back channel to the next login script called. +.Pp +The +.Fn auth_setenv +function adds/deletes any environment variables requested by the +login script to the current environment. +.Pp +The +.Fn auth_setitem +function assigns +.Fa value +to the specified +.Fa item . +The items are described above with the +.Fn auth_getitem +function. +In addition, if +.Fa value +is +.Dv NULL , +the +.Fa item +is cleared. +If +.Fa value +is +.Dv NULL +and +.Fa item +is +.Li AUTH_ALL +then all items are cleared. +.Pp +The +.Fn auth_setoption +function requests that the option +.Fa name +be set with the value of +.Fa value +when a script is executed by +.Fn auth_call . +The actual arguments to the script will be placed at the beginning +of the argument vector. +For each option two arguments will be issued: +.Li -v name=value . +.Pp +The function +.Fn auth_setpwd +establishes the password file entry for the authentication session. +If the name has already been set by +.Fn auth_setitem +then the +.Fa pwd +argument may be +.Dv NULL , +else it must be the password entry to use. +.Pp +The function +.Fn auth_getpwd +retrieves the saved password file entry for the authentication session. +If no entry has been saved (either explicitly via +.Fn auth_setpwd +or implicitly via +.Fn auth_check_expire +or +.Fn auth_check_change ) , +it returns +.Dv NULL . +Note that the memory containing the password file entry is freed by +a call to +.Fn auth_close +or +.Fn auth_clean . +.Pp +The function +.Fn auth_setstate +sets the sessions state to +.Fa state . +Typically this is either +.Li AUTH_OKAY +or 0. +.Sh SEE ALSO +.Xr authenticate 3 , +.Xr login_cap 3 , +.Xr pw_dup 3 , +.Xr login.conf 5 diff --git a/static/openbsd/man3/authenticate.3 b/static/openbsd/man3/authenticate.3 new file mode 100644 index 00000000..e8b8a68b --- /dev/null +++ b/static/openbsd/man3/authenticate.3 @@ -0,0 +1,308 @@ +.\" $OpenBSD: authenticate.3,v 1.19 2022/03/31 17:27:15 naddy Exp $ +.\" +.\" Copyright (c) 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 $From: authenticate.3,v 2.7 1998/09/03 20:27:20 prb Exp $ +.Dd $Mdocdate: March 31 2022 $ +.Dt AUTH_APPROVAL 3 +.Os +.Sh NAME +.Nm auth_approval , +.Nm auth_cat , +.Nm auth_checknologin , +.Nm auth_mkvalue , +.Nm auth_userchallenge , +.Nm auth_usercheck , +.Nm auth_userokay , +.Nm auth_userresponse , +.Nm auth_verify +.Nd simplified interface to the BSD Authentication system +.Sh SYNOPSIS +.In sys/types.h +.In login_cap.h +.In bsd_auth.h +.Ft int +.Fn auth_userokay "char *name" "char *style" "char *type" "char *password" +.Ft auth_session_t * +.Fn auth_userchallenge "char *name" "char *style" "char *type" "char **challengep" +.Ft auth_session_t * +.Fn auth_usercheck "char *name" "char *style" "char *type" "char *password" +.Ft int +.Fn auth_userresponse "auth_session_t *as" "char *response" "int more" +.Ft int +.Fn auth_approval "auth_session_t *as" "struct login_cap *lc" "char *name" "char *type" +.Ft int +.Fn auth_cat "char *file" +.Ft void +.Fn auth_checknologin "struct login_cap *lc" +.Ft char * +.Fn auth_mkvalue "char *value" +.Ft auth_session_t * +.Fn auth_verify "auth_session_t *as" "char *style" "char *name" "..." +.Sh DESCRIPTION +These functions provide a simplified interface to the +.Bx +Authentication system +.Pq see Xr auth_subr 3 . +The +.Fn auth_userokay +function provides a single function call interface. +Provided with a user's name in +.Ar name , +and an optional +.Ar style , +.Ar type , +and +.Ar password , +the +.Fn auth_userokay +function returns a simple yes/no response. +A return value of 0 implies failure; a non-zero return value implies success. +If +.Ar style +is not +.Dv NULL , +it specifies the desired style of authentication to be used. +If it is +.Dv NULL +then the default style for the user is used. +In this case, +.Ar name +may include the desired style by appending it to the user's name with a +single colon +.Pq Sq \&: +as a separator. +If +.Ar type +is not +.Dv NULL +then it is used as the authentication type (such as +.Dq auth-myservice ) . +If +.Ar password +is +.Dv NULL +then +.Fn auth_userokay +operates in an interactive mode with the user on standard input, output, +and error. +If +.Ar password +is specified, +.Fn auth_userokay +operates in a non-interactive mode and only tests the specified passwords. +This non-interactive method does not work with challenge-response +authentication styles. +For security reasons, when a +.Ar password +is specified, +.Fn auth_userokay +will zero out its value before it returns. +.Pp +The +.Fn auth_usercheck +function operates the same as the +.Fn auth_userokay +function except that it does not close the +.Bx +Authentication session created. +Rather than returning the status of the session, it returns +a pointer to the newly created +.Bx +Authentication session. +.Pp +The +.Fn auth_userchallenge +function takes the same +.Ar name , style , +and +.Ar type +arguments as does +.Fn auth_userokay . +However, rather than authenticating the user, it returns a possible +challenge in the pointer pointed to by +.Ar challengep . +The return value of the function is a pointer to a newly created +.Bx +Authentication session. +This challenge, if not +.Dv NULL , +should be displayed to the user. +In any case, the user should provide a password which is +the +.Ar response +in a call to +.Fn auth_userresponse . +In addition to the password, the pointer returned by +.Fn auth_userchallenge +should be passed in as +.Ar as +and the value of +.Va more +should be non-zero if the program wishes to allow more attempts. +If +.Va more +is zero then the session will be closed. +The +.Fn auth_userresponse +function closes the +.Bx +Authentication session and has the same +return value as +.Fn auth_userokay . +For security reasons, when a +.Ar response +is specified, +.Fn auth_userresponse +will zero out its value before it returns. +.Pp +The +.Fn auth_approval +function calls the approval script for the user of the specified +.Ar type . +The string +.Dq approve- +will be prepended to +.Ar type +if missing. +The resulting type is used to look up an entry in +.Pa /etc/login.conf +for the user's class. +If the entry is missing, the generic entry for +.Dq approve +will be used. +The +.Ar name +argument will be passed to the approval program as the name of the user. +The +.Ar lc +argument points to a login class structure. +If it is +.Dv NULL +then a login class structure will be looked up for the class of +user +.Ar name . +The +.Fn auth_approval +function returns a value of 0 on failure to approve the user. +.Pp +Prior to actually calling the approval script, the account's +expiration time, the associated nologin file, and existence +of the account's home directory +.Po +if +.Li requirehome +is set for this class +.Pc +are checked. +Failure on any of these points causes the +.Fn auth_approval +function to return a value of 0 and not actually call the approval script. +.Pp +The +.Fn auth_cat +function opens +.Ar file +for reading and copies its contents to standard output. +It returns 0 if it was unable to open +.Ar file +and 1 otherwise. +.Pp +The +.Fn auth_checknologin +function must be provided with a pointer to a login class. +If the class has a +.Dq nologin +entry defined and it points to a file that can be opened, +the contents of the file will be copied to standard output and +.Xr exit 3 +will be called with a value of 1. +If the class does not have the field +.Dq ignorenologin +and the file +.Pa /etc/nologin +exists, its contents will be copied to standard output and +.Xr exit 3 +will be called with a value of 1. +.Pp +The +.Fn auth_verify +function is a front end to the +.Xr auth_call 3 +function. +It will open a +.Bx +Authentication session, if needed, and will set +the style and user name based on the +.Ar style +and +.Ar name +arguments, if not +.Dv NULL . +Values for the style and user name in an existing +.Bx +Authentication +session will be replaced and the old values freed (if the calling program +has obtained pointers to the style or user name via +.Xr auth_getitem 3 , +those pointers will become invalid). +The variable arguments are passed to +.Fn auth_call +via the +.Xr auth_set_va_list 3 +function. +The, possibly created, +.Bx +Authentication session is returned. +The +.Xr auth_getstate 3 +or +.Xr auth_close 3 +function +should be used to determine the outcome of the authentication request. +.Pp +The +.Fn auth_mkvalue +function takes a NUL-terminated string pointed to by +.Ar value +and returns a NUL-terminated string suitable for passing +back to a calling program on the back channel. +This function is for use by the login scripts themselves. +The string returned should be freed by +.Xr free 3 +when it is no longer needed. +A value of +.Dv NULL +is returned if no memory was available for the new copy of the string. +.Sh SEE ALSO +.Xr auth_subr 3 , +.Xr getpwent 3 , +.Xr pw_dup 3 diff --git a/static/openbsd/man3/authnone_create.3 b/static/openbsd/man3/authnone_create.3 new file mode 100644 index 00000000..40946f9e --- /dev/null +++ b/static/openbsd/man3/authnone_create.3 @@ -0,0 +1,130 @@ +.\" $OpenBSD: authnone_create.3,v 1.3 2013/06/05 03:39:23 tedu Exp $ +.\" Mostly converted to mandoc by Theo de Raadt, Tue Feb 24 04:04:46 MST 1998 +.\" +.\" Copyright (c) 2010, Oracle America, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer in the documentation and/or other materials +.\" provided with the distribution. +.\" * Neither the name of the "Oracle America, Inc." nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt AUTHNONE_CREATE 3 +.Os +.Sh NAME +.Nm auth_destroy , +.Nm authnone_create , +.Nm authunix_create , +.Nm authunix_create_default , +.Nm set_rpc_maxgrouplist +.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 void +.Fn set_rpc_maxgrouplist "int num" +.Sh DESCRIPTION +These routines establish authentication information for use by the +RPC functions described in +.Xr rpc 3 . +.Pp +.Fn auth_destroy +is 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 . +.Pp +.Fn authnone_create +creates and returns an RPC +authentication handle that passes nonusable authentication +information with each remote procedure call. +This is the default authentication used by RPC. +.Pp +.Fn authunix_create +creates and returns an RPC authentication handle that contains +.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. +.Pp +.Fn authunix_create_default +calls +.Fn authunix_create +with the appropriate parameters. +.Pp +.Fn set_rpc_maxgrouplist +allows 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). +.Sh SEE ALSO +.\"Xr rpc_secure 3 , +.Xr rpcgen 1 , +.Xr select 2 , +.Xr getrpcport 3 , +.Xr rpc 3 , +.Xr xdr 3 , +.Xr rpc 5 , +.Xr portmap 8 +.Rs +.%T Remote Procedure Calls: Protocol Specification +.Re +.Rs +.%T Remote Procedure Call Programming Guide +.Re +.Rs +.%T rpcgen Programming Guide +.Re +.Sh STANDARDS +.Rs +.%D June 1988 +.%Q Sun Microsystems, Inc. +.%R RFC 1057 +.%T RPC: Remote Procedure Call Protocol Specification Version 2 +.Re diff --git a/static/openbsd/man3/backtrace.3 b/static/openbsd/man3/backtrace.3 new file mode 100644 index 00000000..47f437fd --- /dev/null +++ b/static/openbsd/man3/backtrace.3 @@ -0,0 +1,151 @@ +.\" $OpenBSD: backtrace.3,v 1.4 2025/06/07 20:54:35 schwarze Exp $ +.\" +.\" Copyright (c) 2021 Todd Mortimer +.\" 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 $Mdocdate: June 7 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 SYNOPSIS +.Lb libexecinfo +.In execinfo.h +.Ft size_t +.Fn backtrace "void **addrlist" "size_t len" +.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_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 +.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 . +.Sh SEE ALSO +.Xr dladdr 3 +.Sh HISTORY +The +.Fn backtrace +library of functions first appeared in +.Nx 7.0 +and was imported into +.Ox 7.0 . +.Sh BUGS +.Bl -enum +.It +Only unwinding with libunwind is supported. +On architectures without libunwind the +.Fn backtrace +function simply returns 0. +.It +Since +.Xr dladdr 3 +only deals with dynamic symbols, local symbols from the main +portion of the program are not printed. +.El diff --git a/static/openbsd/man3/basename.3 b/static/openbsd/man3/basename.3 new file mode 100644 index 00000000..393765bb --- /dev/null +++ b/static/openbsd/man3/basename.3 @@ -0,0 +1,93 @@ +.\" $OpenBSD: basename.3,v 1.25 2020/10/20 19:30:14 naddy Exp $ +.\" +.\" Copyright (c) 1997 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. +.\" +.Dd $Mdocdate: October 20 2020 $ +.Dt BASENAME 3 +.Os +.Sh NAME +.Nm basename +.Nd extract the base portion of a pathname +.Sh SYNOPSIS +.In libgen.h +.Ft char * +.Fn basename "char *path" +.Sh DESCRIPTION +The +.Fn basename +function returns the last component from the pathname pointed to by +.Ar path , +deleting any trailing +.Sq \&/ +characters. +If +.Ar path +consists entirely of +.Sq \&/ +characters, a pointer to the string +.Qq \&/ +is returned. +If +.Ar path +is a null pointer or the empty string, a pointer to the string +.Qq \&. +is returned. +.Sh RETURN VALUES +On successful completion, +.Fn basename +returns a pointer to the last component of +.Ar path . +.Pp +If +.Fn basename +fails, a null pointer is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er ENAMETOOLONG +The path component to be returned was larger than +.Dv PATH_MAX . +.El +.Sh SEE ALSO +.Xr basename 1 , +.Xr dirname 1 , +.Xr dirname 3 +.Sh STANDARDS +The +.Fn basename +function conforms to the X/Open System Interfaces option of the +.St -p1003.1-2008 +specification. +.Sh HISTORY +The +.Fn basename +function first appeared in +.Ox 2.2 . +.Sh AUTHORS +.An Todd C. Miller +.Sh CAVEATS +.Fn basename +returns a pointer to internal static storage space that will be overwritten +by subsequent calls. +.Pp +Other vendor implementations of +.Fn basename +may modify the contents of the string passed to +.Fn basename ; +this should be taken into account when writing code which calls this function +if portability is desired. diff --git a/static/openbsd/man3/bcmp.3 b/static/openbsd/man3/bcmp.3 new file mode 100644 index 00000000..a3cb1dfb --- /dev/null +++ b/static/openbsd/man3/bcmp.3 @@ -0,0 +1,67 @@ +.\" 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. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (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: bcmp.3,v 1.12 2015/11/24 09:14:35 daniel Exp $ +.\" +.Dd $Mdocdate: November 24 2015 $ +.Dt BCMP 3 +.Os +.Sh NAME +.Nm bcmp +.Nd compare byte string +.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. +.Sh SEE ALSO +.Xr memcmp 3 , +.Xr strcasecmp 3 , +.Xr strcmp 3 , +.Xr strcoll 3 , +.Xr strxfrm 3 , +.Xr timingsafe_bcmp 3 +.Sh HISTORY +The +.Fn bcmp +function first appeared in +.Bx 4.2 . diff --git a/static/openbsd/man3/bcopy.3 b/static/openbsd/man3/bcopy.3 new file mode 100644 index 00000000..68c63f92 --- /dev/null +++ b/static/openbsd/man3/bcopy.3 @@ -0,0 +1,67 @@ +.\" 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. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (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: bcopy.3,v 1.12 2015/11/24 09:14:35 daniel Exp $ +.\" +.Dd $Mdocdate: November 24 2015 $ +.Dt BCOPY 3 +.Os +.Sh NAME +.Nm bcopy +.Nd copy bytes +.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 buffer +.Fa src +to buffer +.Fa dst . +The two buffers may overlap. +If +.Fa len +is zero, no bytes are copied. +.Sh SEE ALSO +.Xr memccpy 3 , +.Xr memcpy 3 , +.Xr memmove 3 , +.Xr strcpy 3 , +.Xr strlcpy 3 , +.Xr strncpy 3 +.Sh HISTORY +The +.Fn bcopy +function first appeared in +.Bx 4.2 . diff --git a/static/openbsd/man3/bcrypt_pbkdf.3 b/static/openbsd/man3/bcrypt_pbkdf.3 new file mode 100644 index 00000000..4b690ff7 --- /dev/null +++ b/static/openbsd/man3/bcrypt_pbkdf.3 @@ -0,0 +1,70 @@ +.\" $OpenBSD: bcrypt_pbkdf.3,v 1.7 2025/06/06 22:01:39 schwarze Exp $ +.\" +.\" Copyright (c) 2012 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 $Mdocdate: June 6 2025 $ +.Dt BCRYPT_PBKDF 3 +.Os +.Sh NAME +.Nm bcrypt_pbkdf +.Nd bcrypt password-based key derivation function +.Sh SYNOPSIS +.Lb libutil +.In util.h +.Ft int +.Fn bcrypt_pbkdf "const char *pass" "size_t pass_len" "const uint8_t *salt" \ + "size_t salt_len" "uint8_t *key" "size_t key_len" "unsigned int rounds" +.Sh DESCRIPTION +The +.Nm +function converts a password into a byte array suitable for use as +an encryption key. +The password and salt values are combined and repeatedly hashed +.Ar rounds +times. +The salt value should be randomly generated beforehand. +The repeated hashing is designed to thwart discovery of the key via +password guessing attacks. +The higher the number of rounds, the slower each attempt will be. +.\" A minimum value of at least 4 is recommended. +.Sh RETURN VALUES +The +.Fn bcrypt_pbkdf +function returns 0 to indicate success and \-1 for failure. +.\" .Sh EXAMPLES +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr bcrypt 3 +.Sh STANDARDS +.Rs +.%A Niels Provos and David Mazieres +.%D June 1999 +.%T A Future-Adaptable Password Scheme +.Re +.Pp +.Rs +.%A B. Kaliski +.%D September 2000 +.%R RFC 2898 +.%T PKCS #5: Password-Based Cryptography Specification Version 2.0 +.Re +.\" .Sh HISTORY +.\" .Sh AUTHORS +.Sh CAVEATS +This implementation deviates slightly from the PBKDF2 standard by mixing +output key bits nonlinearly. +By mixing the output bytes together, an attacker is required to perform +all of the work without taking any shortcuts. +.\" .Sh BUGS diff --git a/static/openbsd/man3/bindresvport.3 b/static/openbsd/man3/bindresvport.3 new file mode 100644 index 00000000..ce7d1ac6 --- /dev/null +++ b/static/openbsd/man3/bindresvport.3 @@ -0,0 +1,142 @@ +.\" $OpenBSD: bindresvport.3,v 1.25 2013/06/05 03:39:23 tedu Exp $ +.\" +.\" Copyright (c) 2010, Oracle America, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer in the documentation and/or other materials +.\" provided with the distribution. +.\" * Neither the name of the "Oracle America, Inc." nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt BINDRESVPORT 3 +.Os +.Sh NAME +.Nm bindresvport , +.Nm bindresvport_sa +.Nd bind a socket to a privileged IP port +.Sh SYNOPSIS +.In sys/types.h +.In netinet/in.h +.Ft int +.Fn bindresvport "int sd" "struct sockaddr_in *sin" +.Ft int +.Fn bindresvport_sa "int sd" "struct sockaddr *sa" +.Sh DESCRIPTION +The +.Fn bindresvport +and +.Fn bindresvport_sa +functions are used to bind a socket descriptor to a privileged IP +port, that is, a port number in the range 0-1023. +The +.Fn bindresvport +function operates solely on +.Dv AF_INET +sockets, whereas the +.Fn bindresvport_sa +function is capable of binding both +.Dv AF_INET +and +.Dv AF_INET6 +sockets. +.Pp +Only the superuser may bind to a privileged port; +these functions will fail for any other user. +.Pp +.Fa sd +should be a socket descriptor that was returned by a call to +.Xr socket 2 . +.Pp +If +.Va sin +is not the NULL pointer, +.Va sin->sin_family +must be initialized to the address family of the socket +.Va sd . +If the value of +.Va sin->sin_port +is non-zero, +.Fn bindresvport +will attempt to use the specified port. +Otherwise, a free port in the range 600-1023 will be chosen and, +if the +.Xr bind 2 +succeeds, +.Va sin->sin_port +will be updated with the port that was assigned. +.Pp +If +.Va sin +is the NULL pointer, a free port in the range 600-1023 will be chosen +(as above), but in this case there is no way for +.Fn bindresvport +to communicate to the caller which port was assigned. +.Sh RETURN VALUES +.Fn bindresvport +returns 0 if it is successful, otherwise \-1 is returned and +.Va errno +set to reflect the cause of the error. +.Sh ERRORS +The +.Fn bindresvport +function fails if: +.Bl -tag -width Er +.It Bq Er EBADF +.Fa sd +is not a valid descriptor. +.It Bq Er ENOTSOCK +.Fa sd +is not a socket. +.It Bq Er EADDRNOTAVAIL +The specified address is not available from the local machine. +.It Bq Er EADDRINUSE +The specified address is already in use. +.It Bq Er EINVAL +The socket is already bound to an address. +.It Bq Er EINVAL +The family of the socket and that requested in +.Va sa->sa_family +are not equivalent. +.It Bq Er EACCES +The requested address is protected, and the current user +has inadequate permission to access it. +.It Bq Er EFAULT +The +.Fa name +parameter is not in a valid part of the user +address space. +.It Bq Er ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.It Bq Er EPFNOSUPPORT +The protocol family has not been configured into the +system, no implementation for it exists, +or address family did not match between arguments. +.El +.Sh SEE ALSO +.Xr bind 2 , +.Xr socket 2 , +.Xr rresvport 3 , +.Xr rresvport_af 3 diff --git a/static/openbsd/man3/blowfish.3 b/static/openbsd/man3/blowfish.3 new file mode 100644 index 00000000..c64ccb68 --- /dev/null +++ b/static/openbsd/man3/blowfish.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: blowfish.3,v 1.24 2021/11/29 01:04:45 djm Exp $ +.\" +.\" Copyright 1997 Niels Provos +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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. +.\" +.\" Manual page, using -mandoc macros +.\" +.Dd $Mdocdate: November 29 2021 $ +.Dt BLF_KEY 3 +.Os +.Sh NAME +.Nm blf_key , +.Nm blf_enc , +.Nm blf_dec , +.Nm blf_ecb_encrypt , +.Nm blf_ecb_decrypt , +.Nm blf_cbc_encrypt , +.Nm blf_cbc_decrypt +.Nd Blowfish encryption +.Sh SYNOPSIS +.In blf.h +.Ft void +.Fn blf_key "blf_ctx *state" "const u_int8_t *key" "u_int16_t keylen" +.Ft void +.Fn blf_enc "blf_ctx *state" "u_int32_t *data" "u_int16_t blocks" +.Ft void +.Fn blf_dec "blf_ctx *state" "u_int32_t *data" "u_int16_t blocks" +.Ft void +.Fn blf_ecb_encrypt "blf_ctx *state" "u_int8_t *data" "u_int32_t datalen" +.Ft void +.Fn blf_ecb_decrypt "blf_ctx *state" "u_int8_t *data" "u_int32_t datalen" +.Ft void +.Fn blf_cbc_encrypt "blf_ctx *state" "u_int8_t *iv" "u_int8_t *data" "u_int32_t datalen" +.Ft void +.Fn blf_cbc_decrypt "blf_ctx *state" "u_int8_t *iv" "u_int8_t *data" "u_int32_t datalen" +.Sh DESCRIPTION +.Em Blowfish +is a fast unpatented block cipher designed by Bruce Schneier. +It basically consists of a 16-round Feistel network. +The block size is 64 bits and the maximum key size is 448 bits. +.Pp +The +.Fn blf_key +function initializes the 4 8-bit S-boxes and the 18 Subkeys with +the hexadecimal digits of Pi. +The key is used for further randomization. +The first argument to +.Fn blf_enc +is the initialized state derived from +.Fn blf_key . +The stream of 32-bit words is encrypted in Electronic Codebook +Mode (ECB) and +.Fa blocks +is the number of 64-bit blocks in the stream. +.Fn blf_dec +is used for decrypting Blowfish encrypted blocks. +.Pp +The functions +.Fn blf_ecb_encrypt +and +.Fn blf_ecb_decrypt +are used for encrypting and decrypting octet streams in ECB mode. +The functions +.Fn blf_cbc_encrypt +and +.Fn blf_cbc_decrypt +are used for encrypting and decrypting octet streams in +Cipherblock Chaining Mode (CBC). +For these functions +.Fa datalen +specifies the number of octets of data to encrypt or decrypt. +It must be a multiple of 8 (64-bit block). +The initialisation vector +.Fa iv +points to an 8-byte buffer. +.Sh SEE ALSO +.Xr passwd 1 , +.Xr crypt 3 , +.Xr passwd 5 +.Sh AUTHORS +.An Niels Provos Aq Mt provos@physnet.uni-hamburg.de diff --git a/static/openbsd/man3/bsearch.3 b/static/openbsd/man3/bsearch.3 new file mode 100644 index 00000000..9c66eac0 --- /dev/null +++ b/static/openbsd/man3/bsearch.3 @@ -0,0 +1,84 @@ +.\" 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. +.\" +.\" $OpenBSD: bsearch.3,v 1.10 2015/11/30 17:03:05 jmc Exp $ +.\" +.Dd $Mdocdate: November 30 2015 $ +.Dt BSEARCH 3 +.Os +.Sh NAME +.Nm bsearch +.Nd binary search of a sorted table +.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 dbopen 3 , +.Xr lsearch 3 , +.Xr qsort 3 , +.Xr tsearch 3 +.Sh STANDARDS +The +.Fn bsearch +function conforms to +.St -ansiC . diff --git a/static/openbsd/man3/btowc.3 b/static/openbsd/man3/btowc.3 new file mode 100644 index 00000000..109dd308 --- /dev/null +++ b/static/openbsd/man3/btowc.3 @@ -0,0 +1,87 @@ +.\" $OpenBSD: btowc.3,v 1.3 2013/06/05 03:39:22 tedu Exp $ +.\" $NetBSD: btowc.3,v 1.3 2003/04/16 13:34:40 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 $Mdocdate: June 5 2013 $ +.Dt BTOWC 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm btowc +.Nd convert a single byte character to a wide character +.\" ---------------------------------------------------------------------- +.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 the +.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 . +ISO/IEC 9899/AMD1:1995 +.Pq Dq ISO C90, Amendment 1 . diff --git a/static/openbsd/man3/btree.3 b/static/openbsd/man3/btree.3 new file mode 100644 index 00000000..e49f3000 --- /dev/null +++ b/static/openbsd/man3/btree.3 @@ -0,0 +1,241 @@ +.\" $OpenBSD: btree.3,v 1.25 2022/03/31 17:27:15 naddy Exp $ +.\" $NetBSD: btree.3,v 1.6 1996/05/03 21:26:48 cgd Exp $ +.\" +.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. +.\" +.\" 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 $Mdocdate: March 31 2022 $ +.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 +.Fn dbopen +routine 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 -offset indent +typedef struct { + unsigned long flags; + unsigned int cachesize; + int maxkeypage; + int minkeypage; + unsigned 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 "XXXXXX" +.It Fa flags +The flag value is specified by OR'ing any of the following values: +.Bl -tag -width XXXXX +.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 +.Fn get +routine is used; however, +.Fn 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. +.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 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 it 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 +.Fa flags , +.Fa lorder , +and +.Fa 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 recno 3 +.Rs +.%T "The Ubiquitous B-tree" +.%A Douglas Comer +.%J ACM Comput. Surv. 11 +.%D June 1979 +.%P pp. 121\(en138 +.Re +.Rs +.%T "Prefix B-trees" +.%A Rudolf Bayer +.%A Karl Unterauer +.%J ACM Transactions on Database Systems +.%V Vol. 2 , 1 +.%D March 1977 +.%P pp. 11\(en26 +.Re +.Rs +.%B "The Art of Computer Programming Vol. 3: Sorting and Searching" +.%A D. E. Knuth +.%D 1968 +.%P pp. 471\(en480 +.Re +.Sh BUGS +Only big and little endian byte order is supported. diff --git a/static/openbsd/man3/bzero.3 b/static/openbsd/man3/bzero.3 new file mode 100644 index 00000000..87a23e20 --- /dev/null +++ b/static/openbsd/man3/bzero.3 @@ -0,0 +1,92 @@ +.\" 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. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (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: bzero.3,v 1.13 2017/10/12 15:22:32 schwarze Exp $ +.\" +.Dd $Mdocdate: October 12 2017 $ +.Dt BZERO 3 +.Os +.Sh NAME +.Nm bzero , +.Nm explicit_bzero +.Nd write zeroes to a byte string +.Sh SYNOPSIS +.In strings.h +.Ft void +.Fn bzero "void *b" "size_t len" +.In string.h +.Ft void +.Fn explicit_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. +.Pp +The +.Fn explicit_bzero +variant behaves the same, but will not be removed by a compiler's dead store +optimization pass, making it useful for clearing sensitive memory such as a +password. +.Sh SEE ALSO +.Xr memset 3 , +.Xr swab 3 +.Sh STANDARDS +The +.Fn bzero +function conforms to the X/Open System Interfaces option of the +.St -p1003.1-2004 +specification. +It was removed from the standard in +.St -p1003.1-2008 , +which recommends using +.Xr memset 3 +instead. +.Pp +The +.Fn explicit_bzero +function is an +.Ox +extension. +.Sh HISTORY +The +.Fn bzero +function first appeared in +.Bx 4.2 . +The +.Fn explicit_bzero +function first appeared in +.Ox 5.5 . diff --git a/static/openbsd/man3/c16rtomb.3 b/static/openbsd/man3/c16rtomb.3 new file mode 100644 index 00000000..62cac439 --- /dev/null +++ b/static/openbsd/man3/c16rtomb.3 @@ -0,0 +1,207 @@ +.\" $OpenBSD: c16rtomb.3,v 1.1 2023/08/20 15:02:51 schwarze Exp $ +.\" +.\" Copyright (c) 2023 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 $Mdocdate: August 20 2023 $ +.Dt C16RTOMB 3 +.Os +.Sh NAME +.Nm c16rtomb +.Nd convert one UTF-16 encoded character to UTF-8 +.Sh SYNOPSIS +.In uchar.h +.Ft size_t +.Fo c16rtomb +.Fa "char * restrict s" +.Fa "char16_t c16" +.Fa "mbstate_t * restrict mbs" +.Fc +.Sh DESCRIPTION +This function converts one UTF-16 encoded character to UTF-8. +In some cases, it is necessary to call the function twice +to convert a single character. +.Pp +First, call +.Fn c16rtomb +passing the first 16-bit code unit of the UTF-16 encoded character in +.Fa c16 . +If the return value is greater than 0, the character is part of the UCS-2 +range, the complete UTF-8 encoding consisting of at most +.Dv MB_CUR_MAX +bytes has been written to the storage starting at +.Fa s , +and the function does not need to be called again. +.Pp +If the return value is 0, the first 16-bit code unit is a UTF-16 +high surrogate and the function needs to be called a second time, +this time passing the second 16-bit code unit of the UTF-16 encoded +character in +.Fa c16 +and passing the same +.Fa mbs +again that was also passed to the first call. +If the second 16-bit code unit is a UTF-16 low surrogate, +the second call returns a value greater than 0, +the surrogate pair represents a Unicode code point +beyond the basic multilingual plane, +and the complete UTF-8 encoding consisting of at most +.Dv MB_CUR_MAX +bytes is written to the storage starting at +.Fa s . +.Pp +The output encoding that +.Fn c16rtomb +uses in +.Fa s +is determined by the +.Dv LC_CTYPE +category of the current locale. +.Ox +only supports UTF-8 and ASCII output, +and this function is only useful for UTF-8. +.Pp +The following arguments cause special processing: +.Bl -tag -width 012345678901 +.It Fa c16 No == 0 +A NUL byte is stored to +.Pf * Fa s +and the state object pointed to by +.Fa mbs +is reset to the initial state. +On operating systems other than +.Ox +that support state-dependent multibyte encodings, +a special byte sequence +.Pq Dq shift sequence +is written before the NUL byte to return to the initial state +if that is required by the output encoding +and by the current output encoding state. +.It Fa mbs No == Dv NULL +An internal +.Vt mbstate_t +object specific to the +.Fn c16rtomb +function is used instead of the +.Fa mbs +argument. +This internal object is automatically initialized at program startup +and never changed by any +.Em libc +function except +.Fn c16rtomb . +.It Fa s No == Dv NULL +The object pointed to by +.Fa mbs , +or the internal object if +.Fa mbs +is a +.Dv NULL +pointer, is reset to its initial state, +.Fa c16 +is ignored, and 1 is returned. +.El +.Sh RETURN VALUES +.Fn c16rtomb +returns the number of bytes written to +.Fa s +on success or +.Po Vt size_t Pc Ns \-1 +on failure, specifically: +.Bl -tag -width 10n +.It 0 +The first 16-bit code unit was successfully decoded +as a UTF-16 high surrogate. +Nothing was written to +.Fa s +yet. +.It 1 +The first 16-bit code unit was successfully decoded +as a character in the range U+0000 to U+007F, or +.Fa s +is +.Dv NULL . +.It 2 +The first 16-bit code unit was successfully decoded +as a character in the range U+0080 to U+07FF. +.It 3 +The first 16-bit code unit was successfully decoded +as a character in the range U+0800 to U+D7FF or U+E000 to U+FFFF. +.It 4 +The second 16-bit code unit was successfully decoded as a UTF-16 low +surrogate, resulting in a character in the range U+10000 to U+10FFFF. +.It greater +Return values greater than 4 may occur on operating systems other than +.Ox +for output encodings other than UTF-8, in particular when a shift +sequence was written. +.It Po Vt size_t Pc Ns \-1 +UTF-16 input decoding or +.Dv LC_CTYPE +output encoding failed, or +.Fa mbs +is invalid. +Nothing was written to +.Fa s , +and +.Va errno +has been set. +.El +.Sh ERRORS +.Fn c16rtomb +causes an error in the following cases: +.Bl -tag -width Er +.It Bq Er EILSEQ +UTF-16 input decoding failed because the first 16-bit code unit +is neither a UCS-2 character nor a UTF-16 high surrogate, +or because the second 16-bit code unit is not a UTF-16 low surrogate; +or output encoding failed because the resulting character +cannot be represented in the output encoding selected with +.Dv LC_CTYPE . +.It Bq Er EINVAL +.Fa mbs +points to an invalid or uninitialized +.Vt mbstate_t +object. +.El +.Sh SEE ALSO +.Xr mbrtoc16 3 , +.Xr setlocale 3 , +.Xr wcrtomb 3 +.Sh STANDARDS +.Fn c16rtomb +conforms to +.St -isoC-2011 . +.Sh HISTORY +.Fn c16rtomb +has been available since +.Ox 7.4 . +.Sh CAVEATS +The C11 standard only requires the +.Fa c16 +argument to be interpreted according to UTF-16 +if the predefined environment macro +.Dv __STDC_UTF_16__ +is defined with a value of 1. +On +.Ox , +.In uchar.h +provides this definition. +Other operating systems which do not define +.Dv __STDC_UTF_16__ +could theoretically use a different, +implementation-defined input encoding for +.Fa c16 +instead of UTF-16. +Using UTF-16 becomes mandatory in C23. diff --git a/static/openbsd/man3/cacheflush.3 b/static/openbsd/man3/cacheflush.3 new file mode 100644 index 00000000..5e9e5a4e --- /dev/null +++ b/static/openbsd/man3/cacheflush.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: cacheflush.3,v 1.3 2025/06/06 21:09:33 schwarze Exp $ +.\" +.\" Copyright (c) 2009 Miodrag Vallat. +.\" +.\" 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: June 6 2025 $ +.Dt CACHEFLUSH 3 mips64 +.Os +.Sh NAME +.Nm cacheflush , +.Nm _flush_cache +.Nd CPU cache synchronization functions +.Sh SYNOPSIS +.\" These functions live in libc. +.In machine/sysarch.h +.Ft int +.Fn cacheflush "void *addr" "int nbytes" "int cache" +.Ft int +.Fn _flush_cache "char *addr" "int nbytes" "int cache" +.Sh DESCRIPTION +.Fn cacheflush +allows a process to synchronize the contents of the processor caches with +main memory. +Since MIPS processors have separate instruction and data caches, this +function allows for dynamically generated code to run correctly. +.Pp +.Nm +operates on a contiguous memory range in the current process address space, +starting at address +.Fa addr +and +.Fa nbytes +bytes long. +The caches to be synchronized are specified in the +.Fa cache +argument with one of the following values: +.Pp +.Bl -tag -width "ICACHEXXX" -compact -offset ind +.It Dv ICACHE +synchronize the instruction cache +.It Dv DCACHE +synchronize the data cache +.It Dv BCACHE +synchronize both the instruction and data caches +.El +.Pp +.Nm _flush_cache +is an alias for the +.Nm cacheflush +function. +.Sh RETURN VALUES +Upon successful completion, +.Nm +returns zero. +Otherwise, a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Nm +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The address range specified by +.Fa addr +and +.Fa nbytes +is not part of the process allocated address space. +.It Bq Er EINVAL +.Fa cache +is not valid. +.El diff --git a/static/openbsd/man3/cacos.3 b/static/openbsd/man3/cacos.3 new file mode 100644 index 00000000..e99512ac --- /dev/null +++ b/static/openbsd/man3/cacos.3 @@ -0,0 +1,68 @@ +.\" $OpenBSD: cacos.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CACOS 3 +.Os +.Sh NAME +.Nm cacos , +.Nm cacosf , +.Nm cacosl +.Nd complex circular arc cosine +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn cacos , +.Fn cacosf +and +.Fn cacosl +functions compute the complex circular arc cosine of +.Fa z . +.Pp +For all complex floating-point numbers +.Fa z , +.Bd -literal -offset indent +cacos(z) = Pi/2 - casin(z). +.Ed +.Sh RETURN VALUES +The +.Fn cacos , +.Fn cacosf +and +.Fn cacosl +functions return the complex circular arc cosine of +.Fa z +with unbounded imaginary part, and real part in the interval +.Bq 0, Pi . +.Sh SEE ALSO +.Xr casin 3 , +.Xr catan 3 +.Sh STANDARDS +The +.Fn cacos , +.Fn cacosf +and +.Fn cacosl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/cacosh.3 b/static/openbsd/man3/cacosh.3 new file mode 100644 index 00000000..d3abeeab --- /dev/null +++ b/static/openbsd/man3/cacosh.3 @@ -0,0 +1,69 @@ +.\" $OpenBSD: cacosh.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CACOSH 3 +.Os +.Sh NAME +.Nm cacosh , +.Nm cacoshf , +.Nm cacoshl +.Nd complex inverse hyperbolic cosine +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn cacosh , +.Fn cacoshf +and +.Fn cacoshl +functions compute the complex inverse hyperbolic cosine of +.Fa z . +.Pp +For all complex floating-point numbers +.Fa z , +.Bd -literal -offset indent +cacosh(z) = i acos(z). +.Ed +.Sh RETURN VALUES +The +.Fn cacosh , +.Fn cacoshf +and +.Fn cacoshl +functions return the complex inverse hyperbolic cosine of +.Fa z +with imaginary part in the interval +.Bq -Pi, Pi , +and non-negative real part. +.Sh SEE ALSO +.Xr casinh 3 , +.Xr catanh 3 +.Sh STANDARDS +The +.Fn cacosh , +.Fn cacoshf +and +.Fn cacoshl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/carg.3 b/static/openbsd/man3/carg.3 new file mode 100644 index 00000000..47c98f95 --- /dev/null +++ b/static/openbsd/man3/carg.3 @@ -0,0 +1,60 @@ +.\" $OpenBSD: carg.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CARG 3 +.Os +.Sh NAME +.Nm carg , +.Nm cargf , +.Nm cargl +.Nd complex argument functions +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn carg , +.Fn cargf +and +.Fn cargl +functions compute the argument (also called phase angle) of +.Fa z , +with a branch cut on the negative real axis. +.Sh RETURN VALUES +The +.Fn carg , +.Fn cargf +and +.Fn cargl +functions return the argument in the interval +.Bq -Pi, Pi . +.Sh SEE ALSO +.Xr cimag 3 +.Sh STANDARDS +The +.Fn carg , +.Fn cargf +and +.Fn cargl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/casin.3 b/static/openbsd/man3/casin.3 new file mode 100644 index 00000000..f40fb882 --- /dev/null +++ b/static/openbsd/man3/casin.3 @@ -0,0 +1,68 @@ +.\" $OpenBSD: casin.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CASIN 3 +.Os +.Sh NAME +.Nm casin , +.Nm casinf , +.Nm casinl +.Nd complex circular arc sine +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn casin , +.Fn casinf +and +.Fn casinl +functions compute the complex circular arc sine of +.Fa z . +.Pp +For all complex floating-point numbers +.Fa z , +.Bd -literal -offset indent +casin(z) = -i clog(iz + csqrt(1 - z^2)). +.Ed +.Sh RETURN VALUES +The +.Fn casin , +.Fn casinf +and +.Fn casinl +functions return the complex circular arc sine of +.Fa z +with unbounded imaginary part, and real part in the interval +.Bq -Pi/2, Pi/2 . +.Sh SEE ALSO +.Xr cacos 3 , +.Xr catan 3 +.Sh STANDARDS +The +.Fn casin , +.Fn casinf +and +.Fn casinl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/casinh.3 b/static/openbsd/man3/casinh.3 new file mode 100644 index 00000000..94d78981 --- /dev/null +++ b/static/openbsd/man3/casinh.3 @@ -0,0 +1,69 @@ +.\" $OpenBSD: casinh.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CASINH 3 +.Os +.Sh NAME +.Nm casinh , +.Nm casinhf , +.Nm casinhl +.Nd complex inverse hyperbolic sine +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn casinh , +.Fn casinhf +and +.Fn casinhl +functions compute the complex inverse hyperbolic sine of +.Fa z . +.Pp +For all complex floating-point numbers +.Fa z , +.Bd -literal -offset indent +casinh(z) = -i casin(iz). +.Ed +.Sh RETURN VALUES +The +.Fn casinh , +.Fn casinhf +and +.Fn casinhl +functions return the complex inverse hyperbolic sine of +.Fa z +with imaginary part in the interval +.Bq -Pi/2, Pi/2 , +and unbounded real part. +.Sh SEE ALSO +.Xr cacosh 3 , +.Xr catanh 3 +.Sh STANDARDS +The +.Fn casinh , +.Fn casinhf +and +.Fn casinhl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/catan.3 b/static/openbsd/man3/catan.3 new file mode 100644 index 00000000..1bd376a4 --- /dev/null +++ b/static/openbsd/man3/catan.3 @@ -0,0 +1,70 @@ +.\" $OpenBSD: catan.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CATAN 3 +.Os +.Sh NAME +.Nm catan , +.Nm catanf , +.Nm catanl +.Nd complex circular arc tangent +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn catan , +.Fn catanf +and +.Fn catanl +functions compute the complex circular arc tangent of +.Fa z . +.Pp +If +.Fa z += x + iy, then +.Bd -literal -offset indent +Re catan(z) = 1/2 * atan(2x / (1 - x^2 - y^2)) + k Pi. +Im catan(z) = 1/4 * log((x^2 + (y + 1)^2) / (x^2 + (y - 1)^2)). +.Ed +.Sh RETURN VALUES +The +.Fn catan , +.Fn catanf +and +.Fn catanl +functions return the complex circular arc tangent of +.Fa z +with unbounded imaginary part, and real part in the interval +.Bq -Pi/2, Pi/2 . +.Sh SEE ALSO +.Xr cacos 3 , +.Xr casin 3 +.Sh STANDARDS +The +.Fn catan , +.Fn catanf +and +.Fn catanl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/catanh.3 b/static/openbsd/man3/catanh.3 new file mode 100644 index 00000000..7fd5dd2a --- /dev/null +++ b/static/openbsd/man3/catanh.3 @@ -0,0 +1,69 @@ +.\" $OpenBSD: catanh.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CATANH 3 +.Os +.Sh NAME +.Nm catanh , +.Nm catanhf , +.Nm catanhl +.Nd complex inverse hyperbolic tangent +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn catanh , +.Fn catanhf +and +.Fn catanhl +functions compute the complex inverse hyperbolic tangent of +.Fa z . +.Pp +For all complex floating-point numbers +.Fa z , +.Bd -literal -offset indent +catanh(z) = -i catan(iz). +.Ed +.Sh RETURN VALUES +The +.Fn catanh , +.Fn catanhf +and +.Fn catanhl +functions return the complex inverse hyperbolic tangent of +.Fa z +with imaginary part in the interval +.Bq -Pi/2, Pi/2 , +and unbounded real part. +.Sh SEE ALSO +.Xr cacosh 3 , +.Xr casinh 3 +.Sh STANDARDS +The +.Fn catanh , +.Fn catanhf +and +.Fn catanhl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/catclose.3 b/static/openbsd/man3/catclose.3 new file mode 100644 index 00000000..a17f7eb0 --- /dev/null +++ b/static/openbsd/man3/catclose.3 @@ -0,0 +1,28 @@ +.\" $OpenBSD: catclose.3,v 1.7 2013/06/05 03:39:23 tedu Exp $ +.\" +.\" Written by J.T. Conklin . +.\" Public domain. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt CATCLOSE 3 +.Os +.Sh NAME +.Nm catclose +.Nd close message catalog +.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 catgets 3 , +.Xr catopen 3 +.Sh STANDARDS +The +.Fn catclose +function conforms to +.St -xpg3 . diff --git a/static/openbsd/man3/catgets.3 b/static/openbsd/man3/catgets.3 new file mode 100644 index 00000000..3b5a03eb --- /dev/null +++ b/static/openbsd/man3/catgets.3 @@ -0,0 +1,42 @@ +.\" $OpenBSD: catgets.3,v 1.7 2013/06/05 03:39:23 tedu Exp $ +.\" +.\" Written by J.T. Conklin . +.\" Public domain. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt CATGETS 3 +.Os +.Sh NAME +.Nm catgets +.Nd retrieve string from message catalog +.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 SEE ALSO +.Xr catclose 3 , +.Xr catopen 3 +.Sh STANDARDS +The +.Fn catgets +function conforms to +.St -xpg3 . diff --git a/static/openbsd/man3/catopen.3 b/static/openbsd/man3/catopen.3 new file mode 100644 index 00000000..81bf22e9 --- /dev/null +++ b/static/openbsd/man3/catopen.3 @@ -0,0 +1,62 @@ +.\" $OpenBSD: catopen.3,v 1.8 2013/06/05 03:39:23 tedu Exp $ +.\" +.\" Written by J.T. Conklin . +.\" Public domain. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt CATOPEN 3 +.Os +.Sh NAME +.Nm catopen +.Nd open message catalog +.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 +.Ql / , +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 +.Ql \&%N . +.Pp +If the +.Fa oflag +argument is +.Dv NL_CAT_LOCALE , +the +.Ev LC_MESSAGES +environment variable is used to select the message catalog. +If the +.Fa oflag +argument is zero, the +.Ev LANG +environment variable is used to select the message catalog. +.Sh RETURN VALUES +Upon successful completion, +.Fn catopen +returns a message catalog descriptor. +Otherwise, \-1 is returned and +.Va errno +is set to indicate the error. +.Sh SEE ALSO +.Xr catclose 3 , +.Xr catgets 3 +.Sh STANDARDS +The +.Fn catopen +function conforms to +.St -p1003.1-2008 . diff --git a/static/openbsd/man3/ccos.3 b/static/openbsd/man3/ccos.3 new file mode 100644 index 00000000..b70dd2e0 --- /dev/null +++ b/static/openbsd/man3/ccos.3 @@ -0,0 +1,67 @@ +.\" $OpenBSD: ccos.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CCOS 3 +.Os +.Sh NAME +.Nm ccos , +.Nm ccosf , +.Nm ccosl +.Nd complex circular cosine +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn ccos , +.Fn ccosf +and +.Fn ccosl +functions compute the complex circular cosine of +.Fa z . +.Pp +If +.Fa z += x + iy, then +.Bd -literal -offset indent +ccos(z) = cos(x) cosh(y) - i sin(x) sinh(y). +.Ed +.Sh RETURN VALUES +The +.Fn ccos , +.Fn ccosf +and +.Fn ccosl +functions return the complex circular cosine of +.Fa z . +.Sh SEE ALSO +.Xr csin 3 , +.Xr ctan 3 +.Sh STANDARDS +The +.Fn ccos , +.Fn ccosf +and +.Fn ccosl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/ccosh.3 b/static/openbsd/man3/ccosh.3 new file mode 100644 index 00000000..f4f22746 --- /dev/null +++ b/static/openbsd/man3/ccosh.3 @@ -0,0 +1,67 @@ +.\" $OpenBSD: ccosh.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CCOSH 3 +.Os +.Sh NAME +.Nm ccosh , +.Nm ccoshf , +.Nm ccoshl +.Nd complex hyperbolic cosine +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn ccosh , +.Fn ccoshf +and +.Fn ccoshl +functions compute the complex hyperbolic cosine of +.Fa z . +.Pp +If +.Fa z += x + iy, then +.Bd -literal -offset indent +ccosh(z) = cosh(x) cos(y) + i sinh(x) sin(y). +.Ed +.Sh RETURN VALUES +The +.Fn ccosh , +.Fn ccoshf +and +.Fn ccoshl +functions return the complex hyperbolic cosine of +.Fa z . +.Sh SEE ALSO +.Xr csinh 3 , +.Xr ctanh 3 +.Sh STANDARDS +The +.Fn ccosh , +.Fn ccoshf +and +.Fn ccoshl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/ceil.3 b/static/openbsd/man3/ceil.3 new file mode 100644 index 00000000..80003e2e --- /dev/null +++ b/static/openbsd/man3/ceil.3 @@ -0,0 +1,72 @@ +.\" $OpenBSD: ceil.3,v 1.16 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt CEIL 3 +.Os +.Sh NAME +.Nm ceil , +.Nm ceilf , +.Nm ceill +.Nd round to smallest integral value greater than or equal to x +.Sh SYNOPSIS +.Lb libm +.In math.h +.Ft double +.Fn ceil "double x" +.Ft float +.Fn ceilf "float x" +.Ft long double +.Fn ceill "long double x" +.Sh DESCRIPTION +The +.Fn ceil +function returns the smallest integral value +greater than or equal to +.Fa x . +The +.Fn ceilf +function is a single precision version of +.Fn ceil . +The +.Fn ceill +function is an extended precision version of +.Fn ceil . +.Sh SEE ALSO +.Xr abs 3 , +.Xr fabs 3 , +.Xr floor 3 , +.Xr nextafter 3 , +.Xr rint 3 +.Sh STANDARDS +The +.Fn ceil +function conforms to +.St -ansiC . diff --git a/static/openbsd/man3/cexp.3 b/static/openbsd/man3/cexp.3 new file mode 100644 index 00000000..27b7942c --- /dev/null +++ b/static/openbsd/man3/cexp.3 @@ -0,0 +1,67 @@ +.\" $OpenBSD: cexp.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CEXP 3 +.Os +.Sh NAME +.Nm cexp , +.Nm cexpf , +.Nm cexpl +.Nd complex exponential functions +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn cexp , +.Fn cexpf +and +.Fn cexpl +functions compute the exponential of +.Fa z . +.Pp +If +.Fa z += x + iy, then +.Bd -literal -offset indent +cexp(z) = exp(x) cos(y) + i exp(x) sin(y). +.Ed +.Sh RETURN VALUES +The +.Fn cexp , +.Fn cexpf +and +.Fn cexpl +functions return the exponential of +.Fa z . +.Sh SEE ALSO +.Xr clog 3 , +.Xr cpow 3 +.Sh STANDARDS +The +.Fn cexp , +.Fn cexpf +and +.Fn cexpl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/cgetent.3 b/static/openbsd/man3/cgetent.3 new file mode 100644 index 00000000..4932746f --- /dev/null +++ b/static/openbsd/man3/cgetent.3 @@ -0,0 +1,595 @@ +.\" $OpenBSD: cgetent.3,v 1.3 2022/03/31 17:27:15 naddy 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. +.\" +.Dd $Mdocdate: March 31 2022 $ +.Dt CGETENT 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 cgetusedb +.Nd capability database access routines +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn cgetent "char **buf" "char **db_array" "const char *name" +.Ft int +.Fn cgetset "const char *ent" +.Ft int +.Fn cgetmatch "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" "char **db_array" +.Ft int +.Fn cgetnext "char **buf" "char **db_array" +.Ft int +.Fn cgetclose "void" +.Ft int +.Fn cgetusedb "int usedb" +.Sh DESCRIPTION +The +.Fn cgetent +function extracts the capability record +.Fa name +from the database specified by the null-terminated +file array +.Fa db_array +and returns a pointer to a +copy of it in +.Fa buf . +.Fn cgetent +will first look for files ending in +.Dq .db +(see +.Xr cap_mkdb 1 ) +before accessing the +.Tn ASCII +version of the capability database. +.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 Ns \&'d. +On success 0 is returned, 1 if the returned +record contains an unresolved +.Ic tc +expansion, +\-1 if the requested record couldn't be found, +\-2 if a system error occurred (couldn't open or read a file, +for example) also +setting +.Va errno , +and \-3 if a potential reference loop is detected (see +.Ic tc= +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. +.Fn cgetset +must precede the database traversal. +It must be called before +.Fn cgetent . +If a sequential access is being performed (see below), it must be called +before the first sequential access call +.Pf ( Fn cgetfirst +or +.Fn cgetnext ) , +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 or +.Dv NULL +if the requested capability couldn't be +found. +The end of the capability value is signaled by a +.Sq \&: +or +.Tn ASCII +NUL +(see below for capability database 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 . +On success 0 is returned, \-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, NUL-terminated, +.Xr malloc 3 Ns \&'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 +NUL) is returned on success, \-1 if the requested string capability couldn't +be found, or \-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 +and +.Fn cgetnext +comprise a function group that provides for sequential +access of the null-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 Ns \&'d +copy pointed to by +.Fa buf . +.Ic tc +expansion is done (see +.Ic tc= +comments below). +Upon completion of the database 0 is returned; 1 is returned upon successful +return of a record with possibly more remaining (the end of the database has +not been reached yet); 2 is returned if the record contains an unresolved +.Ic tc +expansion; \-1 is returned if a system error occurred; and \-2 +is returned if a potential reference loop is detected (see +.Ic tc= +comments below). +Upon completion of database (0 return), the database is closed. +.Pp +.Fn cgetclose +closes the file descriptor and resets state used for sequential access. +If neither the +.Fn cgetfirst +nor the +.Fn cgetnext +functions have been called, +.Fn cgetclose +has no effect. +Note that it does not erase the buffer pushed by a call to +.Fn cgetset , +nor does it free the buffer allocated by +.Fn cgetent . +.Pp +.Fn cgetusedb +allows the user to specify whether to use or ignore database files ending in +.Dq .db . +If +.Ar usedb +is zero, files ending in +.Dq .db +will be ignored. +If +.Ar usedb +is non-zero, files ending in +.Dq .db +will be used in preference to the text version. +The default is to process +.Dq .db +files. +.Fn cgetusedb +returns the previous setting. +.Ss Capability database syntax +Capability databases are normally +.Tn ASCII +and may be edited with standard +text editors. +Blank lines and lines beginning with a +.Sq \&# +are comments and are ignored. +Lines ending with a +.Sq \|\e +indicate that the next line is a continuation of the current line; the +.Sq \|\e +and following newline are ignored. +Long lines are usually continued onto several physical +lines by ending each line except the last with a +.Sq \|\e . +.Pp +Capability databases consist of a series of records, one per logical +line. +Each record contains a variable number of colon-separated fields +(capabilities). +Empty fields consisting entirely of whitespace +characters (spaces and tabs) are ignored. +.Pp +The first capability of each record specifies its names, separated by +.Sq \&| +characters. +These names are used to reference records in the database. +By convention, the last name is usually a comment and is not intended as +a lookup tag. +For example, the +.Dq vt220 +record from the +.Nm termcap +database begins with +.Pp +.Dl "vt220\||\|vt200\||\|dec vt220:" +.Pp +giving two names that can be used to access this record. +.Pp +The remaining non-empty capabilities describe a set of (name, value) +bindings, consisting of a name optionally followed by a typed value: +.Bl -column "nameTvalue" -offset indent +.It name Ta "typeless [boolean] capability" +.Em name No "is present [true]" +.It name Ns Em \&T Ns value Ta capability +.Pq Em name , \&T +has value +.Em value +.It name@ Ta "no capability" Em name No exists +.It name Ns Em T Ns \&@ Ta capability +.Pq Em name , T +does not exist +.El +.Pp +Names consist of one or more characters. +Names may contain any character except +.Sq \&: , +but it's usually best to restrict them to the printable +characters and avoid use of graphics like +.Sq \&# , +.Sq \&= , +.Sq \&% , +.Sq \&@ , +etc. +Types are single characters used to separate capability names from their +associated typed values. +Types may be any character except a +.Sq \&: . +Typically, graphics like +.Sq \&# , +.Sq \&= , +.Sq \&% , +etc. are used. +Values may be any number of characters and may contain any character except +.Sq \&: . +.Ss 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 "(cgetcap(buf, name, ':') != NULL)" +.Pp +A special capability, +.Ic tc= name , +is used to indicate that the record specified by +.Fa name +should be substituted for the +.Ic tc +capability. +.Ic tc +capabilities may interpolate records which also contain +.Ic tc +capabilities and more than one +.Ic tc +capability may be used in a record. +A +.Ic tc +expansion scope (i.e., where the argument is searched for) contains the +file in which the +.Ic tc +is declared and all subsequent files in the file array. +.Pp +When a database is searched for a capability record, the first matching +record in the search is returned. +When a record is scanned for a +capability, the first matching capability is returned; the capability +.Ic :nameT@: +will hide any following definition of a value of type +.Em T +for +.Fa name ; +and the capability +.Ic :name@: +will prevent any following values of +.Fa name +from being seen. +.Pp +These features combined with +.Ic tc +capabilities can be used to generate variations of other databases and +records by either adding new capabilities, overriding definitions with new +definitions, or hiding following definitions via +.Sq \&@ +capabilities. +.Ss cgetnum() and cgetstr() syntax and semantics +Two types are predefined by +.Fn cgetnum +and +.Fn cgetstr : +.Bl -column "nameXnumber" -offset indent +.It Em name Ns \&# Ns Em number Ta numeric +capability +.Em name +has value +.Em number +.It Em name Ns = Ns Em string Ta "string capability" +.Em name +has value +.Em string +.It Em name Ns \&#@ Ta "the numeric capability" +.Em name +does not exist +.It Em name Ns \&=@ Ta "the string capability" +.Em name +does not exist +.El +.Pp +Numeric capability values may be given in one of three numeric bases. +If the number starts with either +.Ql 0x +or +.Ql 0X , +it is interpreted as a hexadecimal number (both upper and lower case a-f +may be used to denote the extended hexadecimal digits). +Otherwise, if the number starts with a +.Ql 0 +it is interpreted as an octal number. +Otherwise the number is interpreted as a decimal number. +.Pp +String capability values may contain any character. +Non-printable +.Dv ASCII +codes, new lines, and colons may be conveniently represented by the use +of escape sequences: +.Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)" -offset indent +.It ^X ('\fIX\fP'\~&\~037) control-\fIX\fP +.It \e\|b,\~\e\|B (ASCII\~010) backspace +.It \e\|t,\~\e\|T (ASCII\~011) tab +.It \e\|n,\~\e\|N (ASCII\~012) line\~feed\~(newline) +.It \e\|f,\~\e\|F (ASCII\~014) form\~feed +.It \e\|r,\~\e\|R (ASCII\~015) carriage\~return +.It \e\|e,\~\e\|E (ASCII\~027) escape +.It \e\|c,\~\e\|C (:) colon +.It \e\|\e (\e\|) backslash +.It \e\|^ (^) caret +.It \e\|\fInnn\fP (ASCII\~octal\~\fInnn\fP) +.El +.Pp +A +.Sq \|\e +followed by up to three octal digits directly specifies +the numeric code for a character. +The use of +.Tn ASCII +NULs, while easily +encoded, causes all sorts of problems and must be used with care since +NULs are typically used to denote the end of strings; many applications +use +.Sq \e\|200 +to represent a NUL. +.Sh EXAMPLES +.Bd -unfilled -offset indent +example\||\|an example of binding multiple values to names:\e + :foo%bar:foo^blah:foo@:\e + :abc%xyz:abc^frap:abc$@:\e + :tc=more: +.Ed +.Pp +The capability foo has two values bound to it (bar of type +.Sq \&% +and blah of +type +.Sq \&^ ) +and any other value bindings are hidden. +The capability abc also has two values bound but only a value of type +.Sq \&$ +is prevented from +being defined in the capability record more. +.Bd -unfilled -offset indent +file1: + new\||\|new_record\||\|a modification of "old":\e + :fript=bar:who-cares@:tc=old:blah:tc=extensions: +file2: + old\||\|old_record\||\|an old database record:\e + :fript=foo:who-cares:glork#200: +.Ed +.Pp +The records are extracted by calling +.Fn cgetent +with file1 preceding file2. +In the capability record new in file1, fript=bar overrides the definition +of fript=foo interpolated from the capability record old in file2, +who-cares@ prevents the definition of any who-cares definitions in old +from being seen, glork#200 is inherited from old, and blah and anything +defined by the record extensions is added to those definitions in old. +Note that the position of the fript=bar and who-cares@ definitions before +tc=old is important here. +If they were after, the definitions in old would take precedence. +.Sh DIAGNOSTICS +.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 cgetent +and +.Fn cgetset +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 +.Sh BUGS +Colon +.Pq Sq \&: +characters +or vertical bar +.Pq Sq | +characters cannot be used in names. +.Pp +There are no checks for +.Ic 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/openbsd/man3/check_expire.3 b/static/openbsd/man3/check_expire.3 new file mode 100644 index 00000000..cdf43ce6 --- /dev/null +++ b/static/openbsd/man3/check_expire.3 @@ -0,0 +1,63 @@ +.\" $OpenBSD: check_expire.3,v 1.12 2025/06/06 22:01:39 schwarze Exp $ +.\" +.\" Copyright (c) 2000 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. +.\" +.Dd $Mdocdate: June 6 2025 $ +.Dt LOGIN_CHECK_EXPIRE 3 +.Os +.Sh NAME +.Nm login_check_expire +.Nd check for password expiration +.Sh SYNOPSIS +.Lb libutil +.In stdio.h +.In util.h +.Ft int +.Fn login_check_expire "FILE *back" "struct passwd *pwd" "char *class" "int lastchance" +.Sh DESCRIPTION +The +.Fn login_check_expire +function is called by a +.Bx +Authentication login script to +check whether the user's password entry, as described by +.Fa pwd , +has expired. +.Pp +If a +.Fa class +is specified, it is used instead of the class specified in the user's +password database entry. +If the +.Fa lastchance +argument is non-zero, the user's password has expired, and it has not been +expired longer than +.Dq password-dead +seconds (see +.Xr login.conf 5 ) , +the user will be able to log in one last time to change the password. +.Sh RETURN VALUES +The +.Fn login_check_expire +function returns 0 if the user's password has not expired, and 1 if it has +expired or if an error occurred. +.br +Status and error messages are passed +back to the login script caller via the back channel, +.Fa back . +.Sh SEE ALSO +.Xr auth_subr 3 , +.Xr authenticate 3 , +.Xr login.conf 5 diff --git a/static/openbsd/man3/cimag.3 b/static/openbsd/man3/cimag.3 new file mode 100644 index 00000000..d1713300 --- /dev/null +++ b/static/openbsd/man3/cimag.3 @@ -0,0 +1,60 @@ +.\" $OpenBSD: cimag.3,v 1.5 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2010 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. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt CIMAG 3 +.Os +.Sh NAME +.Nm cimag , +.Nm cimagf , +.Nm cimagl +.Nd compute the imaginary part of a complex number +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn cimag , +.Fn cimagf +and +.Fn cimagl +functions compute the imaginary part of +.Fa z . +.Sh RETURN VALUES +The +.Fn cimag , +.Fn cimagf +and +.Fn cimagl +functions return the imaginary part of the complex number +.Fa z +as a real number. +.Sh SEE ALSO +.Xr carg 3 +.Sh STANDARDS +The +.Fn cimag , +.Fn cimagf +and +.Fn cimagl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/clock.3 b/static/openbsd/man3/clock.3 new file mode 100644 index 00000000..1d21746f --- /dev/null +++ b/static/openbsd/man3/clock.3 @@ -0,0 +1,61 @@ +.\" $OpenBSD: clock.3,v 1.8 2013/06/05 03:39:22 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt CLOCK 3 +.Os +.Sh NAME +.Nm clock +.Nd determine processor time used +.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/openbsd/man3/clock_getcpuclockid.3 b/static/openbsd/man3/clock_getcpuclockid.3 new file mode 100644 index 00000000..d98c8bdd --- /dev/null +++ b/static/openbsd/man3/clock_getcpuclockid.3 @@ -0,0 +1,65 @@ +.\" $OpenBSD: clock_getcpuclockid.3,v 1.3 2015/01/15 19:26:27 schwarze Exp $ +.\" +.\" Copyright (c) 2013 Philip Guenther +.\" +.\" 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: January 15 2015 $ +.Dt CLOCK_GETCPUCLOCKID 3 +.Os +.Sh NAME +.Nm clock_getcpuclockid +.Nd get a clock measuring process CPU time +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn clock_getcpuclockid "pid_t pid" "clockid_t *clock_id" +.Sh DESCRIPTION +The +.Fn clock_getcpuclockid +function allows the calling process to get a +.Vt clockid_t +value that measures the time spent by CPUs running in user or kernel mode +on behalf of the process specified by +.Fa pid . +If +.Fa pid +is zero, then a clock for the calling process will be returned. +.Sh RETURN VALUES +If successful, +.Fn clock_getcpuclockid +will return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn clock_getcpuclockid +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +.Fa pid +is neither zero nor the PID of the calling process. +.El +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr pthread_getcpuclockid 3 +.Sh STANDARDS +The +.Fn clock_getcpuclockid +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn clock_getcpuclockid +function first appeared in IEEE Std 1003.1d-1999 +.Pq Dq POSIX.1d +and has been available since +.Ox 5.4 . diff --git a/static/openbsd/man3/clog.3 b/static/openbsd/man3/clog.3 new file mode 100644 index 00000000..697ce2b5 --- /dev/null +++ b/static/openbsd/man3/clog.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: clog.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CLOG 3 +.Os +.Sh NAME +.Nm clog , +.Nm clogf , +.Nm clogl +.Nd complex natural logarithm +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn clog , +.Fn clogf +and +.Fn clogl +functions compute the complex logarithm to the base +.Ms e +(2.718...) of +.Fa z . +.Pp +If +.Fa z += x + iy, then +.Bd -literal -offset indent +clog(z) = log(sqrt(x^2 + y^2)) + i atan(y / x). +.Ed +.Sh RETURN VALUES +The +.Fn clog , +.Fn clogf +and +.Fn clogl +functions return the complex logarithm to the base +.Ms e +of +.Fa z +with imaginary part in the interval +.Bq -Pi, Pi , +and unbounded real part. +.Sh SEE ALSO +.Xr cexp 3 , +.Xr cpow 3 +.Sh STANDARDS +The +.Fn clog , +.Fn clogf +and +.Fn clogl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/compress.3 b/static/openbsd/man3/compress.3 new file mode 100644 index 00000000..114d9b2b --- /dev/null +++ b/static/openbsd/man3/compress.3 @@ -0,0 +1,4032 @@ +.\" $OpenBSD: compress.3,v 1.35 2026/03/23 09:11:44 jsg Exp $ +.\" +.\" Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler +.\" +.\" 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. +.\" +.\" 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: +.\" +.\" 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. +.\" Altered source versions must be plainly marked as such, and must not be +.\" misrepresented as being the original software. +.\" This notice may not be removed or altered from any source distribution. +.\" +.\" Converted to mdoc format for the OpenBSD project +.\" by Jason McIntyre +.\" +.Dd $Mdocdate: March 23 2026 $ +.Dt COMPRESS 3 +.Os +.Sh NAME +.Nm compress , +.Nm compress_z , +.Nm zlibVersion , +.Nm deflateInit , +.Nm deflate , +.Nm deflateEnd , +.Nm inflateInit , +.Nm inflate , +.Nm inflateEnd , +.Nm deflateInit2 , +.Nm deflateSetDictionary , +.Nm deflateGetDictionary , +.Nm deflateCopy , +.Nm deflateReset , +.Nm deflateParams , +.Nm deflateTune , +.Nm deflateBound , +.Nm deflateBound_z , +.Nm deflatePending , +.Nm deflateUsed , +.Nm deflatePrime , +.Nm deflateSetHeader , +.Nm inflateInit2 , +.Nm inflateSetDictionary , +.Nm inflateGetDictionary , +.Nm inflateSync , +.Nm inflateCopy , +.Nm inflateReset , +.Nm inflateReset2 , +.Nm inflatePrime , +.Nm inflateMark , +.Nm inflateGetHeader , +.Nm inflateBackInit , +.Nm inflateBack , +.Nm inflateBackEnd , +.Nm zlibCompileFlags , +.Nm compress2 , +.Nm compress2_z , +.Nm compressBound , +.Nm compressBound_z , +.Nm uncompress , +.Nm uncompress_z , +.Nm uncompress2 , +.Nm uncompress2_z , +.Nm gzopen , +.Nm gzdopen , +.Nm gzbuffer , +.Nm gzsetparams , +.Nm gzread , +.Nm gzfread , +.Nm gzwrite , +.Nm gzfwrite , +.Nm gzprintf , +.Nm gzputs , +.Nm gzgets , +.Nm gzputc , +.Nm gzgetc , +.Nm gzungetc , +.Nm gzflush , +.Nm gzseek , +.Nm gzrewind , +.Nm gztell , +.Nm gzoffset , +.Nm gzeof , +.Nm gzdirect , +.Nm gzclose , +.Nm gzclose_r , +.Nm gzclose_w , +.Nm gzerror , +.Nm gzclearerr , +.Nm adler32 , +.Nm adler32_z , +.Nm adler32_combine , +.Nm crc32 , +.Nm crc32_z , +.Nm crc32_combine , +.Nm crc32_combine_gen , +.Nm crc32_combine_op +.Nd zlib general purpose compression library +.Sh SYNOPSIS +.Lb libz +.In zlib.h +.Pp +Basic functions +.Pp +.Ft const char * +.Fn zlibVersion "void" +.Ft int +.Fn deflateInit "z_streamp strm" "int level" +.Ft int +.Fn deflate "z_streamp strm" "int flush" +.Ft int +.Fn deflateEnd "z_streamp strm" +.Ft int +.Fn inflateInit "z_streamp strm" +.Ft int +.Fn inflate "z_streamp strm" "int flush" +.Ft int +.Fn inflateEnd "z_streamp strm" +.Pp +Advanced functions +.Pp +.Ft int +.Fn deflateInit2 "z_streamp strm" "int level" "int method" "int windowBits" "int memLevel" "int strategy" +.Ft int +.Fn deflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" +.Ft int +.Fn deflateGetDictionary "z_streamp strm" "Bytef *dictionary" "uInt *dictLength" +.Ft int +.Fn deflateCopy "z_streamp dest" "z_streamp source" +.Ft int +.Fn deflateReset "z_streamp strm" +.Ft int +.Fn deflateParams "z_streamp strm" "int level" "int strategy" +.Ft int +.Fn deflateTune "z_streamp strm" "int good_length" "int max_lazy" "int nice_length" "int max_chain" +.Ft uLong +.Fn deflateBound "z_streamp strm" "uLong sourceLen" +.Ft z_size_t +.Fn deflateBound_z "z_streamp strm" "z_size_t sourceLen" +.Ft int +.Fn deflatePending "z_streamp strm" "unsigned *pending" "int *bits" +.Ft int +.Fn deflateUsed "z_streamp strm" "int *bits" +.Ft int +.Fn deflatePrime "z_streamp strm" "int bits" "int value" +.Ft int +.Fn deflateSetHeader "z_streamp strm" "gz_headerp head" +.Ft int +.Fn inflateInit2 "z_streamp strm" "int windowBits" +.Ft int +.Fn inflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" +.Ft int +.Fn inflateGetDictionary "z_streamp strm" "Bytef *dictionary" "uInt *dictLength" +.Ft int +.Fn inflateSync "z_streamp strm" +.Ft int +.Fn inflateCopy "z_streamp dst" "z_streamp source" +.Ft int +.Fn inflateReset "z_streamp strm" +.Ft int +.Fn inflateReset2 "z_streamp strm" "int windowBits" +.Ft int +.Fn inflatePrime "z_streamp strm" "int bits" "int value" +.Ft int +.Fn inflateMark "z_streamp strm" +.Ft int +.Fn inflateGetHeader "z_streamp strm" "gz_headerp head" +.Ft int +.Fn inflateBackInit "z_stream *strm" "int windowBits" "unsigned char FAR *window" +.Ft int +.Fn inflateBack "z_stream *strm" "in_func in" "void FAR *in_desc" "out_func out" "void FAR *out_desc" +.Ft int +.Fn inflateBackEnd "z_stream *strm" +.Ft uLong +.Fn zlibCompileFlags "void" +.Pp +Utility functions +.Pp +.Fd typedef voidp gzFile; +.Pp +.Ft int +.Fn compress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" +.Ft int +.Fn compress_z "Bytef *dest" "z_size_t *destLen" "const Bytef *source" "z_size_t sourceLen" +.Ft int +.Fn compress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" "int level" +.Ft int +.Fn compress2_z "Bytef *dest" "z_size_t *destLen" "const Bytef *source" "z_size_t sourceLen" "int level" +.Ft uLong +.Fn compressBound "uLong sourceLen" +.Ft z_size_t +.Fn compressBound_z "z_size_t sourceLen" +.Ft int +.Fn uncompress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" +.Ft int +.Fn uncompress_z "Bytef *dest" "z_size_t *destLen" "const Bytef *source" "z_size_t sourceLen" +.Ft int +.Fn uncompress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong *sourceLen" +.Ft int +.Fn uncompress2_z "Bytef *dest" "z_size_t *destLen" "const Bytef *source" "z_size_t *sourceLen" +.Ft gzFile +.Fn gzopen "const char *path" "const char *mode" +.Ft gzFile +.Fn gzdopen "int fd" "const char *mode" +.Ft int +.Fn gzbuffer "gzFile file" "unsigned size" +.Ft int +.Fn gzsetparams "gzFile file" "int level" "int strategy" +.Ft int +.Fn gzread "gzFile file" "voidp buf" "unsigned len" +.Ft int +.Fn gzfread "voidp buf" "z_size_t size" "z_size_t nitems" "gzFile file" +.Ft int +.Fn gzwrite "gzFile file" "voidpc buf" "unsigned len" +.Ft int +.Fn gzfwrite "voidpc buf" "z_size_t size" "z_size_t nitems" "gzFile file" +.Ft int +.Fn gzprintf "gzFile file" "const char *format" "..." +.Ft int +.Fn gzputs "gzFile file" "const char *s" +.Ft char * +.Fn gzgets "gzFile file" "char *buf" "int len" +.Ft int +.Fn gzputc "gzFile file" "int c" +.Ft int +.Fn gzgetc "gzFile file" +.Ft int +.Fn gzungetc "int c" "gzFile file" +.Ft int +.Fn gzflush "gzFile file" "int flush" +.Ft z_off_t +.Fn gzseek "gzFile file" "z_off_t offset" "int whence" +.Ft int +.Fn gzrewind "gzFile file" +.Ft z_off_t +.Fn gztell "gzFile file" +.Ft int +.Fn gzoffset "gzFile file" +.Ft int +.Fn gzeof "gzFile file" +.Ft int +.Fn gzdirect "gzFile file" +.Ft int +.Fn gzclose "gzFile file" +.Ft int +.Fn gzclose_r "gzFile file" +.Ft int +.Fn gzclose_w "gzFile file" +.Ft const char * +.Fn gzerror "gzFile file" "int *errnum" +.Ft void +.Fn gzclearerr "gzFile file" +.Pp +Checksum functions +.Pp +.Ft uLong +.Fn adler32 "uLong adler" "const Bytef *buf" "uInt len" +.Ft uLong +.Fn adler32_z "uLong adler" "const Bytef *buf" "z_size_t len" +.Ft uLong +.Fn adler32_combine "uLong adler1" "uLong adler2" "z_off_t len2" +.Ft uLong +.Fn crc32 "uLong crc" "const Bytef *buf" "uInt len" +.Ft uLong +.Fn crc32_z "uLong adler" "const Bytef *buf" "z_size_t len" +.Ft uLong +.Fn crc32_combine "uLong crc1" "uLong crc2" "z_off_t len2" +.Fn crc32_combine_gen "z_off_t len2" +.Fn crc32_combine_op "uLong crc1" "uLong crc2" "uLong op" +.Sh DESCRIPTION +The +.Nm zlib +compression library provides in-memory compression and decompression functions, +including integrity checks of the uncompressed data. +This version of the library supports only one compression method +.Pq deflation +but other algorithms will be added later and will have the same +stream interface. +.Pp +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 +.Pq providing more output space +before each call. +.Pp +The compressed data format used by default by the in-memory functions is the +.Nm zlib +format, which is a zlib wrapper documented in RFC 1950, +wrapped around a deflate stream, which is itself documented in RFC 1951. +.Pp +The library also supports reading and writing files in +.Xr gzip 1 +.Pq .gz +format with an interface similar to that of +.Xr stdio 3 +using the functions that start with +.Qq gz . +The gzip format is different from the zlib format. +gzip is a gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. +This library can optionally read and write gzip and raw deflate streams +in memory as well. +.Pp +The zlib format was designed to be compact and fast for use in memory +and on communications channels. +The gzip format was designed for single-file compression on file systems, +has a larger header than zlib to maintain directory information, +and uses a different, slower, check method than zlib. +.Pp +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. +.Pp +The functions within the library are divided into the following sections: +.Pp +.Bl -dash -offset indent -compact +.It +Basic functions +.It +Advanced functions +.It +Utility functions +.It +Checksum functions +.El +.Sh BASIC FUNCTIONS +.Bl -tag -width Ds +.It Xo +.Fa const char * +.Fn zlibVersion "void" ; +.Xc +.Pp +The application can compare +.Fn zlibVersion +and +.Dv ZLIB_VERSION +for consistency. +If the first character differs, the library code actually used is +not compatible with the +.In zlib.h +header file used by the application. +This check is automatically made by +.Fn deflateInit +and +.Fn inflateInit . +.It Xo +.Fa int +.Fn deflateInit "z_streamp strm" "int level" ; +.Xc +.Pp +The +.Fn deflateInit +function initializes the internal stream state for compression. +The fields +.Fa zalloc , +.Fa zfree , +and +.Fa opaque +must be initialized before by the caller. +If +.Fa zalloc +and +.Fa zfree +are set to +.Dv NULL , +.Fn deflateInit +updates them to use default allocation functions. +.Fa total_in , +.Fa total_out , +.Fa adler , +and +.Fa msg +are initialized. +.Pp +The compression level must be +.Dv Z_DEFAULT_COMPRESSION , +or between 0 and 9: +1 gives best speed, 9 gives best compression, 0 gives no compression at all +(the input data is simply copied a block at a time). +.Pp +.Dv Z_DEFAULT_COMPRESSION +requests a default compromise between speed and compression +.Pq currently equivalent to level 6 . +.Pp +.Fn deflateInit +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if level is not a valid compression level, +.Dv Z_VERSION_ERROR +if the +.Nm zlib +library version +.Pq zlib_version +is incompatible with the version assumed by the caller +.Pq ZLIB_VERSION . +.Fa msg +is set to null if there is no error message. +.Fn deflateInit +does not perform any compression: this will be done by +.Fn deflate . +.It Xo +.Fa int +.Fn deflate "z_streamp strm" "int flush" ; +.Xc +.Pp +.Fn deflate +compresses as much data as possible, and stops when the input +buffer becomes empty or the output buffer becomes full. +It may introduce some output latency +.Pq reading input without producing any output +except when forced to flush. +.Pp +The detailed semantics are as follows. +.Fn deflate +performs one or both of the following actions: +.Pp +Compress more input starting at +.Fa next_in +and update +.Fa next_in +and +.Fa avail_in +accordingly. +If not all input can be processed +(because there is not enough room in the output buffer), +.Fa next_in +and +.Fa avail_in +are updated and processing will resume at this point for the next call to +.Fn deflate . +.Pp +Generate more output starting at +.Fa next_out +and update +.Fa next_out +and +.Fa avail_out +accordingly. +This action is forced if the parameter +.Fa flush +is non-zero. +Forcing +.Fa flush +frequently degrades the compression ratio, +so this parameter should be set only when necessary. +Some output may be provided even if +.Fa flush +is not set. +.Pp +Before the call to +.Fn deflate , +the application should ensure that at least +one of the actions is possible, by providing more input and/or consuming +more output, and updating +.Fa avail_in +or +.Fa avail_out +accordingly; +.Fa avail_out +should never be zero before the call. +The application can consume the compressed output when it wants, +for example when the output buffer is full +.Pq avail_out == 0 , +or after each call to +.Fn deflate . +If +.Fn deflate +returns +.Dv Z_OK +and with zero +.Fa avail_out , +it must be called again after making room in the +output buffer because there might be more output pending. +See +.Fn deflatePending , +which can be used if desired to determine whether or not there is more output +in that case. +.Pp +Normally the parameter +.Fa flush +is set to +.Dv Z_NO_FLUSH , +which allows +.Fn deflate +to decide how much data to accumulate before producing output, +in order to maximise compression. +.Pp +If the parameter +.Fa flush +is set to +.Dv Z_SYNC_FLUSH , +all pending output is flushed to the output buffer and the output +is aligned on a byte boundary, +so that the decompressor can get all input data available so far. +(In particular +.Fa avail_in +is zero after the call +if enough output space has been provided before the call.) +Flushing may degrade compression for some compression algorithms +and so it should be used only when necessary. +This completes the current deflate block and follows it with +an empty stored block that is three bits plus filler bits to the next byte, +followed by four bytes (00 00 ff ff). +.Pp +If +.Fa flush +is set to +.Dv Z_PARTIAL_FLUSH , +all pending output is flushed to the output buffer, +but the output is not aligned to a byte boundary. +All of the input data so far will be available to the decompressor, as for +.Dv Z_SYNC_FLUSH . +This completes the current deflate block and follows it with an empty fixed +code block that is 10 bits long. +This assures that enough bytes are output in order for the decompressor to +finish the block before the empty fixed codes block. +.Pp +If +.Fa flush +is set to +.Dv Z_BLOCK , +a deflate block is completed and emitted, as for +.Dv Z_SYNC_FLUSH , +but the output is not aligned on a byte boundary, +and up to seven bits of the current block are held to be written as +the next byte after the next deflate block is completed. +In this case, the decompressor may not be provided enough bits at this point in +order to complete decompression of the data provided so far to the compressor. +It may need to wait for the next block to be emitted. +This is for advanced applications that need to control +the emission of deflate blocks. +.Pp +If +.Fa flush +is set to +.Dv Z_FULL_FLUSH , +all output is flushed as with +.Dv Z_SYNC_FLUSH , +and the compression state is reset so that decompression can restart from this +point if previous compressed data has been damaged or if random access +is desired. +Using +.Dv Z_FULL_FLUSH +too often can seriously degrade compression. +.Pp +If +.Fn deflate +returns with avail_out == 0, this function must be called again +with the same value of the flush parameter and more output space +(updated +.Fa avail_out ) , +until the flush is complete +.Pf ( Fn deflate +returns with non-zero +.Fa avail_out ) . +In the case of a +.Dv Z_FULL_FLUSH +or a +.Dv Z_SYNC_FLUSH , +make sure that +.Fa avail_out +is greater than six when the flush marker begins, +in order to avoid repeated flush markers upon calling +.Fn deflate +again when avail_out == 0. +.Pp +If the parameter +.Fa flush +is set to +.Dv Z_FINISH , +pending input is processed, pending output is flushed and +.Fn deflate +returns with +.Dv Z_STREAM_END +if there was enough output space. +If +.Fn deflate +returns with +.Dv Z_OK +or +.Dv Z_BUF_ERROR , +this function must be called again with +.Dv Z_FINISH +and more output space +(updated +.Fa avail_out +but no more input data, until it returns with +.Dv Z_STREAM_END +or an error. +After +.Fn deflate +has returned +.Dv Z_STREAM_END , +the only possible operations on the stream are +.Fn deflateReset +or +.Fn deflateEnd . +.Pp +.Dv Z_FINISH +can be used in the first deflate call after +.Fn deflateInit +if all the compression is to be done in a single step. +In order to complete in one call, +.Fa avail_out +must be at least the value returned by +.Fn deflateBound +(see below). +Then +.Fn deflate +is guaranteed to return +.Dv Z_STREAM_END . +If not enough output space is provided, +.Fn deflate +will not return +.Dv Z_STREAM_END , +and it must be called again as described above. +.Pp +.Fn deflate +sets strm->adler to the Adler-32 checksum of all input read so far +(that is, +.Fa total_in +bytes). +If a gzip stream is being generated, +then strm->adler will be the CRC-32 checksum of the input read so far. +(See +.Fn deflateInit2 +below.) +.Pp +.Fn deflate +may update strm->data_type +if it can make a good guess about the input data type +.Pq Z_BINARY or Z_TEXT . +If in doubt, the data is considered binary. +This field is only for information purposes and does not affect +the compression algorithm in any manner. +.Pp +.Fn deflate +returns +.Dv Z_OK +if some progress has been made +.Pq more input processed or more output produced , +.Dv Z_STREAM_END +if all input has been consumed and all output has been produced +(only when +.Fa flush +is set to +.Dv Z_FINISH ) , +.Dv Z_STREAM_ERROR +if the stream state was inconsistent +(for example, if +.Fa next_in +or +.Fa next_out +was +.Dv NULL +or the state was inadvertently written over by the application), or +.Dv Z_BUF_ERROR +if no progress is possible +(for example, +.Fa avail_in +or +.Fa avail_out +was zero). +Note that +.Dv Z_BUF_ERROR +is not fatal, and +.Fn deflate +can be called again with more input and more output space +to continue compressing. +.It Xo +.Fa int +.Fn deflateEnd "z_streamp strm" ; +.Xc +.Pp +All dynamically allocated data structures for this stream are freed. +This function discards any unprocessed input and does not flush any +pending output. +.Pp +.Fn deflateEnd +returns +.Dv Z_OK +if successful, +.Dv Z_STREAM_ERROR +if the stream state was inconsistent, +.Dv Z_DATA_ERROR +if the stream was freed prematurely +.Pq some input or output was discarded . +In the error case, +.Fa msg +may be set but then points to a static string +.Pq which must not be deallocated . +.It Xo +.Fa int +.Fn inflateInit "z_streamp strm" ; +.Xc +The +.Fn inflateInit +function initializes the internal stream state for decompression. +The fields +.Fa next_in , +.Fa avail_in , +.Fa zalloc , +.Fa zfree , +and +.Fa opaque +must be initialized before by the caller. +In the current version of +.Fn inflate , +the provided input is not read or consumed. +The allocation of a sliding window will be deferred to the first call of +.Fn inflate +(if the decompression does not complete on the first call). +If +.Fa zalloc +and +.Fa zfree +are set to +.Dv NULL , +.Fn inflateInit +updates them to use default allocation functions. +.Fa total_in , +.Fa total_out , +.Fa adler , +and +.Fa msg +are initialized. +.Pp +.Fn inflateInit +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_VERSION_ERROR +if the +.Nm zlib +library version is incompatible with the version assumed by the caller or +.Dv Z_STREAM_ERROR +if the parameters are invalid, such as a null pointer to the structure. +.Fa msg +is set to null if there is no error message. +.Fn inflateInit +does not perform any decompression. +Actual decompression will be done by +.Fn inflate . +So +.Fa next_in , avail_in , next_out , +and +.Fa avail_out +are unused and unchanged. +The current implementation of +.Fn inflateInit +does not process any header information \(em +that is deferred until +.Fn inflate +is called. +.It Xo +.Fa int +.Fn inflate "z_streamp strm" "int flush" ; +.Xc +.Fn inflate +decompresses as much data as possible, and stops when the input +buffer becomes empty or the output buffer becomes full. +It may introduce some output latency +.Pq reading input without producing any output +except when forced to flush. +.Pp +The detailed semantics are as follows. +.Fn inflate +performs one or both of the following actions: +.Pp +Decompress more input starting at +.Fa next_in +and update +.Fa next_in +and +.Fa avail_in +accordingly. +If not all input can be processed +(because there is not enough room in the output buffer), then +.Fa next_in +and +.Fa avail_in +are updated accordingly, +and processing will resume at this point for the next call to +.Fn inflate . +.Pp +Generate more output starting at +.Fa next_out +and update +.Fa next_out +and +.Fa avail_out +accordingly. +.Fn inflate +provides as much output as possible, +until there is no more input data or no more space in the output buffer +.Pq see below about the flush parameter . +.Pp +Before the call to +.Fn inflate , +the application should ensure that at least one of the actions is possible, +by providing more input and/or consuming more output, +and updating the next_* and avail_* values accordingly. +If the caller of +.Fn inflate +does not provide both available input and available output space, +it is possible that there will be no progress made. +The application can consume the uncompressed output when it wants, +for example when the output buffer is full (avail_out == 0), +or after each call to +.Fn inflate . +If +.Fn inflate +returns +.Dv Z_OK +and with zero +.Fa avail_out , +it must be called again after making room +in the output buffer because there might be more output pending. +.Pp +The +.Fa flush +parameter of +.Fn inflate +can be +.Dv Z_NO_FLUSH , Z_SYNC_FLUSH , Z_FINISH , Z_BLOCK +or +.Dv Z_TREES . +.Dv Z_SYNC_FLUSH +requests that +.Fn inflate +flush as much output as possible to the output buffer. +.Dv Z_BLOCK +requests that +.Fn inflate +stop if and when it gets to the next deflate block boundary. +When decoding the zlib or gzip format, this will cause +.Fn inflate +to return immediately after the header and before the first block. +When doing a raw inflate, +.Fn inflate +will go ahead and process the first block, +and will return when it gets to the end of that block, +or when it runs out of data. +.Pp +The +.Dv Z_BLOCK +option assists in appending to or combining deflate streams. +To assist in this, on return +.Fn inflate +always sets strm->data_type to the number of unused bits +in the input taken from strm->next_in, plus 64 if +.Fn inflate +is currently decoding the last block in the deflate stream, plus 128 if +.Fn inflate +returned immediately after decoding an end-of-block code or decoding the +complete header up to just before the first byte of the deflate stream. +The end-of-block will not be indicated until all of the uncompressed +data from that block has been written to strm->next_out. +The number of unused bits may in general be greater than seven, +except when bit 7 of data_type is set, +in which case the number of unused bits will be less than eight. +.Fa data_type +is set as noted here every time +.Fn inflate +returns for all flush options, +and so can be used to determine the amount of currently consumed input in bits. +.Pp +The +.Dv Z_TREES +option behaves as +.Dv Z_BLOCK +does, but it also returns when the end of each deflate block header is reached, +before any actual data in that block is decoded. +This allows the caller to determine the length of the deflate block header for +later use in random access within a deflate block. +256 is added to the value of strm->data_type when +.Fn inflate +returns immediately after reaching the end of the deflate block header. +.Pp +.Fn inflate +should normally be called until it returns +.Dv Z_STREAM_END +or an error. +However if all decompression is to be performed in a single step +.Pq a single call to inflate , +the parameter +.Fa flush +should be set to +.Dv Z_FINISH . +In this case all pending input is processed and all pending output is flushed; +.Fa avail_out +must be large enough to hold all the uncompressed data +for the operation to complete. +(The size of the uncompressed data may have been saved +by the compressor for this purpose.) +The use of +.Dv Z_FINISH +is not required to perform an inflation in one step. +However it may be used to inform +.Fn inflate +that a faster approach can be used for the single +.Fn inflate +call. +.Dv Z_FINISH +also informs +.Fn inflate +to not maintain a sliding window if the stream completes, +which reduces its memory footprint. +If the stream does not complete, +either because not all of the stream is provided or not enough output space +is provided, then a sliding window will be allocated and +.Fn inflate +can be called again to continue the operation as if +.Dv Z_NO_FLUSH +had been used. +.Pp +In this implementation, +.Fn inflate +always flushes as much output as possible to the output buffer, +and always uses the faster approach on the first call. +So the effects of the flush parameter in this implementation are +on the return value of +.Fn inflate +as noted below, +when +.Fn inflate +returns early when +.Dv Z_BLOCK +or +.Dv Z_TREES +is used, and when +.Fn inflate +avoids the allocation of memory for a sliding window when +.Dv Z_FINISH +is used. +.Pp +If a preset dictionary is needed after this call (see +.Fn inflateSetDictionary +below), +.Fn inflate +sets strm->adler to the Adler-32 checksum of the dictionary +chosen by the compressor and returns Z_NEED_DICT; otherwise it sets +strm->adler to the Adler-32 checksum of all output produced so far +(that is, +.Fa total_out +bytes) and returns +.Dv Z_OK , Z_STREAM_END +or an error code as described below. +At the end of the stream, +.Fn inflate +checks that its computed Adler-32 checksum is equal to that saved by +the compressor and returns +.Dv Z_STREAM_END +only if the checksum is correct. +.Pp +.Fn inflate +can decompress and check either zlib-wrapped or gzip-wrapped deflate data. +The header type is detected automatically, if requested when initializing with +.Fn inflateInit2 . +Any information contained in the gzip header is not retained unless +.Fn inflateGetHeader +is used. +When processing gzip-wrapped deflate data, strm->adler32 is set to the CRC-32 +of the output produced so far. +The CRC-32 is checked against the gzip trailer, +as is the uncompressed length, modulo 2^32. +.Pp +.Fn inflate +returns +.Dv Z_OK +if some progress has been made +.Pq more input processed or more output produced , +.Dv Z_STREAM_END +if the end of the compressed data has been reached and all uncompressed output +has been produced, +.Dv Z_NEED_DICT +if a preset dictionary is needed at this point, +.Dv Z_DATA_ERROR +if the input data was corrupted (input stream not conforming to the +.Nm zlib +format or incorrect check value, +in which case strm->msg points to a string with a more specific error), +.Dv Z_STREAM_ERROR +if the stream structure was inconsistent +(for example, +.Fa next_in +or +.Fa next_out +was +.Dv NULL , +or the state was inadvertently over by the application), +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_BUF_ERROR +if no progress was possible or if there was not enough room in the output buffer +when +.Dv Z_FINISH +is used. +Note that +.Dv Z_BUF_ERROR +is not fatal, and +.Fn inflate +can be called again with more input and more output space +to continue compressing. +If +.Dv Z_DATA_ERROR +is returned, the application may then call +.Fn inflateSync +to look for a good compression block if a partial recovery +of the data is desired. +.It Xo +.Fa int +.Fn inflateEnd "z_streamp strm" ; +.Xc +All dynamically allocated data structures for this stream are freed. +This function discards any unprocessed input and does not flush any +pending output. +.Pp +.Fn inflateEnd +returns +.Dv Z_OK +if successful, or +.Dv Z_STREAM_ERROR +if the stream state was inconsistent. +In the error case, +.Fa msg +may be set but then points to a static string +.Pq which must not be deallocated . +.El +.Sh ADVANCED FUNCTIONS +The following functions are needed only in some special applications. +.Bl -tag -width Ds +.It Xo +.Fa int +.Fn deflateInit2 "z_streamp strm" "int level" "int method" "int windowBits" "int memLevel" "int strategy" ; +.Xc +.Pp +This is another version of +.Fn deflateInit +with more compression options. +The fields +.Fa next_in , +.Fa zalloc , +.Fa zfree , +and +.Fa opaque +must be initialized before by the caller. +.Pp +The +.Fa method +parameter is the compression method. +It must be +.Dv Z_DEFLATED +in this version of the library. +.Pp +The +.Fa windowBits +parameter is the base two logarithm of the window size +.Pq the size of the history buffer . +It should be in the range 8..15 for this version of the library. +Larger values of this parameter result in better compression +at the expense of memory usage. +The default value is 15 if +.Fn deflateInit +is used instead. +.Pp +For the current implementation of +.Fn deflate , +a +.Fa windowBits +value of 8 (a window size of 256 bytes) is not supported. +As a result, a request for 8 will result in 9 (a 512-byte window). +In that case, providing 8 to +.Fn inflateInit2 +will result in an error when the zlib header with 9 is +checked against the initialization of +.Fn inflate . +The remedy is to not use 8 with +.Fn deflateInit2 +with this initialization, or at least in that case use 9 with +.Fn inflateInit2 . +.Pp +.Fa windowBits +can also be -8..-15 for raw deflate. +In this case, -windowBits determines the window size. +.Fn deflate +will then generate raw deflate data with no zlib header or trailer, +and will not compute a check value. +.Pp +.Fa windowBits +can also be greater than 15 for optional gzip encoding. +Add 16 to +.Fa windowBits +to write a simple gzip header and trailer around the +compressed data instead of a zlib wrapper. +The gzip header will have no file name, no extra data, no comment, +no modification time +.Pq set to zero , +no header crc, and the operating system will be set to +the appropriate value, +if the operating system was determined at compile time. +If a gzip stream is being written, +strm->adler is a CRC-32 instead of an Adler-32. +.Pp +For raw deflate or gzip encoding, a request for a 256-byte window is +rejected as invalid, since only the zlib header provides a means of +transmitting the window size to the decompressor. +.Pp +The +.Fa memLevel +parameter specifies how much memory should be allocated +for the internal compression state. +memLevel=1 uses minimum memory but is slow and reduces compression ratio; +memLevel=9 uses maximum memory for optimal speed. +The default value is 8. +See +.In zconf.h +for total memory usage as a function of +.Fa windowBits +and +.Fa memLevel . +.Pp +The +.Fa strategy +parameter is used to tune the compression algorithm. +Use the value +.Dv Z_DEFAULT_STRATEGY +for normal data; +.Dv Z_FILTERED +for data produced by a filter +.Pq or predictor ; +.Dv Z_RLE +to limit match distances to one +.Pq run-length encoding , +or +.Dv Z_HUFFMAN_ONLY +to force Huffman encoding only +.Pq no string match . +Filtered data consists mostly of small values with a +somewhat random distribution, +as produced by the PNG filters. +In this case, the compression algorithm is tuned to compress them better. +The effect of +.Dv Z_FILTERED +is to force more Huffman coding and less string matching than the default; +it is intermediate between +.Dv Z_DEFAULT_STRATEGY +and +.Dv Z_HUFFMAN_ONLY . +.Dv Z_RLE +is almost as fast as +.Dv Z_HUFFMAN_ONLY , +but should give better compression for PNG image data than Huffman only. +The degree of string matching from most to none is: +.Dv Z_DEFAULT_STRATEGY , +.Dv Z_FILTERED , +.Dv Z_RLE , +then +.Dv Z_HUFFMAN_ONLY . +The +.Fa strategy +parameter affects the compression ratio but never the correctness of the +compressed output, even if it is not set optimally for the given data. +.Dv Z_FIXED +uses the default string matching, +but prevents the use of dynamic Huffman codes, +allowing for a simpler decoder for special applications. +.Pp +.Fn deflateInit2 +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if any parameter is invalid +.Pq such as an invalid method , +or +.Dv Z_VERSION_ERROR +if the zlib library version (zlib_version) is +incompatible with the version assumed by the caller (ZLIB_VERSION). +.Fa msg +is set to null if there is no error message. +.Fn deflateInit2 +does not perform any compression: this will be done by +.Fn deflate . +.It Xo +.Fa int +.Fn deflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" ; +.Xc +.Pp +Initializes the compression dictionary from the given byte sequence +without producing any compressed output. +When using the zlib format, this function must be called immediately after +.Fn deflateInit , deflateInit2 +or +.Fn deflateReset , +and before any call of +.Fn deflate . +When doing raw deflate, this function must be called either before any call of +.Fn deflate , +or immediately after the completion of a deflate block, +i.e. after all input has been consumed and all output has been delivered +when using any of the flush options +.Dv Z_BLOCK , Z_PARTIAL_FLUSH , Z_SYNC_FLUSH , +or +.Dv Z_FULL_FLUSH . +The compressor and decompressor must use exactly the same dictionary +(see +.Fn inflateSetDictionary ) . +.Pp +The dictionary should consist of strings +.Pq byte sequences +that are likely to be encountered later in the data to be compressed, +with the most commonly used strings preferably put towards +the end of the dictionary. +Using a dictionary is most useful when the data to be compressed is short +and can be predicted with good accuracy; +the data can then be compressed better than with the default empty dictionary. +.Pp +Depending on the size of the compression data structures selected by +.Fn deflateInit +or +.Fn deflateInit2 , +a part of the dictionary may in effect be discarded, +for example if the dictionary is larger than the window size provided in +.Fn deflateInit +or +.Fn deflateInit2 . +Thus the strings most likely to be useful should be +put at the end of the dictionary, not at the front. +In addition, the current implementation of +.Fn deflate +will use at most the window size minus 262 bytes of the provided dictionary. +.Pp +Upon return of this function, strm->adler is set to the Adler-32 value +of the dictionary; the decompressor may later use this value to determine +which dictionary has been used by the compressor. +(The Adler-32 value applies to the whole dictionary even if only a subset +of the dictionary is actually used by the compressor.) +If a raw deflate was requested, then the Adler-32 value is not computed +and strm->adler is not set. +.Pp +.Fn deflateSetDictionary +returns +.Dv Z_OK +if successful, +or +.Dv Z_STREAM_ERROR +if a parameter is invalid +.Pq e.g. dictionary being NULL +or the stream state is inconsistent +(for example if +.Fn deflate +has already been called for this stream or if not at a block boundary for raw +deflate). +.Fn deflateSetDictionary +does not perform any compression: this will be done by +.Fn deflate . +.It Xo +.Fa int +.Fn deflateGetDictionary "z_streamp strm" "Bytef *dictionary uInt *dictLength" ; +.Xc +.Pp +Returns the sliding dictionary being maintained by +.Fn deflate . +.Fa dictLength +is set to the number of bytes in the dictionary, and that many bytes are copied +to +.Fa dictionary . +.Fa dictionary +must have enough space, where 32768 bytes is always enough. +If +.Fn deflateGetDictionary +is called with dictionary equal to +.Dv NULL , +then only the dictionary length is returned, and nothing is copied. +Similarly, if +.Fa dictLength +is +.Dv NULL , +then it is not set. +.Pp +.Fn deflateGetDictionary +may return a length less than the window size, +even when more than the window size in input has been provided. +It may return up to 258 bytes less in that case, +due to how zlib's implementation of +.Fn deflate +manages the sliding window and lookahead for matches, +where matches can be up to 258 bytes long. +If the application needs the last window-size bytes of input, +then that would need to be saved by the application outside of +.Nm zlib . +.Pp +.Fn deflateGetDictionary +returns +.Dv Z_OK +on success, or +.Dv Z_STREAM_ERROR +if the stream state is inconsistent. +.It Xo +.Fa int +.Fn deflateCopy "z_streamp dest" "z_streamp source" ; +.Xc +.Pp +The +.Fn deflateCopy +function sets the destination stream as a complete copy of the source stream. +.Pp +This function can be useful when several compression strategies will be +tried, for example when there are several ways of pre-processing the input +data with a filter. +The streams that will be discarded should then be freed by calling +.Fn deflateEnd . +Note that +.Fn deflateCopy +duplicates the internal compression state which can be quite large, +so this strategy is slow and can consume lots of memory. +.Pp +.Fn deflateCopy +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +(such as +.Fa zalloc +being NULL). +.Fa msg +is left unchanged in both source and destination. +.It Xo +.Fa int +.Fn deflateReset "z_streamp strm" ; +.Xc +.Pp +This function is equivalent to +.Fn deflateEnd +followed by +.Fn deflateInit , +but does not free and reallocate the internal compression state. +The stream will leave the compression level and any other attributes +that may have been set unchanged. +.Fa total_in , +.Fa total_out , +.Fa adler , +and +.Fa msg +are initialized. +.Pp +.Fn deflateReset +returns +.Dv Z_OK +if successful, or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +(such as +.Fa zalloc +or +.Fa state +being NULL). +.It Xo +.Fa int +.Fn deflateParams "z_streamp strm" "int level" "int strategy" ; +.Xc +.Pp +The +.Fn deflateParams +function dynamically updates the compression level and compression strategy. +The interpretation of level and strategy is as in +.Fn deflateInit2 . +This can be used to switch between compression and straight copy +of the input data, or to switch to a different kind of input data +requiring a different strategy. +If the compression approach (which is a function of the level) or the +strategy is changed, and if any input has been consumed in a previous +.Fn deflate +call, then the input available so far is compressed with the old +level and strategy using deflate(strm, Z_BLOCK). +There are three approaches for the compression levels 0, 1..3, and 4..9, +respectively. +The new level and strategy will take effect at the next call of +.Fn deflate . +.Pp +If a deflate(strm, Z_BLOCK) is performed by +.Fn deflateParams , +and it does not have enough output space to complete, +then the parameter change will not take effect. +In this case, +.Fn deflateParams +can be called again with the same parameters and more output space to try again. +.Pp +In order to assure a change in the parameters on the first try, the +deflate stream should be flushed using +.Fn deflate +with +.Dv Z_BLOCK +or other flush request until +.Fa strm.avail_out +is not zero, before calling +.Fn deflateParams . +Then no more input data should be provided before the +.Fn deflateParams +call. +If this is done, the old level and strategy will be applied to the data +compressed before +.Fn deflateParams , +and the new level and strategy will be applied to the data compressed after +.Fn deflateParams . +.Pp +.Fn deflateParams +returns +.Dv Z_OK +on success, +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent or if a parameter was invalid, or +.Dv Z_BUF_ERROR +if there was not enough output space to complete the compression of the +available input data before a change in the strategy or approach. +Note that in the case of a +.Dv Z_BUF_ERROR , +the parameters are not changed. +A return value of +.Dv Z_BUF_ERROR +is not fatal, in which case +.Fn deflateParams +can be retried with more output space. +.It Xo +.Fa int +.Fn deflateTune "z_streamp strm" "int good_length" "int max_lazy" "int nice_length" "int max_chain" ; +.Xc +.Pp +Fine tune +.Fn deflate Ns 's +internal compression parameters. +This should only be used by someone who understands the algorithm +used by zlib's deflate for searching for the best matching string, +and even then only by the most fanatic optimizer +trying to squeeze out the last compressed bit for their specific input data. +Read the +.Pa deflate.c +source code for the meaning of the +.Fa max_lazy , good_length , nice_length , +and +.Fa max_chain +parameters. +.Pp +.Fn deflateTune +can be called after +.Fn deflateInit +or +.Fn deflateInit2 , +and returns +.Dv Z_OK +on success, or +.Dv Z_STREAM_ERROR +for an invalid deflate stream. +.It Xo +.Fa uLong +.Fn deflateBound "z_streamp strm" "uLong sourceLen" ; +.Xc +.Pp +.Fn deflateBound +returns an upper bound on the compressed size after deflation of +.Fa sourceLen +bytes. +It must be called after +.Fn deflateInit +or +.Fn deflateInit2 . +and after +.Fn deflateSetHeader , +if used. +This would be used to allocate an output buffer for deflation in a single pass, +and so would be called before +.Fn deflate . +If that first +.Fn deflate +call is provided the +.Fa sourceLen +input bytes, an output buffer allocated to the size returned by +.Fn deflateBound , +and the flush value +.Dv Z_FINISH , +then +.Fn deflate +is guaranteed to return +.Dv Z_STREAM_END . +Note that it is possible for the compressed size to be larger than +the value returned by +.Fn deflateBound +if flush options other than +.Dv Z_FINISH +or +.Dv Z_NO_FLUSH +are used. +.It Xo +.Fa z_size_t +.Fn deflateBound_z "z_streamp strm" "z_size_t sourceLen" ; +.Xc +.Pp +.Fn deflateBound_z +is the same as +.Fn deflateBound , +but takes and returns a +.Vt z_size_t +length. +Note that a +.Vt long +is 32 bits on Windows. +.It Xo +.Fa int +.Fn deflatePending "z_streamp strm" "unsigned *pending" "int *bits" ; +.Xc +.Pp +.Fn deflatePending +returns the number of bytes and bits of output that have been generated, +but not yet provided in the available output. +The bytes not provided would be due to the available output space +having been consumed. +The number of bits of output not provided are between 0 and 7, +where they await more bits to join them in order to fill out a full byte. +If +.Fa pending +or +.Fa bits +are +.Dv NULL , +then those values are not set. +.Pp +.Fn deflatePending +returns +.Dv Z_OK +if success, or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent. +.It Xo +.Fa int +.Fn deflateUsed "z_streamp strm" "int *bits" ; +.Xc +.Pp +.Fn deflateUsed +returns in +.Pf * Fa bits +the most recent number of deflate bits used in the last byte +when flushing to a byte boundary. +The result is in the range 1..8, or 0 if there has not yet been a flush. +This helps determine the location of the last bit of a deflate stream. +.Pp +.Fn deflateUsed +returns +.Dv Z_OK +if success, or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent. +.It Xo +.Fa int +.Fn deflatePrime "z_streamp strm" "int bits" "int value" ; +.Xc +.Pp +.Fn deflatePrime +inserts +.Fa bits +in the deflate output stream. +The intent is that this function is used to start off the deflate output +with the bits left over from a previous deflate stream when appending to it. +As such, this function can only be used for raw deflate, +and must be used before the first +.Fn deflate +call after a +.Fn deflateInit2 +or +.Fn deflateReset . +.Fa bits +must be less than or equal to 16, +and that many of the least significant bits of +.Fa value +will be inserted in the output. +.Pp +.Fn deflatePrime +returns +.Dv Z_OK +if successful, +.Dv Z_BUF_ERROR +if there was not enough room in the internal buffer to insert the bits, or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent. +.It Xo +.Fa int +.Fn deflateSetHeader "z_streamp strm" "gz_headerp head" ; +.Xc +.Pp +.Fn deflateSetHeader +provides gzip header information for when a gzip +stream is requested by +.Fn deflateInit2 . +.Fn deflateSetHeader +may be called after +.Fn deflateInit2 +or +.Fn deflateReset +and before the first call of +.Fn deflate . +The text, time, os, extra field, name, and comment information +in the provided gz_header structure are written to the gzip header +(xflag is ignored \- the extra flags are set +according to the compression level). +The caller must assure that, if not +.Dv NULL , +.Fa name +and +.Fa comment +are terminated with a zero byte, +and that if +.Fa extra +is not +.Dv NULL , +that +.Fa extra_len +bytes are available there. +If hcrc is true, a gzip header CRC is included. +Note that the current versions of the command-line version of +.Xr gzip 1 +do not support header CRCs, and will report that it is a +.Dq multi-part gzip file +and give up. +.Pp +If +.Fn deflateSetHeader +is not used, the default gzip header has text false, +the time set to zero, and os set to the current operating system, with no +extra, name, or comment fields. +The gzip header is returned to the default state by +.Fn deflateReset . +.Pp +.Fn deflateSetHeader +returns +.Dv Z_OK +if successful, or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent. +.It Xo +.Fa int +.Fn inflateInit2 "z_streamp strm" "int windowBits" ; +.Xc +.Pp +This is another version of +.Fn inflateInit +with an extra parameter. +The fields +.Fa next_in , +.Fa avail_in , +.Fa zalloc , +.Fa zfree , +and +.Fa opaque +must be initialized before by the caller. +.Pp +The +.Fa windowBits +parameter is the base two logarithm of the maximum window size +.Pq the size of the history buffer . +It should be in the range 8..15 for this version of the library. +The default value is 15 if +.Fn inflateInit +is used instead. +.Fa windowBits +must be greater than or equal to the +.Fa windowBits +value provided to +.Fn deflateInit2 +while compressing, or it must be equal to 15 if +.Fn deflateInit2 +was not used. +If a compressed stream with a larger window size is given as input, +.Fn inflate +will return with the error code +.Dv Z_DATA_ERROR +instead of trying to allocate a larger window. +.Pp +.Fa windowBits +can also be zero to request that inflate use the window size in the zlib header +of the compressed stream. +.Pp +.Fa windowBits +can also be -8..-15 for raw inflate. +In this case, -windowBits determines the window size. +.Fn inflate +will then process raw deflate data, not looking for a zlib or gzip header, +not generating a check value, and not looking for any check values +for comparison at the end of the stream. +This is for use with other formats that use the deflate compressed data format +such as zip. +Those formats provide their own check values. +If a custom format is developed using the raw deflate format +for compressed data, it is recommended that a check value such as an Adler-32 +or a CRC-32 be applied to the uncompressed data as is done in the zlib, gzip, +and zip formats. +For most applications, the zlib format should be used as is. +Note that comments above on the use in +.Fn deflateInit2 +applies to the magnitude of +.Fa windowBits . +.Pp +.Fa windowBits +can also be greater than 15 for optional gzip decoding. +Add 32 to windowBits to enable zlib and gzip decoding with automatic header +detection, or add 16 to decode only the gzip format +(the zlib format will return a +.Dv Z_DATA_ERROR ) . +If a gzip stream is being decoded, +strm->adler is a CRC-32 instead of an Adler-32. +Unlike the +.Xr gunzip 1 +utility and +.Fn gzread +(see below), +.Fn inflate +will not automatically decode concatenated gzip streams. +.Fn inflate +will return +.Dv Z_STREAM_END +at the end of the gzip stream. +The state would need to be reset to continue decoding a subsequent gzip stream. +.Pp +.Fn inflateInit2 +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_VERSION_ERROR +if the +.Nm zlib +library version is incompatible with the version assumed by the caller, or +.Dv Z_STREAM_ERROR +if the parameters are invalid, such as a null pointer to the structure. +.Fa msg +is set to null if there is no error message. +.Fn inflateInit2 +does not perform any decompression apart from possibly reading the zlib header +if present: actual decompression will be done by +.Fn inflate . +(So +.Fa next_in +and +.Fa avail_in +may be modified, but +.Fa next_out +and +.Fa avail_out +are unused and unchanged.) +The current implementation of +.Fn inflateInit2 +does not process any header information \(em that is deferred until +.Fn inflate +is called. +.It Xo +.Fa int +.Fn inflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" ; +.Xc +.Pp +Initializes the decompression dictionary from the given uncompressed byte +sequence. +This function must be called immediately after a call to +.Fn inflate +if that call returned +.Dv Z_NEED_DICT . +The dictionary chosen by the compressor can be determined from the +Adler-32 value returned by that call to +.Fn inflate . +The compressor and decompressor must use exactly the same dictionary +(see +.Fn deflateSetDictionary ) . +For raw inflate, this function can be called at any time to set the dictionary. +If the provided dictionary is smaller than the window and there is already +data in the window, then the provided dictionary will amend what's there. +The application must ensure that the dictionary +that was used for compression is provided. +.Pp +.Fn inflateSetDictionary +returns +.Dv Z_OK +if successful, +.Dv Z_STREAM_ERROR +if a parameter is invalid +.Pq e.g. dictionary being NULL +or the stream state is inconsistent, +.Dv Z_DATA_ERROR +if the given dictionary doesn't match the expected one +.Pq incorrect Adler-32 value . +.Fn inflateSetDictionary +does not perform any decompression: this will be done by subsequent calls of +.Fn inflate . +.It Xo +.Fa int +.Fn inflateGetDictionary "z_streamp strm" "Bytef *dictionary" "uInt *dictLength" ; +.Xc +.Pp +Returns the sliding dictionary being maintained by +.Fn inflate . +.Fa dictLength +is set to the number of bytes in the dictionary, and that many bytes are copied +to +.Fa dictionary . +.Fa dictionary +must have enough space, where 32768 bytes is always enough. +If +.Fn inflateGetDictionary +is called with dictionary equal to +.Dv NULL , +then only the dictionary length is returned, and nothing is copied. +Similarly, if +.Fa dictLength is +.Dv NULL , +then it is not set. +.Pp +.Fn inflateGetDictionary +returns +.Dv Z_OK +on success, or +.Dv Z_STREAM_ERROR +if the stream state is inconsistent. +.It Xo +.Fa int +.Fn inflateSync "z_streamp strm" ; +.Xc +.Pp +Skips invalid compressed data until a possible full flush point +(see above the description of +.Fn deflate +with +.Dv Z_FULL_FLUSH ) +can be found, or until all available input is skipped. +No output is provided. +.Pp +.Fn inflateSync +searches for a 00 00 FF FF pattern in the compressed data. +All full flush points have this pattern, but not all occurrences of this +pattern are full flush points. +.Pp +.Fn inflateSync +returns +.Dv Z_OK +if a possible full flush point has been found, +.Dv Z_BUF_ERROR +if no more input was provided, +.Dv Z_DATA_ERROR +if no flush point has been found, or +.Dv Z_STREAM_ERROR +if the stream structure was inconsistent. +In the success case, the application may save the current value of +.Fa total_in +which indicates where valid compressed data was found. +In the error case, the application may repeatedly call +.Fn inflateSync , +providing more input each time, until success or end of the input data. +.It Xo +.Fa int +.Fn inflateCopy "z_streamp dest" "z_streamp source" ; +.Xc +.Pp +Sets the destination stream as a complete copy of the source stream. +.Pp +This function can be useful when randomly accessing a large stream. +The first pass through the stream can periodically record the inflate state, +allowing restarting inflate at those points when randomly accessing the stream. +.Pp +.Fn inflateCopy +returns +.Dv Z_OK +if success, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +(such as +.Fa zalloc +being NULL). +.Fa msg +is left unchanged in both +.Fa source +and +.Fa dest . +.It Xo +.Fa int +.Fn inflateReset "z_streamp strm" ; +.Xc +.Pp +This function is equivalent to +.Fn inflateEnd +followed by +.Fn inflateInit , +but does not free and reallocate the internal decompression state. +The stream will keep attributes that may have been set by +.Fn inflateInit2 . +.Fa total_in , +.Fa total_out , +.Fa adler , +and +.Fa msg +are initialized. +.Pp +.Fn inflateReset +returns +.Dv Z_OK +if successful, or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +(such as +.Fa zalloc +or +.Fa state +being NULL). +.It Xo +.Fa int +.Fn inflateReset2 "z_streamp strm" "int windowBits" ; +.Xc +.Pp +This function is the same as +.Fn inflateReset , +but it also permits changing the wrap and window size requests. +The +.Fa windowBits +parameter is interpreted the same as it is for +.Fa inflateInit2 . +If the window size is changed, then the memory allocated for the window +is freed, and the window will be reallocated by +.Fn inflate +if needed. +.Pp +.Fn inflateReset2 +returns +.Dv Z_OK +if success, or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +(such as +.Fa zalloc +or +.Fa state +being +.Dv NULL ) , +or if the +.Fa windowBits +parameter is invalid. +.It Xo +.Fa int +.Fn inflatePrime "z_stream strm" "int bits" "int value" ; +.Xc +.Pp +This function inserts bits in the inflate input stream. +The intent is to use +.Fn inflatePrime +to start inflating at a bit position in the middle of a byte. +The provided bits will be used before any bytes are used from +.Fa next_in . +This function should be used with raw inflate, +and should be used before the first +.Fn inflate +call after +.Fn inflateInit2 +or +.Fn inflateReset . +It can also be used after an +.Fn inflate +return indicates the end of a +.Fa deflate +block or header when using +.Dv Z_BLOCK . +.Fa bits +must be less than or equal to 16, +and that many of the least significant bits of value +will be inserted in the input. +The other bits in +.Va value +can be non-zero, and will be ignored. +.Pp +If +.Fa bits +is negative, then the input stream bit buffer is emptied. +Then +.Fn inflatePrime +can be called again to put bits in the buffer. +This is used to clear out bits left over after feeding +.Fn inflate +a block description prior to feeding it codes. +.Pp +.Fn inflatePrime +returns +.Dv Z_OK +if successful, or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent, +or if bits is out of range. +If +.Fn inflate +was in the middle of processing a header, trailer, or stored block lengths, then +it is possible for there to be only eight bits available in the bit buffer. +In that case, bits > 8 is considered out of range. +However, when used as outlined above, there will always be 16 bits available in +the buffer for insertion. +As noted in its documentation above, +.Fn inflate +records the number of bits in the bit buffer on return in +.Fa data_type . +32 minus that is the number of bits available for insertion. +Fn inflatePrime +does not update +.Fa data_type +with the new number of bits in buffer. +.It Xo +.Fa long +.Fn inflateMark "z_streamp strm" ; +.Xc +.Pp +This function returns two values: one in the lower 16 bits of the return +value, and the other in the remaining upper bits, obtained by shifting the +return value down 16 bits. +If the upper value is -1 and the lower value is zero, then +.Fn inflate +is currently decoding information outside of a block. +If the upper value is -1 and the lower value is non-zero, then +.Fn inflate +is in the middle of a stored block, with the lower value equaling the number of +bytes from the input remaining to copy. +If the upper value is not -1, then it is the number of bits back from +the current bit position in the input of the code +(literal or length/distance pair) +currently being processed. +In that case the lower value is the number of bytes +already emitted for that code. +.Pp +A code is being processed if +.Fn inflate +is waiting for more input to complete decoding of the code, +or if it has completed decoding but is waiting for +more output space to write the literal or match data. +.Pp +.Fn inflateMark +is used to mark locations in the input data for random access, +which may be at bit positions, +and to note those cases where the output of a code may span +boundaries of random access blocks. +The current location in the input stream can be determined from +.Fa avail_in +and +.Fa data_type +as noted in the description for the +.Dv Z_BLOCK +flush parameter for +.Fn inflate . +.Pp +.Fn inflateMark +returns the value noted above, +or -65536 if the provided source stream state was inconsistent. +.It Xo +.Fa int +.Fn inflateGetHeader "z_streamp strm" "gz_headerp head" ; +.Xc +.Pp +.Fn inflateGetHeader +requests that gzip header information be stored in the +provided gz_header structure. +.Fn inflateGetHeader +may be called after +.Fn inflateInit2 +or +.Fn inflateReset , +and before the first call of +.Fn inflate . +As +.Fn inflate +processes the gzip stream, head->done is zero until the header +is completed, at which time head->done is set to one. +If a zlib stream is being decoded, +then head->done is set to -1 to indicate that there will be +no gzip header information forthcoming. +Note that +.Dv Z_BLOCK +or +.Dv Z_TREES +can be used to force +.Fn inflate +to return immediately after header processing is complete +and before any actual data is decompressed. +.Pp +The text, time, xflags, and os fields are filled in with the gzip header +contents. +hcrc is set to true if there is a header CRC. +(The header CRC was valid if done is set to one.) +The +.Fa extra , +.Fa name , +and +.Fa comment +pointers much each be either +.Dv NULL , +or point to space to store that information from the header. +If +.Fa extra +is not +.Dv NULL , +then +.Fa extra_max +contains the maximum number of bytes to write to +.Fa extra . +Once done is true, +.Fa extra_len +contains the actual extra field length, and +.Fa extra +contains the extra field, or that field truncated if +.Fa extra_max +is less than +.Fa extra_len . +If +.Fa name +is not +.Dv NULL , +then up to +.Fa name_max +characters are written there, +terminated with a zero unless the length is greater than +.Fa name_max . +If comment is not +.Dv NULL , +then up to +.Fa comm_max +characters are written there, +terminated with a zero unless the length is greater than +.Fa comm_max . +When any of extra, name, or comment are not +.Dv NULL +and the respective field is not present in the header, +then that field is set to +.Dv NULL +to signal its absence. +This allows the use of +.Fn deflateSetHeader +with the returned structure to duplicate the header. +However if those fields are set to allocated memory, +then the application will need to save those pointers +elsewhere so that they can be eventually freed. +.Pp +If +.Fn inflateGetHeader +is not used, then the header information is simply discarded. +The header is always checked for validity, +including the header CRC if present. +.Fn inflateReset +will reset the process to discard the header information. +The application would need to call +.Fn inflateGetHeader +again to retrieve the header from the next gzip stream. +.Pp +.Fn inflateGetHeader +returns +.Dv Z_OK +if successful, +or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent. +.It Xo +.Fa int +.Fn inflateBackInit "z_stream *strm" "int windowBits" "unsigned char FAR *window" ; +.Xc +.Pp +Initialize the internal stream state for decompression using +.Fn inflateBack +calls. +The fields +.Fa zalloc , zfree +and +.Fa opaque +in +.Fa strm +must be initialized before the call. +If +.Fa zalloc +and +.Fa zfree +are +.Dv NULL , +then the default library-derived memory allocation routines are used. +.Fa windowBits +is the base two logarithm of the window size, in the range 8..15. +.Fa window +is a caller supplied buffer of that size. +Except for special applications where it is assured that +.Fn deflate +was used with small window sizes, +.Fa windowBits +must be 15 and a 32K byte window must be supplied to be able to decompress +general deflate streams. +.Pp +See +.Fn inflateBack +for the usage of these routines. +.Pp +.Fn inflateBackInit +will return +.Dv Z_OK +on success, +.Dv Z_STREAM_ERROR +if any of the parameters are invalid, +.Dv Z_MEM_ERROR +if the internal state could not be allocated, or +.Dv Z_VERSION_ERROR +if the version of the library does not match the version of the header file. +.It Xo +.Fa int +.Fn inflateBack "z_stream *strm" "in_func in" "void FAR *in_desc" "out_func out" "void FAR *out_desc" ; +.Xc +.Pp +.Fn inflateBack +does a raw inflate with a single call using a call-back +interface for input and output. +This is potentially more efficient than +.Fn inflate +for file I/O applications, in that it avoids copying between the output and the +sliding window by simply making the window itself the output buffer. +.Fn inflate +can be faster on modern CPUs when used with large buffers. +.Fn inflateBack +trusts the application to not change the output buffer passed by +the output function, at least until +.Fn inflateBack +returns. +.Pp +.Fn inflateBackInit +must be called first to allocate the internal state +and to initialize the state with the user-provided window buffer. +.Fn inflateBack +may then be used multiple times to inflate a complete, raw +deflate stream with each call. +.Fn inflateBackEnd +is then called to free the allocated state. +.Pp +A raw deflate stream is one with no zlib or gzip header or trailer. +This routine would normally be used in a utility that reads zip or gzip +files and writes out uncompressed files. +The utility would decode the header and process the trailer on its own, +hence this routine expects only the raw deflate stream to decompress. +This is different from the default behavior of +.Fn inflate , +which expects either a zlib header and trailer around the deflate stream. +.Pp +.Fn inflateBack +uses two subroutines supplied by the caller that are then called by +.Fn inflateBack +for input and output. +.Fn inflateBack +calls those routines until it reads a complete deflate stream and writes out +all of the uncompressed data, or until it encounters an error. +The function's parameters and return types are defined above in the +in_func and out_func typedefs. +.Fn inflateBack +will call in(in_desc, &buf) which should return the +number of bytes of provided input, and a pointer to that input in +.Fa buf . +If there is no input available, +.Fn in +must return zero +\(em buf is ignored in that case \(em +and +.Fn inflateBack +will return a buffer error. +.Fn inflateBack +will call out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. +.Fn out +should return zero on success, or non-zero on failure. +If +.Fn out +returns non-zero, +.Fn inflateBack +will return with an error. +Neither +.Fn in +nor +.Fn out +are permitted to change the contents of the window provided to +.Fn inflateBackInit , +which is also the buffer that +.Fn out +uses to write from. +The length written by +.Fn out +will be at most the window size. +Any non-zero amount of input may be provided by +.Fn in . +.Pp +For convenience, +.Fn inflateBack +can be provided input on the first call by setting strm->next_in +and strm->avail_in. +If that input is exhausted, then +.Fn in +will be called. +Therefore strm->next_in must be initialized before calling +.Fn inflateBack . +If strm->next_in is +.Dv NULL , +then +.Fn in +will be called immediately for input. +If strm->next_in is not +.Dv NULL , +then strm->avail_in must also be initialized, +and then if strm->avail_in is not zero, +input will initially be taken from +strm->next_in[0 .. strm->avail_in \- 1]. +.Pp +The +.Fa in_desc +and +.Fa out_desc +parameters of +.Fn inflateBack +are passed as the first parameter of +.Fn in +and +.Fn out , +respectively, when they are called. +These descriptors can be optionally used to pass any information that the +caller-supplied +.Fn in +and +.Fn out +functions need to do their job. +.Pp +On return, +.Fn inflateBack +will set strm->next_in and strm->avail_in to pass back any unused input +that was provided by the last +.Fn in +call. +The return values of +.Fn inflateBack +can be +.Dv Z_STREAM_END +on success, +.Dv Z_BUF_ERROR +if +.Fn in +or +.Fn out +returned an error, +.Dv Z_DATA_ERROR +if there was a format error in the deflate stream +(in which case strm->msg is set to indicate the nature of the error), +or +.Dv Z_STREAM_ERROR +if the stream was not properly initialized. +In the case of +.Dv Z_BUF_ERROR , +an input or output error can be distinguished using strm->next_in which +will be +.Dv NULL +only if +.Fn in +returned an error. +If strm->next is not +.Dv NULL , +then the +.Dv Z_BUF_ERROR +was due to +.Fn out +returning non-zero. +.Po +.Fn in +will always be called before +.Fn out , +so strm->next_in is assured to be defined if +.Fn out +returns non-zero. +.Pc +Note that +.Fn inflateBack +cannot return +.Dv Z_OK . +.It Xo +.Fa int +.Fn inflateBackEnd "z_stream *strm" ; +.Xc +.Pp +All memory allocated by +.Fn inflateBackInit +is freed. +.Pp +.Fn inflateBackEnd +returns +.Dv Z_OK +on success, or +.Dv Z_STREAM_ERROR +if the stream state was inconsistent. +.It Xo +.Fa uLong +.Fn zlibCompileFlags "void" ; +.Xc +.Pp +This function returns flags indicating compile-time options. +.Pp +Type sizes, two bits each: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It 00 +16 bits +.It 01 +32 bits +.It 10 +64 bits +.It 11 +other: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It 1.0 +size of uInt +.It 3.2 +size of uLong +.It 5.4 +size of voidpf +.Pq pointer +.It 7.6 +size of z_off_t +.El +.El +.Pp +Compiler, assembler, and debug options: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It 8 +ZLIB_DEBUG +.It 9 +ASMV or ASMINF \(em use ASM code +.It 10 +ZLIB_WINAPI \(em exported functions use the WINAPI calling convention +.It 11 +0 +.Pq reserved +.El +.Pp +One-time table building +.Pq smaller code, but not thread-safe if true : +.Pp +.Bl -tag -width Ds -offset indent -compact +.It 12 +BUILDFIXED \(em build static block decoding tables when needed +.It 13 +DYNAMIC_CRC_TABLE \(em build CRC calculation tables when needed +.It 14,15 +0 +.Pq reserved +.El +.Pp +Library content (indicates missing functionality): +.Pp +.Bl -tag -width Ds -offset indent -compact +.It 16 +NO_GZCOMPRESS \(em gz* functions cannot compress +.Pq to avoid linking deflate code when not needed +.It 17 +NO_GZIP \(em deflate can't write gzip streams, and inflate can't detect +and decode gzip streams +.Pq to avoid linking CRC code +.It 18-19 +0 +.Pq reserved +.El +.Pp +Operation variations (changes in library functionality): +.Pp +.Bl -tag -width Ds -offset indent -compact +.It 20 +PKZIP_BUG_WORKAROUND \(em slightly more permissive inflate +.It 21 +FASTEST \(em deflate algorithm with only one, lowest compression level +.It 22,23 +0 +.Pq reserved +.El +.Pp +The sprintf variant used by gzprintf +.Pq zero is best : +.Pp +.Bl -tag -width Ds -offset indent -compact +.It 24 +0 = vs*, 1 = s* \(em 1 means limited to 20 arguments after the format +.It 25 +0 = *nprintf, 1 = *printf \(em 1 means +.Fn gzprintf +not secure! +.It 26 +0 = returns value, 1 = void \(em 1 means inferred string length returned +.El +.Pp +Remainder: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It 27-31 +0 +.Pq reserved +.El +.El +.Sh UTILITY FUNCTIONS +The following utility functions are implemented on top of the +basic stream-oriented functions. +To simplify the interface, +some default options are assumed (compression level and memory usage, +standard memory allocation functions). +The source code of these utility functions can be modified +if you need special options. +.Bl -tag -width Ds +.It Xo +.Fa int +.Fn compress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" ; +.Xc +.Pp +The +.Fn compress +function compresses the source buffer into the destination buffer. +.Fa sourceLen +is the byte length of the source buffer. +On entry, +.Pf * Fa destLen +is the total size of the destination buffer, +which must be at least the value returned by +.Fn compressBound sourcelen . +On exit, +.Pf * Fa destLen +is the actual size of the compressed data. +.Fn compress +is equivalent to +.Fn compress2 +with a level parameter of +.Dv Z_DEFAULT_COMPRESSION . +.Pp +.Fn compress +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, or +.Dv Z_BUF_ERROR +if there was not enough room in the output buffer. +.It Xo +.Fa int +.Fn compress_z "Bytef *dest" "z_size_t *destLen" "const Bytef *source" "z_size_t sourceLen" ; +.Xc +.Pp +.Fn compress_z +is the same as +.Fn compress , +but takes +.Vt z_size_t +lengths. +Note that a +.Vt long +is 32 bits on Windows. +.It Xo +.Fa int +.Fn compress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" "int level" ; +.Xc +.Pp +The +.Fn compress2 +function compresses the source buffer into the destination buffer. +The +.Fa level +parameter has the same meaning as in +.Fn deflateInit . +.Fa sourceLen +is the byte length of the source buffer. +On entry, +.Pf * Fa destLen +is the total size of the destination buffer, +which must be at least the value returned by +.Fn compressBound sourceLen . +On exit, +.Pf * Fa destLen +is the actual size of the compressed buffer. +.Pp +.Fn compress2 +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_BUF_ERROR +if there was not enough room in the output buffer, or +.Dv Z_STREAM_ERROR +if the level parameter is invalid. +.It Xo +.Fa int +.Fn compress2_z "Bytef *dest" "z_size_t *destLen" "const Bytef *source" "z_size_t sourceLen" "int level" ; +.Xc +.Pp +.Fn compress2_z +is the same as +.Fn compress2 +but takes +.Vt z_size_t +lengths. +Note that a +.Vt long +is 32 bits on Windows. +.It Xo +.Fa uLong +.Fn compressBound "uLong sourceLen" ; +.Xc +.Pp +.Fn compressBound +returns an upper bound on the compressed size after +.Fn compress +or +.Fn compress2 +on +.Fa sourceLen +bytes. +It would be used before a +.Fn compress +or +.Fn compress2 +call to allocate the destination buffer. +.It Xo +.Fa z_size_t +.Fn compressBound_z "z_size_t sourceLen" ; +.Xc +.Pp +.Fn compressBound_z +is the same as +.Fn compressBound +but takes and returns a +.Vt z_size_t +length. +Note that a +.Vt long +is 32 bits on Windows. +.It Xo +.Fa int +.Fn uncompress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" ; +.Xc +.Pp +The +.Fn uncompress +function decompresses the source buffer into the destination buffer. +.Fa sourceLen +is the byte length of the source buffer. +On entry, +.Pf * Fa destLen +is the total size of the destination buffer, +which must be large enough to hold the entire uncompressed data. +(The size of the uncompressed data must have been saved previously +by the compressor and transmitted to the decompressor +by some mechanism outside the scope of this compression library.) +On exit, +.Pf * Fa destLen +is the actual size of the uncompressed data. +This function can be used to decompress a whole file at once if the +input file is mmap'ed. +.Pp +.Fn uncompress +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_BUF_ERROR +if there was not enough room in the output buffer, or +.Dv Z_DATA_ERROR +if the input data was corrupted or incomplete. +In the case where there is not enough room, +.Fn uncompress +will fill the output buffer with the uncompressed data up to that point. +.It Xo +.Fa int +.Fn uncompress_z "Bytef *dest" "z_size_t *destLen" "const Bytef *source" "z_size_t sourceLen" ; +.Xc +.Pp +.Fn uncompress_z +is the same as +.Fn uncompress +but takes +.Vt z_size_t +lengths. +Note that a +.Vt long +is 32 bits on Windows. +.It Xo +.Fa int +.Fn uncompress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong *sourceLen" ; +.Xc +.Pp +Same as +.Fn uncompress , +except that +.Fa sourceLen +is a pointer, where the length of the source is +.Fa *sourceLen . +On return, +.Fa *sourceLen +is the number of source bytes consumed. +.It Xo +.Fa int +.Fn uncompress2_z "Bytef *dest" "z_size_t *destLen" "const Bytef *source" "z_size_t *sourceLen" ; +.Xc +.Pp +.Fn uncompress2_z +is the same as +.Fn uncompress +but takes +.Vt z_size_t +lengths. +Note that a +.Vt long +is 32 bits on Windows. +.It Xo +.Fa gzFile +.Fn gzopen "const char *path" "const char *mode" ; +.Xc +.Pp +This library supports reading and writing files in gzip (.gz) format with +an interface similar to that of stdio, using the functions that start with "gz". +The gzip format is different from the zlib format. +gzip is a gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. +.Pp +The +.Fn gzopen +function opens a gzip +.Pq .gz +file for reading or writing. +The mode parameter is as in +.Xr fopen 3 +.Po +.Qq rb +or +.Qq wb +.Pc +but can also include a compression level +.Pq "wb9" +or a strategy: +.Sq f +for filtered data, as in +.Qq wb6f ; +.Sq h +for Huffman only compression, as in +.Qq wb1h , +or +.Sq R +for run-length encoding as in +.Qq wb1R , +or +.Sq F +for fixed code compression as in +.Qq wb9F . +(See the description of +.Fn deflateInit2 +for more information about the strategy parameter.) +.Sq T +will request transparent writing or appending with no compression and not using +the gzip format. +.Sq T +cannot be used to force transparent reading. +Transparent reading is automatically performed +if there is no gzip reader at the start. +Transparent reading can be disabled with the +.Sq G +option, which will instead return an error if there is no gzip header. +.Sq N +will open the file in non-blocking mode. +.Pp +.Sq a +can be used instead of +.Sq w +to request that the gzip stream that will be written be appended to the file. +.Sq + +will result in an error, +since reading and writing to the same gzip file is not supported. +The addition of +.Sq x +when writing will create the file exclusively, +which fails if the file already exists. +On systems that support it, the addition of +.Sq e +when reading or writing will set the flag to close the file on an +.Xr execve 2 +call. +.Pp +These functions, as well as gzip, +will read and decode a sequence of gzip streams in a file. +The append function of +.Fn gzopen +can be used to create such a file. +(Also see +.Fn gzflush +for another way to do this.) +When appending, +.Fn gzopen +does not test whether the file begins with a gzip stream, +nor does it look for the end of the gzip streams to begin appending. +.Fn gzopen +will simply append a gzip stream to the existing file. +.Pp +.Fn gzopen +can be used to read a file which is not in gzip format; +in this case +.Fn gzread +will directly read from the file without decompression. +When reading, this will be detected automatically +by looking for the magic two-byte gzip header. +.Pp +.Fn gzopen +returns +.Dv NULL +if the file could not be opened, +if there was insufficient memory to allocate the gzFile state, +or if an invalid mode was specified +(an +.Sq r , +.Sq w , +or +.Sq a +was not provided, or +.Sq + +was provided). +.Fa errno +can be checked to determine if the reason +.Fn gzopen +failed was that the file could not be opened. +Note that if +.Sq N +is in mode for non-blocking, the +.Xr open 2 +call itself can fail in order to not block. +In that case +.Fn gzopen +return +.Dv NULL +and errno will be +.Dv EAGAIN +or +.Dv EWOULDBLOCK . +The call to +.Fn gzopen +with the resulting file descriptor and +.Sq N +in the mode, +which will set it to non-blocking. +.It Xo +.Fa gzFile +.Fn gzdopen "int fd" "const char *mode" ; +.Xc +.Pp +The +.Fn gzdopen +function associates a gzFile with the file descriptor +.Fa fd . +File descriptors are obtained from calls like +.Xr open 2 , +.Xr dup 2 , +.Xr creat 3 , +.Xr pipe 2 , +or +.Xr fileno 3 +(if the file has been previously opened with +.Xr fopen 3 ) . +The +.Fa mode +parameter is as in +.Fn gzopen . +.Pp +An +.Sq e +in +.Fa mode +will set +.Fa fd Ns No 's +flag to close the file on an +.Xr execve 2 +call. +An +.Sq N +in +.Fa mode +will set +.Fa fd Ns No 's +non-blocking flag. +The next call to +.Fn gzclose +on the returned gzFile will also close the file descriptor fd, +just like fclose(fdopen(fd), mode) closes the file descriptor fd. +If you want to keep fd open, use +.Dq fd = dup(fd_keep); gz = gzdopen(fd, mode); . +The duplicated descriptor should be saved to avoid a leak, since +.Fn gzdopen +does not close fd if it fails. +If you are using +.Fn fileno +to get the file descriptor from a FILE *, +then you will have to use +.Xr dup 2 +to avoid double-closing the file descriptor. +Both +.Fn gzclose +and +.Fn fclose +will close the associated file descriptor, +so they need to have different file descriptors. +.Pp +.Fn gzdopen +returns NULL if there was insufficient memory to allocate the gzFile state, +if an invalid mode was specified +(an 'r', 'w', or 'a' was not provided, or '+' was provided), or if fd is -1. +The file descriptor is not used until the next gz* read, write, seek, +or close operation, so +.Fn gzdopen +will not detect if fd is invalid (unless fd is -1). +.It Xo +.Fa int +.Fn gzbuffer "gzFile file" "unsigned size" ; +.Xc +.Pp +Set the internal buffer size used by this library's functions. +The default buffer size is 8192 bytes. +This function must be called after +.Fn gzopen +or +.Fn gzdopen , +and before any other calls that read or write the file. +The buffer memory allocation is always deferred to the first read or write. +Three times that size in buffer space is allocated. +A larger buffer size of, for example, 64K or 128K bytes, +will noticeably increase the speed of decompression (reading). +.Pp +The new buffer size also affects the maximum length for +.Fn gzprintf . +.Pp +.Fn gzbuffer +returns 0 on success, or -1 on failure, such as being called too late. +.It Xo +.Fa int +.Fn gzsetparams "gzFile file" "int level" "int strategy" ; +.Xc +.Pp +The +.Fn gzsetparams +function dynamically updates the compression level or strategy. +See the description of +.Fn deflateInit2 +for the meaning of these parameters. +Previously provided data is flushed before the parameter change. +.Pp +.Fn gzsetparams +returns +.Dv Z_OK +if successful, +.Dv Z_STREAM_ERROR +if the file was not opened for writing, +.Dv Z_ERRNO +if there is an error writing the flushed data, or +.Dv Z_MEM_ERROR +if there is a memory allocation error. +.It Xo +.Fa int +.Fn gzread "gzFile file" "voidp buf" "unsigned len" ; +.Xc +.Pp +Reads the given number of uncompressed bytes from the compressed file. +If the input file is not in gzip format, +.Fn gzread +copies the given number of bytes into the buffer directly from the file. +.Pp +After reaching the end of a gzip stream in the input, +.Fn gzread +will continue to read, looking for another gzip stream. +Any number of gzip streams may be concatenated in the input file, +and will all be decompressed by +.Fn gzread . +If something other than a gzip stream is encountered after a gzip stream, +that remaining trailing garbage is ignored (and no error is returned). +.Pp +.Fn gzread +can be used to read a gzip file that is being concurrently written. +Upon reaching the end of the input, +.Fn gzread +will return with the available data. +If the error code returned by +.Fn gzerror +is +.Dv Z_OK +or +.Dv Z_BUF_ERROR , +then +.Fn gzclearerr +can be used to clear the end of file indicator in order to permit +.Fn gzread +to be tried again. +.Dv Z_OK +indicates that a gzip stream was completed on the last +.Fn gzread . +.Dv Z_BUF_ERROR +indicates that the input file ended in the middle of a gzip stream. +Note that +.Fn gzread +does not return -1 in the event of an incomplete gzip stream. +This error is deferred until +.Fn gzclose , +which will return +.Dv Z_BUF_ERROR +if the last +.Fn gzread +ended in the middle of a gzip stream. +Alternatively, +.Fn gzerror +can be used before +.Fn gzclose +to detect this case. +.Pp +.Fn gzread +can be used to read a gzip file on a non-blocking device. +If the input stalls and there is no uncompressed data to return, then +.Fn gzread +will return \-1, and errno will be +.Dv EAGAIN +or +.Dv EWOULDBLOCK . +.Fn gzread +can then be called again. +.Pp +.Fn gzread +returns the number of uncompressed bytes actually read, +less than +.Fa len +for end of file, or -1 for error. +If +.Fa len +is too large to fit in an int, +then nothing is read, -1 is returned, and the error state is set to +.Dv Z_STREAM_ERROR . +If some data was read before an error, +then that data is returned until exhausted, +after which the next call will signal the error. +.It Xo +.Fa z_size_t +.Fn gzfread "voidp buf" "z_size_t size" "z_size_t nitems" "gzFile file" ; +.Xc +.Pp +Read up to +.Fa nitems +items of size +.Fa size +from +.Fa file +to +.Fa buf , +otherwise operating as +.Fn gzread +does. +This duplicates the interface of stdio's +.Xr fread 3 , +with size_t request and return types. +If the library defines size_t, then z_size_t is identical to size_t. +If not, then z_size_t is an unsigned integer type that can contain a pointer. +.Pp +.Fn gzfread +returns the number of full items read of size +.Fa size , +or zero if the end of the file was reached and a full item could not be read, +or if there was an error. +.Fn gzerror +must be consulted if zero is returned in order to determine +if there was an error. +If the multiplication of +.Fa size +and +.Fa nitems +overflows, i.e. the product does not fit in a z_size_t, then nothing is read, +zero is returned, and the error state is set to +.Dv Z_STREAM_ERROR . +.Pp +In the event that the end of file is reached and only a partial item is +available at the end, i.e. the remaining uncompressed data length is not a +multiple of size, then the final partial item is nevertheless read into +.Fa buf +and the end-of-file flag is set. +The length of the partial item read is not provided, +but could be inferred from the result of +.Fn gztell . +This behavior is the same as that of +.Xr fread 3 +implementations in common libraries. +This could result in data loss if used with size != 1 +when reading a concurrently written file or +a non-blocking file. +In that case, use size == 1 or +.Fn gzread +instead. +.It Xo +.Fa int +.Fn gzwrite "gzFile file" "voidpc buf" "unsigned len" ; +.Xc +.Pp +The +.Fn gzwrite +function writes the given number of uncompressed bytes into the compressed file. +.Fn gzwrite +returns the number of uncompressed bytes written or 0 in case of error or +if +.Fa len +is 0. +If the write destination is non-blocking, then +.Fn gzwrite +may return a number of bytes written that is not 0 and less than +.Fa len . +If +.Fa len +does not fit in an int, then 0 is returned and nothing is written. +.It Xo +.Fa z_size_t +.Fn gzfwrite "voidpc buf" "z_size_t size" "z_size_t nitems" "gzFile file" ; +.Xc +.Pp +.Fn gzfwrite +writes +.Fa nitems +items of size +.Fa size +from +.Fa buf +to +.Fa file , +duplicating the interface of stdio's +.Xr fwrite 3 , +with size_t request and return types. +If the library defines size_t, then z_size_t is identical to size_t. +If not, then z_size_t is an unsigned integer type that can contain a pointer. +.Pp +.Fn gzfwrite +returns the number of full items written of size +.Fa size , +or zero if there was an error. +If the multiplication of +.Fa size +and +.Fa nitems +overflows, +i.e. the product does not fit in a z_size_t, then nothing is written, +zero is returned, and the error state is set to +.Dv Z_STREAM_ERROR . +.Pp +If writing a concurrently read file or a non-blocking file with size != 1, +a partial item could be written, with no way of knowing +how much of it was not written, resulting in data loss. +In that case, use size == 1 or +.Fn gzwrite +instead. +.It Xo +.Fa int +.Fn gzprintf "gzFile file" "const char *format" "..." ; +.Xc +.Pp +The +.Fn gzprintf +function converts, formats, and writes the args to the compressed file +under control of the format string, as in +.Xr fprintf 3 . +.Fn gzprintf +returns the number of uncompressed bytes actually written, +or a negative zlib error code in case of error. +The number of uncompressed bytes written is limited to 8191, +or one less than the buffer size given to +.Fn gzbuffer . +The caller should ensure that this limit is not exceeded. +If it is exceeded, then +.Fn gzprintf +will return an error +.Pq 0 +with nothing written. +In this case, there may also be a buffer overflow +with unpredictable consequences, which is possible only if +.Nm zlib +was compiled with the insecure functions +.Fn sprintf +or +.Fn vsprintf +because the secure +.Fn snprintf +or +.Fn vsnprintf +functions were not available. +This can be determined using +.Fn zlibCompileFlags . +.It Xo +.Fa int +.Fn gzputs "gzFile file" "const char *s" ; +.Xc +.Pp +The +.Fn gzputs +function writes the given NUL-terminated string to the compressed file, +excluding the terminating NUL character. +.Pp +.Fn gzputs +returns the number of characters written, or -1 in case of error. +.It Xo +.Fa char * +.Fn gzgets "gzFile file" "char *buf" "int len" ; +.Xc +.Pp +The +.Fn gzgets +function reads bytes from the compressed file until len-1 characters are read, +or a newline character is read and transferred to +.Fa buf , +or an end-of-file condition is encountered. +If any characters are read or if len == 1, +the string is terminated with a NUL character. +If no characters are read due to an end-of-file or len < 1, +then the buffer is left untouched. +.Pp +.Fn gzgets +returns +.Fa buf , +which is a NUL-terminated string, or it returns +.Dv NULL +for end-of-file or in case of error. +If some data was read before an error, +then that data is returned until exhausted, after which the next call +will return +.Dv NULL +to signal the error. +.Pp +.Fn gzgets +can be used on a file being concurrently written, +and on a non-blocking device, both as for +.Fn gzread . +However lines may be broken in the middle, +leaving it up to the application +to reassemble them as needed. +.It Xo +.Fa int +.Fn gzputc "gzFile file" "int c" ; +.Xc +.Pp +The +.Fn gzputc +function writes +.Fa c , +converted to an unsigned char, into the compressed file. +.Fn gzputc +returns the value that was written, or -1 in case of error. +.It Xo +.Fa int +.Fn gzgetc "gzFile file" ; +.Xc +.Pp +The +.Fn gzgetc +function reads one byte from the compressed file. +.Fn gzgetc +returns this byte or -1 in case of end of file or error. +If some data was read before an error, +then that data is returned until exhausted, +after which the next call will return \-1 to signal the error. +.Pp +This is implemented as a macro for speed. +As such, it does not do all of the checking the other functions do. +That is, it does not check to see if file is +.Dv NULL , +nor whether the structure +.Fa file +points to has been clobbered or not. +.Pp +.Fn gzgetc +can be used to read a gzip file on a non-blocking device. +If the input stalls and there is no uncompressed data to return, then +.Fn gzgetc +will return \-1, and errno will be +.Dv EAGAIN +or +.Dv EWOULDBLOCK . +.Fn gzread +can then be called again. +.It Xo +.Fa int +.Fn gzungetc "int c" "gzFile file" ; +.Xc +.Pp +Push one character back onto the stream to be read as the first character +on the next read. +At least one character of push-back is allowed. +.Fn gzungetc +returns the character pushed, or -1 on failure. +.Fn gzungetc +will fail if c is -1, +and may fail if a character has been pushed but not read yet. +If +.Fn gzungetc +is used immediately after +.Fn gzopen +or +.Fn gzdopen , +at least the output buffer size of pushed characters is allowed. +(See +.Fn gzbuffer +above.) +The pushed character will be discarded if the stream is repositioned with +.Fn gzseek +or +.Fn gzrewind . +.Pp +gzungetc(\-1, file) will force any pending seek to execute. +Then +.Fn gztell +will report the position, even if the requested seek reached end of file. +This can be used to determine the number of uncompressed bytes +in a gzip file without having to read it into a buffer. +.It Xo +.Fa int +.Fn gzflush "gzFile file" "int flush" ; +.Xc +.Pp +The +.Fn gzflush +function flushes all pending output into the compressed file. +The parameter +.Fa flush +is as in the +.Fn deflate +function. +The return value is the +.Nm zlib +error number (see function +.Fn gzerror +below). +.Fn gzflush +is only permitted when writing. +.Pp +If the flush parameter is +.Dv Z_FINISH , +the remaining data is written and the gzip stream is completed in the output. +If +.Fn gzwrite +is called again, a new gzip stream will be started in the output. +.Fn gzread +is able to read such concatenated gzip streams. +.Pp +.Fn gzflush +should be called only when strictly necessary because it will +degrade compression if called too often. +.It Xo +.Fa z_off_t +.Fn gzseek "gzFile file" "z_off_t offset" "int whence" ; +.Xc +.Pp +Sets the starting position for the next +.Fn gzread +or +.Fn gzwrite +on the given compressed file. +The offset represents a number of bytes in the uncompressed data stream. +The whence parameter is defined as in +.Xr lseek 2 ; +the value +.Dv SEEK_END +is not supported. +.Pp +If the file is opened for reading, this function is emulated but can be +extremely slow. +If the file is opened for writing, only forward seeks are supported; +.Fn gzseek +then compresses a sequence of zeroes up to the new starting position. +For reading or writing, any actual seeking is deferred until +the next read or write operation, or close operation when writing. +.Pp +.Fn gzseek +returns the resulting offset location as measured in bytes from +the beginning of the uncompressed stream, or -1 in case of error, +in particular if the file is opened for writing and the new starting position +would be before the current position. +.It Xo +.Fa int +.Fn gzrewind "gzFile file" ; +.Xc +.Pp +The +.Fn gzrewind +function rewinds the given +.Fa file . +This function is supported only for reading. +.Pp +gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET). +.It Xo +.Fa z_off_t +.Fn gztell "gzFile file" ; +.Xc +.Pp +The +.Fn gztell +function returns the starting position for the next +.Fn gzread +or +.Fn gzwrite +on the given compressed file. +This position represents a number of bytes in the uncompressed data stream, +and is zero when starting, +even if appending or reading a gzip stream from the middle of a file using +.Fn gzdopen . +.Pp +gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR). +.It Xo +.Fa int +.Fn gzoffset "gzFile file" ; +.Xc +.Pp +Returns the current offset in the file being read or written. +This offset includes the count of bytes that precede the gzip stream, +for example when appending or when using +.Fn gzdopen +for reading. +When reading, the offset does not include as yet unused buffered input. +This information can be used for a progress indicator. +On error, +.Fn gzoffset +returns -1. +.It Xo +.Fa int +.Fn gzeof "gzFile file" ; +.Xc +.Pp +Returns true (1) if the end-of-file indicator has been set while reading, +false (0) otherwise. +Note that the end-of-file indicator is set only if the +read tried to go past the end of the input, but came up short. +Therefore just like +.Xr feof 3 , +.Fn gzeof +may return false even if there is no more data to read, +in the event that the last read request was for the exact number of +bytes remaining in the input file. +This will happen if the input file size is an exact multiple of the buffer size. +.Pp +If +.Fn gzeof +returns true, then the read functions will return no more data, +unless the end-of-file indicator is reset by +.Fn gzclearerr +and the input file has grown since the previous end of file was detected. +.It Xo +.Fa int +.Fn gzdirect "gzFile file" ; +.Xc +.Pp +Returns true (1) if +.Fa file +is being copied directly while reading, +or false (0) if +.Fa file +is a gzip stream being decompressed. +.Pp +If the input file is empty, +.Fn gzdirect +will return true, since the input does not contain a gzip stream. +.Pp +If +.Fn gzdirect +is used immediately after +.Fn gzopen +or +.Fn gzdopen , +it will cause buffers to be allocated to allow reading the file +to determine if it is a gzip file. +Therefore if +.Fn gzbuffer +is used, it should be called before +.Fn gzdirect . +If the input is being written concurrently +or the device is non-blocking, then +.Fn gzdirect +may give a different answer once four bytes of input have been accumulated, +which is what is needed to confirm or deny a gzip reader. +Before this, +.Fa gzdirect +will return true (1). +.Pp +When writing, +.Fn gzdirect +returns true (1) if transparent writing was requested +("wT" for the +.Fn gzopen +mode), +or false (0) otherwise. +(Note: +.Fn gzdirect +is not needed when writing. +Transparent writing must be explicitly requested, +so the application already knows the answer. +When linking statically, using +.Fn gzdirect +will include all of the zlib code for gzip file reading and decompression, +which may not be desired.) +.It Xo +.Fa int +.Fn gzclose "gzFile file" ; +.Xc +.Pp +Flushes all pending output if necessary, closes the compressed file and +deallocates the (de)compression state. +Note that once file is closed, you cannot call +.Fn gzerror +with +.Fa file , +since its structures have been deallocated. +.Fn gzclose +must not be called more than once on the same file, +just as +.Xr free 3 +must not be called more than once on the same allocation. +.Pp +.Fn gzclose +will return +.Dv Z_STREAM_ERROR +if +.Fa file +is not valid, +.Dv Z_ERRNO +on a file operation error, +.Dv Z_MEM_ERROR +if out of memory, +.Dv Z_BUF_ERROR +if the last read ended in the middle of a gzip stream, or +.Dv Z_OK +on success. +.It Xo +.Fa int +.Fn gzclose_r "gzFile file" ; +.Xc +.It Xo +.Fa int +.Fn gzclose_w "gzFile file" ; +.Xc +.Pp +Same as +.Fn gzclose , +but +.Fn gzclose_r +is only for use when reading, and +.Fn gzclose_w +is only for use when writing or appending. +The advantage to using these instead of +.Fn gzclose +is that they avoid linking in zlib compression or decompression code +that is not used when only reading or only writing, respectively. +If +.Fn gzclose +is used, then both compression and decompression code will be included +in the application when linking to a static zlib library. +.It Xo +.Fa const char * +.Fn gzerror "gzFile file" "int *errnum" ; +.Xc +.Pp +The +.Fn gzerror +function returns the error message for the last error which occurred on the +given compressed +.Fa file . +If +.Fa errnum +is not +.Dv NULL , +.Pf * Fa errnum +is set to the +.Nm zlib +error number. +If an error occurred in the file system and not in the compression library, +.Fa errnum +is set to +.Dv Z_ERRNO +and the application may consult errno to get the exact error code. +.Pp +The application must not modify the returned string. +Future calls to this function may invalidate the previously returned string. +If +.Ar file +is closed, then the string previously returned by +.Fn gzerror +will no longer be available. +.Pp +.Fn gzerror +should be used to distinguish errors from end-of-file for those +functions above that do not distinguish those cases in their return values. +.It Xo +.Fa void +.Fn gzclearerr "gzFile file" ; +.Xc +Clears the error and end-of-file flags for +.Fa file . +This is analogous to the +.Fn clearerr +function in stdio. +This is useful for continuing to read a gzip file +that is being written concurrently. +.El +.Sh CHECKSUM FUNCTIONS +These functions are not related to compression but are exported +anyway because they might be useful in applications using the +compression library. +.Bl -tag -width Ds +.It Xo +.Fa uLong +.Fn adler32 "uLong adler" "const Bytef *buf" "uInt len" ; +.Xc +The +.Fn adler32 +function updates a running Adler-32 checksum with the bytes buf[0..len-1] +and returns the updated checksum. +If +.Fa buf +is +.Dv NULL , +this function returns the required initial value for the checksum. +.Pp +An Adler-32 checksum is almost as reliable as a CRC-32 but can be computed +much faster. +Usage example: +.Bd -unfilled -offset indent +uLong adler = adler32(0L, NULL, 0); + +while (read_buffer(buffer, length) != EOF) { +adler = adler32(adler, buffer, length); +} +if (adler != original_adler) error(); +.Ed +.It Xo +.Fa uLong +.Fn adler32_z "uLong adler" "const Bytef *buf" "z_size_t len" ; +.Xc +.Pp +The same as +.Fn adler32 , +but with a size_t length. +.It Xo +.Fa uLong +.Fn adler32_combine "uLong adler1" "uLong adler2" "z_off_t len2" ; +.Xc +.Pp +The +.Fn adler32_combine +function combines two Adler-32 checksums into one. +For two sequences of bytes, seq1 and seq2 with lengths len1 and len2, +Adler-32 checksums are calculated for each, adler1 and adler2. +.Fn adler32_combine +returns the Adler-32 checksum of seq1 and seq2 concatenated, +requiring only adler1, adler2, and len2. +Note that the z_off_t type (like off_t) is a signed integer. +If +.Ar len2 +is negative, the result has no meaning or utility. +.It Xo +.Fa uLong +.Fn crc32 "uLong crc" "const Bytef *buf" "uInt len" ; +.Xc +.Pp +The +.Fn crc32 +function updates a running CRC-32 with the bytes buf[0..len-1] +and returns the updated CRC-32. +If +.Fa buf +is +.Dv NULL , +this function returns the required initial value for the CRC. +Pre- and post-conditioning +.Pq one's complement +is performed within this function so it shouldn't be done by the application. +Usage example: +.Bd -unfilled -offset indent +uLong crc = crc32(0L, NULL, 0); + +while (read_buffer(buffer, length) != EOF) { +crc = crc32(crc, buffer, length); +} +if (crc != original_crc) error(); +.Ed +.It Xo +.Fa uLong +.Fn crc32_z "uLong adler "const Bytef *buf" "z_size_t len" ; +.Xc +.Pp +The same as +.Fn crc32 , +but with a size_t length. +.It Xo +.Fa uLong +.Fn crc32_combine "uLong crc1" "uLong crc2" "z_off_t len2" ; +.Xc +.Pp +The +.Fn crc32_combine +function combines two CRC-32 check values into one. +For two sequences of bytes, +seq1 and seq2 with lengths len1 and len2, +CRC-32 check values are calculated for each, crc1 and crc2. +.Fn crc32_combine +returns the CRC-32 check value of seq1 and seq2 concatenated, +requiring only crc1, crc2, and len2. +len2 must be non-negative, otherwise zero is returned. +.It Xo +.Fa uLong +.Fn crc32_combine_gen "z_off_t len2" ; +.Xc +.Pp +The +.Fn crc32_combine_gen +function returns the operator corresponding to the length len2, +to be used with +.Fn crc32_combine_op . +len2 must be non-negative, otherwise zero is returned. +.It Xo +.Fa uLong +.Fn crc32_combine_op "uLong crc1" "uLong crc2" "uLong op" ; +.Xc +.Pp +The +.Fn crc32_combine_op +function gives the same result as +.Fn crc32_combine , +using op in place of len2. +op is generated from len2 by +.Fn crc32_combine_gen . +This is faster than +.Fn crc32_combine +if the generated op is used more than once. +.El +.Sh STRUCTURES +.Bd -unfilled +struct internal_state; + +typedef struct z_stream_s { + Bytef *next_in; /* next input byte */ + uInt avail_in; /* number of bytes available at next_in */ + off_t total_in; /* total number of input bytes read so far */ + + Bytef *next_out; /* next output byte will go here */ + uInt avail_out; /* remaining free space at next_out */ + off_t total_out; /* total number of bytes output so far */ + + char *msg; /* last error message, NULL if no error */ + struct internal_state FAR *state; /* not visible by applications */ + + alloc_func zalloc; /* used to allocate the internal state */ + free_func zfree; /* used to free the internal state */ + voidpf opaque; /* private data object passed to zalloc and zfree*/ + + int data_type; /* best guess about the data type: binary or text + for deflate, or the decoding state for inflate */ + uLong adler; /* Adler-32 or CRC-32 value of the uncompressed data */ + uLong reserved; /* reserved for future use */ +} z_stream; + +typedef z_stream FAR * z_streamp; +.Ed +.Bd -unfilled +/* + gzip header information passed to and from zlib routines. + See RFC 1952 for more details on the meanings of these fields. +*/ +typedef struct gz_header_s { + int text; /* true if compressed data believed to be text */ + uLong time; /* modification time */ + int xflags; /*extra flags (not used when writing a gzip file)*/ + int os; /* operating system */ + Bytef *extra; /* pointer to extra field or NULL if none */ + uInt extra_len; /* extra field length (valid if extra != NULL) */ + uInt extra_max; /* space at extra (only when reading header) */ + Bytef *name; /* pointer to zero-terminated file name or NULL*/ + uInt name_max; /* space at name (only when reading header) */ + Bytef *comment; /* pointer to zero-terminated comment or NULL */ + uInt comm_max; /* space at comment (only when reading header) */ + int hcrc; /* true if there was or will be a header crc */ + int done; /* true when done reading gzip header (not used + when writing a gzip file) */ +} gz_header; + +typedef gz_header FAR *gz_headerp; +.Ed +.Pp +The application must update +.Fa next_in +and +.Fa avail_in +when +.Fa avail_in +has dropped to zero. +It must update +.Fa next_out +and +.Fa avail_out +when +.Fa avail_out +has dropped to zero. +The application must initialize +.Fa zalloc , +.Fa zfree , +and +.Fa opaque +before calling the init function. +All other fields are set by the compression library +and must not be updated by the application. +.Pp +The +.Fa opaque +value provided by the application will be passed as the first +parameter for calls to +.Fn zalloc +and +.Fn zfree . +This can be useful for custom memory management. +The compression library attaches no meaning to the +.Fa opaque +value. +.Pp +.Fa zalloc +must return +.Dv NULL +if there is not enough memory for the object. +If +.Nm zlib +is used in a multi-threaded application, +.Fa zalloc +and +.Fa zfree +must be thread safe. +In that case, +.Nm zlib +is thread-safe. +When +.Fa zalloc +and +.Fa zfree +are +.Dv NULL +on entry to the initialization function, +they are set to internal routines that use the standard library functions +.Xr malloc 3 +and +.Xr free 3 . +.Pp +On 16-bit systems, the functions +.Fa zalloc +and +.Fa zfree +must be able to allocate exactly 65536 bytes, +but will not be required to allocate more than this if the symbol MAXSEG_64K +is defined (see +.In zconf.h ) . +.Pp +WARNING: On MSDOS, pointers returned by +.Fa zalloc +for objects of exactly 65536 bytes *must* have their offset normalized to zero. +The default allocation function provided by this library ensures this (see +.Pa zutil.c ) . +To reduce memory requirements and avoid any allocation of 64K objects, +at the expense of compression ratio, +compile the library with -DMAX_WBITS=14 (see +.In zconf.h ) . +.Pp +The fields +.Fa total_in +and +.Fa total_out +can be used for statistics or progress reports. +After compression, +.Fa total_in +holds the total size of the uncompressed data and may be saved for use +in the decompressor +(particularly if the decompressor wants to decompress everything +in a single step). +.Sh CONSTANTS +.Bd -unfilled +#define Z_NO_FLUSH 0 +#define Z_PARTIAL_FLUSH 1 +#define Z_SYNC_FLUSH 2 +#define Z_FULL_FLUSH 3 +#define Z_FINISH 4 +#define Z_BLOCK 5 +#define Z_TREES 6 +/* Allowed flush values; see deflate() and inflate() below for details */ + +#define Z_OK 0 +#define Z_STREAM_END 1 +#define Z_NEED_DICT 2 +#define Z_ERRNO (-1) +#define Z_STREAM_ERROR (-2) +#define Z_DATA_ERROR (-3) +#define Z_MEM_ERROR (-4) +#define Z_BUF_ERROR (-5) +#define Z_VERSION_ERROR (-6) +/* Return codes for the compression/decompression functions. + * Negative values are errors, + * positive values are used for special but normal events. + */ + +#define Z_NO_COMPRESSION 0 +#define Z_BEST_SPEED 1 +#define Z_BEST_COMPRESSION 9 +#define Z_DEFAULT_COMPRESSION (-1) +/* compression levels */ + +#define Z_FILTERED 1 +#define Z_HUFFMAN_ONLY 2 +#define Z_RLE 3 +#define Z_FIXED 4 +#define Z_DEFAULT_STRATEGY 0 +/* compression strategy; see deflateInit2() below for details */ + +#define Z_BINARY 0 +#define Z_TEXT 1 +#define Z_ASCII Z_TEXT /* for compatibility with 1.2.2 and earlier */ +#define Z_UNKNOWN 2 +/* Possible values of the data_type field for deflate() */ + +#define Z_DEFLATED 8 +/* The deflate compression method + * (the only one supported in this version) +*/ + +#define Z_NULL 0 /* for initializing zalloc, zfree, opaque */ + +#define zlib_version zlibVersion() +/* for compatibility with versions < 1.0.2 */ +.Ed +.Sh VARIOUS HACKS +deflateInit and inflateInit are macros to allow checking the +.Nm zlib +version and the compiler's view of +.Fa z_stream . +.Bl -tag -width Ds +.It Xo +.Fa int +.Fn deflateInit_ "z_stream strm" "int level" "const char *version" "int stream_size" ; +.Xc +.It Xo +.Fa int +.Fn inflateInit_ "z_stream strm" "const char *version" "int stream_size" ; +.Xc +.It Xo +.Fa int +.Fo deflateInit2_ +.Fa "z_stream strm" +.Fa "int level" +.Fa "int method" +.Fa "int windowBits" +.Fa "int memLevel" +.Fa "int strategy" +.Fa "const char *version" +.Fa "int stream_size" +.Fc ; +.Xc +.It Xo +.Fa int +.Fn inflateInit2_ "z_stream strm" "int windowBits" "const char *version" "int stream_size" ; +.Xc +.It Xo +.Fa int +.Fn inflateBackInit_ "z_stream *strm" "int windowBits" "unsigned char FAR *window" "const char *version" "int stream_size" ; +.Xc +.It Xo +.Fa const char * +.Fn zError "int err" ; +.Xc +.It Xo +.Fa int +.Fn inflateSyncPoint "z_streamp z" ; +.Xc +.It Xo +.Fa const uLongf * +.Fn "get_crc_table" "void" ; +.Xc +.El +.Sh SEE ALSO +.Xr compress 1 , +.Xr gzip 1 +.Sh STANDARDS +.Rs +.%A P. Deutsch +.%A J-L. Gailly +.%D May 1996 +.%R RFC 1950 +.%T ZLIB Compressed Data Format Specification version 3.3 +.Re +.Pp +.Rs +.%A P. Deutsch +.%D May 1996 +.%R RFC 1951 +.%T DEFLATE Compressed Data Format Specification version 1.3 +.Re +.Pp +.Rs +.%A P. Deutsch +.%D May 1996 +.%R RFC 1952 +.%T GZIP file format specification version 4.3 +.Re +.Sh HISTORY +This manual page is based on an HTML version of +.In zlib.h +converted by +.An piaip Aq Mt piaip@csie.ntu.edu.tw +and was converted to mdoc format by the +.Ox +project. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/static/openbsd/man3/confstr.3 b/static/openbsd/man3/confstr.3 new file mode 100644 index 00000000..82bde43c --- /dev/null +++ b/static/openbsd/man3/confstr.3 @@ -0,0 +1,205 @@ +.\" $OpenBSD: confstr.3,v 1.20 2014/01/21 03:15:45 schwarze 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. +.\" +.Dd $Mdocdate: January 21 2014 $ +.Dt CONFSTR 3 +.Os +.Sh NAME +.Nm confstr +.Nd get string-valued configurable variables +.Sh SYNOPSIS +.In unistd.h +.Ft size_t +.Fn confstr "int name" "char *buf" "size_t len" +.Sh DESCRIPTION +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 include file +.In unistd.h . +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 NUL terminated. +.Pp +The available values are as follows: +.Bl -tag -width "123456" -compact +.It Li _CS_PATH +Return a value for the +.Ev PATH +environment variable that finds all the standard utilities. +.Pp +.It Li _CS_V7_ENV +Return a space separated list of environment variable assignments +(other than +.Ev PATH ) +necessary for obtaining a shell environment compliant with +.St -p1003.1-2008 . +.Pp +.It Li _CS_V6_ENV +Return a space separated list of environment variable assignments +(other than +.Ev PATH ) +necessary for obtaining a shell environment compliant with +.St -p1003.1-2001 . +.Pp +.It Li _CS_POSIX_V7_THREADS_CFLAGS +Return the compiler flags for compiling objects in a program that +uses multiple threads. +.Pp +.It Li _CS_POSIX_V7_THREADS_LDFLAGS +Return the linker flags for linking an executable that uses multiple +threads. +.Pp +.It Li _CS_POSIX_V7_WIDTH_RESTRICTED_ENVS +.It Li _CS_POSIX_V6_WIDTH_RESTRICTED_ENVS +Return a newline separated list of supported compilation environments +in which none of the following types are wider than type +.Vt long : +.Vt blksize_t , cc_t , mode_t , nfds_t , pid_t , ptrdiff_t , size_t , +.Vt speed_t , ssize_t , suseconds_t , tcflag_t , wchar_t , +and +.Vt wint_t . +.Pp +.It Li _CS_POSIX_V7_ILP32_OFFBIG_CFLAGS +.It Li _CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS +.It Li _CS_POSIX_V7_ILP32_OFFBIG_LIBS +.It Li _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS +.It Li _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS +.It Li _CS_POSIX_V6_ILP32_OFFBIG_LIBS +If +.Fn sysconf _SC_V7_ILP32_OFFBIG +returns a value greater than zero, +return the compiler flags for compiling objects, +the linker flags for linking an executable, +or the linker arguments for additional libraries, respectively, +for a compilation environment with 32-bit +.Vt int , long , +and +.Vt pointer +types and an +.Vt off_t +type that has a width of at least 64 bits. +Otherwise, the result is unspecified. +.Pp +.It Li _CS_POSIX_V7_LP64_OFF64_CFLAGS +.It Li _CS_POSIX_V7_LP64_OFF64_LDFLAGS +.It Li _CS_POSIX_V7_LP64_OFF64_LIBS +.It Li _CS_POSIX_V6_LP64_OFF64_CFLAGS +.It Li _CS_POSIX_V6_LP64_OFF64_LDFLAGS +.It Li _CS_POSIX_V6_LP64_OFF64_LIBS +If +.Fn sysconf _SC_V7_LP64_OFF64 +returns a value greater than zero, +return the compiler flags for compiling objects, +the linker flags for linking an executable, +or the linker arguments for additional libraries, respectively, +for a compilation environment with 64-bit +.Vt int , long , pointer , +and +.Vt off_t +types. +Otherwise, the result is unspecified. +.Pp +.It Li _CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS +.It Li _CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS +.It Li _CS_POSIX_V7_LPBIG_OFFBIG_LIBS +.It Li _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS +.It Li _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS +.It Li _CS_POSIX_V6_LPBIG_OFFBIG_LIBS +If +.Fn sysconf _SC_V7_LPBIG_OFFBIG +returns a value greater than zero, +return the compiler flags for compiling objects, +the linker flags for linking an executable, +or the linker arguments for additional libraries, respectively, +for a compilation environment with +.Vt int , long , pointer , +and +.Vt off_t +types that all have widths of at least 64 bits. +Otherwise, the result is unspecified. +.El +.Sh RETURN VALUES +If the call to +.Nm +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 +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa name +argument is invalid. +.El +.Sh SEE ALSO +.Xr pathconf 2 , +.Xr sysconf 3 +.Sh STANDARDS +The +.Nm +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Nm +function first appeared in +.Bx 4.4 . diff --git a/static/openbsd/man3/conj.3 b/static/openbsd/man3/conj.3 new file mode 100644 index 00000000..88cfff6c --- /dev/null +++ b/static/openbsd/man3/conj.3 @@ -0,0 +1,60 @@ +.\" $OpenBSD: conj.3,v 1.6 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2010 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. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt CONJ 3 +.Os +.Sh NAME +.Nm conj , +.Nm conjf , +.Nm conjl +.Nd compute the complex conjugate +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn conj , +.Fn conjf +and +.Fn conjl +functions reverse the sign of the imaginary part of +.Fa z , +producing the complex conjugate. +.Sh RETURN VALUES +The +.Fn conj , +.Fn conjf +and +.Fn conjl +functions return the complex conjugate of the complex number +.Fa z . +.Sh SEE ALSO +.Xr carg 3 +.Sh STANDARDS +The +.Fn conj , +.Fn conjf +and +.Fn conjl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/copysign.3 b/static/openbsd/man3/copysign.3 new file mode 100644 index 00000000..db6402a5 --- /dev/null +++ b/static/openbsd/man3/copysign.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: copysign.3,v 1.5 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt COPYSIGN 3 +.Os +.Sh NAME +.Nm copysign , +.Nm copysignf , +.Nm copysignl +.Nd copy sign +.Sh SYNOPSIS +.Lb libm +.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" +.Sh DESCRIPTION +.Fn copysign +returns +.Fa x +with its sign changed to +.Fa y Ns 's. +The +.Fn copysignf +function is a single precision version of +.Fn copysign . +The +.Fn copysignl +function is an extended precision version of +.Fn copysign . +.Sh SEE ALSO +.Xr fabs 3 +.Sh STANDARDS +.St -ieee754 +.Sh HISTORY +The +.Nm copysign , +.Nm copysignf +and +.Nm copysignl +functions appeared in +.Bx 4.3 , +.Nx 1.1 +and +.Ox 4.5 , +respectively. diff --git a/static/openbsd/man3/cos.3 b/static/openbsd/man3/cos.3 new file mode 100644 index 00000000..9508b34c --- /dev/null +++ b/static/openbsd/man3/cos.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: cos.3,v 1.17 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt COS 3 +.Os +.Sh NAME +.Nm cos , +.Nm cosf , +.Nm cosl +.Nd cosine functions +.Sh SYNOPSIS +.Lb libm +.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 +function computes the cosine of +.Fa x +(measured in radians). +The +.Fn cosf +function is a single precision version of +.Fn cos . +The +.Fn cosl +function is an extended precision version of +.Fn cos . +A large magnitude argument may yield a result with little or no +significance. +.Sh RETURN VALUES +The +.Fn cos , +.Fn cosf +and +.Fn cosl +functions return the cosine value. +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cosh 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 first appeared in +.At v1 . diff --git a/static/openbsd/man3/cosh.3 b/static/openbsd/man3/cosh.3 new file mode 100644 index 00000000..e59474e2 --- /dev/null +++ b/static/openbsd/man3/cosh.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: cosh.3,v 1.18 2025/06/07 10:33:06 schwarze 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. +.\" +.\" from: @(#)cosh.3 5.1 (Berkeley) 5/2/91 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt COSH 3 +.Os +.Sh NAME +.Nm cosh , +.Nm coshf , +.Nm coshl +.Nd hyperbolic cosine functions +.Sh SYNOPSIS +.Lb libm +.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 +function computes the hyperbolic cosine of +.Fa x . +The +.Fn coshf +function is a single precision version of +.Fn cosh . +The +.Fn coshl +function is an extended precision version of +.Fn cosh . +.Sh RETURN VALUES +If the magnitude of x is too large, +.Fn cosh "x" , +.Fn coshf "x" +and +.Fn coshl "x" +return infinity and set the global variable +.Va errno +to +.Er ERANGE . +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 +.Sh HISTORY +The +.Fn cosh +function first appeared in +.At v7 . diff --git a/static/openbsd/man3/cpow.3 b/static/openbsd/man3/cpow.3 new file mode 100644 index 00000000..ee513cd5 --- /dev/null +++ b/static/openbsd/man3/cpow.3 @@ -0,0 +1,65 @@ +.\" $OpenBSD: cpow.3,v 1.4 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CPOW 3 +.Os +.Sh NAME +.Nm cpow , +.Nm cpowf , +.Nm cpowl +.Nd complex power functions +.Sh SYNOPSIS +.Lb libm +.In complex.h +.Ft double complex +.Fn cpow "double complex x" "double complex z" +.Ft float complex +.Fn cpowf "float complex x" "float complex z" +.Ft long double complex +.Fn cpowl "long double complex x" "long double complex z" +.Sh DESCRIPTION +The +.Fn cpow , +.Fn cpowf +and +.Fn cpowl +functions compute the complex number +.Fa x +raised to the complex power +.Fa z , +with a branch cut along the negative real axis for the first argument. +.Sh RETURN VALUES +The +.Fn cpow , +.Fn cpowf +and +.Fn cpowl +functions return the complex number +.Fa x +raised to the complex power +.Fa z . +.Sh SEE ALSO +.Xr cexp 3 , +.Xr clog 3 +.Sh STANDARDS +The +.Fn cpow , +.Fn cpowf +and +.Fn cpowl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/cproj.3 b/static/openbsd/man3/cproj.3 new file mode 100644 index 00000000..2851522d --- /dev/null +++ b/static/openbsd/man3/cproj.3 @@ -0,0 +1,68 @@ +.\" $OpenBSD: cproj.3,v 1.7 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2010 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. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt CPROJ 3 +.Os +.Sh NAME +.Nm cproj , +.Nm cprojf , +.Nm cprojl +.Nd compute projection onto Riemann sphere +.Sh SYNOPSIS +.Lb libm +.In complex.h +.Ft double complex +.Fn cproj "double complex z" +.Ft float complex +.Fn cprojf "float complex z" +.Ft long double complex +.Fn cprojl "long double complex z" +.Sh DESCRIPTION +The +.Fn cproj , +.Fn cprojf +and +.Fn cprojl +functions compute a projection of +.Fa z +onto the Riemann sphere. +.Sh RETURN VALUES +The +.Fn cproj , +.Fn cprojf +and +.Fn cprojl +functions return +.Fa z +for all finite complex numbers. +If +.Fa z +has an infinite part (even if the other part is NaN), +they return the equivalent of: +.Bd -literal -offset indent +INFINITY + I * copysign(0.0, cimag(z)) +.Ed +.Sh SEE ALSO +.Xr cimag 3 +.Sh STANDARDS +The +.Fn cproj , +.Fn cprojf +and +.Fn cprojl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/creal.3 b/static/openbsd/man3/creal.3 new file mode 100644 index 00000000..ad10bf12 --- /dev/null +++ b/static/openbsd/man3/creal.3 @@ -0,0 +1,59 @@ +.\" $OpenBSD: creal.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CREAL 3 +.Os +.Sh NAME +.Nm creal , +.Nm crealf , +.Nm creall +.Nd complex real functions +.Sh SYNOPSIS +.Lb libm +.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" +.Sh DESCRIPTION +The +.Fn creal , +.Fn crealf +and +.Fn creall +functions compute the real part of +.Fa z . +.Sh RETURN VALUES +The +.Fn creal , +.Fn crealf +and +.Fn creall +functions return the real part of +.Fa z . +.Sh SEE ALSO +.Xr carg 3 +.Sh STANDARDS +The +.Fn creal , +.Fn crealf +and +.Fn creall +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/creat.3 b/static/openbsd/man3/creat.3 new file mode 100644 index 00000000..2563ef0c --- /dev/null +++ b/static/openbsd/man3/creat.3 @@ -0,0 +1,64 @@ +.\" Copyright (c) 1989, 1990 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. +.\" +.\" $OpenBSD: creat.3,v 1.9 2022/12/13 06:56:06 jmc Exp $ +.\" +.Dd $Mdocdate: December 13 2022 $ +.Dt CREAT 3 +.Os +.Sh NAME +.Nm creat +.Nd create a new file +.Sh SYNOPSIS +.In sys/types.h +.In sys/stat.h +.In fcntl.h +.Ft int +.Fn creat "const char *path" "mode_t mode" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr open 2 . +.Ef +.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 first appeared as a system call in +.At v1 . diff --git a/static/openbsd/man3/crypt.3 b/static/openbsd/man3/crypt.3 new file mode 100644 index 00000000..6a21571d --- /dev/null +++ b/static/openbsd/man3/crypt.3 @@ -0,0 +1,144 @@ +.\" $OpenBSD: crypt.3,v 1.46 2025/01/09 23:18:08 jsg Exp $ +.\" +.\" FreeSec: libcrypt +.\" +.\" Copyright (c) 1994 David Burren +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the author nor the names of other contributors +.\" may 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. +.\" +.\" Manual page, using -mandoc macros +.\" +.Dd $Mdocdate: January 9 2025 $ +.Dt CRYPT 3 +.Os +.Sh NAME +.Nm crypt , +.Nm bcrypt_gensalt , +.Nm bcrypt +.Nd password hashing +.Sh SYNOPSIS +.In stdlib.h +.Pp +.In unistd.h +.Ft char * +.Fn crypt "const char *key" "const char *setting" +.In pwd.h +.Ft char * +.Fn bcrypt_gensalt "u_int8_t log_rounds" +.Ft char * +.Fn bcrypt "const char *key" "const char *salt" +.Sh DESCRIPTION +These functions are deprecated in favor of +.Xr crypt_checkpass 3 +and +.Xr crypt_newhash 3 . +.Pp +The +.Fn crypt +function performs password hashing. +Additional code has been added to deter key search attempts and to use +stronger hashing algorithms. +.Pp +The first argument to +.Fn crypt +is a NUL-terminated +string +.Fa key , +typically a user's typed password. +The second, +.Fa setting , +currently supports a single form. +If it begins +with a string character +.Pq Ql $ +and a number then a different algorithm is used depending on the number. +At the moment +.Ql $2 +chooses Blowfish hashing; see below for more information. +.Ss Blowfish crypt +The Blowfish version of 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 string. +The maximum password length is 72. +The final Blowfish password entry is created by encrypting the string +.Pp +.Dq 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. +An encoded +.Sq 8 +would specify 256 rounds. +A valid Blowfish password looks like this: +.Pp +.Dq $2b$12$FPWWO2RJ3CK4FINTw0Hi8OiPKJcX653gzSS.jqltHFMxyDmmQ0Hqq . +.Pp +The whole Blowfish password string is passed as +.Fa setting +for interpretation. +.Sh RETURN VALUES +The function +.Fn crypt +returns a pointer to the encrypted value on success, and +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr encrypt 1 , +.Xr login 1 , +.Xr passwd 1 , +.Xr blowfish 3 , +.Xr crypt_checkpass 3 , +.Xr getpass 3 , +.Xr passwd 5 +.Sh HISTORY +An M-209 based +.Fn crypt +function appeared in +.At v3 . +A DES-based +.Fn crypt +first appeared in +.At v7 . +.Fn bcrypt +first appeared in +.Ox 2.1 . +.Sh BUGS +The +.Fn crypt +function returns a pointer to static data, and subsequent calls to +.Fn crypt +will modify the same object. diff --git a/static/openbsd/man3/crypt_checkpass.3 b/static/openbsd/man3/crypt_checkpass.3 new file mode 100644 index 00000000..07a77ae7 --- /dev/null +++ b/static/openbsd/man3/crypt_checkpass.3 @@ -0,0 +1,113 @@ +.\" $OpenBSD: crypt_checkpass.3,v 1.13 2021/10/29 10:54:33 deraadt Exp $ +.\" +.\" Copyright (c) 2014 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 $Mdocdate: October 29 2021 $ +.Dt CRYPT_CHECKPASS 3 +.Os +.Sh NAME +.Nm crypt_checkpass , +.Nm crypt_newhash +.Nd password hashing +.Sh SYNOPSIS +.In pwd.h +.In unistd.h +.Ft int +.Fn crypt_checkpass "const char *password" "const char *hash" +.Ft int +.Fn crypt_newhash "const char *password" "const char *pref" "char *hash" "size_t hashsize" +.Sh DESCRIPTION +The +.Fn crypt_checkpass +function simplifies checking a user's password. +If both the +.Fa hash +and the +.Fa password +are the empty string, authentication +is a success. +Otherwise, the +.Fa password +is hashed and compared to the provided +.Fa hash . +If the +.Fa hash +is +.Dv NULL , +authentication will always fail, but a default +amount of work is performed to simulate the hashing operation. +A successful match will return 0. +A failure will return \-1 and set +.Xr errno 2 . +.Pp +The +.Fn crypt_newhash +function simplifies the creation of new password hashes. +The provided +.Fa password +is randomly salted and hashed and stored in +.Fa hash . +The size of the available space is specified by +.Fa hashsize , +which should be +.Dv _PASSWORD_LEN . +The +.Fa pref +argument identifies the preferred hashing algorithm and parameters. +Possible values are: +.Bl -tag -width Ds +.It Dq bcrypt, +The bcrypt algorithm, where the value of rounds can be between 4 and 31 and +specifies the base 2 logarithm of the number of rounds. +If rounds is omitted or the special value +.Sq a , +an appropriate number of rounds is automatically selected based on system +performance. +.El +.Sh RETURN VALUES +.Rv -std crypt_checkpass crypt_newhash +.Sh ERRORS +The +.Fn crypt_checkpass +function sets +.Va errno +to +.Er EACCES +when authentication fails. +.Pp +The +.Fn crypt_newhash +function sets +.Va errno +to +.Er EINVAL +if +.Fa pref +is unsupported or insufficient space is provided. +.Sh SEE ALSO +.Xr crypt 3 , +.Xr login.conf 5 , +.Xr passwd 5 +.Sh HISTORY +The function +.Fn crypt_checkpass +first appeared in +.Ox 5.6 , +and +.Fn crypt_newhash +in +.Ox 5.7 . +.Sh AUTHORS +.An Ted Unangst Aq Mt tedu@openbsd.org diff --git a/static/openbsd/man3/crypto.3 b/static/openbsd/man3/crypto.3 new file mode 100644 index 00000000..ddc8b056 --- /dev/null +++ b/static/openbsd/man3/crypto.3 @@ -0,0 +1,419 @@ +.\" $OpenBSD: crypto.3,v 1.31 2025/04/25 20:04:09 tb Exp $ +.\" OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 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. +.\" +.\" The original file was written by Ulf Moeller and +.\" Dr. Stephen Henson . +.\" Copyright (c) 2000, 2002 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: April 25 2025 $ +.Dt CRYPTO 3 +.Os +.Sh NAME +.Nm crypto +.Nd OpenSSL cryptographic library +.Sh DESCRIPTION +The OpenSSL crypto 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 TLS and S/MIME, and they have also been used to +implement SSH, OpenPGP, and other cryptographic standards. +.Pp +.Sy Symmetric ciphers +including AES, Blowfish, CAST, ChaCha20, IDEA, DES, RC2, and RC4 +are provided by the generic interface +.Xr EVP_EncryptInit 3 . +Low-level stand-alone interfaces include +.Xr AES_encrypt 3 , +.Xr BF_set_key 3 , +.Xr ChaCha 3 , +.Xr DES_set_key 3 , +.Xr RC2_encrypt 3 , +and +.Xr RC4 3 . +.Pp +.Sy Public key cryptography and key agreement +are provided by +.Xr DH_new 3 , +.Xr ECDH_compute_key 3 , +.Xr X25519 3 , +.Xr DSA_new 3 , +.Xr ECDSA_SIG_new 3 , +.Xr RSA_new 3 , +and +.Xr EVP_PKEY_new 3 . +.Pp +.Sy Certificates +are handled by +.Xr X509_new 3 +and +.Xr X509v3_add_ext 3 . +.Pp +.Sy Authentication codes and hash functions +offered include +.Xr EVP_DigestInit 3 , +.Xr CMAC_Init 3 , +.Xr HMAC 3 , +.Xr MD4 3 , +.Xr MD5 3 , +.Xr RIPEMD160 3 , +.Xr SHA1 3 , +and +.Xr SHA256 3 . +.Pp +.Sy Input, output, and data encoding +facilities include +.Xr ASN1_TYPE_get 3 , +.Xr BIO_new 3 , +.Xr CMS_ContentInfo_new 3 , +.Xr evp 3 , +.Xr EVP_EncodeInit 3 , +.Xr PEM_read 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_sign 3 , +.Xr PKCS12_create 3 , +and +.Xr SMIME_write_PKCS7 3 . +.Pp +.Sy Auxiliary features include: +.Bl -dash -compact +.It +configuration file handling: see +.Xr OPENSSL_config 3 +.It +error reporting: see +.Xr ERR 3 +.It +.Xr OCSP_REQUEST_new 3 +.It +.Xr UI_new 3 +.El +.Pp +.Sy Internal utilities +include +.Xr BIO_f_buffer 3 , +.Xr BN_new 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr lh_new 3 , +and +.Xr STACK_OF 3 . +.Sh NAMING CONVENTIONS +Elements used in the names of API functions include the following: +.Bl -tag -width Ds +.It add0 +See +.Dq set0 +below. +.It add1 +See +.Dq set1 +below. +.It BIO +basic input and/or output abstraction: +The function manipulates objects of the idiosyncratic OpenSSL +.Vt BIO +object type. +See +.Xr BIO_new 3 . +.It bio +The function uses a +.Vt BIO +object for input or output. +In many cases, simpler variants of the function are available +that operate directly on +.In stdio.h +.Vt FILE +objects or directly in RAM, usually using byte arrays. +.It BIO_f_ +filter BIO: +The function returns a pointer to a static built-in object that, +when passed to +.Xr BIO_new 3 , +results in the creation of a BIO object that can write data to +and/or read data from another +.Vt BIO +object. +.It BIO_s_ +source and/or sink BIO: +The function returns a pointer to a static built-in object that, +when passed to +.Xr BIO_new 3 , +results in the creation of a BIO object +that can write data to an external destination +and/or read data from an external source, +for example a file descriptor or object, a memory buffer, or the network. +.It BN +big number: +The function operates on +.Vt BIGNUM +objects representing integer numbers of variable, almost unlimited size. +See +.Xr BN_new 3 . +.It cb +callback: +The function takes or returns a function pointer +that is called by API functions from inside the library. +The function pointed to may be defined by the application program. +In some cases, API functions with +.Dq cb +in their name may return function pointers to internal functions +defined inside the library that are not API functions. +The element +.Dq cb +is also used in the names of some function pointer datatypes +declared with +.Sy typedef . +In a small number of cases, the all caps form +.Dq CB +is used with the same meaning. +.It CTX +context: +The function operates on a wrapper object around another object. +The purposes and properties of such +.Dq CTX +wrapper objects vary wildly depending on the objects in question. +A few function names use the lower case form +.Dq ctx +in the same sense. +.It d2i +DER to internal: +The function decodes input conforming to ASN.1 basic encoding rules (BER) +and either stores the result in an existing object +or in a newly allocated object. +The latter is usually preferable because +creating a new object is more robust and less error prone. +In spite of the name, the input usually does not need to conform to ASN.1 +distinguished encoding rules (DER), which are more restrictive than BER. +.It EVP +digital EnVeloPe library: +See +.Xr evp 3 . +.It ex +This name element is used for two completely unrelated purposes. +.Pp +extended version: +The function is similar to an older function without the +.Dq ex +in its name, but takes one or more additional arguments +in order to make it more versatile. +In several cases, the older version is now deprecated. +.Pp +extra data: +Some object types support storing additional, application-specific data +inside objects in addition to the data the object is designed to hold. +The function sets, retrieves, or prepares for using such extra data. +Related function names usually contain +.Dq ex_data +or +.Dq ex_new_index . +See +.Xr CRYPTO_set_ex_data 3 . +.It fp +file pointer: +The function takes a +.Vt FILE * +argument. +Usually, the function is a variant of another function taking a +.Vt BIO * +argument instead. +.It i2d +internal to DER: +The function encodes an object passed as an argument +according to ASN.1 distinguished encoding rules (DER). +There are a few rare exceptions of functions that have +.Dq i2d +in their name but produce output anyway +that only conforms to ASN.1 basic encoding rules (BER) and not to DER. +.It get0 +The function returns an internal pointer +owned by the object passed as an argument. +The returned pointer must not be freed by the calling code. +It will be freed automatically +when the object owning the pointer will be freed. +.It get1 +The function returns a copy of a sub-object +of an object passed as an argument. +The caller is responsible for freeing the returned object +when it is no longer needed. +.Pp +If the object type is reference counted, usually the reference count +is incremented instead of copying the object. +Consequently, modifying the returned object may still impact all +objects containing references to it. +The caller is responsible for freeing the returned object +when it is no longer needed; for reference-counted objects still +referenced elsewhere, this will merely decrement the reference count. +.It get +Functions containing +.Dq get +in their name without a following digit may behave in +.Dq get0 +or, more rarely, in +.Dq get1 +style. +To find out which is the case, refer to the individual manual pages. +.It lh +linear hash: +The function manipulates a dynamic hash table. +See +.Xr lh_new 3 . +.It md +message digest. +Some function names use the all caps form +.Dq MD +in the same sense. +.It meth +The function manipulates an object holding a function table. +Usually, such function tables allow the application program +to implement additional cryptographic or I/O algorithms +and to use them with the same high-level API functions as the +algorithms provided by the library itself, or to replace the +implementations of algorithms provided by the library with +custom implementations provided by the application program. +Some API functions use the name elements +.Dq method +or +.Dq METHOD +in the same sense. +See also the +.Dq cb +entry in the present list. +.It nid +numerical identifier: +A non-standard, LibreSSL-specific +.Vt int +number associated with an ASN.1 object identifier. +In several cases, the all caps form +.Dq NID +is used in the same sense. +See +.Xr OBJ_nid2obj 3 . +.It obj +This name element and its all caps form +.Dq OBJ +usually refer to ASN.1 object identifiers represented by the +.Vt ASN1_OBJECT +data type. +See +.Xr ASN1_OBJECT_new 3 . +.It PKEY +In most cases, this name element and its lower case form +.Dq pkey +mean +.Dq private key , +but for both forms, there are some cases where they mean +.Dq public key +instead. +.It set0 +The function transfers ownership of a pointer passed as an argument +to an object passed as another argument, +by storing the pointer inside the object. +The transferred pointer must not be freed by the calling code. +It will be freed automatically +when the object now owning the pointer will be freed. +.It set1 +The function copies the content of one object passed as an argument +into another object also passed as an argument. +When the calling code no longer needs the copied object, +it can free that object. +.Pp +In some cases, if the object to be copied is reference counted, +the function does not actually copy the object but merely increments +its reference count and stores the pointer to it in the other object. +When the calling code no longer needs its original pointer to +the now inner object, it can free the original pointer, thus +decrementing the reference count of the inner object +and transferring ownership of the inner object to the outer object. +The inner object will then be freed automatically +when the outer object is freed later on. +.It set +Functions containing +.Dq set +in their name without a following digit may behave in +.Dq set0 +or, more rarely, in +.Dq set1 +style. +To find out which is the case, refer to the individual manual pages. +.It sk +stack: +The function manipulates a variable-sized array of pointers +in the idiosyncratic style described in +.Xr OPENSSL_sk_new 3 . +.It TS +X.509 time-stamp protocol: +See +.Xr TS_REQ_new 3 . +.It up_ref +The function increments the reference count of the argument by one. +Only a minority of object types support reference counting. +For those that do, if the reference count is greater than one, +the corresponding +.Dq free +function reverses the effect of one call to the +.Dq up_ref +function rather than freeing the object. +.El +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 diff --git a/static/openbsd/man3/csh.3 b/static/openbsd/man3/csh.3 new file mode 100644 index 00000000..588fc32f --- /dev/null +++ b/static/openbsd/man3/csh.3 @@ -0,0 +1,650 @@ +.\" $OpenBSD: csh.3,v 1.7 2010/07/22 08:30:29 jmc Exp $ +.\" $NetBSD: csh.3,v 1.3 1995/03/21 09:03:38 cgd 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 +argv: Undefined variable. +% +.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 backdir = ~/backup +set noglob +foreach i ($argv) + + if ($i !~ *.c) continue # not a .c file so do nothing + + if (! \-r $backdir/$i:t) then + echo $i:t not in backup... not cp\'ed + continue + endif + + cmp -s $i $backdir/$i:t # to set $status + + if ($status != 0) then + echo new backup of $i + cp $i $backdir/$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 +`: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 UNIX. 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 ensure that this `$' was not variable substituted. +We could also have ensured 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/openbsd/man3/csin.3 b/static/openbsd/man3/csin.3 new file mode 100644 index 00000000..171ff098 --- /dev/null +++ b/static/openbsd/man3/csin.3 @@ -0,0 +1,67 @@ +.\" $OpenBSD: csin.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CSIN 3 +.Os +.Sh NAME +.Nm csin , +.Nm csinf , +.Nm csinl +.Nd complex circular sine +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn csin , +.Fn csinf +and +.Fn csinl +functions compute the complex circular sine of +.Fa z . +.Pp +If +.Fa z += x + iy, then +.Bd -literal -offset indent +csin(z) = sin(x) cosh(y) + i cos(x) sinh(y). +.Ed +.Sh RETURN VALUES +The +.Fn csin , +.Fn csinf +and +.Fn csinl +functions return the complex circular sine of +.Fa z . +.Sh SEE ALSO +.Xr ccos 3 , +.Xr ctan 3 +.Sh STANDARDS +The +.Fn csin , +.Fn csinf +and +.Fn csinl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/csinh.3 b/static/openbsd/man3/csinh.3 new file mode 100644 index 00000000..b0355493 --- /dev/null +++ b/static/openbsd/man3/csinh.3 @@ -0,0 +1,66 @@ +.\" $OpenBSD: csinh.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CSINH 3 +.Os +.Sh NAME +.Nm csinh , +.Nm csinhf , +.Nm csinhl +.Nd complex hyperbolic sine +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn csinh , +.Fn csinhf +and +.Fn csinhl +functions compute the complex hyperbolic sine of +.Fa z . +.Pp +For all complex floating-point numbers +.Fa z , +.Bd -literal -offset indent +csinh(z) = (cexp(z) - cexp(-z)) / 2. +.Ed +.Sh RETURN VALUES +The +.Fn csinh , +.Fn csinhf +and +.Fn csinhl +functions return the complex hyperbolic sine of +.Fa z . +.Sh SEE ALSO +.Xr ccosh 3 , +.Xr ctanh 3 +.Sh STANDARDS +The +.Fn csinh , +.Fn csinhf +and +.Fn csinhl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/csqrt.3 b/static/openbsd/man3/csqrt.3 new file mode 100644 index 00000000..f66f693d --- /dev/null +++ b/static/openbsd/man3/csqrt.3 @@ -0,0 +1,73 @@ +.\" $OpenBSD: csqrt.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CSQRT 3 +.Os +.Sh NAME +.Nm csqrt , +.Nm csqrtf , +.Nm csqrtl +.Nd complex square root +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn csqrt , +.Fn csqrtf +and +.Fn csqrtl +functions compute the complex square root of +.Fa z . +.Pp +If +.Fa z += x + iy, then +.Bd -literal -offset indent +Re csqrt(z) = [ (|z| + x) / 2 ]^(1/2). +Im csqrt(z) = [ (|z| - x) / 2 ]^(1/2). +.Ed +.Pp +Note that -csqrt(z) is also a square root of +.Fa z . +The root chosen +is always in the right half plane and Im csqrt(z) has the same sign +as y. +.Sh RETURN VALUES +The +.Fn csqrt , +.Fn csqrtf +and +.Fn csqrtl +functions return the complex square root of +.Fa z . +.Sh SEE ALSO +.Xr cpow 3 +.Sh STANDARDS +The +.Fn csqrt , +.Fn csqrtf +and +.Fn csqrtl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/ctan.3 b/static/openbsd/man3/ctan.3 new file mode 100644 index 00000000..034decd7 --- /dev/null +++ b/static/openbsd/man3/ctan.3 @@ -0,0 +1,73 @@ +.\" $OpenBSD: ctan.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CTAN 3 +.Os +.Sh NAME +.Nm ctan , +.Nm ctanf , +.Nm ctanl +.Nd complex circular tangent +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn ctan , +.Fn ctanf +and +.Fn ctanl +functions compute the complex circular tangent of +.Fa z . +.Pp +If +.Fa z += x + iy, then +.Bd -literal -offset indent +ctan(z) = (sin(2x) + i sinh(2y)) / (cos(2x) + cosh(2y)). +.Ed +.Pp +On the real axis the denominator is zero at odd multiples of Pi/2. +The denominator is evaluated by its Taylor series near these points. +.Bd -literal -offset indent +ctan(z) = -i ctanh(iz). +.Ed +.Sh RETURN VALUES +The +.Fn ctan , +.Fn ctanf +and +.Fn ctanl +functions return the complex circular tangent of +.Fa z . +.Sh SEE ALSO +.Xr ccos 3 , +.Xr csin 3 +.Sh STANDARDS +The +.Fn ctan , +.Fn ctanf +and +.Fn ctanl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/ctanh.3 b/static/openbsd/man3/ctanh.3 new file mode 100644 index 00000000..809773c3 --- /dev/null +++ b/static/openbsd/man3/ctanh.3 @@ -0,0 +1,67 @@ +.\" $OpenBSD: ctanh.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt CTANH 3 +.Os +.Sh NAME +.Nm ctanh , +.Nm ctanhf , +.Nm ctanhl +.Nd complex hyperbolic tangent +.Sh SYNOPSIS +.Lb libm +.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 +The +.Fn ctanh , +.Fn ctanhf +and +.Fn ctanhl +functions compute the complex hyperbolic tangent of +.Fa z . +.Pp +If +.Fa z += x + iy, then +.Bd -literal -offset indent +ctanh(z) = (sinh(2x) + i sin(2y)) / (cosh(2x) + cos(2y)). +.Ed +.Sh RETURN VALUES +The +.Fn ctanh , +.Fn ctanhf +and +.Fn ctanhl +functions return the complex hyperbolic tangent of +.Fa z . +.Sh SEE ALSO +.Xr ccosh 3 , +.Xr csinh 3 +.Sh STANDARDS +The +.Fn ctanh , +.Fn ctanhf +and +.Fn ctanhl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/ctermid.3 b/static/openbsd/man3/ctermid.3 new file mode 100644 index 00000000..cf81cd6f --- /dev/null +++ b/static/openbsd/man3/ctermid.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: ctermid.3,v 1.10 2014/01/21 03:15:45 schwarze 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. +.\" +.Dd $Mdocdate: January 21 2014 $ +.Dt CTERMID 3 +.Os +.Sh NAME +.Nm ctermid +.Nd generate terminal pathname +.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 a 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 +(as defined in the include +file +.In stdio.h ) +bytes long. +.Pp +The current implementation simply generates +.Qq /dev/tty . +.Sh RETURN VALUES +The +.Fn ctermid +function returns a non-null pointer, which is equal to the +.Ar buf +argument if it is not +.Dv NULL . +.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-88 . diff --git a/static/openbsd/man3/ctime.3 b/static/openbsd/man3/ctime.3 new file mode 100644 index 00000000..ea4c6f7c --- /dev/null +++ b/static/openbsd/man3/ctime.3 @@ -0,0 +1,421 @@ +.\" $OpenBSD: ctime.3,v 1.52 2026/04/15 00:20:28 job Exp $ +.\" +.\" +.Dd $Mdocdate: April 15 2026 $ +.Dt CTIME 3 +.Os +.Sh NAME +.Nm asctime , +.Nm asctime_r , +.Nm ctime , +.Nm ctime_r , +.Nm difftime , +.Nm gmtime , +.Nm gmtime_r , +.Nm localtime , +.Nm localtime_r , +.Nm mktime , +.Nm timegm , +.Nm timelocal +.Nd convert date and time to ASCII +.Sh SYNOPSIS +.In sys/types.h +.In time.h +.Vt extern char *tzname[2] ; +.Ft char * +.Fn ctime "const time_t *clock" +.Ft char * +.Fn ctime_r "const time_t *clock" "char *buf" +.Ft double +.Fn difftime "time_t time1" "time_t time0" +.Ft char * +.Fn asctime "const struct tm *tm" +.Ft char * +.Fn asctime_r "const struct tm *tm" "char *buf" +.Ft struct tm * +.Fn localtime "const time_t *clock" +.Ft struct tm * +.Fn localtime_r "const time_t *clock" "struct tm *result" +.Ft struct tm * +.Fn gmtime "const time_t *clock" +.Ft struct tm * +.Fn gmtime_r "const time_t *clock" "struct tm *result" +.Ft time_t +.Fn mktime "struct tm *tm" +.Ft time_t +.Fn timegm "struct tm *tm" +.Ft time_t +.Fn timelocal "struct tm *tm" +.Sh DESCRIPTION +The +.Fn ctime +function converts a +.Vt time_t , +pointed to by +.Fa clock , +and returns a pointer to a +string of the form +.Pp +.Dl Thu Nov 24 18:22:48 1986\en +.Pp +Years requiring fewer than four characters are padded with leading zeroes. +For years longer than four characters, the string is of the form +.Pp +.Dl Thu Nov 24 18:22:48\ \ \ \ \ 81986\en +.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_r +function converts the calendar time pointed to by +.Fa clock +to local time in exactly the same way as +.Fn ctime +and puts the string into the array pointed to by +.Fa buf +(which contains at least 26 bytes) and returns +.Fa buf . +Unlike +.Fn ctime , +the thread-safe version +.Fn ctime_r +is not required to set +.Va tzname . +.Pp +The +.Fn localtime +and +.Fn gmtime +functions return pointers to +.Vt tm +structures, described below. +.Fn localtime +corrects for the time zone and any time zone adjustments +(such as Daylight Saving Time in the United States). +After filling in the +.Vt tm +structure, +.Fn localtime +sets the +.Fa tm_isdst Ns 'th +element of +.Va tzname +to a pointer to an +ASCII string that's the time zone abbreviation to be used with +the return value of +.Fn localtime . +.Pp +.Fn gmtime +converts to Coordinated Universal Time. +.Pp +The +.Fn localtime_r +and +.Fn gmtime_r +functions convert the calendar time pointed to by +.Fa clock +into a broken-down time in exactly the same way as their non-reentrant +counterparts, +.Fn localtime +and +.Fn gmtime , +but instead store the result directly into the structure pointed to by +.Fa result . +Unlike +.Fn localtime , +the reentrant version is not required to set +.Va tzname . +.Pp +.Fn asctime +converts a time value contained in a +.Vt tm +structure to a string, +as shown in the above example, +and returns a pointer to the string. +.Fn asctime_r +uses the buffer pointed to by +.Fa buf +(which should contain at least 26 bytes) and then +returns +.Fa buf . +.Pp +.Fn mktime +converts the broken-down time, +expressed as local time, +in the structure pointed to by +.Fa tm +into a calendar time value with the same encoding as that of the values +returned by the +.Fn time +function. +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. +(A positive or zero value for +.Fa tm_isdst +causes +.Fn mktime +to presume initially that summer time (for example, Daylight Saving Time +in the U.S.A.)\& +respectively, +is or is not in effect for the specified time. +A negative value for +.Fa tm_isdst +causes the +.Fn mktime +function to attempt to divine whether summer 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.) +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. +.Fn mktime +returns the specified calendar time; +if the calendar time cannot be represented, +it returns \-1. +.Pp +.Fn timelocal +is a deprecated interface that is equivalent to calling +.Fn mktime +with a negative value for +.Fa tm_isdst . +.Pp +.Fn timegm +converts the broken-down time, as returned by +.Fn gmtime , +into a calendar time value with the same encoding as that of the values +returned by the +.Fn time +function. +.Pp +.Fn difftime +returns the difference between two calendar times, +.Pf ( Fa time1 No \- Fa time0 ) , +expressed in seconds. +.Pp +Declarations of all the functions and externals, and the +.Vt tm +structure, are in the +.In time.h +header file. +The structure (of type) +.Vt struct tm +includes the following fields: +.Bd -literal -offset indent + 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 summer time in effect? */ + long tm_gmtoff; /* offset from UT in seconds */ + const char *tm_zone; /* abbreviation of timezone name */ +.Ed +.Pp +The +.Fa tm_zone +and +.Fa tm_gmtoff +fields exist, and are filled in by +.Fn mktime , +.Fn localtime , +.Fn timegm , +and +.Fn gmtime , +but are not standardized. +There is no guarantee that these fields will continue to exist +in this form and they may be altered or removed in a future release. +.Pp +.Fa tm_isdst +is non-zero if summer time is in effect. +.Pp +.Fa 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. +.Sh RETURN VALUES +The functions +.Fn ctime , +.Fn ctime_r , +.Fn asctime , +.Fn asctime_r , +.Fn localtime , +.Fn localtime_r , +.Fn gmtime +and +.Fn gmtime_r +return NULL on error. +The functions +.Fn mktime +and +.Fn timegm +return \-1 on error, +which is ambiguous because \-1 also is a legitimate conversion result. +.Sh FILES +.Bl -tag -width "/usr/share/zoneinfo/posixrules" -compact +.It Pa /usr/share/zoneinfo +time zone information directory +.It Pa /etc/localtime +local time zone file +.It Pa /usr/share/zoneinfo/posixrules +used with POSIX-style TZ's +.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 getenv 3 , +.Xr strftime 3 , +.Xr time 3 , +.Xr tzset 3 , +.Xr tzfile 5 , +.Xr zic 8 +.Sh STANDARDS +The functions +.Fn asctime , +.Fn ctime , +.Fn difftime , +.Fn gmtime , +.Fn localtime , +and +.Fn mktime +conform to +.St -ansiC . +.Pp +The functions +.Fn asctime_r , +.Fn ctime_r , +.Fn gmtime_r , +and +.Fn localtime_r +conform to +.St -p1003.1-2008 . +.Pp +The functions +.Fn timegm +and +.Fn timelocal +are extensions to these standards. +.Sh HISTORY +A +.Fn ctime +function first appeared in +.At v1 . +.Pp +The functions +.Fn asctime , +.Fn gmtime , +and +.Fn localtime +first appeared in +.At v5 , +.Fn difftime +and +.Fn mktime +in +.Bx 4.3 Reno , +and +.Fn timegm +and +.Fn timelocal +in SunOS 4.0. +.Pp +The functions +.Fn asctime_r , +.Fn ctime_r , +.Fn gmtime_r , +and +.Fn localtime_r +have been available since +.Ox 2.5 . +.Sh CAVEATS +The return values +of the non re-entrant functions +point to static data; +the data is overwritten by each call. +The +.Fa tm_zone +field of a returned +.Vt struct tm +points to a static array of characters, which +will also be overwritten at the next call +(and by calls to +.Xr tzset 3 ) . +.Pp +.Fn asctime +and +.Fn ctime +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. +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 +A workaround for the ambiguous return value of +.Fn mktime +is to use +.Fa tm_wday +as a sentinel. +If +.Fa tm_wday +did not change from \-1, an error has occurred. +.Bd -literal -offset indent +struct tm tm; +\&... +tm.tm_wday = -1; +if (mktime(&tm) == -1 && tm.tm_wday == -1) + goto error; +.Ed +.Pp +The default system time zone may be set by running +.Dq Li zic -l timezone +as the superuser. +.Pp +Avoid using out-of-range values with +.Fn mktime +when setting up lunch with promptness sticklers in Riyadh. +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. diff --git a/static/openbsd/man3/curs_add_wch.3 b/static/openbsd/man3/curs_add_wch.3 new file mode 100644 index 00000000..9324ebcd --- /dev/null +++ b/static/openbsd/man3/curs_add_wch.3 @@ -0,0 +1,357 @@ +'\" t +.\" $OpenBSD: curs_add_wch.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\"*************************************************************************** +.\" Copyright 2019-2021,2023 Thomas E. Dickey * +.\" Copyright 2001-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_add_wch.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_add_wch 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBadd_wch\fP, +\fBwadd_wch\fP, +\fBmvadd_wch\fP, +\fBmvwadd_wch\fP, +\fBecho_wchar\fP, +\fBwecho_wchar\fP \- add a complex character and rendition to a \fBcurses\fP window, then advance the cursor +.SH SYNOPSIS +\fB#include \fP +.sp +.B "int add_wch( const cchar_t *\fIwch\fB );" +.br +.B "int wadd_wch( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );" +.br +.B "int mvadd_wch( int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );" +.br +.B "int mvwadd_wch( WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );" +.sp +.B "int echo_wchar( const cchar_t *\fIwch\fB );" +.br +.B "int wecho_wchar( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );" +.SH DESCRIPTION +.SS add_wch +The +\fBadd_wch\fP, +\fBwadd_wch\fP, +\fBmvadd_wch\fP, and +\fBmvwadd_wch\fP +functions put the complex character \fIwch\fP into the given +window at its current position, +which is then advanced. +These functions perform +wrapping and special-character processing as follows: +.bP +If \fIwch\fP refers to a spacing character, +then any previous character at that location is removed. +A new character specified by \fIwch\fP is +placed at that location with rendition specified by \fIwch\fP. +The cursor then advances after this spacing character, +to prepare for writing the next character on the screen. +.IP +The newly added spacing character is the base of the active complex character. +Subsequent non-spacing characters can be combined with this base +until another spacing character is written to the screen, +or the cursor is moved, e.g., using \fBwmove\fP. +.bP +If \fIwch\fP refers to a non-spacing character, +it is appended to the active complex character, +retaining the previous characters at that location. +The rendition specified by \fIwch\fP is ignored. +.IP +The cursor is not advanced after adding a non-spacing character. +Subsequent calls to add non-spacing characters will update the same position. +.bP +If the character part of \fIwch\fP is +a tab, newline, backspace or other control character, +the window is updated and the cursor moves as if \fBaddch\fP were called. +.SS echo_wchar +The \fBecho_wchar\fP +function is functionally equivalent to a call to +\fBadd_wch\fP +followed by a call to +\fBrefresh\fP(3). +Similarly, the +\fBwecho_wchar\fP +is functionally equivalent to a call to +\fBwadd_wch\fP +followed by a call to +\fBwrefresh\fP. +The knowledge +that only a single character is being output is taken into consideration and, +for non-control characters, a considerable performance gain might be seen +by using the *\fBecho\fP* functions instead of their equivalents. +.SS Line Graphics +Like \fBaddch\fP(3), +\fBaddch_wch\fP accepts symbols which make it simple to draw lines and other +frequently used special characters. +These symbols correspond to the same VT100 line-drawing set as +\fBaddch\fP(3). +.PP +.TS +l l l l l +l l l l l +_ _ _ _ _ +lw(1.5i) lw5 lw5 lw5 lw20. +\fBACS\fP \fBUnicode\fP \fBASCII\fP \fBacsc\fP \fBGlyph\fP +\fBName\fP \fBDefault\fP \fBDefault\fP \fBchar\fP \fBName\fP +WACS_BLOCK 0x25ae # 0 solid square block +WACS_BOARD 0x2592 # h board of squares +WACS_BTEE 0x2534 + v bottom tee +WACS_BULLET 0x00b7 o ~ bullet +WACS_CKBOARD 0x2592 : a checker board (stipple) +WACS_DARROW 0x2193 v . arrow pointing down +WACS_DEGREE 0x00b0 ' f degree symbol +WACS_DIAMOND 0x25c6 + ` diamond +WACS_GEQUAL 0x2265 > > greater-than-or-equal-to +WACS_HLINE 0x2500 \- q horizontal line +WACS_LANTERN 0x2603 # i lantern symbol +WACS_LARROW 0x2190 < , arrow pointing left +WACS_LEQUAL 0x2264 < y less-than-or-equal-to +WACS_LLCORNER 0x2514 + m lower left-hand corner +WACS_LRCORNER 0x2518 + j lower right-hand corner +WACS_LTEE 0x2524 + t left tee +WACS_NEQUAL 0x2260 ! | not-equal +WACS_PI 0x03c0 * { greek pi +WACS_PLMINUS 0x00b1 # g plus/minus +WACS_PLUS 0x253c + n plus +WACS_RARROW 0x2192 > + arrow pointing right +WACS_RTEE 0x251c + u right tee +WACS_S1 0x23ba \- o scan line 1 +WACS_S3 0x23bb \- p scan line 3 +WACS_S7 0x23bc \- r scan line 7 +WACS_S9 0x23bd \&_ s scan line 9 +WACS_STERLING 0x00a3 f } pound-sterling symbol +WACS_TTEE 0x252c + w top tee +WACS_UARROW 0x2191 ^ \- arrow pointing up +WACS_ULCORNER 0x250c + l upper left-hand corner +WACS_URCORNER 0x2510 + k upper right-hand corner +WACS_VLINE 0x2502 | x vertical line +.TE +.PP +The wide-character configuration of ncurses also defines symbols +for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''): +.PP +.TS +l l l l l +l l l l l +_ _ _ _ _ +lw(1.5i) lw5 lw5 lw5 lw20. +\fBACS\fP \fBUnicode\fP \fBASCII\fP \fBacsc\fP \fBGlyph\fP +\fBName\fP \fBDefault\fP \fBDefault\fP \fBchar\fP \fBName\fP +WACS_T_BTEE 0x253b + V thick tee pointing up +WACS_T_HLINE 0x2501 - Q thick horizontal line +WACS_T_LLCORNER 0x2517 + M thick lower left corner +WACS_T_LRCORNER 0x251b + J thick lower right corner +WACS_T_LTEE 0x252b + T thick tee pointing right +WACS_T_PLUS 0x254b + N thick large plus +WACS_T_RTEE 0x2523 + U thick tee pointing left +WACS_T_TTEE 0x2533 + W thick tee pointing down +WACS_T_ULCORNER 0x250f + L thick upper left corner +WACS_T_URCORNER 0x2513 + K thick upper right corner +WACS_T_VLINE 0x2503 | X thick vertical line +.TE +.PP +and for double-lines (\fBacsc\fP \*(``A\*('' to \*(``I\*(''): +.PP +.TS +l l l l l +l l l l l +_ _ _ _ _ +lw(1.5i) lw5 lw5 lw5 lw20. +\fBACS\fP \fBUnicode\fP \fBASCII\fP \fBacsc\fP \fBGlyph\fP +\fBName\fP \fBDefault\fP \fBDefault\fP \fBchar\fP \fBName\fP +WACS_D_BTEE 0x2569 + H double tee pointing up +WACS_D_HLINE 0x2550 - R double horizontal line +WACS_D_LLCORNER 0x255a + D double lower left corner +WACS_D_LRCORNER 0x255d + A double lower right corner +WACS_D_LTEE 0x2560 + F double tee pointing right +WACS_D_PLUS 0x256c + E double large plus +WACS_D_RTEE 0x2563 + G double tee pointing left +WACS_D_TTEE 0x2566 + I double tee pointing down +WACS_D_ULCORNER 0x2554 + C double upper left corner +WACS_D_URCORNER 0x2557 + B double upper right corner +WACS_D_VLINE 0x2551 | Y double vertical line +.TE +.PP +Unicode's descriptions for these characters differs slightly from ncurses, +by introducing the term \*(``light\*('' (along with less important details). +Here are its descriptions for the normal, thick, and double horizontal lines: +.bP +U+2500 BOX DRAWINGS LIGHT HORIZONTAL +.bP +U+2501 BOX DRAWINGS HEAVY HORIZONTAL +.bP +U+2550 BOX DRAWINGS DOUBLE HORIZONTAL +.SH RETURN VALUE +All routines return the integer \fBERR\fP upon failure and \fBOK\fP on success. +.PP +X/Open does not define any error conditions. +This implementation returns an error +.bP +if the window pointer is null or +.bP +if it is not possible to add a complete character in the window. +.PP +The latter may be due to different causes: +.bP +If \fBscrollok\fP(3) is not enabled, +writing a character at the lower right margin succeeds. +However, an error is returned because +it is not possible to wrap to a new line +.bP +If an error is detected when converting a multibyte character to a sequence +of bytes, +or if it is not possible to add all of the resulting bytes in the window, +an error is returned. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +Note that +\fBadd_wch\fP, +\fBmvadd_wch\fP, +\fBmvwadd_wch\fP, and +\fBecho_wchar\fP +may be macros. +.SH PORTABILITY +All of these functions are described in the XSI Curses standard, Issue 4. +The defaults specified for line-drawing characters apply in the POSIX locale. +.SS WACS Symbols +X/Open Curses makes it clear that the WACS_ symbols should be defined as +a pointer to \fBcchar_t\fP data, e.g., in the discussion of \fBborder_set\fP. +A few implementations are problematic: +.bP +NetBSD curses defines the symbols as a \fBwchar_t\fP within a \fBcchar_t\fP. +.bP +HPUX curses equates some of the \fBACS_\fP symbols +to the analogous \fBWACS_\fP symbols as if the \fBACS_\fP symbols were +wide characters. +The misdefined symbols are the arrows +and other symbols which are not used for line-drawing. +.PP +X/Open Curses does not define symbols for thick- or double-lines. +SVr4 curses implementations defined their line-drawing symbols in +terms of intermediate symbols. +This implementation extends those symbols, providing new definitions +which are not in the SVr4 implementations. +.PP +Not all Unicode-capable terminals provide support for VT100-style +alternate character sets (i.e., the \fBacsc\fP capability), +with their corresponding line-drawing characters. +X/Open Curses did not address the aspect of integrating Unicode with +line-drawing characters. +Existing implementations of Unix curses (AIX, HPUX, Solaris) +use only the \fBacsc\fP character-mapping to provide this feature. +As a result, those implementations can only use single-byte line-drawing +characters. +Ncurses 5.3 (2002) provided a table of Unicode values to solve these problems. +NetBSD curses incorporated that table in 2010. +.PP +In this implementation, the Unicode values are used instead of the +terminal description's \fBacsc\fP mapping as discussed in ncurses(3) +for the environment variable \fBNCURSES_NO_UTF8_ACS\fP. +In contrast, for the same cases, the line-drawing characters +described in \fBcurs_addch\fP(3) will use only the ASCII default values. +.PP +Having Unicode available does not solve all of the problems with +line-drawing for curses: +.bP +The closest Unicode equivalents to the +VT100 graphics \fIS1\fP, \fIS3\fP, \fIS7\fP and \fIS9\fP +frequently are not displayed at +the regular intervals which the terminal used. +.bP +The \fIlantern\fP is a special case. +It originated with the AT&T 4410 terminal in the early 1980s. +There is no accessible documentation depicting the lantern symbol +on the AT&T terminal. +.IP +Lacking documentation, most readers assume that a \fIstorm lantern\fP +was intended. +But there are several possibilities, all with problems. +.IP +Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and U+1F3EE. +Those were not available in 2002, and are irrelevant since +they lie outside the BMP and as a result are not generally available +in terminals. +They are not storm lanterns, in any case. +.IP +Most \fIstorm lanterns\fP have a tapering glass chimney +(to guard against tipping); +some have a wire grid protecting the chimney. +.IP +For the tapering appearance, \[u2603] U+2603 was adequate. +In use on a terminal, no one can tell what the image represents. +Unicode calls it a snowman. +.IP +Others have suggested these alternatives: +\[sc] U+00A7 (section mark), +\[u0398] U+0398 (theta), +\[u03A6] U+03A6 (phi), +\[u03B4] U+03B4 (delta), +\[u2327] U+2327 (x in a rectangle), +\[u256C] U+256C (forms double vertical and horizontal), and +\[u2612] U+2612 (ballot box with x). +.SS Complex Characters +The complex character type \fBcchar_t\fR +can store more than one wide character (\fBwchar_t\fR). +The X/Open Curses description does not mention this possibility, +describing only the cases where \fIwch\fP is a spacing character +or a non-spacing character. +.PP +This implementation assumes that \fIwch\fP is constructed using +\fBsetcchar\fP(3), and in turn that the result +.bP +contains at most one spacing character in the beginning of its list of wide +characters, +and zero or more non-spacing characters +or +.bP +may hold one non-spacing character. +.PP +In the latter case, ncurses adds the non-spacing character to the active +(base) spacing character. +.SH SEE ALSO +.na +.hy 0 +\fBcurses\fP(3), +\fBcurs_addch\fP(3), +\fBcurs_attr\fP(3), +\fBcurs_clear\fP(3), +\fBcurs_getcchar\fP(3), +\fBcurs_outopts\fP(3), +\fBcurs_refresh\fP(3), +\fBputwc\fP(3) diff --git a/static/openbsd/man3/curs_add_wchstr.3 b/static/openbsd/man3/curs_add_wchstr.3 new file mode 100644 index 00000000..6b4ea771 --- /dev/null +++ b/static/openbsd/man3/curs_add_wchstr.3 @@ -0,0 +1,124 @@ +.\" $OpenBSD: curs_add_wchstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\"*************************************************************************** +.\" Copyright 2019-2021,2022 Thomas E. Dickey * +.\" Copyright 2002-2012,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_add_wchstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_add_wchstr 3 2022-02-12 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBadd_wchstr\fP, +\fBadd_wchnstr\fP, +\fBwadd_wchstr\fP, +\fBwadd_wchnstr\fP, +\fBmvadd_wchstr\fP, +\fBmvadd_wchnstr\fP, +\fBmvwadd_wchstr\fP, +\fBmvwadd_wchnstr\fP \- add an array of complex characters (and attributes) to a curses window +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +.PP +\fBint add_wchstr(const cchar_t *\fIwchstr\fB);\fR +.br +\fBint add_wchnstr(const cchar_t *\fIwchstr\fB, int \fIn\fB);\fR +.br +\fBint wadd_wchstr(WINDOW *\fR \fIwin\fB, const cchar_t *\fIwchstr\fB);\fR +.br +\fBint wadd_wchnstr(WINDOW *\fR \fIwin\fB, const cchar_t *\fIwchstr\fB, int \fIn\fB);\fR +.sp +\fBint mvadd_wchstr(int \fIy\fB, int \fIx\fB, const cchar_t *\fIwchstr\fB);\fR +.br +\fBint mvadd_wchnstr(int \fIy\fB, int \fIx\fB, const cchar_t *\fIwchstr\fB, int \fIn\fB);\fR +.br +\fBint mvwadd_wchstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const cchar_t *\fIwchstr\fB);\fR +.br +\fBint mvwadd_wchnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const cchar_t *\fIwchstr\fB, int \fIn\fB);\fR +.fi +.SH DESCRIPTION +These functions copy the (null-terminated) +array of complex characters \fIwchstr\fP +into the window image structure +starting at the current cursor position. +The four functions with \fIn\fP as the last +argument copy at most \fIn\fP elements, +but no more than will fit on the line. +If \fBn\fP=\fB\-1\fP then the whole array is copied, +to the maximum number of characters that will fit on the line. +.PP +The window cursor is \fInot\fP advanced. +These functions work faster than \fBwaddnstr\fP. +On the other hand: +.bP +they do not perform checking +(such as for the newline, backspace, or carriage return characters), +.bP +they do not advance the current cursor position, +.bP +they do not expand other control characters to ^-escapes, and +.bP +they truncate the string if it crosses the right margin, +rather than wrapping it around to the new line. +.PP +These functions end successfully +on encountering a null \fBcchar_t\fP, or +when they have filled the current line. +If a complex character cannot completely fit at the end of the current line, +the remaining columns are filled with the background character and rendition. +.SH RETURN VALUE +All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success. +.PP +X/Open does not define any error conditions. +This implementation returns an error +if the window pointer is null. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +All functions except \fBwadd_wchnstr\fP may be macros. +.SH PORTABILITY +These entry points are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_addwstr\fP(3). +.PP +Comparable functions in the narrow-character (ncurses) library are +described in +\fBcurs_addchstr\fP(3). diff --git a/static/openbsd/man3/curs_addch.3 b/static/openbsd/man3/curs_addch.3 new file mode 100644 index 00000000..c3a69980 --- /dev/null +++ b/static/openbsd/man3/curs_addch.3 @@ -0,0 +1,323 @@ +'\" t +.\" $OpenBSD: curs_addch.3,v 1.5 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_addch.3,v 1.5 2023/10/17 09:52:08 nicm Exp $ +.TH curs_addch 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBaddch\fP, +\fBwaddch\fP, +\fBmvaddch\fP, +\fBmvwaddch\fP, +\fBechochar\fP, +\fBwechochar\fP \- add a character (with attributes) to a \fBcurses\fP window, then advance the cursor +.SH SYNOPSIS +\fB#include \fP +.PP +\fBint addch(const chtype \fIch\fB);\fR +.br +\fBint waddch(WINDOW *\fIwin\fB, const chtype \fIch\fB);\fR +.br +\fBint mvaddch(int \fIy\fB, int \fIx\fB, const chtype \fIch\fB);\fR +.br +\fBint mvwaddch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const chtype \fIch\fB);\fR +.sp +\fBint echochar(const chtype \fIch\fB);\fR +.br +\fBint wechochar(WINDOW *\fIwin\fB, const chtype \fIch\fB);\fR +.br +.SH DESCRIPTION +.SS Adding characters +The \fBaddch\fP, \fBwaddch\fP, \fBmvaddch\fP and \fBmvwaddch\fP routines put +the character \fIch\fP into the given window at its current window position, +which is then advanced. +They are analogous to \fBputchar\fP(3) in \fBstdio\fP(3). +If the advance is at the right margin: +.bP +The cursor automatically wraps to the beginning of the next line. +.bP +At the bottom of the current scrolling region, +and if \fBscrollok\fP(3) is enabled, +the scrolling region is scrolled up one line. +.bP +If \fBscrollok\fP(3) is not enabled, +writing a character at the lower right margin succeeds. +However, an error is returned because +it is not possible to wrap to a new line +.PP +If \fIch\fP is a tab, newline, carriage return or backspace, +the cursor is moved appropriately within the window: +.bP +Backspace moves the cursor one character left; at the left +edge of a window it does nothing. +.bP +Carriage return moves the cursor to the window left margin on the current line. +.bP +Newline does a \fBclrtoeol\fP, +then moves the cursor to the window left margin on the next line, +scrolling the window if on the last line. +.bP +Tabs are considered to be at every eighth column. +The tab interval may be altered by setting the \fBTABSIZE\fP variable. +.PP +If \fIch\fP is any other nonprintable character, +it is drawn in printable form, +using the same convention as \fBunctrl\fR(3): +.bP +Control characters are displayed in the \fB^\fIX\fR notation. +.bP +Values above 128 are either meta characters +(if the screen has not been initialized, +or if \fBmeta\fP(3) has been called with a \fBTRUE\fP E parameter), +shown in the \fBM\-\fIX\fR notation, or are displayed as themselves. +In the latter case, the values may not be printable; +this follows the X/Open specification. +.PP +Calling \fBwinch\fP after adding a +nonprintable character does not return the character itself, +but instead returns the printable representation of the character. +.PP +Video attributes can be combined with a character argument passed to +\fBaddch\fP or related functions by logical-ORing them into the character. +(Thus, text, including attributes, can be copied from one place to another +using \fBinch\fP(3) and \fBaddch\fP.) See the \fBcurs_attr\fP(3) page for +values of predefined video attribute constants that can be usefully OR'ed +into characters. +.SS Echoing characters +The \fBechochar\fP and \fBwechochar\fP routines are equivalent to a call to +\fBaddch\fP followed by a call to \fBrefresh\fP(3), or a call to \fBwaddch\fP +followed by a call to \fBwrefresh\fP. +The knowledge that only a single +character is being output is used and, for non-control characters, a +considerable performance gain may be seen by using these routines instead of +their equivalents. +.SS Line Graphics +The following variables may be used to add line drawing characters to the +screen with routines of the \fBaddch\fP family. +The default character listed +below is used if the \fBacsc\fP capability does not define a terminal-specific +replacement for it, +or if the terminal and locale configuration requires Unicode but the +library is unable to use Unicode. +.PP +The names are taken from VT100 nomenclature. +.PP +.TS +l l l l +l l l l +_ _ _ _ +l l l l. +\fBACS\fP \fBACS\fP \fBacsc\fP \fBGlyph\fP +\fBName\fP \fBDefault\fP \fBchar\fP \fBName\fP +ACS_BLOCK # 0 solid square block +ACS_BOARD # h board of squares +ACS_BTEE + v bottom tee +ACS_BULLET o ~ bullet +ACS_CKBOARD : a checker board (stipple) +ACS_DARROW v . arrow pointing down +ACS_DEGREE ' f degree symbol +ACS_DIAMOND + ` diamond +ACS_GEQUAL > > greater-than-or-equal-to +ACS_HLINE \- q horizontal line +ACS_LANTERN # i lantern symbol +ACS_LARROW < , arrow pointing left +ACS_LEQUAL < y less-than-or-equal-to +ACS_LLCORNER + m lower left-hand corner +ACS_LRCORNER + j lower right-hand corner +ACS_LTEE + t left tee +ACS_NEQUAL ! | not-equal +ACS_PI * { greek pi +ACS_PLMINUS # g plus/minus +ACS_PLUS + n plus +ACS_RARROW > + arrow pointing right +ACS_RTEE + u right tee +ACS_S1 \- o scan line 1 +ACS_S3 \- p scan line 3 +ACS_S7 \- r scan line 7 +ACS_S9 \&_ s scan line 9 +ACS_STERLING f } pound-sterling symbol +ACS_TTEE + w top tee +ACS_UARROW ^ \- arrow pointing up +ACS_ULCORNER + l upper left-hand corner +ACS_URCORNER + k upper right-hand corner +ACS_VLINE | x vertical line +.TE +.SH RETURN VALUE +All routines return the integer \fBERR\fP upon failure and \fBOK\fP on success +(the SVr4 manuals specify only +\*(``an integer value other than \fBERR\fP\*('') upon successful completion, +unless otherwise noted in the preceding routine descriptions. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.PP +If it is not possible to add a complete character, +an error is returned: +.bP +If \fBscrollok\fP(3) is not enabled, +writing a character at the lower right margin succeeds. +However, an error is returned because +it is not possible to wrap to a new line +.bP +If an error is detected when converting a multibyte character to a sequence +of bytes, +or if it is not possible to add all of the resulting bytes in the window, +an error is returned. +.SH NOTES +Note that \fBaddch\fP, \fBmvaddch\fP, \fBmvwaddch\fP, and +\fBechochar\fP may be macros. +.SH PORTABILITY +All these functions are described in the XSI Curses standard, Issue 4. +The defaults specified for forms-drawing characters apply in the POSIX locale. +.SS ACS Symbols +X/Open Curses states that the \fBACS_\fP definitions are \fBchar\fP constants. +For the wide-character implementation (see \fBcurs_add_wch\fP), +there are analogous \fBWACS_\fP definitions which are \fBcchar_t\fP constants. +Some implementations are problematic: +.bP +Some implementations define the ACS symbols to a constant +(such as Solaris), while others define those to entries in an array. +.IP +This implementation uses an array \fBacs_map\fP, as done in SVr4 curses. +NetBSD also uses an array, actually named \fB_acs_char\fP, with a \fB#define\fP +for compatibility. +.bP +HPUX curses equates some of the \fBACS_\fP symbols +to the analogous \fBWACS_\fP symbols as if the \fBACS_\fP symbols were +wide characters. +The misdefined symbols are the arrows +and other symbols which are not used for line-drawing. +.bP +X/Open Curses (issues 2 through 7) has a typographical error +for the ACS_LANTERN symbol, equating its \*(``VT100+ Character\*('' +to \fBI\fP (capital I), while the header files for SVr4 curses +and the various implementations use \fBi\fP (lowercase). +.IP +None of the terminal descriptions on Unix platforms use uppercase-I, +except for Solaris (i.e., \fBscreen\fP's terminal description, +apparently based on the X/Open documentation around 1995). +On the other hand, the terminal description \fIgs6300\fP +(AT&T PC6300 with EMOTS Terminal Emulator) uses lowercase-i. +.LP +Some ACS symbols +(ACS_S3, +ACS_S7, +ACS_LEQUAL, +ACS_GEQUAL, +ACS_PI, +ACS_NEQUAL, +ACS_STERLING) +were not documented in +any publicly released System V. +However, many publicly available terminfos +include \fBacsc\fP strings in which their key characters (pryz{|}) are +embedded, and a second-hand list of their character descriptions has come +to light. +The ACS-prefixed names for them were invented for \fBncurses\fP(3). +.LP +The \fIdisplayed\fP values for the \fBACS_\fP and \fBWACS_\fP constants +depend on +.bP +the library configuration, i.e., \fBncurses\fP versus \fBncursesw\fP, +where the latter is capable of displaying Unicode while the former is not, and +.bP +whether the \fIlocale\fP uses UTF-8 encoding. +.LP +In certain cases, the terminal is unable to display line-drawing characters +except by using UTF-8 (see the discussion of \fBNCURSES_NO_UTF8_ACS\fP in +ncurses(3)). +.SS Character Set +X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains +a single character. +As discussed in \fBcurs_attr\fP(3), that character may have been +more than eight bits in an SVr3 or SVr4 implementation, +but in the X/Open Curses model, the details are not given. +The important distinction between SVr4 curses and X/Open Curses is +that the non-character information (attributes and color) was +separated from the character information which is packed in a \fBchtype\fP +to pass to \fBwaddch\fP. +.PP +In this implementation, \fBchtype\fP holds an eight-bit character. +But ncurses allows multibyte characters to be passed in a succession +of calls to \fBwaddch\fP. +The other implementations do not do this; +a call to \fBwaddch\fP passes exactly one character +which may be rendered as one or more cells on the screen +depending on whether it is printable. +.PP +Depending on the locale settings, +ncurses will inspect the byte passed in each call to \fBwaddch\fP, +and check if the latest call will continue a multibyte sequence. +When a character is \fIcomplete\fP, +ncurses displays the character and moves to the next position in the screen. +.PP +If the calling application interrupts the succession of bytes in +a multibyte character by moving the current location (e.g., using \fBwmove\fP), +ncurses discards the partially built character, +starting over again. +.PP +For portability to other implementations, +do not rely upon this behavior: +.bP +check if a character can be represented as a single byte in the current locale +before attempting call \fBwaddch\fP, and +.bP +call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP. +.SS TABSIZE +The \fBTABSIZE\fP variable is implemented in SVr4 and other versions of curses, +but is not part of X/Open curses +(see \fBcurs_variables\fP(3) for more details). +.LP +If \fIch\fP is a carriage return, +the cursor is moved to the beginning of the current row of the window. +This is true of other implementations, but is not documented. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_attr\fP(3), +\fBcurs_clear\fP(3), +\fBcurs_inch\fP(3), +\fBcurs_outopts\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_variables\fP(3), +\fBputc\fP(3). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_add_wch\fP(3). diff --git a/static/openbsd/man3/curs_addchstr.3 b/static/openbsd/man3/curs_addchstr.3 new file mode 100644 index 00000000..3c03e6a6 --- /dev/null +++ b/static/openbsd/man3/curs_addchstr.3 @@ -0,0 +1,119 @@ +.\" $OpenBSD: curs_addchstr.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2019-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2012,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_addchstr.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.TH curs_addchstr 3 2022-02-12 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBaddchstr\fP, +\fBaddchnstr\fP, +\fBwaddchstr\fP, +\fBwaddchnstr\fP, +\fBmvaddchstr\fP, +\fBmvaddchnstr\fP, +\fBmvwaddchstr\fP, +\fBmvwaddchnstr\fP \- add a string of characters (and attributes) to a \fBcurses\fP window +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +.PP +\fBint addchstr(const chtype *\fIchstr\fB);\fR +.br +\fBint addchnstr(const chtype *\fIchstr\fB, int \fIn\fB);\fR +.br +\fBint waddchstr(WINDOW *\fIwin\fB, const chtype *\fIchstr\fB);\fR +.br +\fBint waddchnstr(WINDOW *\fIwin\fB, const chtype *\fIchstr\fB, int \fIn\fB);\fR +.sp +\fBint mvaddchstr(int \fIy\fB, int \fIx\fB, const chtype *\fIchstr\fB);\fR +.br +\fBint mvaddchnstr(int \fIy\fB, int \fIx\fB, const chtype *\fIchstr\fB, int \fIn\fB);\fR +.br +\fBint mvwaddchstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const chtype *\fIchstr\fB);\fR +.br +\fBint mvwaddchnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const chtype *\fIchstr\fB, int \fIn\fB);\fR +.fi +.SH DESCRIPTION +These functions copy the (null-terminated) +\fIchstr\fP array +into the window image structure +starting at the current cursor position. +The four functions with \fIn\fP as the last +argument copy at most \fIn\fP elements, +but no more than will fit on the line. +If \fBn\fP=\fB\-1\fP then the whole array is copied, +to the maximum number of characters that will fit on the line. +.PP +The window cursor is \fInot\fP advanced. +These functions work faster than \fBwaddnstr\fP. +On the other hand: +.bP +they do not perform checking +(such as for the newline, backspace, or carriage return characters), +.bP +they do not advance the current cursor position, +.bP +they do not expand other control characters to ^-escapes, and +.bP +they truncate the string if it crosses the right margin, +rather than wrapping it around to the new line. +.SH RETURN VALUE +All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success. +.PP +X/Open does not define any error conditions. +This implementation returns an error +if the window pointer is null. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +All functions except \fBwaddchnstr\fP may be macros. +.SH PORTABILITY +These entry points are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_addstr\fP(3). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_add_wchstr\fP(3). diff --git a/static/openbsd/man3/curs_addstr.3 b/static/openbsd/man3/curs_addstr.3 new file mode 100644 index 00000000..5afc67ae --- /dev/null +++ b/static/openbsd/man3/curs_addstr.3 @@ -0,0 +1,121 @@ +.\" $OpenBSD: curs_addstr.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2019-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2012,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_addstr.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.TH curs_addstr 3 2023-03-11 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBaddstr\fP, +\fBaddnstr\fP, +\fBwaddstr\fP, +\fBwaddnstr\fP, +\fBmvaddstr\fP, +\fBmvaddnstr\fP, +\fBmvwaddstr\fP, +\fBmvwaddnstr\fP \- add a string of characters to a \fBcurses\fP window and advance cursor +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +.PP +\fBint addstr(const char *\fIstr\fB);\fR +.br +\fBint addnstr(const char *\fIstr\fB, int \fIn\fB);\fR +.br +\fBint waddstr(WINDOW *\fIwin\fB, const char *\fIstr\fB);\fR +.br +\fBint waddnstr(WINDOW *\fIwin\fB, const char *\fIstr\fB, int \fIn\fB);\fR +.sp +\fBint mvaddstr(int \fIy\fB, int \fIx\fB, const char *\fIstr\fB);\fR +.br +\fBint mvaddnstr(int \fIy\fB, int \fIx\fB, const char *\fIstr\fB, int \fIn\fB);\fR +.br +\fBint mvwaddstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const char *\fIstr\fB);\fR +.br +\fBint mvwaddnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const char *\fIstr, int \fIn\fB);\fR +.fi +.SH DESCRIPTION +These functions write the (null-terminated) character string +\fIstr\fP on the given window. +It is similar to calling \fBwaddch\fP once for each byte in the string. +.PP +The \fImv\fP functions perform cursor movement once, before writing any +characters. +Thereafter, the cursor is advanced as a side-effect of writing to the window. +.PP +The four functions with \fIn\fP as the last argument +write at most \fIn\fP bytes, +or until a terminating null is reached. +If \fIn\fP is \-1, then the entire string will be added. +.SH RETURN VALUE +All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success. +.PP +X/Open does not define any error conditions. +This implementation returns an error +.bP +if the window pointer is null or +.bP +if the string pointer is null or +.bP +if the corresponding calls to \fBwaddch\fP return an error. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +If an error is returned by the \fBwmove\fP, +no characters are added to the window. +.PP +If an error is returned by \fBwaddch\fP +(e.g., +because the window is not large enough, +or an illegal byte sequence was detected) +only part of the string may be added. +Aside from that, +there is a special case in \fBwaddch\fP where an error may be +returned after successfully writing a character to the lower-right corner +of a window when \fBscrollok\fP(3) is disabled. +.SH NOTES +All of these functions except \fBwaddnstr\fP may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_addch\fP(3). diff --git a/static/openbsd/man3/curs_addwstr.3 b/static/openbsd/man3/curs_addwstr.3 new file mode 100644 index 00000000..d5046cd8 --- /dev/null +++ b/static/openbsd/man3/curs_addwstr.3 @@ -0,0 +1,117 @@ +.\" $OpenBSD: curs_addwstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\"*************************************************************************** +.\" Copyright 2019-2022,2023 Thomas E. Dickey * +.\" Copyright 2002-2012,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_addwstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_addwstr 3 2023-07-15 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBaddwstr\fP, +\fBaddnwstr\fP, +\fBwaddwstr\fP, +\fBwaddnwstr\fP, +\fBmvaddwstr\fP, +\fBmvaddnwstr\fP, +\fBmvwaddwstr\fP, +\fBmvwaddnwstr\fP \- add a string of wide characters to a \fBcurses\fP window and advance cursor +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +.PP +\fBint addwstr(const wchar_t *\fIwstr\fB);\fR +.br +\fBint addnwstr(const wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.br +\fBint waddwstr(WINDOW *\fIwin\fB, const wchar_t *\fIwstr\fB);\fR +.br +\fBint waddnwstr(WINDOW *\fIwin\fB, const wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.sp +\fBint mvaddwstr(int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB);\fR +.br +\fBint mvaddnwstr(int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.br +\fBint mvwaddwstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB);\fR +.br +\fBint mvwaddnwstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.fi +.SH DESCRIPTION +These functions write the characters of the +(null-terminated) \fBwchar_t\fP character string +\fIwstr\fP on the given window. +It is similar to constructing a \fBcchar_t\fP for +each \fBwchar_t\fR in the string, +then calling \fBwadd_wch\fP(3) for the resulting \fBcchar_t\fP: +.bP +spacing and non-spacing characters in the string +are processed one at a time, and +.bP +control characters are processed as in \fBwaddch\fP(3). +.PP +The \fImv\fP functions perform cursor movement once, before writing any +characters. +Thereafter, the cursor is advanced as a side-effect of writing to the window. +.PP +The four functions with \fIn\fP as the last argument +write at most \fIn\fP \fBwchar_t\fP characters, +or until a terminating null is reached. +If \fIn\fP is \-1, then the entire string will be added. +.SH RETURN VALUE +All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success. +.PP +X/Open does not define any error conditions. +This implementation returns an error +.bP +if the window pointer is null or +.bP +if the string pointer is null or +.bP +if the corresponding calls to \fBwadd_wch\fP return an error. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +All of these functions except \fBwaddnwstr\fP may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_addch\fP(3), +\fBcurs_add_wch\fP(3). diff --git a/static/openbsd/man3/curs_attr.3 b/static/openbsd/man3/curs_attr.3 new file mode 100644 index 00000000..46c099b7 --- /dev/null +++ b/static/openbsd/man3/curs_attr.3 @@ -0,0 +1,617 @@ +'\" t +.\" $OpenBSD: curs_attr.3,v 1.5 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_attr.3,v 1.5 2023/10/17 09:52:08 nicm Exp $ +.TH curs_attr 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de NS +.ie n .sp +.el .sp .5 +.ie n .in +4 +.el .in +2 +.nf +.ft CR \" Courier +.. +.de NE +.fi +.ft R +.ie n .in -4 +.el .in -2 +.. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.\" --------------------------------------------------------------------------- +.SH NAME +.\" attr_get +\fBattr_get\fP, +\fBwattr_get\fP, +\fBattr_set\fP, +\fBwattr_set\fP, +.\" .br +\fBattr_off\fP, +\fBwattr_off\fP, +\fBattr_on\fP, +\fBwattr_on\fP, +.\" .br +\fBattroff\fP, +\fBwattroff\fP, +\fBattron\fP, +\fBwattron\fP, +\fBattrset\fP, +\fBwattrset\fP, +.\" .br +\fBchgat\fP, +\fBwchgat\fP, +\fBmvchgat\fP, +\fBmvwchgat\fP, +.\" .br +\fBcolor_set\fP, +\fBwcolor_set\fP, +.\" .br +\fBstandend\fP, +\fBwstandend\fP, +\fBstandout\fP, +\fBwstandout\fP \- \fBcurses\fP character and window attribute control routines +.ad +.hy +.\" --------------------------------------------------------------------------- +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint attr_get(attr_t *\fIattrs\fB, short *\fIpair\fB, void *\fIopts\fB);\fR +.br +\fBint wattr_get(WINDOW *\fIwin\fB, attr_t *\fIattrs\fB, short *\fIpair\fB,\fR \fBvoid *\fIopts\fB);\fR +.br +\fBint attr_set(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR +.br +\fBint wattr_set(WINDOW *\fIwin\fB, attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR +.sp +\fBint attr_off(attr_t \fIattrs\fB, void *\fIopts\fB);\fR +.br +\fBint wattr_off(WINDOW *\fIwin\fB, attr_t \fIattrs\fB, void *\fIopts\fB);\fR +.br +\fBint attr_on(attr_t \fIattrs\fB, void *\fIopts\fB);\fR +.br +\fBint wattr_on(WINDOW *\fIwin\fB, attr_t \fIattrs\fB, void *\fIopts\fB);\fR +.sp +\fBint attroff(int \fIattrs);\fR +.br +\fBint wattroff(WINDOW *\fIwin\fB, int \fIattrs\fB);\fR +.br +\fBint attron(int \fIattrs\fB);\fR +.br +\fBint wattron(WINDOW *\fIwin\fB, int \fIattrs\fB);\fR +.br +\fBint attrset(int \fIattrs\fB);\fR +.br +\fBint wattrset(WINDOW *\fIwin\fB, int \fIattrs\fB);\fR +.sp +\fBint chgat(int \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB,\fR \fBconst void *\fIopts\fB);\fR +.br +\fBint wchgat(WINDOW *\fIwin\fB,\fR + \fBint \fIn\fB, attr_t \fIattr\fB,\fR \fBshort \fIpair\fB, const void *\fIopts\fB);\fR +.br +\fBint mvchgat(int \fIy\fB, int \fIx\fB,\fR + \fBint \fIn\fB, attr_t \fIattr\fB,\fR \fBshort \fIpair\fB, const void *\fIopts\fB);\fR +.br +\fBint mvwchgat(WINDOW *\fIwin, int \fIy, int \fIx\fB,\fR + \fBint \fIn,\fR \fBattr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR +.sp +\fBint color_set(short \fIpair\fB, void* \fIopts\fB);\fR +.br +\fBint wcolor_set(WINDOW *\fIwin\fB, short \fIpair\fB,\fR \fBvoid* \fIopts);\fR +.sp +\fBint standend(void);\fP +.br +\fBint wstandend(WINDOW *\fIwin\fB);\fR +.br +\fBint standout(void);\fP +.br +\fBint wstandout(WINDOW *\fIwin\fB);\fR +.\" --------------------------------------------------------------------------- +.SH DESCRIPTION +These routines manipulate the current attributes of the named window, +which then apply to all characters that are written into +the window with \fBwaddch\fP, \fBwaddstr\fP and \fBwprintw\fP. +Attributes are +a property of the character, and move with the character through any scrolling +and insert/delete line/character operations. +To the extent possible, they are +displayed as appropriate modifications to the graphic rendition of characters +put on the screen. +.PP +These routines do not affect the attributes used +when erasing portions of the window. +See \fBcurs_bkgd\fP(3) for functions which modify the attributes used for +erasing and clearing. +.PP +Routines which do not have a \fBWINDOW*\fP parameter apply to \fBstdscr\fP. +For example, +\fBattr_set\fP is the \fBstdscr\fP variant of \fBwattr_set\fP. +.\" --------------------------------------------------------------------------- +.SS Window attributes +There are two sets of functions: +.bP +functions for manipulating the window attributes and color: +\fBwattr_set\fP and \fBwattr_get\fP. +.bP +functions for manipulating only the window attributes (not color): +\fBwattr_on\fP and \fBwattr_off\fP. +.PP +The \fBwattr_set\fP function sets the current attributes +of the given window to \fIattrs\fP, with color specified by \fIpair\fP. +.PP +Use \fBwattr_get\fP to retrieve attributes for the given window. +.PP +Use \fBattr_on\fP and \fBwattr_on\fP to turn on window attributes, i.e., +values OR'd together in \fIattr\fP, +without affecting other attributes. +Use \fBattr_off\fP and \fBwattr_off\fP to turn off window attributes, +again values OR'd together in \fIattr\fP, +without affecting other attributes. +.\" --------------------------------------------------------------------------- +.SS Legacy window attributes +The X/Open window attribute routines which \fIset\fP or \fIget\fP, +turn \fIon\fP or \fIoff\fP +are extensions of older routines +which assume that color pairs are OR'd into the attribute parameter. +These newer routines use similar names, because +X/Open simply added an underscore (\fB_\fP) for the newer names. +.PP +The \fBint\fP datatype used in the legacy routines is treated as if +it is the same size as \fBchtype\fP (used by \fBaddch\fP(3)). +It holds the common video attributes (such as bold, reverse), +as well as a few bits for color. +Those bits correspond to the \fBA_COLOR\fP symbol. +The \fBCOLOR_PAIR\fP macro provides a value which can be OR'd into +the attribute parameter. +For example, +as long as that value fits into the \fBA_COLOR\fP mask, +then these calls produce similar results: +.NS +attrset(A_BOLD | COLOR_PAIR(\fIpair\fP)); +attr_set(A_BOLD, \fIpair\fP, NULL); +.NE +.PP +However, if the value does not fit, then the \fBCOLOR_PAIR\fP macro +uses only the bits that fit. +For example, because in ncurses \fBA_COLOR\fP has eight (8) bits, +then \fBCOLOR_PAIR(\fI259\fB)\fR is 4 +(i.e., 259 is 4 more than the limit 255). +.PP +The \fBPAIR_NUMBER\fP macro extracts a pair number from an \fBint\fP +(or \fBchtype\fP). +For example, the \fIinput\fP and \fIoutput\fP values in these statements +would be the same: +.NS +int value = A_BOLD | COLOR_PAIR(\fIinput\fP); +int \fIoutput\fP = PAIR_NUMBER(value); +.NE +.PP +The \fBattrset\fP routine is a legacy feature predating SVr4 curses +but kept in X/Open Curses for the same reason that SVr4 curses kept it: +compatibility. +.PP +The remaining \fBattr\fP* functions operate exactly like the corresponding +\fBattr_\fP* functions, except that they take arguments of type \fBint\fP +rather than \fBattr_t\fP. +.PP +There is no corresponding \fBattrget\fP function as such in X/Open Curses, +although ncurses provides \fBgetattrs\fP (see curs_legacy(3)). +.\" --------------------------------------------------------------------------- +.SS Change character rendition +The routine \fBchgat\fP changes the attributes of a given number of characters +starting at the current cursor location of \fBstdscr\fP. +It does not update +the cursor and does not perform wrapping. +A character count of \-1 or greater +than the remaining window width means to change attributes all the way to the +end of the current line. +The \fBwchgat\fP function generalizes this to any window; +the \fBmvwchgat\fP function does a cursor move before acting. +.PP +In these functions, +the color \fIpair\fP argument is a color-pair index +(as in the first argument of \fBinit_pair\fP, see \fBcurs_color\fP(3)). +.\" --------------------------------------------------------------------------- +.SS Change window color +The routine \fBcolor_set\fP sets the current color of the given window to the +foreground/background combination described by the color \fIpair\fP parameter. +.\" --------------------------------------------------------------------------- +.SS Standout +The routine \fBstandout\fP is +the same as \fBattron(A_STANDOUT)\fP. +The routine \fBstandend\fP is the same +as \fBattrset(A_NORMAL)\fP or \fBattrset(0)\fP, that is, it turns off all +attributes. +.PP +X/Open does not mark these \*(``restricted\*('', because +.bP +they have well established legacy use, and +.bP +there is no ambiguity about the way the attributes +might be combined with a color pair. +.\" --------------------------------------------------------------------------- +.SH VIDEO ATTRIBUTES +The following video attributes, defined in \fB\fP, can be passed to +the routines \fBattron\fP, \fBattroff\fP, and \fBattrset\fP, or OR'd with the +characters passed to \fBaddch\fP (see \fBcurs_addch\fP(3)). +.PP +.RS +.TS +l l +_ _ _ +l l . +\fBName\fP \fBDescription\fP +\fBA_NORMAL\fP Normal display (no highlight) +\fBA_STANDOUT\fP Best highlighting mode of the terminal. +\fBA_UNDERLINE\fP Underlining +\fBA_REVERSE\fP Reverse video +\fBA_BLINK\fP Blinking +\fBA_DIM\fP Half bright +\fBA_BOLD\fP Extra bright or bold +\fBA_PROTECT\fP Protected mode +\fBA_INVIS\fP Invisible or blank mode +\fBA_ALTCHARSET\fP Alternate character set +\fBA_ITALIC\fP Italics (non-X/Open extension) +\fBA_CHARTEXT\fP Bit-mask to extract a character +\fBA_COLOR\fP Bit-mask to extract a color (legacy routines) +.TE +.RE +.PP +These video attributes are supported by \fBattr_on\fP and related functions +(which also support the attributes recognized by \fBattron\fP, etc.): +.PP +.RS +.TS +l l +_ _ _ +l l . +\fBName\fP \fBDescription\fP +\fBWA_HORIZONTAL\fP Horizontal highlight +\fBWA_LEFT\fP Left highlight +\fBWA_LOW\fP Low highlight +\fBWA_RIGHT\fP Right highlight +\fBWA_TOP\fP Top highlight +\fBWA_VERTICAL\fP Vertical highlight +.TE +.RE +.PP +The return values of many of these routines are not meaningful (they are +implemented as macro-expanded assignments and simply return their argument). +The SVr4 manual page claims (falsely) that these routines always return \fB1\fP. +.\" --------------------------------------------------------------------------- +.SH NOTES +These functions may be macros: +.sp +.RS +\fBattroff\fP, \fBwattroff\fP, \fBattron\fP, \fBwattron\fP, +\fBattrset\fP, \fBwattrset\fP, \fBstandend\fP and \fBstandout\fP. +.RE +.PP +Color pair values can only be OR'd with attributes if the pair +number is less than 256. +The alternate functions such as \fBcolor_set\fP can pass a color pair +value directly. +However, ncurses ABI 4 and 5 simply OR this value +within the alternate functions. +You must use ncurses ABI 6 to support more than 256 color pairs. +.\" --------------------------------------------------------------------------- +.SH HISTORY +X/Open Curses is largely based on SVr4 curses, +adding support for \*(``wide-characters\*('' (not specific to Unicode). +Some of the X/Open differences from SVr4 curses address the way +video attributes can be applied to wide-characters. +But aside from that, \fBattrset\fP and \fBattr_set\fP are similar. +SVr4 curses provided the basic features for manipulating video attributes. +However, earlier versions of curses provided a part of these features. +.PP +As seen in 2.8BSD, curses assumed 7-bit characters, +using the eighth bit of a byte to represent the \fIstandout\fP +feature (often implemented as bold and/or reverse video). +The BSD curses library provided functions \fBstandout\fP and \fBstandend\fP +which were carried along into X/Open Curses due to their pervasive use +in legacy applications. +.PP +Some terminals in the 1980s could support a variety of video attributes, +although the BSD curses library could do nothing with those. +System V (1983) provided an improved curses library. +It defined the \fBA_\fP symbols for use by applications to manipulate the +other attributes. +There are few useful references for the chronology. +.PP +Goodheart's book +\fIUNIX Curses Explained\fP (1991) describes SVr3 (1987), +commenting on several functions: +.bP +the \fBattron\fP, \fBattroff\fP, \fBattrset\fP functions +(and most of the functions found in SVr4 but not in BSD curses) were +introduced by System V, +.bP +the alternate character set feature with \fBA_ALTCHARSET\fP was +added in SVr2 and improved in SVr3 (by adding \fBacs_map[]\fP), +.bP +\fBstart_color\fP and related color-functions were introduced by System V.3.2, +.bP +pads, soft-keys were added in SVr3, and +.PP +Goodheart did not mention the background character or the \fBcchar_t\fP type. +Those are respectively SVr4 and X/Open features. +He did mention the \fBA_\fP constants, but did not indicate their values. +Those were not the same in different systems, +even for those marked as System V. +.PP +Different Unix systems used different sizes for the bit-fields in \fBchtype\fP +for \fIcharacters\fP and \fIcolors\fP, and took into account the different +integer sizes (32-bit versus 64-bit). +.PP +This table showing the number of bits for \fBA_COLOR\fP +and \fBA_CHARTEXT\fP +was gleaned from the curses header files for +various operating systems and architectures. +The inferred architecture and notes reflect +the format and size of the defined constants +as well as clues such as the alternate character set implementation. +A 32-bit library can be used on a 64-bit system, +but not necessarily the reverse. +.PP +.RS +.TS +l l l l l l +_ _ _ _ _ _ +l l l l l l . +\fBYear\fP \fBSystem\fP \fBArch\fP \fBColor\fP \fBChar\fP \fBNotes\fP +1992 Solaris 5.2 32 6 17 SVr4 curses +1992 HPUX 9 32 no 8 SVr2 curses +1992 AIX 3.2 32 no 23 SVr2 curses +1994 OSF/1 r3 32 no 23 SVr2 curses +1995 HP-UX 10.00 32 6 16 SVr3 \*(``curses_colr\*('' +1995 HP-UX 10.00 32 6 8 SVr4, X/Open curses +1995 Solaris 5.4 32/64 7 16 X/Open curses +1996 AIX 4.2 32 7 16 X/Open curses +1996 OSF/1 r4 32 6 16 X/Open curses +1997 HP-UX 11.00 32 6 8 X/Open curses +2000 U/Win 32/64 7/31 16 uses \fBchtype\fP +.TE +.RE +.PP +Notes: +.RS 3 +.PP +Regarding HP-UX, +.bP +HP-UX 10.20 (1996) added support for 64-bit PA-RISC processors in 1996. +.bP +HP-UX 10.30 (1997) marked \*(``curses_colr\*('' obsolete. +That version of curses was dropped with HP-UX 11.30 in 2006. +.PP +Regarding OSF/1 (and Tru64), +.bP +These used 64-bit hardware. +Like ncurses, the OSF/1 curses interface is not customized for 32-bit +and 64-bit versions. +.bP +Unlike other systems which evolved from AT&T code, +OSF/1 provided a new implementation for X/Open curses. +.PP +Regarding Solaris, +.bP +The initial release of Solaris was in 1992. +.bP +The \fIxpg4\fP (X/Open) curses was developed by MKS from 1990 to 1995. +Sun's copyright began in 1996. +.bP +Sun updated the X/Open curses interface +after 64-bit support was introduced in 1997, +but did not modify the SVr4 curses interface. +.PP +Regarding U/Win, +.bP +Development of the curses library began in 1991, stopped in 2000. +.bP +Color support was added in 1998. +.bP +The library uses only \fBchtype\fP (no \fBcchar_t\fP). +.RE +.PP +Once X/Open curses was adopted in the mid-1990s, the constraint of +a 32-bit interface with many colors and wide-characters for \fBchtype\fP +became a moot point. +The \fBcchar_t\fP structure (whose size and +members are not specified in X/Open Curses) could be extended as needed. +.PP +Other interfaces are rarely used now: +.bP +BSD curses was improved slightly in 1993/1994 using Keith Bostic's +modification to make the library 8-bit clean for \fBnvi\fP(1). +He moved \fIstandout\fP attribute to a structure member. +.IP +The resulting 4.4BSD curses was replaced by ncurses over the next ten years. +.bP +U/Win is rarely used now. +.\" --------------------------------------------------------------------------- +.SH EXTENSIONS +This implementation provides the \fBA_ITALIC\fP attribute for terminals +which have the \fBenter_italics_mode\fP (\fBsitm\fP) +and \fBexit_italics_mode\fP (\fBritm\fP) capabilities. +Italics are not mentioned in X/Open Curses. +Unlike the other video attributes, \fBA_ITALIC\fP is unrelated +to the \fBset_attributes\fP capabilities. +This implementation makes the assumption that +\fBexit_attribute_mode\fP may also reset italics. +.PP +Each of the functions added by XSI Curses has a parameter \fIopts\fP, +which X/Open Curses still (after more than twenty years) documents +as reserved for future use, saying that it should be \fBNULL\fP. +This implementation uses that parameter in ABI 6 for the functions which +have a color-pair parameter to support \fIextended color pairs\fP: +.bP +For functions which modify the color, e.g., +\fBwattr_set\fP and \fBwattr_on\fP, +if \fIopts\fP is set it is treated as a pointer to \fBint\fP, +and used to set the color pair instead of the \fBshort\fP \fIpair\fP parameter. +.bP +For functions which retrieve the color, e.g., +\fBwattr_get\fP, +if \fIopts\fP is set it is treated as a pointer to \fBint\fP, +and used to retrieve the color pair as an \fBint\fP value, +in addition to +retrieving it via the standard pointer to \fBshort\fP parameter. +.bP +For functions which turn attributes off, e.g., +\fBwattr_off\fP, +the \fIopts\fP parameter is ignored except +except to check that it is \fBNULL\fP. +.\" --------------------------------------------------------------------------- +.SH PORTABILITY +These functions are supported in the XSI Curses standard, Issue 4. +The standard defined the dedicated type for highlights, +\fBattr_t\fP, which was not defined in SVr4 curses. +The functions taking \fBattr_t\fP arguments were not supported under SVr4. +.PP +Very old versions of this library did not force an update of the screen +when changing the attributes. +Use \fBtouchwin\fP to force the screen to match the updated attributes. +.PP +The XSI Curses standard states that whether the traditional functions +\fBattron\fP/\fBattroff\fP/\fBattrset\fP can manipulate attributes other than +\fBA_BLINK\fP, \fBA_BOLD\fP, \fBA_DIM\fP, \fBA_REVERSE\fP, \fBA_STANDOUT\fP, or +\fBA_UNDERLINE\fP is \*(``unspecified\*(''. +Under this implementation as well as +SVr4 curses, these functions correctly manipulate all other highlights +(specifically, \fBA_ALTCHARSET\fP, \fBA_PROTECT\fP, and \fBA_INVIS\fP). +.PP +XSI Curses added these entry points: +.sp +.RS +\fBattr_get\fP, \fBattr_on\fP, +\fBattr_off\fP, \fBattr_set\fP, \fBwattr_on\fP, \fBwattr_off\fP, +\fBwattr_get\fP, \fBwattr_set\fP +.RE +.PP +The new functions are intended to work with +a new series of highlight macros prefixed with \fBWA_\fP. +The older macros have direct counterparts in the newer set of names: +.PP +.RS +.ne 9 +.TS +l l +_ _ _ +l l . +\fBName\fP \fBDescription\fP +\fBWA_NORMAL\fP Normal display (no highlight) +\fBWA_STANDOUT\fP Best highlighting mode of the terminal. +\fBWA_UNDERLINE\fP Underlining +\fBWA_REVERSE\fP Reverse video +\fBWA_BLINK\fP Blinking +\fBWA_DIM\fP Half bright +\fBWA_BOLD\fP Extra bright or bold +\fBWA_ALTCHARSET\fP Alternate character set +.TE +.RE +.PP +XSI curses does not assign values to these symbols, +nor does it state whether or not they are related to the +similarly-named A_NORMAL, etc.: +.bP +The XSI curses standard specifies that each pair of corresponding \fBA_\fP +and \fBWA_\fP-using functions operates on the same current-highlight +information. +.bP +However, in some implementations, those symbols have unrelated values. +.IP +For example, the Solaris \fIxpg4\fP (X/Open) curses declares +\fBattr_t\fP to be an unsigned short integer (16-bits), +while \fBchtype\fP is a unsigned integer (32-bits). +The \fBWA_\fP symbols in this case are different from the \fBA_\fP symbols +because they are used for a smaller datatype which does not +represent \fBA_CHARTEXT\fP or \fBA_COLOR\fP. +.IP +In this implementation (as in many others), the values happen to be +the same because it simplifies copying information between +\fBchtype\fP and \fBcchar_t\fP variables. +.bP +Because ncurses's \fBattr_t\fP can hold a color pair +(in the \fBA_COLOR\fP field), +a call to +\fBwattr_on\fP, +\fBwattr_off\fP, or +\fBwattr_set\fP +may alter the window's color. +If the color pair information in the attribute parameter is zero, +no change is made to the window's color. +.IP +This is consistent with SVr4 curses; +X/Open Curses does not specify this. +.PP +The XSI standard extended conformance level adds new highlights +\fBA_HORIZONTAL\fP, \fBA_LEFT\fP, \fBA_LOW\fP, \fBA_RIGHT\fP, \fBA_TOP\fP, +\fBA_VERTICAL\fP (and corresponding \fBWA_\fP macros for each). +As of August 2013, +no known terminal provides these highlights +(i.e., via the \fBsgr1\fP capability). +.\" --------------------------------------------------------------------------- +.SH RETURN VALUE +All routines return the integer \fBOK\fP on success, or \fBERR\fP on failure. +.PP +X/Open does not define any error conditions. +.PP +This implementation +.bP +returns an error if the window pointer is null. +.bP +returns an error if the color pair parameter +for \fBwcolor_set\fP is outside the range 0..COLOR_PAIRS\-1. +.bP +does not return an error if either of the parameters of \fBwattr_get\fP +used for retrieving attribute or color-pair values is \fBNULL\fP. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.\" --------------------------------------------------------------------------- +.SH SEE ALSO +.na +\fBcurses\fP(3), +\fBcurs_addch\fP(3), +\fBcurs_addstr\fP(3), +\fBcurs_bkgd\fP(3), +\fBcurs_printw\fP(3), +\fBcurs_variables\fP(3) diff --git a/static/openbsd/man3/curs_beep.3 b/static/openbsd/man3/curs_beep.3 new file mode 100644 index 00000000..18d34ef1 --- /dev/null +++ b/static/openbsd/man3/curs_beep.3 @@ -0,0 +1,63 @@ +.\" $OpenBSD: curs_beep.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2020,2021 Thomas E. Dickey * +.\" Copyright 1998-2005,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_beep.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.TH curs_beep 3 2021-12-25 "ncurses 6.4" "Library calls" +.SH NAME +\fBbeep\fP, \fBflash\fP \- \fBcurses\fP bell and screen flash routines +.SH SYNOPSIS +\fB#include \fP +.PP +\fBint beep(void);\fP +.br +\fBint flash(void);\fP +.br +.SH DESCRIPTION +The \fBbeep\fP and \fBflash\fP routines are used to alert the terminal user. +The routine \fBbeep\fP sounds an audible alarm on the terminal, if possible; +otherwise it flashes the screen (visible bell). +The routine \fBflash\fP +flashes the screen, and if that is not possible, sounds the alert. +If neither +alert is possible, nothing happens. +Nearly all terminals have an audible alert +(bell or beep), but only some can flash the screen. +.SH RETURN VALUE +These routines return \fBOK\fP if they succeed in beeping or flashing, +\fBERR\fP otherwise. +.SH EXTENSIONS +SVr4's beep and flash routines always returned \fBOK\fP, so it was not +possible to tell when the beep or flash failed. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +Like SVr4, it specifies that they always return \fBOK\fP. +.SH SEE ALSO +\fBcurses\fP(3) diff --git a/static/openbsd/man3/curs_bkgd.3 b/static/openbsd/man3/curs_bkgd.3 new file mode 100644 index 00000000..8fc3b607 --- /dev/null +++ b/static/openbsd/man3/curs_bkgd.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: curs_bkgd.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_bkgd.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.TH curs_bkgd 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBbkgdset\fP, \fBwbkgdset\fP, +\fBbkgd\fP, \fBwbkgd\fP, +\fBgetbkgd\fP \- \fBcurses\fP window background manipulation routines +.SH SYNOPSIS +\fB#include \fP +.PP +\fBvoid bkgdset(chtype \fIch\fB);\fR +.br +\fBvoid wbkgdset(WINDOW *\fIwin, chtype \fIch\fB);\fR +.sp +\fBint bkgd(chtype \fIch\fB);\fR +.br +\fBint wbkgd(WINDOW *\fIwin\fB, chtype \fIch\fB);\fR +.sp +\fBchtype getbkgd(WINDOW *\fIwin\fB);\fR +.br +.SH DESCRIPTION +.SS bkgdset +The \fBbkgdset\fP and \fBwbkgdset\fP routines +set the \fIbackground\fP for a window. +A window's background is a \fBchtype\fP consisting of +any combination of attributes (i.e., rendition) and a character: +.bP +The attribute part of the background is combined (OR'ed) with all non-blank +characters that are written into the window with \fBwaddch\fP. +.bP +Both the character and attribute parts of the background are combined with +blank characters that are written into the window. +.PP +The background becomes a property of each +character and moves with the character through any scrolling and +insert/delete line/character operations. +.PP +To the extent possible on a particular terminal, +the attribute part of the background is displayed +as the graphic rendition of the character put on the screen. +.SS bkgd +The \fBbkgd\fP and \fBwbkgd\fP functions +set the background property of the current or specified window +and then apply this setting to every character position in that window. +According to X/Open Curses, it should do this: +.bP +The rendition of every character on the screen is changed to +the new background rendition. +.bP +Wherever the former background character +appears, it is changed to the new background character. +.PP +Neither X/Open Curses nor the SVr4 manual pages give details about +the way the rendition of characters on the screen is updated when +\fBbkgd\fP or \fBwbkgd\fP is used to change the background character. +.PP +This implementation, like SVr4 curses, does not store the background +and window attribute contributions to each cell separately. +It updates the rendition by comparing the character, non-color attributes and +colors contained in the background. +For each cell in the window, whether or not it is blank: +.bP +The library first compares the \fIcharacter\fP, +and if it matches the current character part of the background, +it replaces that with the new background character. +.IP +When \fBbkgdset\fP is used to set the background character, +that does not update each cell in the window. +A subsequent call to \fBbkgd\fP will only modify the \fIcharacter\fP in +cells which match the current background character. +.bP +The library then checks if the cell uses color, +i.e., its color pair value is nonzero. +If not, it simply replaces the attributes and color pair in the +cell with those from the new background character. +.bP +If the cell uses color, +and that matches the color in the current background, +the library removes attributes +which may have come from the current background +and adds attributes from the new background. +It finishes by setting the cell +to use the color from the new background. +.bP +If the cell uses color, +and that does not match the color in the current background, +the library updates only the non-color attributes, +first removing those which may have come from the current background, +and then adding attributes from the new background. +.PP +If the background's character value is zero (0), a space is assumed. +.PP +If the terminal does not support color, +or if color has not been started with \fBstart_color\fP, +the new background character's color attribute will be ignored. +.SS getbkgd +The \fBgetbkgd\fP function returns the given window's current background +character/attribute pair. +.SH RETURN VALUE +These functions are described in the XSI Curses standard, Issue 4. +It specifies that \fBbkgd\fP and \fBwbkgd\fP return \fBERR\fP on failure, +but gives no failure conditions. +.PP +The routines \fBbkgd\fP and \fBwbkgd\fP return the integer \fBOK\fP, +unless the library has not been initialized. +.PP +In contrast, +the SVr4.0 manual says \fBbkgd\fP and \fBwbkgd\fP may return \fBOK\fP +"or a non-negative integer if \fBimmedok\fP is set", +which refers to the return value from \fBwrefresh\fP +(used to implement the immediate repainting). +The SVr4 curses \fBwrefresh\fP returns the number of characters +written to the screen during the refresh. +This implementation does not do that. +.SH NOTES +Note that \fBbkgdset\fP and \fBbkgd\fP may be macros. +.PP +X/Open Curses mentions that the character part of the background must +be a single-byte value. +This implementation, like SVr4, checks to ensure that, +and will reuse the old background character if the check fails. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4 +(X/Open Curses). +.SH SEE ALSO +.na +\fBcurses\fP(3), +\fBcurs_addch\fP(3), +\fBcurs_attr\fP(3), +\fBcurs_outopts\fP(3) diff --git a/static/openbsd/man3/curs_bkgrnd.3 b/static/openbsd/man3/curs_bkgrnd.3 new file mode 100644 index 00000000..44deb443 --- /dev/null +++ b/static/openbsd/man3/curs_bkgrnd.3 @@ -0,0 +1,119 @@ +.\" $OpenBSD: curs_bkgrnd.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2002-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_bkgrnd.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.TH curs_bkgrnd 3 2023-08-12 "ncurses 6.4" "Library calls" +.SH NAME +\fBbkgrnd\fP, +\fBwbkgrnd\fP, +\fBbkgrndset\fP, +\fBwbkgrndset\fP, +\fBgetbkgrnd\fP, +\fBwgetbkgrnd\fP \- \fBcurses\fP window complex background manipulation routines +.SH SYNOPSIS +\fB#include \fR +.sp +\fBint bkgrnd(\fB const cchar_t *\fIwch\fB);\fR +.br +\fBint wbkgrnd(\fB WINDOW *\fIwin\fB, const cchar_t *\fIwch\fB);\fR +.sp +\fBvoid bkgrndset(const cchar_t *\fIwch\fR \fB);\fR +.br +\fBvoid wbkgrndset(WINDOW *\fIwin\fB, const cchar_t *\fIwch\fB);\fR +.sp +\fBint getbkgrnd(cchar_t *\fIwch\fB);\fR +.br +\fBint wgetbkgrnd(WINDOW *\fIwin\fB, cchar_t *\fIwch\fB);\fR +.SH DESCRIPTION +.SS bkgrndset +The \fBbkgrndset\fP and \fBwbkgrndset\fP routines manipulate the +background of the named window. +The window background is a \fBcchar_t\fP consisting of +any combination of attributes (i.e., rendition) and a complex character. +.bP +The attribute part of the background is combined (OR'ed) with all non-blank +characters that are written into the window with \fBwaddch\fP. +.bP +Both +the character and attribute parts of the background are combined with +the blank characters. +.PP +The background becomes a property of the +character and moves with the character through any scrolling and +insert/delete line/character operations. +.PP +To the extent possible on a +particular terminal, the attribute part of the background is displayed +as the graphic rendition of the character put on the screen. +.SS bkgrnd +The \fBbkgrnd\fP and \fBwbkgrnd\fP functions +set the background property of the current or specified window +and then apply this setting to every character position in that window: +.bP +The rendition of every character on the screen is changed to +the new background rendition. +.bP +Wherever the former background character +appears, it is changed to the new background character. +.SS getbkgrnd +The \fBgetbkgrnd\fP function returns the given window's current background +character/attribute pair via the \fBwch\fP pointer. +If the given window pointer is null, +the character is not updated (but no error returned). +.SH NOTES +Note that +\fBbkgrnd\fP, +\fBbkgrndset\fP, and +\fBgetbkgrnd\fP +may be macros. +.PP +X/Open Curses does not provide details on how the rendition is changed. +This implementation follows the approach used in SVr4 curses, +which is explained in the manual page for \fBwbkgd\fP. +.SH RETURN VALUE +The \fBbkgrndset\fP and \fBwbkgrndset\fP routines do not return a value. +.PP +Upon successful completion, the other functions return \fBOK\fP. +Otherwise, they return \fBERR\fP: +.bP +A null window pointer is treated as an error. +.bP +A null character pointer is treated as an error. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4 +(X/Open Curses). +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_bkgd\fP(3) diff --git a/static/openbsd/man3/curs_border.3 b/static/openbsd/man3/curs_border.3 new file mode 100644 index 00000000..d6dd7ad3 --- /dev/null +++ b/static/openbsd/man3/curs_border.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: curs_border.3,v 1.12 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2007,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_border.3,v 1.12 2023/10/17 09:52:08 nicm Exp $ +.TH curs_border 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.na +.hy 0 +.SH NAME +\fBborder\fP, +\fBwborder\fP, +\fBbox\fP, +\fBhline\fP, +\fBwhline\fP, +\fBvline\fP, +\fBwvline\fP, +\fBmvhline\fP, +\fBmvwhline\fP, +\fBmvvline\fP, +\fBmvwvline\fP \- create \fBcurses\fP borders, horizontal and vertical lines +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint border(chtype \fIls\fB, chtype \fIrs\fB, chtype \fIts\fB, chtype \fIbs\fB,\fR + \fBchtype \fItl\fB, chtype \fItr\fB, chtype \fIbl\fB, chtype \fIbr\fB);\fR +.br +\fBint wborder(WINDOW *\fIwin\fB, chtype \fIls\fB, chtype \fIrs\fB,\fR + \fBchtype \fIts\fB, chtype \fIbs\fB, chtype \fItl\fB, chtype \fItr\fB,\fR + \fBchtype \fIbl\fB, chtype \fIbr\fB);\fR +.sp +\fBint box(WINDOW *\fIwin\fB, chtype \fIverch\fB, chtype \fIhorch\fB);\fR +.sp +\fBint hline(chtype \fIch\fB, int \fIn\fB);\fR +.br +\fBint whline(WINDOW *\fIwin\fB, chtype \fIch\fB, int \fIn\fB);\fR +.br +\fBint vline(chtype \fIch\fB, int \fIn\fB);\fR +.br +\fBint wvline(WINDOW *\fIwin\fB, chtype \fIch\fB, int \fIn\fB);\fR +.sp +\fBint mvhline(int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR +.br +\fBint mvwhline(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR +.br +\fBint mvvline(int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR +.br +\fBint mvwvline(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR +.SH DESCRIPTION +The \fBborder\fP, \fBwborder\fP and \fBbox\fP routines +draw a box around the edges of a window. +Other than the window, each argument is a character with attributes: +.sp +.RS +\fIls\fP \- left side, +.br +\fIrs\fP \- right side, +.br +\fIts\fP \- top side, +.br +\fIbs\fP \- bottom side, +.br +\fItl\fP \- top left-hand corner, +.br +\fItr\fP \- top right-hand corner, +.br +\fIbl\fP \- bottom left-hand corner, and +.br +\fIbr\fP \- bottom right-hand corner. +.RE +.PP +If any of these arguments is zero, then the corresponding +default values (defined in \fBcurses.h\fP) are used instead: +.sp +.RS +\fBACS_VLINE\fP, +.br +\fBACS_VLINE\fP, +.br +\fBACS_HLINE\fP, +.br +\fBACS_HLINE\fP, +.br +\fBACS_ULCORNER\fP, +.br +\fBACS_URCORNER\fP, +.br +\fBACS_LLCORNER\fP, +.br +\fBACS_LRCORNER\fP. +.RE +.PP +\fBbox(\fIwin\fB, \fIverch\fB, \fIhorch\fB)\fR is a shorthand +for the following call: \fBwborder(\fIwin\fB,\fR \fIverch\fB,\fR +\fIverch\fB,\fR \fIhorch\fB,\fR \fIhorch\fB, 0, 0, 0, 0)\fR. +.PP +The \fBhline\fP and \fBwhline\fP functions draw a horizontal (left to right) +line using \fIch\fP starting at the current cursor position in the window. +The +current cursor position is not changed. +The line is at most \fIn\fP characters +long, or as many as fit into the window. +.PP +The \fBvline\fP and \fBwvline\fP functions draw a vertical (top to bottom) line +using \fIch\fP starting at the current cursor position in the window. +The +current cursor position is not changed. +The line is at most \fIn\fP characters +long, or as many as fit into the window. +.SH RETURN VALUE +All routines return the integer \fBOK\fP. +The SVr4.0 manual says "or a +non-negative integer if \fBimmedok\fP is set", but this appears to be an error. +.PP +X/Open does not define any error conditions. +This implementation returns an error +if the window pointer is null. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +The borders generated by these functions are \fIinside\fP borders (this +is also true of SVr4 curses, though the fact is not documented). +.PP +Note that \fBborder\fP and \fBbox\fP may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +The standard specifies that they return \fBERR\fP on failure, +but specifies no error conditions. +.SH SEE ALSO +\fBcurses\fP(3), \fBcurs_outopts\fP(3). diff --git a/static/openbsd/man3/curs_border_set.3 b/static/openbsd/man3/curs_border_set.3 new file mode 100644 index 00000000..e0d7b98f --- /dev/null +++ b/static/openbsd/man3/curs_border_set.3 @@ -0,0 +1,207 @@ +.\" $OpenBSD: curs_border_set.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2019-2022,2023 Thomas E. Dickey * +.\" Copyright 2002-2011,2012 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_border_set.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_border_set 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.na +.hy 0 +.SH NAME +\fBborder_set\fP, +\fBwborder_set\fP, +\fBbox_set\fP, +\fBhline_set\fP, +\fBwhline_set\fP, +\fBmvhline_set\fP, +\fBmvwhline_set\fP, +\fBvline_set\fP, +\fBwvline_set\fP, +\fBmvvline_set\fP, +\fBmvwvline_set\fP \- create \fBcurses\fP borders or lines using complex characters and renditions +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint border_set(\fP + \fBconst cchar_t *\fIls\fR, \fBconst cchar_t *\fIrs\fR, + \fBconst cchar_t *\fIts\fR, \fBconst cchar_t *\fIbs\fR, + \fBconst cchar_t *\fItl\fR, \fBconst cchar_t *\fItr\fR, + \fBconst cchar_t *\fIbl\fR, \fBconst cchar_t *\fIbr\fR +\fB);\fP +.br +\fBint wborder_set(\fP + \fBWINDOW *win\fP, + \fBconst cchar_t *\fIls\fR, \fBconst cchar_t *\fIrs\fR, + \fBconst cchar_t *\fIts\fR, \fBconst cchar_t *\fIbs\fR, + \fBconst cchar_t *\fItl\fR, \fBconst cchar_t *\fItr\fR, + \fBconst cchar_t *\fIbl\fR, \fBconst cchar_t *\fIbr\fB);\fR +.br +\fBint box_set(\fP + \fBWINDOW *win\fP, + \fBconst cchar_t *\fIverch\fR, + \fBconst cchar_t *\fIhorch\fB);\fR +.br +\fBint hline_set(\fP + \fBconst cchar_t *\fIwch\fR, \fBint \fIn\fB);\fR +.br +\fBint whline_set(\fP + \fBWINDOW *\fIwin\fR, + \fBconst cchar_t *\fIwch\fR, \fBint \fIn\fB);\fR +.br +\fBint mvhline_set(\fP + \fBint \fIy\fR, \fBint \fIx\fR, + \fBconst cchar_t *\fIwch\fR, \fBint \fIn\fB);\fR +.br +\fBint mvwhline_set(\fP + \fBWINDOW *\fIwin\fR, + \fBint \fIy\fR, \fBint \fIx\fR, + \fBconst cchar_t *\fIwch\fR, \fBint \fIn\fB);\fR +.br +\fBint vline_set(\fP + \fBconst cchar_t *\fIwch\fR, \fBint \fIn\fB);\fR +.br +\fBint wvline_set(\fP + \fBWINDOW *\fIwin\fR, + \fBconst cchar_t *\fIwch\fR, \fBint \fIn\fB);\fR +.br +\fBint mvvline_set(\fP + \fBint \fIy\fR, \fBint \fIx\fR, + \fBconst cchar_t *\fIwch\fR, \fBint \fIn\fB);\fR +.br +\fBint mvwvline_set(\fP + \fBWINDOW *\fIwin\fR, + \fBint \fIy\fR, \fBint \fIx\fR, + \fBconst cchar_t *\fIwch\fR, \fBint \fIn\fB);\fR +.SH DESCRIPTION +The +\fBborder_set\fP +and +\fBwborder_set\fP +functions draw a border around the edges of the current or specified window. +These functions do not change the cursor position, and do not wrap. +.PP +Other than the window, each argument is a complex character with attributes: +.RS +\fIls\fP \- left side, +.br +\fIrs\fP \- right side, +.br +\fIts\fP \- top side, +.br +\fIbs\fP \- bottom side, +.br +\fItl\fP \- top left-hand corner, +.br +\fItr\fP \- top right-hand corner, +.br +\fIbl\fP \- bottom left-hand corner, and +.br +\fIbr\fP \- bottom right-hand corner. +.RE +.PP +If any of these arguments is zero, then the corresponding +default values (defined in \fBcurses.h\fP) are used instead: +.RS +\fBWACS_VLINE\fP, +.br +\fBWACS_VLINE\fP, +.br +\fBWACS_HLINE\fP, +.br +\fBWACS_HLINE\fP, +.br +\fBWACS_ULCORNER\fP, +.br +\fBWACS_URCORNER\fP, +.br +\fBWACS_LLCORNER\fP, and +.br +\fBWACS_LRCORNER\fP. +.RE +.PP +\fBbox_set(\fIwin\fR, \fIverch\fB, \fIhorch\fB);\fR +is a shorthand for the following call: +.PP +\fBwborder_set(\fIwin\fB, \fIverch\fB, \fIverch\fB,\fR + \fIhorch\fB, \fIhorch\fB, NULL, NULL, NULL, NULL);\fR +.PP +The +\fB*line_set\fP +functions use +\fIwch\fP +to draw a line starting at the current cursor position in the window. +The line is at most \fIn\fP characters long or as many as fit into the window. +The current cursor position is not changed. +.PP +The +\fBhline_set\fP, +\fBmvhline_set\fP, +\fBmvwhline_set\fP, and +\fBwhline_set\fP +functions draw a line proceeding toward the last column of the same line. +.PP +The +\fBvline_set\fP, +\fBmvvline_set\fP, +\fBmvwvline_set\fP, and +\fBwvline_set\fP +functions draw a line proceeding toward the last line of the window. +.br +.SH NOTES +Note that +\fBborder_set\fP, +\fBhline_set\fP, +\fBmvhline_set\fP, +\fBmvvline_set\fP, +\fBmvwhline_set\fP, +\fBmvwvline_set\fP, and +\fBvline_set\fP +may be macros. +.SH RETURN VALUE +Upon successful completion, these functions return +\fBOK\fP. +Otherwise, they return +\fBERR\fP. +.PP +Functions using a window parameter return an error if it is null. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH SEE ALSO +\fBncurses\fP(3), +\fBcurs_add_wch\fP(3), +\fBcurs_border\fP(3), +\fBcurs_outopts\fP(3) diff --git a/static/openbsd/man3/curs_clear.3 b/static/openbsd/man3/curs_clear.3 new file mode 100644 index 00000000..461ae77e --- /dev/null +++ b/static/openbsd/man3/curs_clear.3 @@ -0,0 +1,136 @@ +.\" $OpenBSD: curs_clear.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2016 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_clear.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.TH curs_clear 3 2023-07-01 "ncurses 6.4" "Library calls" +.na +.hy 0 +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBerase\fP, +\fBwerase\fP, +\fBclear\fP, +\fBwclear\fP, +\fBclrtobot\fP, +\fBwclrtobot\fP, +\fBclrtoeol\fP, +\fBwclrtoeol\fP \- clear all or part of a \fBcurses\fP window +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint erase(void);\fP +.br +\fBint werase(WINDOW *\fIwin\fB);\fR +.sp +\fBint clear(void);\fP +.br +\fBint wclear(WINDOW *\fIwin\fB);\fR +.sp +\fBint clrtobot(void);\fP +.br +\fBint wclrtobot(WINDOW *\fIwin\fB);\fR +.sp +\fBint clrtoeol(void);\fP +.br +\fBint wclrtoeol(WINDOW *\fIwin\fB);\fR +.SH DESCRIPTION +.SS erase/werase +The \fBerase\fP and \fBwerase\fP routines copy blanks to every +position in the window, clearing the screen. +.PP +Blanks created by erasure have the current background rendition (as set +by \fBwbkgdset\fP(3)) merged into them. +.SS clear/wclear +The \fBclear\fP and \fBwclear\fP routines are like \fBerase\fP and +\fBwerase\fP, but they also call \fBclearok\fP(3), so that the screen is +cleared completely on the next call to \fBwrefresh\fP for that window +and repainted from scratch. +.SS clrtobot/wclrtobot +The \fBclrtobot\fP and \fBwclrtobot\fP routines erase from the cursor to the +end of screen. +That is, they erase all lines below the cursor in the window. +Also, the current line to the right of the cursor, inclusive, is erased. +.SS clrtoeol/wclrtoeol +The \fBclrtoeol\fP and \fBwclrtoeol\fP routines erase the current line +to the right of the cursor, inclusive, to the end of the current line. +.SH RETURN VALUE +All routines return the integer \fBOK\fP on success and \fBERR\fP on failure. +.PP +X/Open defines no error conditions. +In this implementation, +.bP +functions using a window pointer parameter return an error if it is null +.bP +\fBwclrtoeol\fP returns an error +if the cursor position is about to wrap. +.SH NOTES +Note that \fBerase\fP, \fBwerase\fP, \fBclear\fP, \fBwclear\fP, +\fBclrtobot\fP, and \fBclrtoeol\fP may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +The +standard specifies that they return \fBERR\fP on failure, but specifies no +error conditions. +.PP +The SVr4.0 manual says that these functions could +return "a non-negative integer if \fBimmedok\fP(3) is set", +referring to the return-value of \fBwrefresh\fP. +In that implementation, \fBwrefresh\fP would return a count of +the number of characters written to the terminal. +.PP +Some historic curses implementations had, as an undocumented feature, the +ability to do the equivalent of \fBclearok(..., 1)\fP by saying +\fBtouchwin(stdscr)\fP or \fBclear(stdscr)\fP. +This will not work under +ncurses. +.PP +This implementation, and others such as Solaris, +sets the current position to 0,0 after erasing +via \fBwerase\fP and \fBwclear\fP. +That fact is not documented in other implementations, +and may not be true of implementations +which were not derived from SVr4 source. +.PP +Not obvious from the description, +most implementations clear the screen after \fBwclear\fP +even for a subwindow or derived window. +If you do not want to clear the screen during the next \fBwrefresh\fP, +use \fBwerase\fP instead. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_outopts\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_variables\fP(3) diff --git a/static/openbsd/man3/curs_color.3 b/static/openbsd/man3/curs_color.3 new file mode 100644 index 00000000..5f0b8a0a --- /dev/null +++ b/static/openbsd/man3/curs_color.3 @@ -0,0 +1,542 @@ +.\" $OpenBSD: curs_color.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_color.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.TH curs_color 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.ds n 5 +.na +.hy 0 +.SH NAME +\fBstart_color\fP, +\fBhas_colors\fP, +\fBcan_change_color\fP, +\fBinit_pair\fP, +\fBinit_color\fP, +\fBinit_extended_pair\fP, +\fBinit_extended_color\fP, +\fBcolor_content\fP, +\fBpair_content\fP, +\fBextended_color_content\fP, +\fBextended_pair_content\fP, +\fBreset_color_pairs\fP, +\fBCOLOR_PAIR\fP, +\fBPAIR_NUMBER\fP \- \fBcurses\fP color manipulation routines +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint start_color(void);\fP +.sp +\fBbool has_colors(void);\fP +.br +\fBbool can_change_color(void);\fP +.sp +\fBint init_pair(short \fIpair\fB, short \fIf\fB, short \fIb\fB);\fR +.br +\fBint init_color(short \fIcolor\fB, short \fIr\fB, short \fIg\fB, short \fIb\fB);\fR +.br +/* extensions */ +.br +\fBint init_extended_pair(int \fIpair\fB, int \fIf\fB, int \fIb\fB);\fR +.br +\fBint init_extended_color(int \fIcolor\fB, int \fIr\fB, int \fIg\fB, int \fIb\fB);\fR +.sp +\fBint color_content(short \fIcolor\fB, short *\fIr\fB, short *\fIg\fB, short *\fIb\fB);\fR +.br +\fBint pair_content(short \fIpair\fB, short *\fIf\fB, short *\fIb\fB);\fR +.br +/* extensions */ +.br +\fBint extended_color_content(int \fIcolor\fB, int *\fIr\fB, int *\fIg\fB, int *\fIb\fB);\fR +.br +\fBint extended_pair_content(int \fIpair\fB, int *\fIf\fB, int *\fIb\fB);\fR +.sp +/* extensions */ +.br +\fBvoid reset_color_pairs(void);\fP +.sp +\fBint COLOR_PAIR(int \fIn\fB);\fR +.br +\fBPAIR_NUMBER(\fIattrs\fB);\fR +.SH DESCRIPTION +.SS Overview +\fBcurses\fP supports color attributes on terminals with that capability. +To use these routines \fBstart_color\fP must be called, usually right after +\fBinitscr\fP. +Colors are always used in pairs (referred to as color-pairs). +A color-pair consists of a foreground color (for characters) and a background +color (for the blank field on which the characters are displayed). +A programmer initializes a color-pair with the routine \fBinit_pair\fP. +After it has been initialized, \fBCOLOR_PAIR\fP(\fIn\fP) +can be used to convert the pair to a video attribute. +.PP +If a terminal is capable of redefining colors, the programmer can use the +routine \fBinit_color\fP to change the definition of a color. +The routines \fBhas_colors\fP and \fBcan_change_color\fP +return \fBTRUE\fP or \fBFALSE\fP, +depending on whether the terminal has color capabilities and whether the +programmer can change the colors. +The routine \fBcolor_content\fP allows a +programmer to extract the amounts of red, green, and blue components in an +initialized color. +The routine \fBpair_content\fP allows a programmer to find +out how a given color-pair is currently defined. +.SS Color Rendering +The \fBcurses\fP library combines these inputs to produce the +actual foreground and background colors shown on the screen: +.bP +per-character video attributes (e.g., via \fBwaddch\fP), +.bP +the window attribute (e.g., by \fBwattrset\fP), and +.bP +the background character (e.g., \fBwbkgdset\fP). +.PP +Per-character and window attributes are usually set by a parameter containing +video attributes including a color pair value. +Some functions such as \fBwattr_set\fP use a separate parameter which +is the color pair number. +.PP +The background character is a special case: it includes a character value, +just as if it were passed to \fBwaddch\fP. +.PP +The \fBcurses\fP library does the actual work of combining these color +pairs in an internal function called from \fBwaddch\fP: +.bP +If the parameter passed to \fBwaddch\fP is \fIblank\fP, +and it uses the special color pair 0, +.RS +.bP +\fBcurses\fP next checks the window attribute. +.bP +If the window attribute does not use color pair 0, +\fBcurses\fP uses the color pair from the window attribute. +.bP +Otherwise, \fBcurses\fP uses the background character. +.RE +.bP +If the parameter passed to \fBwaddch\fP is \fInot blank\fP, +or it does not use the special color pair 0, +\fBcurses\fP prefers the color pair from the parameter, +if it is nonzero. +Otherwise, it tries the window attribute next, and finally the +background character. +.PP +Some \fBcurses\fP functions such as \fBwprintw\fP call \fBwaddch\fP. +Those do not combine its parameter with a color pair. +Consequently those calls use only the window attribute or +the background character. +.SH CONSTANTS +In \fB\fP the following macros are defined. +These are the standard colors (ISO-6429). +\fBcurses\fP also assumes that \fBCOLOR_BLACK\fP is the default +background color for all terminals. +.PP +.nf + \fBCOLOR_BLACK\fP + \fBCOLOR_RED\fP + \fBCOLOR_GREEN\fP + \fBCOLOR_YELLOW\fP + \fBCOLOR_BLUE\fP + \fBCOLOR_MAGENTA\fP + \fBCOLOR_CYAN\fP + \fBCOLOR_WHITE\fP +.fi +.PP +Some terminals support more than the eight (8) \*(``ANSI\*('' colors. +There are no standard names for those additional colors. +.SH VARIABLES +.SS COLORS +is initialized by \fBstart_color\fP to the maximum number of colors +the terminal can support. +.SS COLOR_PAIRS +is initialized by \fBstart_color\fP to the maximum number of color pairs +the terminal can support. +.SH FUNCTIONS +.SS start_color +The \fBstart_color\fP routine requires no arguments. +It must be called if the programmer wants to use colors, and before any other +color manipulation routine is called. +It is good practice to call this routine right after \fBinitscr\fP. +\fBstart_color\fP does this: +.bP +It initializes two global variables, \fBCOLORS\fP and +\fBCOLOR_PAIRS\fP (respectively defining the maximum number of colors +and color-pairs the terminal can support). +.bP +It initializes the special color pair \fB0\fP to the default foreground +and background colors. +No other color pairs are initialized. +.bP +It restores the colors on the terminal to the values +they had when the terminal was just turned on. +.bP +If the terminal supports the \fBinitc\fP (\fBinitialize_color\fP) capability, +\fBstart_color\fP +initializes its internal table representing the +red, green, and blue components of the color palette. +.IP +The components depend on whether the terminal uses +CGA (aka \*(``ANSI\*('') or +HLS (i.e., the \fBhls\fP (\fBhue_lightness_saturation\fP) capability is set). +The table is initialized first for eight basic colors +(black, red, green, yellow, blue, magenta, cyan, and white), +using weights that depend upon the CGA/HLS choice. +For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP +depending on whether the corresponding +red, green, or blue component is used or not. +That permits using \fB1000\fP to represent bold/bright colors. +After the initial eight colors +(if the terminal supports more than eight colors) +the components are initialized using the same pattern, +but with weights of \fB1000\fP. +SVr4 uses a similar scheme, but uses \fB1000\fP +for the components of the initial eight colors. +.IP +\fBstart_color\fP does not attempt to set the terminal's color palette +to match its built-in table. +An application may use \fBinit_color\fP to alter the internal table +along with the terminal's color. +.PP +These limits apply to color values and color pairs. +Values outside these limits are not legal, and may result in a runtime error: +.bP +\fBCOLORS\fP corresponds to the terminal database's \fBmax_colors\fP capability, +(see \fBterminfo\fP(\*n)). +.bP +color values are expected to be in the range \fB0\fP to \fBCOLORS\-1\fP, +inclusive (including \fB0\fP and \fBCOLORS\-1\fP). +.bP +a special color value \fB\-1\fP is used in certain extended functions +to denote the \fIdefault color\fP (see \fBuse_default_colors\fP(3)). +.bP +\fBCOLOR_PAIRS\fP corresponds to +the terminal database's \fBmax_pairs\fP capability, +(see \fBterminfo\fP(\*n)). +.bP +legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP, +inclusive. +.bP +color pair \fB0\fP is special; it denotes \*(``no color\*(''. +.IP +Color pair \fB0\fP is assumed to be white on black, +but is actually whatever the terminal implements before color is initialized. +It cannot be modified by the application. +.SS has_colors +The \fBhas_colors\fP routine requires no arguments. +It returns \fBTRUE\fP if +the terminal can manipulate colors; otherwise, it returns \fBFALSE\fP. +This routine facilitates writing terminal-independent programs. +For example, a programmer can use it to decide +whether to use color or some other video attribute. +.SS can_change_color +The \fBcan_change_color\fP routine requires no arguments. +It returns \fBTRUE\fP if the terminal supports colors +and can change their definitions; +other, it returns \fBFALSE\fP. +This routine facilitates writing terminal-independent programs. +.SS init_pair +The \fBinit_pair\fP routine changes the definition of a color-pair. +It takes three arguments: +the number of the color-pair to be changed, the foreground +color number, and the background color number. +For portable applications: +.bP +The first argument must be a legal color pair value. +If default colors are used (see \fBuse_default_colors\fP(3)) +the upper limit is adjusted to allow for extra pairs which use +a default color in foreground and/or background. +.bP +The second and third arguments must be legal color values. +.PP +If the color-pair was previously initialized, +the screen is refreshed and all occurrences of that color-pair +are changed to the new definition. +.PP +As an extension, ncurses allows you to set color pair \fB0\fP via +the \fBassume_default_colors\fP(3) routine, or to specify the use of +default colors (color number \fB\-1\fP) if you first invoke the +\fBuse_default_colors\fP(3) routine. +.SS init_extended_pair +Because \fBinit_pair\fP uses signed \fBshort\fPs for its parameters, +that limits color-pairs and color-values +to 32767 on modern hardware. +The extension \fBinit_extended_pair\fP uses \fBint\fPs +for the color-pair and color-value, +allowing a larger number of colors to be supported. +.SS init_color +The \fBinit_color\fP routine changes the definition of a color. +It takes four arguments: +the number of the color to be changed followed by three RGB values +(for the amounts of red, green, and blue components). +.bP +The first argument must be a legal color value; +default colors are not allowed here. +(See the section \fBColors\fP for the default color index.) +.bP +Each of the last three arguments +must be a value in the range \fB0\fP through \fB1000\fP. +.PP +When \fBinit_color\fP is used, all +occurrences of that color on the screen immediately change to the new +definition. +.SS init_extended_color +Because \fBinit_color\fP uses signed \fBshort\fPs for its parameters, +that limits color-values and their red, green, and blue components +to 32767 on modern hardware. +The extension \fBinit_extended_color\fP uses \fBint\fPs +for the color value and +for setting the red, green, and blue components, +allowing a larger number of colors to be supported. +.SS color_content +The \fBcolor_content\fP routine gives programmers a way to find the intensity +of the red, green, and blue (RGB) components in a color. +It requires four arguments: the color number, and three addresses +of \fBshort\fRs for storing +the information about the amounts of red, green, and blue components in the +given color. +.bP +The first argument must be a legal color value, i.e., +\fB0\fP through \fBCOLORS\-1\fP, inclusive. +.bP +The values that are stored at the addresses pointed to by the +last three arguments are in the range +\fB0\fP (no component) through \fB1000\fP +(maximum amount of component), inclusive. +.SS extended_color_content +Because \fBcolor_content\fP uses signed \fBshort\fPs for its parameters, +that limits color-values and their red, green, and blue components +to 32767 on modern hardware. +The extension \fBextended_color_content\fP uses \fBint\fPs +for the color value and +for returning the red, green, and blue components, +allowing a larger number of colors to be supported. +.SS pair_content +The \fBpair_content\fP routine allows programmers to find out what colors a +given color-pair consists of. +It requires three arguments: the color-pair +number, and two addresses of \fBshort\fRs for storing the foreground and the +background color numbers. +.bP +The first argument must be a legal color value, +i.e., in the range \fB1\fP through \fBCOLOR_PAIRS\-1\fP, inclusive. +.bP +The values that are stored at the addresses pointed +to by the second and third arguments are in the +range \fB0\fP through \fBCOLORS\fP, inclusive. +.SS extended_pair_content +Because \fBpair_content\fP uses signed \fBshort\fPs for its parameters, +that limits color-pair and color-values to 32767 on modern hardware. +The extension \fBextended_pair_content\fP uses \fBint\fPs +for the color pair and +for returning the foreground and background colors, +allowing a larger number of colors to be supported. +.SS reset_color_pairs +The extension \fBreset_color_pairs\fP tells ncurses to discard all +of the color-pair information which was set with \fBinit_pair\fP. +It also touches the current- and standard-screens, allowing an application to +switch color palettes rapidly. +.SS PAIR_NUMBER +\fBPAIR_NUMBER(\fIattrs\fR) extracts the color +value from its \fIattrs\fP parameter and returns it as a color pair number. +.SS COLOR_PAIR +Its inverse \fBCOLOR_PAIR(\fIn\fB)\fR converts a color pair number +to an attribute. +Attributes can hold color pairs in the range 0 to 255. +If you need a color pair larger than that, you must use functions +such as \fBattr_set\fP (which pass the color pair as a separate parameter) +rather than the legacy functions such as \fBattrset\fP. +.SH RETURN VALUE +The routines \fBcan_change_color\fP and \fBhas_colors\fP return \fBTRUE\fP +or \fBFALSE\fP. +.PP +All other routines return the integer \fBERR\fP upon failure and an \fBOK\fP +(SVr4 specifies only \*(``an integer value +other than \fBERR\fP\*('') upon successful completion. +.PP +X/Open defines no error conditions. +SVr4 does document some error conditions which apply in general: +.bP +This implementation will return \fBERR\fP on attempts to +use color values outside the range \fB0\fP to \fBCOLORS\fP\-1 +(except for the default colors extension), +or use color pairs outside the range \fB0\fP to \fBCOLOR_PAIRS\-1\fP. +.IP +Color values used in \fBinit_color\fP must be +in the range \fB0\fP to \fB1000\fP. +.IP +An error is returned from all functions +if the terminal has not been initialized. +.IP +An error is returned from secondary functions such as \fBinit_pair\fP +if \fBstart_color\fP was not called. +.bP +SVr4 does much the same, except that +it returns \fBERR\fP from \fBpair_content\fP if the pair was not initialized +using \fBinit_pairs\fP +and +it returns \fBERR\fP from \fBcolor_content\fP +if the terminal does not support changing colors. +.IP +This implementation does not return \fBERR\fP for either case. +.PP +Specific functions make additional checks: +.RS 3 +.TP 5 +\fBinit_color\fP +returns an error if the terminal does not support +this feature, e.g., if the \fBinitialize_color\fP capability is absent +from the terminal description. +.TP 5 +\fBstart_color\fP +returns an error if the color table cannot be allocated. +.RE +.SH NOTES +In the \fBncurses\fP implementation, there is a separate color activation flag, +color palette, color pairs table, +and associated \fBCOLORS\fP and \fBCOLOR_PAIRS\fP counts +for each screen; the \fBstart_color\fP function only affects the current +screen. +The SVr4/XSI interface is not really designed with this in mind, and +historical implementations may use a single shared color palette. +.PP +Setting an implicit background color via a color pair affects only +character cells that a character write operation explicitly touches. +To change +the background color used when parts of a window are blanked by erasing or +scrolling operations, see \fBcurs_bkgd\fP(3). +.PP +Several caveats apply on older x86 machines +(e.g., i386, i486) with VGA-compatible graphics: +.bP +COLOR_YELLOW is actually brown. +To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fP attribute. +.bP +The A_BLINK attribute should in theory cause the background to go bright. +This often fails to work, and even some cards for which it mostly works +(such as the +Paradise and compatibles) do the wrong thing when you try to set a bright +\*(``yellow\*('' background (you get a blinking yellow foreground instead). +.bP +Color RGB values are not settable. +.SH HISTORY +SVr3.2 introduced color support to curses in 1987. +.PP +SVr4 made internal changes, +e.g., moving the storage for the color state +from \fBSP\fP (the \fBSCREEN\fP structure) +to \fBcur_term\fP (the \fBTERMINAL\fP structure), +but provided the same set of library functions. +.PP +SVr4 curses limits the number of color pairs to 64, +reserving color pair zero (0) as the terminal's initial uncolored state. +This limit arises because the color pair information is a bitfield +in the \fBchtype\fP data type (denoted by \fBA_COLOR\fP). +.PP +Other implementations of curses had different limits: +.bP +PCCurses (1987-1990) provided for only eight (8) colors. +.bP +PDCurses (1992-present) inherited the 8-color limitation from PCCurses, +but changed this to 256 in version 2.5 (2001), +along with changing \fBchtype\fP from 16-bits to 32-bits. +.bP +X/Open Curses (1992-present) +added a new structure \fBcchar_t\fP to store the character, +attributes and color-pair values, allowing increased range of color-pairs. +Both color-pairs and color-values used a signed \fBshort\fP, +limiting values to 15 bits. +.bP +ncurses (1992-present) uses eight bits for \fBA_COLOR\fP in \fBchtype\fP values. +.IP +Version 5.3 provided a wide-character interface (2002), +but left color-pairs as part of the attributes-field. +.IP +Since version 6 (2015), +ncurses uses a separate \fBint\fP for color-pairs in the \fBcchar_t\fP values. +When those color-pair values fit in 8 bits, +ncurses allows color-pairs to be manipulated +via the functions using \fBchtype\fP values. +.bP +NetBSD curses used 6 bits from +2000 (when colors were first supported) until 2004. +At that point, NetBSD changed to use 10 bits. +As of 2021, that size is unchanged. +Like ncurses before version 6, +the NetBSD color-pair information is stored in +the attributes field of \fBcchar_t\fP, limiting the number of color-pairs +by the size of the bitfield. +.SH PORTABILITY +.SS Extensions +The functions marked as extensions were designed for \fBncurses\fP(3), +and are not found in SVr4 curses, 4.4BSD curses, +or any other previous version of curses. +.SS Standards +This implementation satisfies XSI Curses's minimum maximums +for \fBCOLORS\fP and \fBCOLOR_PAIRS\fP. +.PP +The \fBinit_pair\fP routine accepts negative values of foreground +and background color to support the \fBuse_default_colors\fP(3) extension, +but only if that routine has been first invoked. +.PP +The assumption that \fBCOLOR_BLACK\fP is the default +background color for all terminals can be modified using the +\fBassume_default_colors\fP(3) extension. +.PP +This implementation checks the pointers, +e.g., for the values returned by +\fBcolor_content\fP and \fBpair_content\fP, +and will treat those as optional parameters when null. +.PP +X/Open Curses does not specify a limit for the number of colors and +color pairs which a terminal can support. +However, in its use of \fBshort\fP for the parameters, +it carries over SVr4's implementation detail for the compiled +terminfo database, which uses signed 16-bit numbers. +This implementation provides extended versions of those functions +which use \fBshort\fP parameters, +allowing applications to use larger color- and pair-numbers. +.PP +The \fBreset_color_pairs\fP function is an extension of ncurses. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_initscr\fP(3), +\fBcurs_attr\fP(3), +\fBcurs_variables\fP(3), +\fBdefault_colors\fP(3) diff --git a/static/openbsd/man3/curs_delch.3 b/static/openbsd/man3/curs_delch.3 new file mode 100644 index 00000000..8f07abce --- /dev/null +++ b/static/openbsd/man3/curs_delch.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: curs_delch.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2006,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_delch.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.TH curs_delch 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBdelch\fP, +\fBwdelch\fP, +\fBmvdelch\fP, +\fBmvwdelch\fP \- delete character under the cursor in a \fBcurses\fP window +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint delch(void);\fP +.br +\fBint wdelch(WINDOW *\fIwin\fB);\fR +.br +\fBint mvdelch(int \fIy\fB, int \fIx\fB);\fR +.br +\fBint mvwdelch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR +.SH DESCRIPTION +These routines delete the character under the cursor; all characters to the +right of the cursor on the same line are moved to the left one position and the +last character on the line is filled with a blank. +The cursor position does +not change (after moving to \fIy\fP, \fIx\fP, if specified). +(This does not +imply use of the hardware delete character feature.) +.SH RETURN VALUE +All routines return the integer \fBERR\fP upon failure and an \fBOK\fP (SVr4 +specifies only "an integer value other than \fBERR\fP") upon successful +completion. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +Note that \fBdelch\fP, \fBmvdelch\fP, and \fBmvwdelch\fP may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +The +standard specifies that they return \fBERR\fP on failure, but specifies no +error conditions. +.SH SEE ALSO +\fBcurses\fP(3) diff --git a/static/openbsd/man3/curs_deleteln.3 b/static/openbsd/man3/curs_deleteln.3 new file mode 100644 index 00000000..5af86330 --- /dev/null +++ b/static/openbsd/man3/curs_deleteln.3 @@ -0,0 +1,94 @@ +.\" $OpenBSD: curs_deleteln.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2007,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_deleteln.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.TH curs_deleteln 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBdeleteln\fP, +\fBwdeleteln\fP, +\fBinsdelln\fP, +\fBwinsdelln\fP, +\fBinsertln\fP, +\fBwinsertln\fP \- delete and insert lines in a \fBcurses\fP window +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint deleteln(void);\fP +.br +\fBint wdeleteln(WINDOW *\fIwin\fB);\fR +.sp +\fBint insdelln(int \fIn\fB);\fR +.br +\fBint winsdelln(WINDOW *\fIwin\fB, int \fIn\fB);\fR +.sp +\fBint insertln(void);\fP +.br +\fBint winsertln(WINDOW *\fIwin\fB);\fR +.SH DESCRIPTION +The \fBdeleteln\fP and \fBwdeleteln\fP routines delete the line under the +cursor in the window; all lines below the current line are moved up one line. +The bottom line of the window is cleared. +The cursor position does not change. +.PP +The \fBinsdelln\fP and \fBwinsdelln\fP routines, for positive \fIn\fP, insert +\fIn\fP lines into the specified window above the current line. +The \fIn\fP +bottom lines are lost. +For negative \fIn\fP, delete \fIn\fP lines (starting +with the one under the cursor), and move the remaining lines up. +The bottom +\fIn\fP lines are cleared. +The current cursor position remains the same. +.PP +The \fBinsertln\fP and \fBwinsertln\fP routines insert a blank line above the +current line and the bottom line is lost. +.SH RETURN VALUE +All routines return the integer \fBERR\fP upon failure and an \fBOK\fP (SVr4 +specifies only "an integer value other than \fBERR\fP") upon successful +completion. +.PP +X/Open defines no error conditions. +In this implementation, +if the window parameter is null, an error is returned. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +The +standard specifies that they return \fBERR\fP on failure, but specifies no +error conditions. +.SH NOTES +Note that all but \fBwinsdelln\fP may be macros. +.PP +These routines do not require a hardware line delete or insert feature in the +terminal. +In fact, they will not use hardware line delete/insert unless +\fBidlok(..., TRUE)\fP has been set on the current window. +.SH SEE ALSO +\fBcurses\fP(3) diff --git a/static/openbsd/man3/curs_extend.3 b/static/openbsd/man3/curs_extend.3 new file mode 100644 index 00000000..e3aea028 --- /dev/null +++ b/static/openbsd/man3/curs_extend.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: curs_extend.3,v 1.7 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1999-2010,2016 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1999-on +.\" +.\" $Id: curs_extend.3,v 1.7 2023/10/17 09:52:08 nicm Exp $ +.TH curs_extend 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBcurses_version\fP, +\fBuse_extended_names\fP \- miscellaneous curses extensions +. +.SH SYNOPSIS +\fB#include \fP +.sp +\fBconst char * curses_version(void);\fP +.br +\fBint use_extended_names(bool \fIenable\fB);\fR +.SH DESCRIPTION +These functions are extensions to the curses library +which do not fit easily into other categories. +.SS curses_version +Use \fBcurses_version\fP +to get the version number, including patch level of the library, +prefixed by \*(``ncurses\*('', e.g., +.RS +.sp +.B ncurses 5.0.19991023 +.RE +.SS use_extended_names +The \fBuse_extended_names\fP +function controls whether the calling application +is able to use user-defined or nonstandard names +which may be compiled into the terminfo +description, i.e., via the terminfo or termcap interfaces. +Normally these names are available for use, since the essential decision +is made by using the \fB\-x\fP option of \fBtic\fP to compile +extended terminal definitions. +However you can disable this feature +to ensure compatibility with other implementations of curses. +.SH RETURN VALUE +\fBcurses_version\fP returns a pointer to static memory; you should not free +this in your application. +.PP +\fBuse_extended_names\fP returns the previous state, allowing you to +save this and restore it. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on +Version 7, BSD or System V implementations. +It is recommended that +any code depending on them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBcurs_getch\fP(3), +\fBcurs_mouse\fP(3), +\fBcurs_print\fP(3), +\fBcurs_util\fP(3), +\fBdefault_colors\fP(3), +\fBdefine_key\fP(3), +\fBkeybound\fP(3), +\fBkeyok\fP(3), +\fBresizeterm\fP(3), +\fBwresize\fP(3). +.SH AUTHOR +Thomas Dickey. diff --git a/static/openbsd/man3/curs_get_wch.3 b/static/openbsd/man3/curs_get_wch.3 new file mode 100644 index 00000000..459e45ed --- /dev/null +++ b/static/openbsd/man3/curs_get_wch.3 @@ -0,0 +1,195 @@ +.\" $OpenBSD: curs_get_wch.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 2002-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_get_wch.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_get_wch 3 2022-02-12 "ncurses 6.4" "Library calls" +.na +.hy 0 +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBget_wch\fP, +\fBwget_wch\fP, +\fBmvget_wch\fP, +\fBmvwget_wch\fP, +\fBunget_wch\fP \- get (or push back) a wide character from curses terminal keyboard +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint get_wch(wint_t *\fIwch\fB);\fR +.br +\fBint wget_wch(WINDOW *\fIwin\fB, wint_t *\fIwch\fB);\fR +.br +\fBint mvget_wch(int \fIy\fB, int \fIx\fB, wint_t *\fIwch\fB);\fR +.br +\fBint mvwget_wch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, wint_t *\fIwch\fB);\fR +.sp +\fBint unget_wch(const wchar_t \fIwch\fB);\fR +.SH DESCRIPTION +.SS wget_wch +The +\fBget_wch\fP, +\fBwget_wch\fP, +\fBmvget_wch\fP, and +\fBmvwget_wch\fP +functions read a character +from the terminal associated with the current or specified window. +In no-delay mode, +if no input is waiting, the value \fBERR\fP is returned. +In delay mode, +the program waits until the system passes text through to the program. +Depending on the setting of \fBcbreak\fP, +this is after one character (cbreak mode), +or after the first newline (nocbreak mode). +In half-delay mode, +the program waits until the user types a character or the specified +timeout interval has elapsed. +.PP +Unless \fBnoecho\fP has been set, +these routines echo the character into the designated window. +.PP +If the window is not a pad and has been moved or modified since the +last call to \fBwrefresh\fP, +\fBwrefresh\fP will be called before another character is read. +.PP +If \fBkeypad\fP is enabled, +these functions respond to +the pressing of a function key by setting the object pointed to by +\fIwch\fP +to the keycode assigned to the function key, +and returning \fBKEY_CODE_YES\fP. +If a character (such as escape) that could be the +beginning of a function key is received, curses sets a timer. +If the remainder +of the sequence does arrive within the designated time, curses passes through +the character; otherwise, curses returns the function key value. +For this +reason, many terminals experience a delay between the time a user presses +the escape key and the time the escape is returned to the program. +.PP +The keycodes returned by these functions are the same as those +returned by \fBwgetch\fP: +.bP +The predefined function +keys are listed in \fB\fP as macros with values outside the range +of 8-bit characters. +Their names begin with \fBKEY_\fP. +.bP +Other (user-defined) function keys +which may be defined using \fBdefine_key\fP(3) have no names, +but also are expected to have values outside the range of 8-bit characters. +.SS unget_wch +The +\fBunget_wch\fP +function pushes the wide character +\fIwch\fP +back onto the head of the input queue, so the wide character +is returned by the next call to +\fBget_wch\fP. +The pushback of +one character is guaranteed. +If the program calls +\fBunget_wch\fP +too many times without an intervening call to +\fBget_wch\fP, +the operation may fail. +.PP +Unlike \fBungetch\fP and \fBwgetch\fP, +\fBunget_wch\fP cannot distinguish special characters +returned by \fBwget_wch\fP from ordinary characters. +An application can push special keys +which it may read via \fBwget_wch\fP +by checking for the \fBKEY_CODE_YES\fP result, +and using \fBungetch\fP for those special keys. +.SH NOTES +The header file +\fB\fP +automatically +includes the header file +\fB\fP. +.PP +Applications should not define the escape key by itself as a single-character +function. +.PP +When using +\fBget_wch\fP, +\fBwget_wch\fP, +\fBmvget_wch\fP, or +\fBmvwget_wch\fP, applications should +not use +\fBnocbreak\fP +mode and +\fBecho\fP +mode +at the same time. +Depending on the state of the tty driver when each character +is typed, the program may produce undesirable results. +.PP +All functions except \fBwget_wch\fP and \fBunget_wch\fP +may be macros. +.SH RETURN VALUE +When +\fBget_wch\fP, +\fBwget_wch\fP, +\fBmvget_wch\fP, and +\fBmvwget_wch\fP +functions successfully +report the pressing of a function key, they return +\fBKEY_CODE_YES\fP. +When they successfully report a wide character, they return +\fBOK\fP. +Otherwise, they return +\fBERR\fP. +.PP +Upon successful completion, +\fBunget_wch\fP +returns +\fBOK\fP. +Otherwise, the function returns +\fBERR\fP. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_getch\fP(3), +\fBcurs_ins_wch\fP(3), +\fBcurs_inopts\fP(3), +\fBcurs_move\fP(3), +\fBcurs_refresh\fP(3) diff --git a/static/openbsd/man3/curs_get_wstr.3 b/static/openbsd/man3/curs_get_wstr.3 new file mode 100644 index 00000000..116a1a7e --- /dev/null +++ b/static/openbsd/man3/curs_get_wstr.3 @@ -0,0 +1,226 @@ +.\" $OpenBSD: curs_get_wstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2002-2012,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_get_wstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_get_wstr 3 2023-08-05 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBget_wstr\fP, +\fBgetn_wstr\fP, +\fBwget_wstr\fP, +\fBwgetn_wstr\fP, +\fBmvget_wstr\fP, +\fBmvgetn_wstr\fP, +\fBmvwget_wstr\fP, +\fBmvwgetn_wstr\fP \- get an array of wide characters from a curses terminal keyboard +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +.sp +\fBint get_wstr(wint_t *\fIwstr\fB);\fR +.br +\fBint getn_wstr(wint_t *\fIwstr\fB, int \fIn\fB);\fR +.br +\fBint wget_wstr(WINDOW *\fIwin\fB, wint_t *\fIwstr\fB);\fR +.br +\fBint wgetn_wstr(WINDOW *\fIwin\fB, wint_t *\fIwstr\fB, int \fIn\fB);\fR +.sp +\fBint mvget_wstr(int \fIy\fB, int \fIx\fB, wint_t *\fIwstr\fB);\fR +.br +\fBint mvgetn_wstr(int \fIy\fB, int \fIx\fB, wint_t *\fIwstr\fB, int \fIn\fB);\fR +.br +\fBint mvwget_wstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, wint_t *\fIwstr\fB);\fR +.br +\fBint mvwgetn_wstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, wint_t *\fIwstr\fB, int \fIn\fB);\fR +.fi +.SH DESCRIPTION +The function +\fBwgetn_wstr\fP +is equivalent to a series of calls to +\fBwget_wch\fP(3) +until a newline or carriage return terminates the series: +.bP +The terminating character is not included in the returned string. +.bP +An end-of-file condition is represented by \fBWEOF\fP, +as defined in \fB\fP. +.bP +In all instances, the end of the string is terminated +by a null \fBwchar_t\fP. +.bP +The function stores the result in the area pointed to +by the \fIwstr\fP parameter. +.bP +The function reads at most \fIn\fP characters, +thus preventing a possible overflow of the input buffer. +.IP +Any attempt to enter more characters +(other than the terminating newline or carriage return) +causes a beep. +.IP +Function keys also cause a beep and are ignored. +.PP +The user's \fIerase\fP and \fIkill\fP characters are interpreted: +.bP +The \fIerase\fP character (e.g., \fB^H\fP) erases the character +at the end of the buffer, moving the cursor to the left. +.IP +If \fIkeypad\fP mode is on for the window, +\fBKEY_LEFT\fP and \fBKEY_BACKSPACE\fP +are both considered equivalent to the user's \fIerase\fP character. +.bP +The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer, +leaving the cursor at the beginning of the buffer. +.PP +Characters input are echoed only if \fBecho\fP is currently on. +In that case, +backspace is echoed as deletion of the previous character +(typically a left motion). +.PP +The +\fBgetn_wstr\fP, +\fBmvgetn_wstr\fP, +\fBmvwgetn_wstr\fP, and +\fBwgetn_wstr\fP +functions are identical +to the +\fBget_wstr\fP, +\fBmvget_wstr\fP, +\fBmvwget_wstr\fP, and +\fBwget_wstr\fP +functions, respectively, +except that the +\fB*n_*\fP +versions read at most +\fIn\fP +characters, letting the application prevent overflow of the +input buffer. +.SH NOTES +Any of these functions other than +\fBwgetn_wstr\fP +may be macros. +.PP +Using +\fBget_wstr\fP, +\fBmvget_wstr\fP, +\fBmvwget_wstr\fP, or +\fBwget_wstr\fP +to read a line that +overflows the array pointed to by +\fBwstr\fP +causes undefined +results. +The use of +\fBgetn_wstr\fP, +\fBmvgetn_wstr\fP, +\fBmvwgetn_wstr\fP, or +\fBwgetn_wstr\fP, +respectively, is recommended. +.PP +These functions cannot return \fBKEY_\fP values because there +is no way to distinguish a \fBKEY_\fP value from a valid \fBwchar_t\fP value. +may be macros. +.SH RETURN VALUE +All of these functions return the integer \fBOK\fP upon successful completion. +If unsuccessful, they return \fBERR\fP. +.PP +X/Open defines no error conditions. +.PP +In this implementation, +these functions return an error +.bP +if the window pointer is null, +.bP +if its timeout expires without having any data, or +.bP +if the associated call to +\fBwget_wch\fP +failed. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH PORTABILITY +These functions are described in The Single Unix Specification, Version 2. +No error conditions are defined. +.PP +This implementation returns \fBERR\fP if the window pointer is null, +or if the lower-level \fBwget_wch\fP call returns an \fBERR\fP. +In the latter case, +an \fBERR\fP return without other data is treated as an end-of-file condition, +and the returned array contains a \fBWEOF\fP followed by a null \fBwchar_t\fP. +.PP +X/Open curses documented these functions to pass an array of \fBwchar_t\fP +in 1997, but that was an error because of this part of the description: +.RS +.PP +The effect of \fBget_wstr\fP is as though a series of calls to +\fBget_wch\fP were made, until a newline character, end-of-line character, or +end-of-file character is processed. +.RE +.PP +The latter function \fIget_wch\fP can return a negative value, +while \fBwchar_t\fP is a unsigned type. +All of the vendors implement this using \fBwint_t\fP, following the standard. +.PP +X/Open Curses, Issue 7 (2009) is unclear regarding whether +the terminating \fInull \fBwchar_t\fR +value is counted in the length parameter \fIn\fP. +X/Open Curses, Issue 7 revised the corresponding description +of \fBwgetnstr\fP to address this issue. +The unrevised description of \fBwget_nwstr\fP can be interpreted either way. +This implementation counts the terminator in the length. +.PP +X/Open Curses does not specify what happens if the length \fIn\fP is negative. +.bP +For analogy with \fBwgetnstr\fP, +ncurses 6.2 uses a limit (based on \fBLINE_MAX\fP). +.bP +Some other implementations (such as Solaris xcurses) do the same, +while others (PDCurses) do not allow this. +.bP +NetBSD 7 curses imitates ncurses 6.1 in this regard, +treating a \fB\-1\fP as an indefinite number of characters. +.SH SEE ALSO +Functions: +\fBcurses\fP(3), +\fBcurs_get_wch\fP(3), +\fBcurs_getstr\fP(3). diff --git a/static/openbsd/man3/curs_getcchar.3 b/static/openbsd/man3/curs_getcchar.3 new file mode 100644 index 00000000..f2137028 --- /dev/null +++ b/static/openbsd/man3/curs_getcchar.3 @@ -0,0 +1,196 @@ +.\"*************************************************************************** +.\" Copyright 2019-2021,2023 Thomas E. Dickey * +.\" Copyright 2001-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_getcchar.3,v 1.1 2023/10/17 09:52:08 nicm Exp $ +.TH curs_getcchar 3 2023-07-01 "ncurses 6.4" "Library calls" +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBgetcchar\fP, +\fBsetcchar\fP \- Get a wide character string and rendition from a \fBcchar_t\fP or set a \fBcchar_t\fP from a wide-character string +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint getcchar(\fP +.br +.B " const cchar_t *\fIwcval\fP," +.br +.B " wchar_t *\fIwch\fP," +.br +.B " attr_t *\fIattrs\fP," +.br +.B " short *\fIcolor_pair\fP," +.br +.B " void *\fIopts\fP );" +.sp +.B "int setcchar(" +.br +.B " cchar_t *\fIwcval\fP," +.br +.B " const wchar_t *\fIwch\fP," +.br +.B " const attr_t \fIattrs\fP," +.br +.B " short \fIcolor_pair\fP," +.br +.B " const void *\fIopts\fP );" +.SH DESCRIPTION +.SS getcchar +The \fBgetcchar\fP function gets a wide-character string +and rendition from a \fBcchar_t\fP argument. +When \fIwch\fP is not a null pointer, +the \fBgetcchar\fP function does the following: +.bP +Extracts information from a \fBcchar_t\fP value \fIwcval\fP +.bP +Stores the character attributes in the location pointed to by \fIattrs\fP +.bP +Stores the color-pair in the location pointed to by \fIcolor_pair\fP +.bP +Stores the wide-character string, +characters referenced by \fIwcval\fP, into the array pointed to by \fIwch\fP. +.PP +When +\fIwch\fP +is a null pointer, the +\fBgetcchar\fP +function does the following: +.bP +Obtains the number of wide characters pointed to by \fIwcval\fP +.bP +Does not change the data referenced by +\fIattrs\fP +or +\fIcolor_pair\fP +.SS setcchar +The \fBsetcchar\fP function initializes the location pointed to by \fIwcval\fP +by using: +.bP +The character attributes in +\fIattrs\fP +.bP +The color pair in +\fIcolor_pair\fP +.bP +The wide-character string pointed to by \fIwch\fP. +The string must be L'\\0' terminated, +contain at most one spacing character, +which must be the first. +.IP +Up to \fBCCHARW_MAX\fP\-1 nonspacing characters may follow. +Additional nonspacing characters are ignored. +.IP +The string may contain a single control character instead. +In that case, no nonspacing characters are allowed. +.SH EXTENSIONS +X/Open Curses documents the \fIopts\fP argument as reserved for future use, +saying that it must be null. +This implementation +uses that parameter in ABI 6 for the functions which have a color-pair +parameter to support extended color pairs: +.bP +For functions which modify the color, e.g., \fBsetcchar\fP, +if \fIopts\fP is set it is treated as a pointer to \fBint\fP, +and used to set the color pair instead of the \fBshort\fP pair parameter. +.bP +For functions which retrieve the color, e.g., \fBgetcchar\fP, +if \fIopts\fP is set it is treated as a pointer to \fBint\fP, +and used to retrieve the color pair as an \fBint\fP value, +in addition retrieving it via the standard pointer to \fBshort\fP parameter. +.SH NOTES +The \fIwcval\fP argument may be a value generated by a call to +\fBsetcchar\fP or by a function that has a \fBcchar_t\fP output argument. +If \fIwcval\fP is constructed by any other means, the effect is unspecified. +.SH RETURN VALUE +When \fIwch\fP is a null pointer, +\fBgetcchar\fP returns the number of wide characters referenced by +\fIwcval\fP, +including one for a trailing null. +.PP +When \fIwch\fP is not a null pointer, +\fBgetcchar\fP returns \fBOK\fP upon successful completion, +and \fBERR\fP otherwise. +.PP +Upon successful completion, \fBsetcchar\fP returns \fBOK\fP. +Otherwise, it returns \fBERR\fP. +.SH PORTABILITY +The \fBCCHARW_MAX\fP symbol is specific to ncurses. +X/Open Curses does not provide details for the layout of the \fBcchar_t\fP +structure. +It tells what data are stored in it: +.bP +a spacing character (\fBwchar_t\fP, i.e., 32-bits). +.bP +non-spacing characters (again, \fBwchar_t\fP's). +.bP +attributes (at least 16 bits, inferred from the various ACS- and WACS-flags). +.bP +color pair (at least 16 bits, inferred from the \fBunsigned short\fP type). +.PP +The non-spacing characters are optional, +in the sense that zero or more may be stored in a \fBcchar_t\fP. +XOpen/Curses specifies a limit: +.RS 4 +.PP +Implementations may limit the number of non-spacing characters that can be +associated with a spacing character, provided any limit is at least 5. +.RE +.PP +The Unix implementations at the time follow that limit: +.bP +AIX\ 4 and OSF1\ 4 use the same declaration with an array of 5 non-spacing +characters \fIz\fP and a single spacing character \fIc\fP. +.bP +HP-UX\ 10 uses an opaque structure with 28 bytes, +which is large enough for the 6 \fBwchar_t\fP values. +.bP +Solaris \fIxpg4\fP curses uses a single array of 6 \fBwchar_t\fP values. +.PP +This implementation's \fBcchar_t\fP was defined in 1995 +using \fB5\fP for the total of spacing and non-spacing characters +(\fBCCHARW_MAX\fP). +That was probably due to a misreading of the AIX\ 4 header files, +because the X/Open Curses document was not generally available at that time. +Later (in 2002), this detail was overlooked when beginning to implement +the functions using the structure. +.PP +In practice, even four non-spacing characters may seem enough. +X/Open Curses documents possible uses for non-spacing characters, +including using them for ligatures between characters +(a feature apparently not supported by any curses implementation). +Unicode does not limit the (analogous) number of combining characters, +so some applications may be affected. +.SH SEE ALSO +Functions: +\fBcurs_attr\fP(3), +\fBcurs_color\fP(3), +\fBcurses\fP(3), +\fBwcwidth\fP(3). diff --git a/static/openbsd/man3/curs_getch.3 b/static/openbsd/man3/curs_getch.3 new file mode 100644 index 00000000..6ee26d07 --- /dev/null +++ b/static/openbsd/man3/curs_getch.3 @@ -0,0 +1,419 @@ +'\" t +.\" $OpenBSD: curs_getch.3,v 1.6 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_getch.3,v 1.6 2023/10/17 09:52:08 nicm Exp $ +.TH curs_getch 3 2023-08-19 "ncurses 6.4" "Library calls" +.na +.hy 0 +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBgetch\fP, +\fBwgetch\fP, +\fBmvgetch\fP, +\fBmvwgetch\fP, +\fBungetch\fP, +\fBhas_key\fP \- get (or push back) characters from \fBcurses\fP terminal keyboard +.ad +.hy +.SH SYNOPSIS +.B #include +.PP +.B int getch(void); +.br +.B int wgetch(WINDOW *\fIwin\fB); +.sp +.B int mvgetch(int \fIy\fB, int \fIx\fB); +.br +.B int mvwgetch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB); +.sp +.B int ungetch(int \fIch\fB); +.sp +/* extension */ +.br +.B int has_key(int \fIch\fB); +.br +.SH DESCRIPTION +.SS Reading characters +The \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP and \fBmvwgetch\fP, routines read +a character from the window. +In no-delay mode, if no input is waiting, the value \fBERR\fP is returned. +In delay mode, the program waits until the system +passes text through to the program. +Depending on the setting of \fBcbreak\fP, +this is after one character (cbreak mode), +or after the first newline (nocbreak mode). +In half-delay mode, +the program waits until a character is typed or the +specified timeout has been reached. +.PP +If \fBecho\fP is enabled, and the window is not a pad, +then the character will also be echoed into the +designated window according to the following rules: +.bP +If the character is the current erase character, left arrow, or backspace, +the cursor is moved one space to the left and that screen position is erased +as if \fBdelch\fP had been called. +.bP +If the character value is any other \fBKEY_\fP define, the user is alerted +with a \fBbeep\fP call. +.bP +If the character is a carriage-return, +and if \fBnl\fP is enabled, +it is translated to a line-feed after echoing. +.bP +Otherwise the character is simply output to the screen. +.PP +If the window is not a pad, and it has been moved or modified since the last +call to \fBwrefresh\fP, \fBwrefresh\fP will be called before another character +is read. +.SS Keypad mode +If \fBkeypad\fP is \fBTRUE\fP, and a function key is pressed, the token for +that function key is returned instead of the raw characters: +.bP +The predefined function +keys are listed in \fB\fP as macros with values outside the range +of 8-bit characters. +Their names begin with \fBKEY_\fP. +.bP +Other (user-defined) function keys which may be defined +using \fBdefine_key\fP(3) +have no names, but also are expected to have values outside the range of +8-bit characters. +.PP +Thus, a variable +intended to hold the return value of a function key must be of short size or +larger. +.PP +When a character that could be the beginning of a function key is received +(which, on modern terminals, means an escape character), +\fBcurses\fP sets a timer. +If the remainder of the sequence does not come in within the designated +time, the character is passed through; +otherwise, the function key value is returned. +For this reason, many terminals experience a delay between the time +a user presses the escape key and the escape is returned to the program. +.PP +In \fBncurses\fP, the timer normally expires after +the value in \fBESCDELAY\fP (see \fBcurs_variables\fP(3)). +If \fBnotimeout\fP is \fBTRUE\fP, the timer does not expire; +it is an infinite (or very large) value. +Because function keys usually begin with an escape character, +the terminal may appear to hang in notimeout mode after pressing the escape key +until another key is pressed. +.SS Ungetting characters +The \fBungetch\fP routine places \fIch\fP back onto the input queue to be +returned by the next call to \fBwgetch\fP. +There is just one input queue for all windows. +.SS Predefined key-codes +The following special keys are defined in \fB\fP. +.bP +Except for the special case \fBKEY_RESIZE\fP, +it is necessary to enable \fBkeypad\fP for \fBgetch\fP to return these codes. +.bP +Not all of these are necessarily supported on any particular terminal. +.bP +The naming convention may seem obscure, with some apparent +misspellings (such as \*(``RSUME\*('' for \*(``resume\*(''). +The names correspond to the long terminfo capability names for the keys, +and were defined long ago, in the 1980s. +.PP +.RS +.TS +tab(/) ; +l l . +\fBName\fP/\fBKey\fP \fBname\fP +_ +KEY_BREAK/Break key +KEY_DOWN/The four arrow keys ... +KEY_UP +KEY_LEFT +KEY_RIGHT +KEY_HOME/Home key (upward+left arrow) +KEY_BACKSPACE/Backspace +KEY_F0/T{ +Function keys; space for 64 keys is reserved. +T} +KEY_F(\fIn\fP)/T{ +For 0 \(<= \fIn\fP \(<= 63 +T} +KEY_DL/Delete line +KEY_IL/Insert line +KEY_DC/Delete character +KEY_IC/Insert char or enter insert mode +KEY_EIC/Exit insert char mode +KEY_CLEAR/Clear screen +KEY_EOS/Clear to end of screen +KEY_EOL/Clear to end of line +KEY_SF/Scroll 1 line forward +KEY_SR/Scroll 1 line backward (reverse) +KEY_NPAGE/Next page +KEY_PPAGE/Previous page +KEY_STAB/Set tab +KEY_CTAB/Clear tab +KEY_CATAB/Clear all tabs +KEY_ENTER/Enter or send +KEY_SRESET/Soft (partial) reset +KEY_RESET/Reset or hard reset +KEY_PRINT/Print or copy +KEY_LL/Home down or bottom (lower left) +KEY_A1/Upper left of keypad +KEY_A3/Upper right of keypad +KEY_B2/Center of keypad +KEY_C1/Lower left of keypad +KEY_C3/Lower right of keypad +KEY_BTAB/Back tab key +KEY_BEG/Beg(inning) key +KEY_CANCEL/Cancel key +KEY_CLOSE/Close key +KEY_COMMAND/Cmd (command) key +KEY_COPY/Copy key +KEY_CREATE/Create key +KEY_END/End key +KEY_EXIT/Exit key +KEY_FIND/Find key +KEY_HELP/Help key +KEY_MARK/Mark key +KEY_MESSAGE/Message key +KEY_MOUSE/Mouse event occurred +KEY_MOVE/Move key +KEY_NEXT/Next object key +KEY_OPEN/Open key +KEY_OPTIONS/Options key +KEY_PREVIOUS/Previous object key +KEY_REDO/Redo key +KEY_REFERENCE/Ref(erence) key +KEY_REFRESH/Refresh key +KEY_REPLACE/Replace key +KEY_RESIZE/Screen resized +KEY_RESTART/Restart key +KEY_RESUME/Resume key +KEY_SAVE/Save key +KEY_SBEG/Shifted beginning key +KEY_SCANCEL/Shifted cancel key +KEY_SCOMMAND/Shifted command key +KEY_SCOPY/Shifted copy key +KEY_SCREATE/Shifted create key +KEY_SDC/Shifted delete char key +KEY_SDL/Shifted delete line key +KEY_SELECT/Select key +KEY_SEND/Shifted end key +KEY_SEOL/Shifted clear line key +KEY_SEXIT/Shifted exit key +KEY_SFIND/Shifted find key +KEY_SHELP/Shifted help key +KEY_SHOME/Shifted home key +KEY_SIC/Shifted insert key +KEY_SLEFT/Shifted left arrow key +KEY_SMESSAGE/Shifted message key +KEY_SMOVE/Shifted move key +KEY_SNEXT/Shifted next key +KEY_SOPTIONS/Shifted options key +KEY_SPREVIOUS/Shifted prev key +KEY_SPRINT/Shifted print key +KEY_SREDO/Shifted redo key +KEY_SREPLACE/Shifted replace key +KEY_SRIGHT/Shifted right arrow key +KEY_SRSUME/Shifted resume key +KEY_SSAVE/Shifted save key +KEY_SSUSPEND/Shifted suspend key +KEY_SUNDO/Shifted undo key +KEY_SUSPEND/Suspend key +KEY_UNDO/Undo key +.TE +.RE +.PP +Keypad is arranged like this: +.PP +.RS +.TS +allbox tab(/) ; +c c c . +\fBA1\fP/\fBup\fP/\fBA3\fP +\fBleft\fP/\fBB2\fP/\fBright\fP +\fBC1\fP/\fBdown\fP/\fBC3\fP +.TE +.RE +.sp +A few of these predefined values do \fInot\fP correspond to a real key: +.bP +.B KEY_RESIZE +is returned when the \fBSIGWINCH\fP signal has been detected +(see \fBinitscr\fP(3) and \fBresizeterm\fP(3)). +This code is returned whether or not \fBkeypad\fP has been enabled. +.bP +.B KEY_MOUSE +is returned for mouse-events (see \fBcurs_mouse\fP(3)). +This code relies upon whether or not \fBkeypad\fP(3) has been enabled, +because (e.g., with \fBxterm\fP(1) mouse prototocol) ncurses must +read escape sequences, +just like a function key. +.SS Testing key-codes +The \fBhas_key\fP routine takes a key-code value from the above list, and +returns \fBTRUE\fP or \fBFALSE\fP according to whether +the current terminal type recognizes a key with that value. +.PP +The library also supports these extensions: +.RS 3 +.TP 5 +.B define_key +defines a key-code for a given string (see \fBdefine_key\fP(3)). +.TP 5 +.B key_defined +checks if there is a key-code defined for a given +string (see \fBkey_defined\fP(3)). +.RE +.SH RETURN VALUE +All routines return the integer \fBERR\fP upon failure and an integer value +other than \fBERR\fP (\fBOK\fP in the case of \fBungetch\fP) upon successful +completion. +.RS 3 +.TP 5 +\fBungetch\fP +returns \fBERR\fP +if there is no more room in the FIFO. +.TP +\fBwgetch\fP +returns \fBERR\fP +if the window pointer is null, or +if its timeout expires without having any data, or +if the execution was interrupted by a signal (\fBerrno\fP will be set to +\fBEINTR\fP). +.RE +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +Use of the escape key by a programmer for a single character function is +discouraged, as it will cause a delay of up to one second while the +keypad code looks for a following function-key sequence. +.PP +Some keys may be the same as commonly used control +keys, e.g., +\fBKEY_ENTER\fP versus control/M, +\fBKEY_BACKSPACE\fP versus control/H. +Some curses implementations may differ according to whether they +treat these control keys specially (and ignore the terminfo), or +use the terminfo definitions. +\fBNcurses\fP uses the terminfo definition. +If it says that \fBKEY_ENTER\fP is control/M, +\fBgetch\fP will return \fBKEY_ENTER\fP +when you press control/M. +.PP +Generally, \fBKEY_ENTER\fP denotes the character(s) sent by the \fIEnter\fP +key on the numeric keypad: +.bP +the terminal description lists the most useful keys, +.bP +the \fIEnter\fP key on the regular keyboard is already handled by +the standard ASCII characters for carriage-return and line-feed, +.bP +depending on whether \fBnl\fP or \fBnonl\fP was called, +pressing \*(``Enter\*('' on the regular keyboard +may return either a carriage-return or line-feed, and finally +.bP +\*(``Enter or send\*('' is the standard description for this key. +.PP +When using \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP, or +\fBmvwgetch\fP, nocbreak mode (\fBnocbreak\fP) and echo mode +(\fBecho\fP) should not be used at the same time. +Depending on the +state of the tty driver when each character is typed, the program may +produce undesirable results. +.PP +Note that \fBgetch\fP, \fBmvgetch\fP, and \fBmvwgetch\fP may be macros. +.PP +Historically, the set of keypad macros was largely defined by the extremely +function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Safari 4. +Modern +personal computers usually have only a small subset of these. +IBM PC-style +consoles typically support little more than \fBKEY_UP\fP, \fBKEY_DOWN\fP, +\fBKEY_LEFT\fP, \fBKEY_RIGHT\fP, \fBKEY_HOME\fP, \fBKEY_END\fP, +\fBKEY_NPAGE\fP, \fBKEY_PPAGE\fP, and function keys 1 through 12. +The Ins key +is usually mapped to \fBKEY_IC\fP. +.SH PORTABILITY +The *get* functions are described in the XSI Curses standard, Issue 4. +They +read single-byte characters only. +The standard specifies that they return +\fBERR\fP on failure, but specifies no error conditions. +.PP +The echo behavior of these functions on input of \fBKEY_\fP or backspace +characters was not specified in the SVr4 documentation. +This description is +adopted from the XSI Curses standard. +.PP +The behavior of \fBgetch\fP and friends in the presence of handled signals is +unspecified in the SVr4 and XSI Curses documentation. +Under historical curses +implementations, it varied depending on whether the operating system's +implementation of handled signal receipt interrupts a \fBread\fP(2) call in +progress or not, and also (in some implementations) depending on whether an +input timeout or non-blocking mode has been set. +.PP +\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related +terminfo capabilities, but no higher-level functions use the feature. +The implementation in ncurses is an extension. +.PP +\fBKEY_RESIZE\fP is an extension first implemented for ncurses. +NetBSD curses later added this extension. +.PP +Programmers concerned about portability should be prepared for either of two +cases: (a) signal receipt does not interrupt \fBgetch\fP; (b) signal receipt +interrupts \fBgetch\fP and causes it to return \fBERR\fP with \fBerrno\fP set to +\fBEINTR\fP. +.PP +The \fBhas_key\fP function is unique to \fBncurses\fP. +We recommend that +any code using it be conditionalized on the \fBNCURSES_VERSION\fP feature macro. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_inopts\fP(3), +\fBcurs_mouse\fP(3), +\fBcurs_move\fP(3), +\fBcurs_outopts\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_variables\fP(3), +\fBresizeterm\fP(3). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_get_wch\fP(3). diff --git a/static/openbsd/man3/curs_getstr.3 b/static/openbsd/man3/curs_getstr.3 new file mode 100644 index 00000000..0b33bffe --- /dev/null +++ b/static/openbsd/man3/curs_getstr.3 @@ -0,0 +1,292 @@ +.\" $OpenBSD: curs_getstr.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_getstr.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.TH curs_getstr 3 2023-08-05 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBgetstr\fP, +\fBgetnstr\fP, +\fBwgetstr\fP, +\fBwgetnstr\fP, +\fBmvgetstr\fP, +\fBmvgetnstr\fP, +\fBmvwgetstr\fP, +\fBmvwgetnstr\fP \- accept character strings from \fBcurses\fP terminal keyboard +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint getstr(char *\fIstr\fB);\fR +.br +\fBint getnstr(char *\fIstr\fB, int \fIn\fB);\fR +.br +\fBint wgetstr(WINDOW *\fIwin\fB, char *\fIstr\fB);\fR +.br +\fBint wgetnstr(WINDOW *\fIwin\fB, char *\fIstr\fB, int \fIn\fB);\fR +.sp +\fBint mvgetstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR +.br +\fBint mvwgetstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR +.br +\fBint mvgetnstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR +.br +\fBint mvwgetnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR +.SH DESCRIPTION +The function +\fBwgetnstr\fP +is equivalent to a series of calls to +\fBwgetch\fP(3), +until a newline or carriage return terminates the series: +.bP +The terminating character is not included in the returned string. +.bP +In all instances, the end of the string is terminated +by a NUL. +.bP +The function stores the result in the area pointed to +by the \fIstr\fP parameter. +.bP +The function reads at most \fIn\fP characters, +thus preventing a possible overflow of the input buffer. +.IP +Any attempt to enter more characters +(other than the terminating newline or carriage return) +causes a beep. +.IP +Function keys also cause a beep and are ignored. +.PP +The user's \fIerase\fP and \fIkill\fP characters are interpreted: +.bP +The \fIerase\fP character (e.g., \fB^H\fP) erases the character +at the end of the buffer, moving the cursor to the left. +.IP +If \fIkeypad\fP mode is on for the window, +\fBKEY_LEFT\fP and \fBKEY_BACKSPACE\fP +are both considered equivalent to the user's \fIerase\fP character. +.bP +The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer, +leaving the cursor at the beginning of the buffer. +.PP +Characters input are echoed only if \fBecho\fP is currently on. +In that case, +backspace is echoed as deletion of the previous character +(typically a left motion). +.PP +The +\fBgetnstr\fP, +\fBmvgetnstr\fP, +\fBmvwgetnstr\fP, and +\fBwgetnstr\fP +functions are identical +to the +\fBgetstr\fP, +\fBmvgetstr\fP, +\fBmvwgetstr\fP, and +\fBwgetstr\fP +functions, respectively, +except that the +\fB*n*\fP +versions read at most +\fIn\fP +characters, letting the application prevent overflow of the +input buffer. +.SH NOTES +Any of these functions other than +\fBwgetnstr\fP +may be macros. +.PP +Using +\fBgetstr\fP, +\fBmvgetstr\fP, +\fBmvwgetstr\fP, or +\fBwgetstr\fP +to read a line that +overflows the array pointed to by +\fBstr\fP +causes undefined +results. +The use of +\fBgetnstr\fP, +\fBmvgetnstr\fP, +\fBmvwgetnstr\fP, or +\fBwgetnstr\fP, +respectively, is recommended. +.SH RETURN VALUE +All of these functions return the integer \fBOK\fP upon successful completion. +(SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('') +If unsuccessful, they return \fBERR\fP. +.PP +X/Open defines no error conditions. +.PP +In this implementation, +these functions return an error +.bP +if the window pointer is null, +.bP +if its timeout expires without having any data, or +.bP +if the associated call to +\fBwgetch\fP +failed. +.PP +This implementation provides an extension as well. +If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP +rather than \fBOK\fP or \fBERR\fP. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH PORTABILITY +These functions are described in The Single Unix Specification, Version 2. +No error conditions are defined. +.PP +This implementation returns \fBERR\fP if the window pointer is null, +or if the lower-level \fBwgetch\fP(3) call returns an \fBERR\fP. +.PP +SVr3 and early SVr4 curses implementations did not reject function keys; +the SVr4.0 documentation claimed that \*(``special keys\*('' +(such as function keys, +\*(``home\*('' key, +\*(``clear\*('' key, +\fIetc\fP.) are \*(``interpreted\*('', +without giving details. +It lied. +In fact, the \*(``character\*('' value appended to the +string by those implementations was predictable but not useful +(being, in fact, the low-order eight bits of the key's KEY_ value). +.PP +The functions \fBgetnstr\fP, \fBmvgetnstr\fP, and \fBmvwgetnstr\fP were +present but not documented in SVr4. +.PP +X/Open Curses, Issue 5 (2007) stated that these functions +\*(``read at most \fIn\fP bytes\*('' +but did not state whether the terminating NUL is counted in that limit. +X/Open Curses, Issue 7 (2009) changed that to say they +\*(``read at most \fIn\fP\-1 bytes\*('' +to allow for the terminating NUL. +As of 2018, some implementations count it, some do not: +.bP +ncurses 6.1 and PDCurses do not count the NUL in the given limit, while +.bP +Solaris SVr4 and NetBSD curses count the NUL as part of the limit. +.bP +Solaris xcurses provides both: +its wide-character \fBwget_nstr\fP reserves a NUL, +but its \fBwgetnstr\fP does not count the NUL consistently. +.PP +In SVr4 curses, +a negative value of \fIn\fP tells \fBwgetnstr\fP to assume that the +caller's buffer is large enough to hold the result, +i.e., to act like \fBwgetstr\fP. +X/Open Curses does not mention this +(or anything related to negative or zero values of \fIn\fP), +however most implementations +use the feature, with different limits: +.bP +Solaris SVr4 curses and PDCurses limit the result to 255 bytes. +Other Unix systems than Solaris are likely to use the same limit. +.bP +Solaris xcurses limits the result to \fBLINE_MAX\fP bytes. +.bP +NetBSD 7 assumes no particular limit for the result from \fBwgetstr\fP. +However, it limits the \fBwgetnstr\fP parameter \fIn\fP to ensure +that it is greater than zero. +.IP +A comment in NetBSD's source code states that this is specified in SUSv2. +.bP +ncurses (before 6.2) assumes no particular limit for the result +from \fBwgetstr\fP, and treats the \fIn\fP parameter of \fBwgetnstr\fP +like SVr4 curses. +.bP +ncurses 6.2 uses \fBLINE_MAX\fP, +or a larger (system-dependent) value +which the \fBsysconf\fP function may provide. +If neither \fBLINE_MAX\fP or \fBsysconf\fP is available, +ncurses uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit). +In either case, it reserves a byte for the terminating NUL. +.PP +Although \fBgetnstr\fP is equivalent to a series of calls to \fBgetch\fP, +it also makes changes to the curses modes to allow simple editing of +the input buffer: +.bP +\fBgetnstr\fP saves the current value of the \fBnl\fP, \fBecho\fP, +\fBraw\fP and \fBcbreak\fP modes, and sets +\fBnl\fP, +\fBnoecho\fP, +\fBnoraw\fP, and +\fBcbreak\fP. +.IP +\fBgetnstr\fP handles the echoing of characters, +rather than relying on the caller to set an appropriate mode. +.bP +It also obtains the \fIerase\fP and \fIkill\fP characters +from \fBerasechar\fP and \fBkillchar\fP, respectively. +.bP +On return, \fBgetnstr\fP restores the modes to their previous values. +.PP +Other implementations differ in their treatment of special characters: +.bP +While they may set the \fIecho\fP mode, +other implementations do not modify the \fIraw\fP mode, +They may take the \fIcbreak\fP +mode set by the caller into account when deciding whether to handle +echoing within \fBgetnstr\fP or as a side-effect of the \fBgetch\fP calls. +.bP +The original ncurses (as \fIpcurses\fP in 1986) set \fBnoraw\fP and \fBcbreak\fP +when accepting input for \fBgetnstr\fP. +That may have been done to make function- and cursor-keys work; +it is not necessary with ncurses. +.IP +Since 1995, ncurses has provided signal handlers for INTR and QUIT +(e.g., \fB^C\fP or \fB^\\\fP). +With the \fBnoraw\fP and \fBcbreak\fP settings, +those may catch a signal and stop the program, +where other implementations allow one to enter those characters in the buffer. +.bP +Starting in 2021 (ncurses 6.3), \fBgetnstr\fP sets \fBraw\fP, +rather than \fBnoraw\fP and \fBcbreak\fP for better compatibility with +SVr4-curses, e.g., allowing one to enter a \fB^C\fP into the buffer. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_getch\fP(3), +\fBcurs_termattrs\fP(3), +\fBcurs_variables\fP(3). diff --git a/static/openbsd/man3/curs_getyx.3 b/static/openbsd/man3/curs_getyx.3 new file mode 100644 index 00000000..6c6b6f19 --- /dev/null +++ b/static/openbsd/man3/curs_getyx.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: curs_getyx.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2020-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2007,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_getyx.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.TH curs_getyx 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBgetyx\fP, +\fBgetparyx\fP, +\fBgetbegyx\fP, +\fBgetmaxyx\fP \- get \fBcurses\fP cursor and window coordinates +.SH SYNOPSIS +\fB#include \fP +.sp +\fBvoid getyx(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR +.br +\fBvoid getparyx(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR +.br +\fBvoid getbegyx(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR +.br +\fBvoid getmaxyx(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR +.SH DESCRIPTION +The \fBgetyx\fP macro places the current cursor position of the given window in +the two integer variables \fIy\fP and \fIx\fP. +.PP +If \fIwin\fP is a subwindow, the \fBgetparyx\fP macro places the beginning +coordinates of the subwindow relative to the parent window into two integer +variables \fIy\fP and \fIx\fP. +Otherwise, \fB\-1\fP is placed into \fIy\fP and \fIx\fP. +.PP +Like \fBgetyx\fP, the \fBgetbegyx\fP and \fBgetmaxyx\fP macros store +the current beginning coordinates and size of the specified window. +.SH RETURN VALUE +The return values of these macros are undefined (i.e., +they should not be used as the right-hand side of assignment statements). +.SH NOTES +All of these interfaces are macros. +A "\fB&\fP" is not necessary before the variables \fIy\fP and \fIx\fP. +.SH PORTABILITY +The +\fBgetyx\fP, +\fBgetparyx\fP, +\fBgetbegyx\fP and +\fBgetmaxyx\fP +macros are described in the XSI Curses standard, Issue 4. +.PP +This implementation also provides functions +\fBgetbegx\fP, +\fBgetbegy\fP, +\fBgetcurx\fP, +\fBgetcury\fP, +\fBgetmaxx\fP, +\fBgetmaxy\fP, +\fBgetparx\fP and +\fBgetpary\fP +for compatibility with older versions of curses. +.PP +Although X/Open Curses does not address this, +many implementations provide members of the WINDOW structure +containing values corresponding to these macros. +For best portability, do not rely on using the data in WINDOW, +since some implementations make WINDOW opaque (do not allow +direct use of its members). +.PP +Besides the problem of opaque structures, +the data stored in like-named members may not have like-values in +different implementations. +For example, the WINDOW._maxx and WINDOW._maxy values in ncurses +have (at least since release 1.8.1) differed by one from some +other implementations. +The difference is hidden by means of the macro \fBgetmaxyx\fP. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_legacy\fP(3), +\fBcurs_opaque\fP(3) diff --git a/static/openbsd/man3/curs_in_wch.3 b/static/openbsd/man3/curs_in_wch.3 new file mode 100644 index 00000000..5b5efacc --- /dev/null +++ b/static/openbsd/man3/curs_in_wch.3 @@ -0,0 +1,72 @@ +.\" $OpenBSD: curs_in_wch.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 2002-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_in_wch.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_in_wch 3 2022-02-12 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBin_wch\fP, +\fBmvin_wch\fP, +\fBmvwin_wch\fP, +\fBwin_wch\fP \- extract a complex character and rendition from a window +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint in_wch(cchar_t *\fIwcval\fB);\fR +.br +\fBint win_wch(WINDOW *\fIwin\fB, cchar_t *\fIwcval\fB);\fR +.sp +\fBint mvin_wch(int \fIy\fB, int \fIx\fB, cchar_t *\fIwcval\fB);\fR +.br +\fBint mvwin_wch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, cchar_t *\fIwcval\fB);\fR +.SH DESCRIPTION +These functions extract the complex character and rendition from +the current position in the named window into the \fBcchar_t\fP object +referenced by wcval. +.SH RETURN VALUE +No errors are defined in the XSI Curses standard. +This implementation checks for null pointers, returns \fBERR\fP in that case. +Also, the \fImv\fP routines check for error moving the cursor, +returning \fBERR\fP in that case. +Otherwise they return \fBOK\fP. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +Note that all of these routines may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_inch\fP(3). diff --git a/static/openbsd/man3/curs_in_wchstr.3 b/static/openbsd/man3/curs_in_wchstr.3 new file mode 100644 index 00000000..96899c6a --- /dev/null +++ b/static/openbsd/man3/curs_in_wchstr.3 @@ -0,0 +1,127 @@ +.\" $OpenBSD: curs_in_wchstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 2002-2012,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_in_wchstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_in_wchstr 3 2022-02-12 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.na +.hy 0 +.SH NAME +\fBin_wchstr\fP, +\fBin_wchnstr\fP, +\fBwin_wchstr\fP, +\fBwin_wchnstr\fP, +\fBmvin_wchstr\fP, +\fBmvin_wchnstr\fP, +\fBmvwin_wchstr\fP, +\fBmvwin_wchnstr\fP \- get an array of complex characters and renditions from a curses window +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +.sp +\fBint in_wchstr(cchar_t *\fIwchstr\fB);\fR +.br +\fBint in_wchnstr(cchar_t *\fIwchstr\fB, int \fIn\fB);\fR +.br +\fBint win_wchstr(WINDOW *\fIwin\fB, cchar_t *\fIwchstr\fB);\fR +.br +\fBint win_wchnstr(WINDOW *\fIwin\fB, cchar_t *\fIwchstr\fB, int \fIn\fB);\fR +.sp +\fBint mvin_wchstr(int \fIy\fB, int \fIx\fB, cchar_t *\fIwchstr\fB);\fR +.br +\fBint mvin_wchnstr(int \fIy\fB, int \fIx\fB, cchar_t *\fIwchstr\fB, int \fIn\fB);\fR +.br +\fBint mvwin_wchstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, cchar_t *\fIwchstr\fB);\fR +.br +\fBint mvwin_wchnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, cchar_t *\fIwchstr\fR, int \fIn\fB);\fR +.fi +.SH DESCRIPTION +These functions return an array of complex characters in \fIwchstr\fP, +starting at the current cursor position in the named window. +Attributes (rendition) are stored with the characters. +.PP +The +\fBin_wchnstr\fP, +\fBmvin_wchnstr\fP, +\fBmvwin_wchnstr\fP +and +\fBwin_wchnstr\fP +fill the array +with at most +\fIn\fP +\fBcchar_t\fP +elements. +.br +.SH NOTES +Note that all routines except +\fBwin_wchnstr\fP +may be +macros. +.PP +Reading a line that overflows the array pointed to by +\fIwchstr\fP +with +\fBin_wchstr\fP, +\fBmvin_wchstr\fP, +\fBmvwin_wchstr\fP +or +\fBwin_wchstr\fP +causes undefined results. +Therefore, the use of +\fBin_wchnstr\fP, +\fBmvin_wchnstr\fP, +\fBmvwin_wchnstr\fP, or +\fBwin_wchnstr\fP +is recommended. +.SH RETURN VALUE +Upon successful completion, these functions return +\fBOK\fP. +Otherwise, they return +\fBERR\fP. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH PORTABILITY +The XSI Curses defines no error conditions. +This implementation checks for null pointers, +returning \fBERR\fP in that case. +.SH SEE ALSO +Functions: +\fBcurses\fP(3), +\fBcurs_in_wch\fP(3), +\fBcurs_instr\fP(3), +\fBcurs_inwstr\fP(3) +\fBcurs_inchstr\fP(3) diff --git a/static/openbsd/man3/curs_inch.3 b/static/openbsd/man3/curs_inch.3 new file mode 100644 index 00000000..255cc07d --- /dev/null +++ b/static/openbsd/man3/curs_inch.3 @@ -0,0 +1,120 @@ +'\" t +.\" $OpenBSD: curs_inch.3,v 1.5 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_inch.3,v 1.5 2023/10/17 09:52:08 nicm Exp $ +.TH curs_inch 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBinch\fP, +\fBwinch\fP, +\fBmvinch\fP, +\fBmvwinch\fP \- get a character and attributes from a \fBcurses\fP window +.SH SYNOPSIS +\fB#include \fP +.sp +\fBchtype inch(void);\fP +.br +\fBchtype winch(WINDOW *\fIwin\fB);\fR +.sp +\fBchtype mvinch(int \fIy\fB, int \fIx\fB);\fR +.br +\fBchtype mvwinch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR +.SH DESCRIPTION +These routines return the character, of type \fBchtype\fP, at the current +position in the named window. +If any attributes are set for that position, +their values are OR'ed into the value returned. +Constants defined in +\fB\fP can be used with the \fB&\fP (logical AND) operator to +extract the character or attributes alone. +. +.SS Attributes +The following bit-masks may be AND-ed with characters returned by \fBwinch\fP. +.PP +.TS +l l . +\fBA_CHARTEXT\fP Bit-mask to extract character +\fBA_ATTRIBUTES\fP Bit-mask to extract attributes +\fBA_COLOR\fP Bit-mask to extract color-pair field information +.TE +.SH RETURN VALUE +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.PP +The \fBwinch\fP function does not return an error if the window contains +characters larger than 8-bits (255). +Only the low-order 8 bits of the character are used by \fBwinch\fP. +.SH NOTES +Note that all of these routines may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.PP +Very old systems (before standardization) provide a different function +with the same name: +.bP +The \fBwinch\fP function was part of the original BSD curses library, +which stored a 7-bit character combined with the \fIstandout\fP attribute. +.IP +In BSD curses, \fBwinch\fP returned only the character (as an integer) +with the \fIstandout\fP attribute removed. +.bP +System V curses added support for several video attributes which +could be combined with characters in the window. +.IP +Reflecting this improvement, the function was altered to return the +character combined with all video attributes in a \fBchtype\fP value. +.PP +X/Open Curses does not specify +the size and layout of attributes, color and character values in +\fBchtype\fP; it is implementation-dependent. +This implementation uses 8 bits for character values. +An application using more bits, e.g., a Unicode value, +should use the wide-character equivalents to these functions. +.SH SEE ALSO +.TP 5 +\fBcurses\fP(3) +gives an overview of the WINDOW and \fBchtype\fP data types. +.TP 5 +\fBcurs_attr\fP(3) +goes into more detail, pointing out portability problems and +constraints on the use of \fBchtype\fP for returning window information. +.TP 5 +\fBcurs_in_wch\fP(3) +describes comparable functions for the wide-character (ncursesw) library. diff --git a/static/openbsd/man3/curs_inchstr.3 b/static/openbsd/man3/curs_inchstr.3 new file mode 100644 index 00000000..dc8475a6 --- /dev/null +++ b/static/openbsd/man3/curs_inchstr.3 @@ -0,0 +1,115 @@ +.\" $OpenBSD: curs_inchstr.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_inchstr.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.TH curs_inchstr 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBinchstr\fP, +\fBinchnstr\fP, +\fBwinchstr\fP, +\fBwinchnstr\fP, +\fBmvinchstr\fP, +\fBmvinchnstr\fP, +\fBmvwinchstr\fP, +\fBmvwinchnstr\fP \- get a string of characters (and attributes) from a \fBcurses\fP window +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint inchstr(chtype *\fIchstr\fB);\fR +.br +\fBint inchnstr(chtype *\fIchstr\fB, int \fIn\fB);\fR +.br +\fBint winchstr(WINDOW *\fIwin\fB, chtype *\fIchstr\fB);\fR +.br +\fBint winchnstr(WINDOW *\fIwin\fB, chtype *\fIchstr\fB, int \fIn\fB);\fR +.sp +\fBint mvinchstr(int \fIy\fB, int \fIx\fB, chtype *\fIchstr\fB);\fR +.br +\fBint mvinchnstr(int \fIy\fB, int \fIx\fB, chtype *\fIchstr\fB, int \fIn\fB);\fR +.br +\fBint mvwinchstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, chtype *\fIchstr\fB);\fR +.br +\fBint mvwinchnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, chtype *\fIchstr\fB, int \fIn\fB);\fR +.SH DESCRIPTION +These routines return a NULL-terminated array of \fBchtype\fP quantities, +starting at the current cursor position in the named window and ending at the +right margin of the window. +The four functions with \fIn\fP as +the last argument, return a leading substring at most \fIn\fP characters long +(exclusive of the trailing (chtype)0). +Constants defined in \fB\fP can be used with the \fB&\fP (logical +AND) operator to extract the character or the attribute alone from any position +in the \fIchstr\fP [see \fBcurs_inch\fP(3)]. +.SH RETURN VALUE +All routines return the integer \fBERR\fP upon failure and an integer value +other than \fBERR\fP upon successful completion (the number of characters +retrieved, exclusive of the trailing 0). +.PP +X/Open Curses defines no error conditions. +In this implementation: +.bP +If the \fIwin\fP parameter is null, an error is returned, +.bP +If the \fIchstr\fP parameter is null, an error is returned, +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +Note that all routines except \fBwinchnstr\fP may be macros. +SVr4 does not +document whether the result string is zero-terminated; it does not document +whether a length limit argument includes any trailing 0; and it does not +document the meaning of the return value. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +It is no +more specific than the SVr4 documentation on the trailing 0. +It does specify +that the successful return of the functions is \fBOK\fP. +.SH SEE ALSO +\fBcurses\fP(3), \fBcurs_inch\fP(3). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_in_wchstr\fP(3). diff --git a/static/openbsd/man3/curs_initscr.3 b/static/openbsd/man3/curs_initscr.3 new file mode 100644 index 00000000..23fca562 --- /dev/null +++ b/static/openbsd/man3/curs_initscr.3 @@ -0,0 +1,310 @@ +.\" $OpenBSD: curs_initscr.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_initscr.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.TH curs_initscr 3 2023-08-19 "ncurses 6.4" "Library calls" +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.na +.hy 0 +.SH NAME +\fBinitscr\fP, +\fBnewterm\fP, +\fBendwin\fP, +\fBisendwin\fP, +\fBset_term\fP, +\fBdelscreen\fP \- \fBcurses\fP screen initialization and manipulation routines +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBWINDOW *initscr(void);\fP +.br +\fBint endwin(void);\fP +.sp +\fBbool isendwin(void);\fP +.sp +\fBSCREEN *newterm(const char *\fItype\fB, FILE *\fIoutf\fB, FILE *\fIinf\fB);\fR +.br +\fBSCREEN *set_term(SCREEN *\fInew\fB);\fR +.br +\fBvoid delscreen(SCREEN* \fIsp\fB);\fR +.SH DESCRIPTION +.SS initscr +\fBinitscr\fP is normally the first \fBcurses\fP routine to call when +initializing a program. +A few special routines sometimes need to be called before it; +these are \fBslk_init\fP(3), \fBfilter\fP, \fBripoffline\fP, +\fBuse_env\fP. +For multiple-terminal applications, +\fBnewterm\fP may be called before \fBinitscr\fP. +.PP +The initscr code determines the terminal type and initializes all \fBcurses\fP +data structures. +\fBinitscr\fP also causes the first call to \fBrefresh\fP(3) +to clear the screen. +If errors occur, \fBinitscr\fP writes an appropriate error +message to standard error and exits; +otherwise, a pointer is returned to \fBstdscr\fP. +.SS newterm +A program that outputs to more than one terminal should use the \fBnewterm\fP +routine for each terminal instead of \fBinitscr\fP. +A program that needs to inspect capabilities, +so it can continue to run in a line-oriented mode if the +terminal cannot support a screen-oriented program, would also use +\fBnewterm\fP. +.PP +The routine \fBnewterm\fP should be called once for each terminal. +It returns a variable of type \fBSCREEN *\fP which should be saved +as a reference to that terminal. +\fBnewterm\fP's arguments are +.bP +the \fItype\fP of the terminal to be used in place of \fB$TERM\fP, +.bP +an output stream connected to the terminal, and +.bP +an input stream connected to the terminal +.PP +If the \fItype\fP parameter is \fBNULL\fP, \fB$TERM\fP will be used. +.PP +The file descriptor of the output stream is passed to \fBsetupterm\fP(3), +which returns a pointer to a \fBTERMINAL\fP structure. +\fBnewterm\fP's return value holds a pointer to the \fBTERMINAL\fP structure. +.SS endwin +The program must also call +\fBendwin\fP for each terminal being used before exiting from \fBcurses\fP. +If \fBnewterm\fP is called more than once for the same terminal, the first +terminal referred to must be the last one for which \fBendwin\fP is called. +.PP +A program should always call \fBendwin\fP before exiting or escaping from +\fBcurses\fP mode temporarily. +This routine +.bP +resets colors to correspond with the default color pair 0, +.bP +moves the cursor to the lower left-hand corner of the screen, +.bP +clears the remainder of the line so that it uses the default colors, +.bP +sets the cursor to normal visibility (see \fBcurs_set\fP(3)), +.bP +stops cursor-addressing mode using the \fIexit_ca_mode\fP terminal capability, +.bP +restores tty modes (see \fBreset_shell_mode\fP(3)). +.PP +Calling \fBrefresh\fP(3) or \fBdoupdate\fP(3) after a +temporary escape causes the program to resume visual mode. +.SS isendwin +The \fBisendwin\fP routine returns \fBTRUE\fP if \fBendwin\fP has been +called without any subsequent calls to \fBwrefresh\fP, +and \fBFALSE\fP otherwise. +.SS set_term +The \fBset_term\fP routine is used to switch between different terminals. +The screen reference \fInew\fP becomes the new current terminal. +The previous terminal is returned by the routine. +This is the only routine which manipulates \fBSCREEN\fP pointers; +all other routines affect only the current terminal. +.SS delscreen +The \fBdelscreen\fP routine frees storage associated with the +\fBSCREEN\fP data structure. +The \fBendwin\fP routine does not do +this, so \fBdelscreen\fP should be called after \fBendwin\fP if a +particular \fBSCREEN\fP is no longer needed. +.SH RETURN VALUE +\fBendwin\fP returns the integer \fBERR\fP upon failure and \fBOK\fP +upon successful completion. +.PP +Routines that return pointers always return \fBNULL\fP on error. +.PP +X/Open defines no error conditions. +In this implementation +.bP +\fBendwin\fP returns an error if the terminal was not initialized. +.bP +\fBnewterm\fP +returns an error if it cannot allocate the data structures for the screen, +or for the top-level windows within the screen, +i.e., +\fBcurscr\fP, \fBnewscr\fP, or \fBstdscr\fP. +.bP +\fBset_term\fP +returns no error. +.SH PORTABILITY +These functions were described in the XSI Curses standard, Issue 4. +As of 2015, the current document is X/Open Curses, Issue 7. +.SS Differences +X/Open specifies that portable applications must not +call \fBinitscr\fP more than once: +.bP +The portable way to use \fBinitscr\fP is once only, +using \fBrefresh\fP (see curs_refresh(3)) +to restore the screen after \fBendwin\fP. +.bP +This implementation allows using \fBinitscr\fP after \fBendwin\fP. +.PP +Old versions of curses, e.g., BSD 4.4, would return a null pointer +from \fBinitscr\fP when an error is detected, rather than exiting. +It is safe but redundant to check the return value of \fBinitscr\fP +in XSI Curses. +.PP +Calling \fBendwin\fP does not dispose of the memory allocated in \fBinitscr\fP +or \fBnewterm\fP. +Deleting a \fBSCREEN\fP provides a way to do this: +.bP +X/Open Curses does not say what happens to \fBWINDOW\fPs when \fBdelscreen\fP +\*(``frees storage associated with the \fBSCREEN\fP\*('' +nor does the SVr4 documentation help, +adding that it should be called after \fBendwin\fP if a \fBSCREEN\fP +is no longer needed. +.bP +However, \fBWINDOW\fPs are implicitly associated with a \fBSCREEN\fP. +so that it is reasonable to expect \fBdelscreen\fP to deal with these. +.bP +SVr4 curses deletes the standard \fBWINDOW\fP structures +\fBstdscr\fP and \fBcurscr\fP as well as a work area \fBnewscr\fP. +SVr4 curses ignores other windows. +.bP +Since version 4.0 (1996), ncurses has maintained a list of all windows +for each screen, +using that information to delete those windows when \fBdelscreen\fP is called. +.bP +NetBSD copied this feature of ncurses in 2001. +PDCurses follows the SVr4 model, +deleting only the standard \fBWINDOW\fP structures. +.SS High-level versus low-level +Different implementations may disagree regarding the level of some functions. +For example, \fBSCREEN\fP (returned by \fBnewterm\fP) and +\fBTERMINAL\fP (returned by \fBsetupterm\fP(3)) hold file descriptors for +the output stream. +If an application switches screens using \fBset_term\fR, +or switches terminals using \fBset_curterm\fP(3), +applications which use the output file descriptor can have different +behavior depending on which structure holds the corresponding descriptor. +.PP +For example +.bP +NetBSD's \fBbaudrate\fP(3) function uses the descriptor in \fBTERMINAL\fP. +\fBncurses\fP and SVr4 use the descriptor in \fBSCREEN\fP. +.bP +NetBSD and \fBncurses\fP use the descriptor +in \fBTERMINAL\fP +for terminal I/O modes, +e.g., +\fBdef_shell_mode\fP(3), +\fBdef_prog_mode\fP(3). +SVr4 curses uses the descriptor in \fBSCREEN\fP. +.SS Unset TERM Variable +If the TERM variable is missing or empty, \fBinitscr\fP uses the +value \*(``unknown\*('', +which normally corresponds to a terminal entry with the \fIgeneric\fP +(\fIgn\fP) capability. +Generic entries are detected by \fBsetupterm\fP(3) +and cannot be used for full-screen operation. +Other implementations may handle a missing/empty TERM variable differently. +.SS Signal Handlers +Quoting from X/Open Curses, section 3.1.1: +.RS 5 +.hy 0 +.PP +.I Curses implementations may provide for special handling of the +.I \fBSIGINT\fP, +.I \fBSIGQUIT\fP and +.I \fBSIGTSTP\fP signals +.I if their disposition is \fBSIG_DFL\fP at the time +\fBinitscr\fI is called \fR... +.PP +.I Any special handling for these signals may remain in effect for the +.I life of the process or until the process changes the disposition of +.I the signal. +.PP +.I None of the Curses functions are required to be safe +.I with respect to signals \fP... +.RE +.hy +.PP +This implementation establishes signal handlers during initialization, +e.g., \fBinitscr\fP or \fBnewterm\fP. +Applications which must handle these signals should set up the corresponding +handlers \fIafter\fP initializing the library: +.TP 5 +.B SIGINT +The handler \fIattempts\fP to cleanup the screen on exit. +Although it \fIusually\fP works as expected, there are limitations: +.RS 5 +.bP +Walking the \fBSCREEN\fP list is unsafe, since all list management +is done without any signal blocking. +.bP +On systems which have \fBREENTRANT\fP turned on, \fBset_term\fP uses +functions which could deadlock or misbehave in other ways. +.bP +\fBendwin\fP calls other functions, many of which use stdio or +other library functions which are clearly unsafe. +.RE +.TP 5 +.B SIGTERM +This uses the same handler as \fBSIGINT\fP, with the same limitations. +It is not mentioned in X/Open Curses, but is more suitable for this +purpose than \fBSIGQUIT\fP (which is used in debugging). +.TP 5 +.B SIGTSTP +This handles the \fIstop\fP signal, used in job control. +When resuming the process, this implementation discards pending +input with \fBflushinput\fP (see curs_util(3)), and repaints the screen +assuming that it has been completely altered. +It also updates the saved terminal modes with \fBdef_shell_mode\fP +(see \fBcurs_kernel\fP(3)). +.TP 5 +.B SIGWINCH +This handles the window-size changes which were ignored in +the standardization efforts. +The handler sets a (signal-safe) variable +which is later tested in \fBwgetch\fP (see curs_getch(3)). +If \fBkeypad\fP has been enabled for the corresponding window, +\fBwgetch\fP returns the key symbol \fBKEY_RESIZE\fP. +At the same time, \fBwgetch\fP calls \fBresizeterm\fP to adjust the +standard screen \fBstdscr\fP, +and update other data such as \fBLINES\fP and \fBCOLS\fP. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_kernel\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_slk\fP(3), +\fBterminfo\fP(3), +\fBcurs_util\fP(3), +\fBcurs_variables\fP(3). diff --git a/static/openbsd/man3/curs_inopts.3 b/static/openbsd/man3/curs_inopts.3 new file mode 100644 index 00000000..8f42fda3 --- /dev/null +++ b/static/openbsd/man3/curs_inopts.3 @@ -0,0 +1,415 @@ +'\" t +.\" $OpenBSD: curs_inopts.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_inopts.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.TH curs_inopts 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.na +.hy 0 +.SH NAME +\fBcbreak\fP, +\fBecho\fP, +\fBhalfdelay\fP, +\fBintrflush\fP, +\fBis_cbreak\fP, +\fBis_echo\fP, +\fBis_nl\fP, +\fBis_raw\fP, +\fBkeypad\fP, +\fBmeta\fP, +\fBnl\fP, +\fBnocbreak\fP, +\fBnodelay\fP, +\fBnoecho\fP, +\fBnonl\fP, +\fBnoqiflush\fP, +\fBnoraw\fP, +\fBnotimeout\fP, +\fBqiflush\fP, +\fBraw\fP, +\fBtimeout\fP, +\fBwtimeout\fP, +\fBtypeahead\fP \- \fBcurses\fP input options +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.PP +\fBint cbreak(void);\fP +.br +\fBint nocbreak(void);\fP +.sp +\fBint echo(void);\fP +.br +\fBint noecho(void);\fP +.sp +\fBint intrflush(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.br +\fBint keypad(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.br +\fBint meta(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.br +\fBint nodelay(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.br +\fBint notimeout(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.sp +\fBint nl(void);\fP +.br +\fBint nonl(void);\fP +.sp +\fBint raw(void);\fP +.br +\fBint noraw(void);\fP +.sp +\fBvoid qiflush(void);\fP +.br +\fBvoid noqiflush(void);\fP +.sp +\fBint halfdelay(int \fItenths\fB);\fR +.br +\fBvoid timeout(int \fIdelay\fB);\fR +.br +\fBvoid wtimeout(WINDOW *\fIwin\fB, int \fIdelay\fB);\fR +.sp +\fBint typeahead(int \fIfd\fB);\fR +.sp +/* extensions */ +.br +\fBint is_cbreak(void);\fP +.br +\fBint is_echo(void);\fP +.br +\fBint is_nl(void);\fP +.br +\fBint is_raw(void);\fP +.br +.SH DESCRIPTION +The \fBncurses\fP library provides several functions which let an application +change the way input from the terminal is handled. +Some are global, applying to all windows. +Others apply only to a specific window. +Window-specific settings are not automatically applied to new or derived +windows. +An application must apply these to each window, if the same behavior +is needed. +.\" +.SS cbreak/nocbreak +Normally, the tty driver buffers typed characters until a newline or carriage +return is typed. +The \fBcbreak\fP routine disables line buffering and +erase/kill character-processing (interrupt and flow control characters are +unaffected), making characters typed by the user immediately available to the +program. +The \fBnocbreak\fP routine returns the terminal to normal (cooked) +mode. +.PP +Initially the terminal may or may not be in \fBcbreak\fP mode, as the mode is +inherited; therefore, a program should call \fBcbreak\fP or \fBnocbreak\fP +explicitly. +Most interactive programs using \fBcurses\fP set the \fBcbreak\fP +mode. +Note that \fBcbreak\fP overrides \fBraw\fP. +[See \fBcurs_getch\fP(3) for a +discussion of how these routines interact with \fBecho\fP and \fBnoecho\fP.] +.\" +.SS echo/noecho +The \fBecho\fP and \fBnoecho\fP routines control whether characters typed by +the user are echoed by \fBgetch\fP(3) as they are typed. +Echoing by the tty +driver is always disabled, but initially \fBgetch\fP is in echo mode, so +characters typed are echoed. +Authors of most interactive programs prefer to do +their own echoing in a controlled area of the screen, or not to echo at all, so +they disable echoing by calling \fBnoecho\fP. +[See \fBcurs_getch\fP(3) for a +discussion of how these routines interact with \fBcbreak\fP and +\fBnocbreak\fP.] +.\" +.SS halfdelay +The \fBhalfdelay\fP routine is used for half-delay mode, which is similar to +\fBcbreak\fP mode in that characters typed by the user are immediately +available to the program. +However, after blocking for \fItenths\fP tenths of +seconds, \fBERR\fP is returned if nothing has been typed. +The value of \fItenths\fP +must be a number between 1 and 255. +Use \fBnocbreak\fP to leave half-delay +mode. +.\" +.SS intrflush +If the \fBintrflush\fP option is enabled (\fIbf\fP is \fBTRUE\fP), and an +interrupt key is pressed on the keyboard (interrupt, break, quit), all output in +the tty driver queue will be flushed, giving the effect of faster response to +the interrupt, but causing \fBcurses\fP to have the wrong idea of what is on +the screen. +Disabling the option (\fIbf\fP is \fBFALSE\fP) prevents the +flush. +The default for the option is inherited from the tty driver settings. +The window argument is ignored. +.\" +.SS keypad +The \fBkeypad\fP option enables the keypad of the user's terminal. +If +enabled (\fIbf\fP is \fBTRUE\fP), the user can press a function key +(such as an arrow key) and \fBwgetch\fP(3) returns a single value +representing the function key, as in \fBKEY_LEFT\fP. +If disabled +(\fIbf\fP is \fBFALSE\fP), \fBcurses\fP does not treat function keys +specially and the program has to interpret the escape sequences +itself. +If the keypad in the terminal can be turned on (made to +transmit) and off (made to work locally), turning on this option +causes the terminal keypad to be turned on when \fBwgetch\fP(3) is +called. +The default value for keypad is \fBFALSE\fP. +.\" +.SS meta +Initially, whether the terminal returns 7 or 8 significant bits on +input depends on the control mode of the tty driver [see \fBtermios\fP(3)]. +To force 8 bits to be returned, invoke \fBmeta\fP(\fIwin\fP, +\fBTRUE\fP); this is equivalent, under POSIX, to setting the CS8 flag +on the terminal. +To force 7 bits to be returned, invoke +\fBmeta\fP(\fIwin\fP, \fBFALSE\fP); this is equivalent, under POSIX, +to setting the CS7 flag on the terminal. +The window argument, +\fIwin\fP, is always ignored. +If the terminfo capabilities \fBsmm\fP +(meta_on) and \fBrmm\fP (meta_off) are defined for the terminal, +\fBsmm\fP is sent to the terminal when \fBmeta\fP(\fIwin\fP, +\fBTRUE\fP) is called and \fBrmm\fP is sent when \fBmeta\fP(\fIwin\fP, +\fBFALSE\fP) is called. +.\" +.SS nl/nonl +The \fBnl\fP and \fBnonl\fP routines control whether the underlying display +device translates the return key into newline on input. +.\" +.SS nodelay +The \fBnodelay\fP option causes \fBgetch\fP to be a non-blocking call. +If no input is ready, \fBgetch\fP returns \fBERR\fP. +If disabled +(\fIbf\fP is \fBFALSE\fP), \fBgetch\fP waits until a key is pressed. +.SS notimeout +When interpreting an escape sequence, \fBwgetch\fP(3) sets a timer +while waiting for the next character. +If \fBnotimeout(\fIwin\fR, +\fBTRUE\fP) is called, then \fBwgetch\fP does not set a timer. +The +purpose of the timeout is to differentiate between sequences received +from a function key and those typed by a user. +.\" +.SS raw/noraw +The \fBraw\fP and \fBnoraw\fP routines place the terminal into or out of raw +mode. +Raw mode is similar to \fBcbreak\fP mode, in that characters typed are +immediately passed through to the user program. +The differences are that in +raw mode, the interrupt, quit, suspend, and flow control characters are all +passed through uninterpreted, instead of generating a signal. +The behavior of +the BREAK key depends on other bits in the tty driver that are not set by +\fBcurses\fP. +.\" +.SS qiflush/noqiflush +When the \fBnoqiflush\fP routine is used, normal flush of input and +output queues associated with the \fBINTR\fP, \fBQUIT\fP and +\fBSUSP\fP characters will not be done [see \fBtermios\fP(3)]. +When +\fBqiflush\fP is called, the queues will be flushed when these control +characters are read. +You may want to call \fBnoqiflush\fP in a signal +handler if you want output to continue as though the interrupt +had not occurred, after the handler exits. +.\" +.SS timeout/wtimeout +The \fBtimeout\fP and \fBwtimeout\fP routines set blocking or +non-blocking read for a given window. +If \fIdelay\fP is negative, +blocking read is used (i.e., waits indefinitely for +input). +If \fIdelay\fP is zero, then non-blocking read is used +(i.e., read returns \fBERR\fP if no input is waiting). +If +\fIdelay\fP is positive, then read blocks for \fIdelay\fP +milliseconds, and returns \fBERR\fP if there is still no input. +Hence, these routines provide the same functionality as \fBnodelay\fP, +plus the additional capability of being able to block for only +\fIdelay\fP milliseconds (where \fIdelay\fP is positive). +.\" +.SS typeahead +The \fBcurses\fP library does \*(``line-breakout optimization\*('' +by looking for typeahead periodically while updating the screen. +If input is found, and it is coming from a tty, +the current update is postponed until +\fBrefresh\fP(3) or \fBdoupdate\fP is called again. +This allows faster response to commands typed in advance. +Normally, the input FILE +pointer passed to \fBnewterm\fP, or \fBstdin\fP in the case that +\fBinitscr\fP was used, will be used to do this typeahead checking. +The \fBtypeahead\fP routine specifies that the file descriptor +\fIfd\fP is to be used to check for typeahead instead. +If \fIfd\fP is +\-1, then no typeahead checking is done. +.\" +.SH RETURN VALUE +All routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +(SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('') +upon successful completion, +unless otherwise noted in the preceding routine descriptions. +.PP +X/Open does not define any error conditions. +In this implementation, +functions with a window parameter will return an error if it is null. +Any function will also return an error if the terminal was not initialized. +Also, +.RS 3 +.TP 5 +\fBhalfdelay\fP +returns an error +if its parameter is outside the range 1..255. +.RE +.SH EXTENSIONS +This implementation provides four functions which may be used to detect +if the corresponding flags were set or reset: +.PP +.TS +l l l. +\fBQuery\fP \fBSet\fP \fBReset\fP +_ +is_cbreak cbreak nocbreak +is_echo echo noecho +is_nl nl nonl +is_raw raw noraw +.TE +.PP +In each case, the function returns +.TP 5 +1 +if the flag is set, +.TP 5 +0 +if the flag is reset, or +.TP 5 +-1 +if the curses library was not initialized. +.PP +These routines are specific to ncurses. +They were not supported on Version 7, BSD or System V implementations. +It is recommended that any code depending on ncurses extensions +be conditioned using NCURSES_VERSION. +.SH PORTABILITY +Except as noted in the section on extensions, +these functions are described in the XSI Curses standard, Issue 4. +.PP +The ncurses library obeys the XPG4 standard and the historical practice of the +AT&T curses implementations, in that the echo bit is cleared when curses +initializes the terminal state. +BSD curses differed from this slightly; it +left the echo bit on at initialization, but the BSD \fBraw\fP call turned it +off as a side-effect. +For best portability, set \fBecho \fPor \fBnoecho\fP explicitly +just after initialization, even if your program remains in cooked mode. +.PP +The XSI Curses standard is ambiguous on the question of whether \fBraw\fP +should disable the CRLF translations controlled by \fBnl\fP and \fBnonl\fP. +BSD curses did turn off these translations; AT&T curses (at least as late as +SVr1) did not. +We chose to do so, on the theory that a programmer requesting +raw input wants a clean (ideally 8-bit clean) connection that the operating +system will not alter. +.PP +When \fBkeypad\fP is first enabled, +ncurses loads the key-definitions for the current terminal description. +If the terminal description includes extended string capabilities, +e.g., from using the \fB\-x\fP option of \fBtic\fP, +then ncurses also defines keys for the capabilities whose names +begin with \*(``k\*(''. +The corresponding keycodes are generated and (depending on previous +loads of terminal descriptions) may differ from one execution of a +program to the next. +The generated keycodes are recognized by the \fBkeyname\fP function +(which will then return a name beginning with \*(``k\*('' denoting the +terminfo capability name rather than \*(``K\*('', used for curses key-names). +On the other hand, an application can use \fBdefine_key\fP to establish +a specific keycode for a given string. +This makes it possible for an application to check for an extended +capability's presence with \fBtigetstr\fP, +and reassign the keycode to match its own needs. +.PP +Low-level applications can use \fBtigetstr\fP to obtain the definition +of any particular string capability. +Higher-level applications which use the curses \fBwgetch\fP +and similar functions to return keycodes rely upon the order in which +the strings are loaded. +If more than one key definition has the same string value, +then \fBwgetch\fP can return only one keycode. +Most curses implementations (including ncurses) +load key definitions in the order +defined by the array of string capability names. +The last key to be loaded determines the keycode which will be returned. +In ncurses, you may also have extended capabilities interpreted as +key definitions. +These are loaded after the predefined keys, +and if a capability's value is the same as a previously-loaded +key definition, +the later definition is the one used. +.SH NOTES +Note that +\fBecho\fP, +\fBnoecho\fP, +\fBhalfdelay\fP, +\fBintrflush\fP, +\fBmeta\fP, +\fBnl\fP, +\fBnonl\fP, +\fBnodelay\fP, +\fBnotimeout\fP, +\fBnoqiflush\fP, +\fBqiflush\fP, +\fBtimeout\fP, and +\fBwtimeout\fP may be macros. +.PP +The \fBnoraw\fP and \fBnocbreak\fP calls follow historical practice in that +they attempt to restore to normal (\*(``cooked\*('') mode +from raw and cbreak modes respectively. +Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver +control states that are hard to predict or understand; it is not recommended. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_getch\fP(3), +\fBcurs_initscr\fP(3), +\fBcurs_util\fP(3), +\fBdefine_key\fP(3), +\fBtermios\fP(3) diff --git a/static/openbsd/man3/curs_ins_wch.3 b/static/openbsd/man3/curs_ins_wch.3 new file mode 100644 index 00000000..e01c60a0 --- /dev/null +++ b/static/openbsd/man3/curs_ins_wch.3 @@ -0,0 +1,69 @@ +.\" $OpenBSD: curs_ins_wch.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\"*************************************************************************** +.\" Copyright 2019-2021,2022 Thomas E. Dickey * +.\" Copyright 2002-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_ins_wch.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_ins_wch 3 2022-02-12 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBins_wch\fP, +\fBmvins_wch\fP, +\fBmvwins_wch\fP, +\fBwins_wch\fP \- insert a complex character and rendition into a window +.SH SYNOPSIS +#include +.sp +\fBint ins_wch(const cchar_t *\fIwch\fB);\fR +.br +\fBint wins_wch(WINDOW *\fIwin\fB, const cchar_t *\fIwch\fB);\fR +.sp +\fBint mvins_wch(int \fIy\fB, int \fIx\fB, const cchar_t *\fIwch\fB);\fR +.br +\fBint mvwins_wch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const cchar_t *\fIwch\fB);\fR +.SH DESCRIPTION +These routines, insert the complex character \fIwch\fP with rendition +before the character under the cursor. +All characters to the right of the cursor are moved one space to the right, +with the possibility of the rightmost character on the line being lost. +The insertion operation does not change the cursor position. +.SH RETURN VALUE +If successful, these functions return \fBOK\fP. +If not, they return \fBERR\fP. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH ERRORS +No errors are defined. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_insch\fP(3). diff --git a/static/openbsd/man3/curs_ins_wstr.3 b/static/openbsd/man3/curs_ins_wstr.3 new file mode 100644 index 00000000..b5e819a8 --- /dev/null +++ b/static/openbsd/man3/curs_ins_wstr.3 @@ -0,0 +1,112 @@ +.\" $OpenBSD: curs_ins_wstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\"*************************************************************************** +.\" Copyright 2019-2021,2022 Thomas E. Dickey * +.\" Copyright 2002-2012,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_ins_wstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_ins_wstr 3 2022-02-12 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.na +.hy 0 +.SH NAME +\fBins_wstr\fP, +\fBins_nwstr\fP, +\fBwins_wstr\fP, +\fBwins_nwstr\fP, +\fBmvins_wstr\fP, +\fBmvins_nwstr\fP, +\fBmvwins_wstr\fP, +\fBmvwins_nwstr\fP \- insert a wide-character string into a curses window +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +.sp +\fBint ins_wstr(const wchar_t *\fIwstr);\fR +.br +\fBint ins_nwstr(const wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.br +\fBint wins_wstr(WINDOW *\fIwin\fB, const wchar_t *\fIwstr\fB);\fR +.br +\fBint wins_nwstr(WINDOW *\fIwin\fB, const wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.sp +\fBint mvins_wstr(int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB);\fR +.br +\fBint mvins_nwstr(int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.br +\fBint mvwins_wstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB);\fR +.br +\fBint mvwins_nwstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.fi +.SH DESCRIPTION +These routines insert a \fBwchar_t\fP character string +(as many characters as will fit on the line) +before the character under the cursor. +All characters to the right of the cursor are shifted right, +with the possibility of the rightmost characters on the line being lost. +No wrapping is performed. +The cursor position does not change +(after moving to \fIy\fP, \fIx\fP, if specified). +The four routines with \fIn\fP as the last argument +insert a leading substring of at most \fIn\fP \fBwchar_t\fP characters. +If \fIn\fP is less than 1, the entire string is inserted. +.PP +If a character in \fIwstr\fP is a tab, newline, carriage return or +backspace, the cursor is moved appropriately within the window. +A newline also does a \fBclrtoeol\fP before moving. +Tabs are considered to be at every eighth column. +If a character in \fIwstr\fP is another control character, +it is drawn in the \fB^\fIX\fR notation. +Calling \fBwin_wch\fP after adding a control character +(and moving to it, if necessary) +does not return the control character, +but instead returns a character in the ^-representation +of the control character. +.SH NOTES +Note that all but wins_nwstr may be macros. +.PP +If the first character in the string is a nonspacing character, these +functions will fail. +XSI does not define what will happen if a nonspacing character follows +a control character. +.SH RETURN VALUE +Upon successful completion, these functions return \fBOK\fP. +Otherwise, they return \fBERR\fP. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_insstr\fP(3), +\fBcurs_in_wch\fP(3), +\fBcurs_ins_wch\fP(3). diff --git a/static/openbsd/man3/curs_insch.3 b/static/openbsd/man3/curs_insch.3 new file mode 100644 index 00000000..f87bf983 --- /dev/null +++ b/static/openbsd/man3/curs_insch.3 @@ -0,0 +1,80 @@ +.\" $OpenBSD: curs_insch.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_insch.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.TH curs_insch 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBinsch\fP, +\fBwinsch\fP, +\fBmvinsch\fP, +\fBmvwinsch\fP \- insert a character before cursor in a \fBcurses\fP window +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint insch(chtype \fIch\fB);\fR +.br +\fBint winsch(WINDOW *\fIwin\fB, chtype \fIch\fB);\fR +.sp +\fBint mvinsch(int \fIy\fB, int \fIx\fB, chtype \fIch\fB);\fR +.br +\fBint mvwinsch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, chtype \fIch\fB);\fR +.SH DESCRIPTION +These routines insert the character \fIch\fP before the character under the +cursor. +All characters to the right of the cursor are moved one space to the +right, with the possibility of the rightmost character on the line being lost. +The insertion operation does not change the cursor position. +.SH RETURN VALUE +All routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +(SVr4 specifies only "an integer value other than \fBERR\fP") +upon successful completion, +unless otherwise noted in the preceding routine descriptions. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +These routines do not necessarily imply use of a hardware insert character +feature. +.PP +Note that \fBinsch\fP, \fBmvinsch\fP, and \fBmvwinsch\fP may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fP(3). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_ins_wch\fP(3). diff --git a/static/openbsd/man3/curs_insstr.3 b/static/openbsd/man3/curs_insstr.3 new file mode 100644 index 00000000..7edc43b8 --- /dev/null +++ b/static/openbsd/man3/curs_insstr.3 @@ -0,0 +1,106 @@ +.\" $OpenBSD: curs_insstr.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2019-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_insstr.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.TH curs_insstr 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBinsstr\fP, +\fBinsnstr\fP, +\fBwinsstr\fP, +\fBwinsnstr\fP, +\fBmvinsstr\fP, +\fBmvinsnstr\fP, +\fBmvwinsstr\fP, +\fBmvwinsnstr\fP \- insert string before cursor in a \fBcurses\fP window +.SH SYNOPSIS +\fB#include \fP +.br +\fBint insstr(const char *\fIstr\fB);\fR +.br +\fBint insnstr(const char *\fIstr\fB, int \fIn\fB);\fR +.br +\fBint winsstr(WINDOW *\fIwin\fB, const char *\fIstr\fB);\fR +.br +\fBint winsnstr(WINDOW *\fIwin\fB, const char *\fIstr\fB, int \fIn\fB);\fR +.sp +\fBint mvinsstr(int \fIy\fB, int \fIx\fB, const char *\fIstr\fB);\fR +.br +\fBint mvinsnstr(int \fIy\fB, int \fIx\fB, const char *\fIstr\fB, int \fIn\fB);\fR +.br +\fBint mvwinsstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const char *\fIstr\fB);\fR +.br +\fBint mvwinsnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const char *\fIstr\fB, int \fIn\fB);\fR +.SH DESCRIPTION +These routines insert a character string +(as many characters as will fit on the line) +before the character under the cursor. +All characters to the right of the cursor are shifted right +with the possibility of the rightmost characters on the line being lost. +The cursor position does not change +(after moving to \fIy\fP, \fIx\fP, if specified). +The functions with \fIn\fP as the last argument +insert a leading substring of at most \fIn\fP characters. +If \fIn\fP<=0, then the entire string is inserted. +.PP +Special characters are handled as in \fBaddch\fP. +.SH RETURN VALUE +All routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +(SVr4 specifies only "an integer value other than \fBERR\fP") +upon successful completion, +unless otherwise noted in the preceding routine descriptions. +.PP +X/Open defines no error conditions. +In this implementation, +if the window parameter is null or the str parameter is null, +an error is returned. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +Note that all but \fBwinsnstr\fP may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4, which adds +const qualifiers to the arguments. +.LP +The Single Unix Specification, Version 2 states that +\fBinsnstr\fP and \fBwinsnstr\fP perform wrapping. +This is probably an error, since it makes this group of functions inconsistent. +Also, no implementation of curses documents this inconsistency. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_util\fP(3), +\fBcurs_clear\fP(3), +\fBcurs_inch\fP(3). diff --git a/static/openbsd/man3/curs_instr.3 b/static/openbsd/man3/curs_instr.3 new file mode 100644 index 00000000..03caed84 --- /dev/null +++ b/static/openbsd/man3/curs_instr.3 @@ -0,0 +1,100 @@ +.\" $OpenBSD: curs_instr.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_instr.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.TH curs_instr 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBinstr\fP, +\fBinnstr\fP, +\fBwinstr\fP, +\fBwinnstr\fP, +\fBmvinstr\fP, +\fBmvinnstr\fP, +\fBmvwinstr\fP, +\fBmvwinnstr\fP \- get a string of characters from a \fBcurses\fP window +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint instr(char *\fIstr\fB);\fR +.br +\fBint innstr(char *\fIstr\fB, int \fIn\fB);\fR +.br +\fBint winstr(WINDOW *\fIwin\fB, char *\fIstr\fB);\fR +.br +\fBint winnstr(WINDOW *\fIwin\fB, char *\fIstr\fB, int \fIn\fB);\fR +.sp +\fBint mvinstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR +.br +\fBint mvinnstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR +.br +\fBint mvwinstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR +.br +\fBint mvwinnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR +.SH DESCRIPTION +These routines return a string of characters in \fIstr\fP, extracted starting +at the current cursor position in the named window. +Attributes are stripped from the characters. +The four +functions with \fIn\fP as the last argument return a leading substring at most +\fIn\fP characters long (exclusive of the trailing NUL). +.SH RETURN VALUE +All of the functions return \fBERR\fP upon failure, +or the number of characters actually read into the string. +.PP +X/Open Curses defines no error conditions. +In this implementation: +.bP +If the \fIwin\fP parameter is null, an error is returned, +.bP +If the \fIchstr\fP parameter is null, an error is returned, +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH NOTES +Note that all routines except \fBwinnstr\fP may be macros. +.SH PORTABILITY +SVr4 does not +document whether a length limit includes or excludes the trailing NUL. +.PP +The ncurses library extends the XSI description by allowing a negative +value for \fIn\fP. +In this case, the functions return the string ending at the right margin. +.SH SEE ALSO +\fBcurses\fP(3). diff --git a/static/openbsd/man3/curs_inwstr.3 b/static/openbsd/man3/curs_inwstr.3 new file mode 100644 index 00000000..966b239b --- /dev/null +++ b/static/openbsd/man3/curs_inwstr.3 @@ -0,0 +1,105 @@ +.\" $OpenBSD: curs_inwstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2002-2012,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_inwstr.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH curs_inwstr 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBinwstr\fP, +\fBinnwstr\fP, +\fBwinwstr\fP, +\fBwinnwstr\fP, +\fBmvinwstr\fP, +\fBmvinnwstr\fP, +\fBmvwinwstr\fP, +\fBmvwinnwstr\fP \- get a string of \fBwchar_t\fP characters from a curses window +.SH SYNOPSIS +.nf +\fB#include \fP +.sp +\fBint inwstr(\fBwchar_t *\fIwstr\fB);\fR +.br +\fBint innwstr(\fBwchar_t *\fIwstr\fB, int \fIn\fB);\fR +.br +\fBint winwstr(\fBWINDOW *\fIwin\fB, wchar_t *\fIwstr\fB);\fR +.br +\fBint winnwstr(\fBWINDOW *\fIwin\fB, wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.sp +\fBint mvinwstr(\fBint \fIy\fB, int \fIx\fB, wchar_t *\fIwstr\fB);\fR +.br +\fBint mvinnwstr(\fBint \fIy\fB, int \fIx\fB, wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.br +\fBint mvwinwstr(\fBWINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, wchar_t *\fIwstr\fB);\fR +.br +\fBint mvwinnwstr(\fBWINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, wchar_t *\fIwstr\fB, int \fIn\fB);\fR +.fi +.SH DESCRIPTION +These routines return a string of \fBwchar_t\fP wide characters in \fIwstr\fP, +extracted starting at the current cursor position in the named window. +.PP +The four functions with \fIn\fP as the last argument return +a leading substring at most \fIn\fP characters long +(exclusive of the trailing NUL). +Transfer stops at the end of the current line, or when \fIn\fP characters have +been stored at the location referenced by \fIwstr\fP. +.PP +If the size \fIn\fP is not large enough to store a complete complex character, +an error is generated. +.SH NOTES +All routines except +\fBwinnwstr\fP +may be macros. +.PP +Each cell in the window holds a complex character (i.e., base- +and combining-characters) together with attributes and color. +These functions store only the wide characters, +ignoring attributes and color. +Use \fBin_wchstr\fP to return the complex characters from a window. +.SH RETURN VALUE +All routines return +\fBERR\fP +upon failure. +Upon +successful completion, the *\fBinwstr\fP +routines return +\fBOK\fP, and the *\fBinnwstr\fP +routines return the +number of characters read into the string. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_instr\fP(3), +\fBcurs_in_wchstr\fP(3) diff --git a/static/openbsd/man3/curs_kernel.3 b/static/openbsd/man3/curs_kernel.3 new file mode 100644 index 00000000..07b470d2 --- /dev/null +++ b/static/openbsd/man3/curs_kernel.3 @@ -0,0 +1,225 @@ +.\" $OpenBSD: curs_kernel.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_kernel.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.TH curs_kernel 3 2023-08-19 "ncurses 6.4" "Library calls" +.na +.hy 0 +.SH NAME +\fBdef_prog_mode\fP, +\fBdef_shell_mode\fP, +\fBreset_prog_mode\fP, +\fBreset_shell_mode\fP, +\fBresetty\fP, +\fBsavetty\fP, +\fBgetsyx\fP, +\fBsetsyx\fP, +\fBripoffline\fP, +\fBcurs_set\fP, +\fBnapms\fP \- low-level \fBcurses\fP routines +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint def_prog_mode(void);\fP +.br +\fBint def_shell_mode(void);\fP +.sp +\fBint reset_prog_mode(void);\fP +.br +\fBint reset_shell_mode(void);\fP +.sp +\fBint resetty(void);\fP +.br +\fBint savetty(void);\fP +.sp +\fBvoid getsyx(int \fIy\fB, int \fIx\fB);\fR +.br +\fBvoid setsyx(int \fIy\fB, int \fIx\fB);\fR +.sp +\fBint ripoffline(int \fIline\fB, int (*\fIinit\fB)(WINDOW *, int));\fR +.br +\fBint curs_set(int \fIvisibility\fB);\fR +.br +\fBint napms(int \fIms\fB);\fR +.SH DESCRIPTION +The following routines give low-level access +to various \fBcurses\fP capabilities. +These routines typically are used inside library routines. +.SS def_prog_mode, def_shell_mode +The \fBdef_prog_mode\fP and \fBdef_shell_mode\fP routines save the +current terminal modes as the \*(``program\*('' +(in \fBcurses\fP) or \*(``shell\*('' +(not in \fBcurses\fP) state for use by the \fBreset_prog_mode\fP and +\fBreset_shell_mode\fP routines. +This is done automatically by \fBinitscr\fP. +There is one such save area for each screen context +allocated by \fBnewterm\fP. +.SS reset_prog_mode, reset_shell_mode +The \fBreset_prog_mode\fP and \fBreset_shell_mode\fP routines restore +the terminal to \*(``program\*('' (in \fBcurses\fP) or \*(``shell\*('' (out of +\fBcurses\fP) state. +These are done automatically by \fBendwin\fP(3) and, +after an \fBendwin\fP, by \fBdoupdate\fP, +so they normally are not called. +.SS resetty, savetty +The \fBresetty\fP and \fBsavetty\fP routines save and restore the +state of the terminal modes. +\fBsavetty\fP saves the current state in +a buffer and \fBresetty\fP restores the state to what it was at the +last call to \fBsavetty\fP. +.SS getsyx +The \fBgetsyx\fP routine returns the current coordinates +of the \fIvirtual screen\fP cursor in \fIy\fP and \fIx\fP. +If \fBleaveok\fP is currently \fBTRUE\fP, then +\fB\-1\fP,\fB\-1\fP is returned. +If lines have been removed from the top of the +screen, using \fBripoffline\fP, \fIy\fP and \fIx\fP include these lines; +therefore, \fIy\fP and \fIx\fP should be used only as arguments for +\fBsetsyx\fP. +.PP +Few applications will use this feature, +most use \fBgetyx\fP instead. +.SS setsyx +The \fBsetsyx\fP routine sets +the \fIvirtual screen\fP cursor to \fIy\fP, \fIx\fP. +If \fIy\fP and \fIx\fP are both \fB\-1\fP, then +\fBleaveok\fP is set. +The two routines \fBgetsyx\fP and \fBsetsyx\fP +are designed to be used by a library routine, which manipulates +\fBcurses\fP windows but does not want to change the current position +of the program's cursor. +The library routine would call \fBgetsyx\fP +at the beginning, do its manipulation of its own windows, do a +\fBwnoutrefresh\fP on its windows, call \fBsetsyx\fP, and then call +\fBdoupdate\fP. +.PP +Few applications will use this feature, +most use \fBwmove\fP instead. +.SS ripoffline +The \fBripoffline\fP routine provides access to the same facility that +\fBslk_init\fP [see \fBcurs_slk\fP(3)] uses to reduce the size of the +screen. +\fBripoffline\fP must be called before \fBinitscr\fP or +\fBnewterm\fP is called, to prepare these initial actions: +.bP +If \fIline\fP is positive, a line is removed from the top of \fBstdscr\fP. +.bP +if \fIline\fP is negative, a line is removed from the bottom. +.PP +When the resulting initialization is done inside \fBinitscr\fP, the +routine \fBinit\fP (supplied by the user) is called with two +arguments: +.bP +a window pointer to the one-line window that has been +allocated and +.bP +an integer with the number of columns in the window. +.PP +Inside this initialization routine, the integer variables \fBLINES\fP +and \fBCOLS\fP (defined in \fB\fP) are not guaranteed to be +accurate and \fBwrefresh\fP or \fBdoupdate\fP must not be called. +It is allowable to call \fBwnoutrefresh\fP during the initialization routine. +.PP +\fBripoffline\fP can be called up to five times before calling \fBinitscr\fP or +\fBnewterm\fP. +.SS curs_set +The \fBcurs_set\fP routine sets the cursor state to invisible, +normal, or very visible for \fBvisibility\fP equal to \fB0\fP, +\fB1\fP, or \fB2\fP respectively. +If the terminal supports the \fIvisibility\fP requested, +the previous \fIcursor\fP state is returned; +otherwise, \fBERR\fP is returned. +.SS napms +The \fBnapms\fP routine is used to sleep for \fIms\fP milliseconds. +.SH RETURN VALUE +Except for \fBcurs_set\fP, these routines always return \fBOK\fP. +.PP +\fBcurs_set\fP +returns the previous cursor state, or \fBERR\fP if the +requested \fIvisibility\fP is not supported. +.PP +X/Open defines no error conditions. +In this implementation +.TP 5 +.na +.hy 0 +\fBdef_prog_mode\fP, \fBdef_shell_mode\fP, \fBreset_prog_mode\fP, \fBreset_shell_mode\fP +.hy +.ad +return an error +if the terminal was not initialized, or +if the I/O call to obtain the terminal settings fails. +.TP 5 +\fBripoffline\fP +returns an error if the maximum number of ripped-off lines +exceeds the maximum (NRIPS = 5). +.SH NOTES +Note that \fBgetsyx\fP is a macro, so \fB&\fP is not necessary before +the variables \fIy\fP and \fIx\fP. +.PP +Older SVr4 man pages warn that the return value +of \fBcurs_set\fP \*(``is currently incorrect\*(''. +This implementation gets it right, but it may be unwise to count +on the correctness of the return value anywhere else. +.PP +Both ncurses and SVr4 will call \fBcurs_set\fP in \fBendwin\fP +if \fBcurs_set\fP +has been called to make the cursor other than normal, i.e., either +invisible or very visible. +There is no way for ncurses to determine the initial cursor state to +restore that. +.SH PORTABILITY +The \fIvirtual screen\fP functions \fBsetsyx\fP and \fBgetsyx\fP +are not described in the XSI Curses standard, Issue 4. +All other functions are as described in XSI Curses. +.PP +The SVr4 documentation describes \fBsetsyx\fP and \fBgetsyx\fP +as having return type int. +This is misleading, as they are macros with no documented semantics +for the return value. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_initscr\fP(3), +\fBcurs_outopts\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_scr_dump\fP(3), +\fBcurs_slk\fP(3), +\fBcurs_variables\fP(3). diff --git a/static/openbsd/man3/curs_legacy.3 b/static/openbsd/man3/curs_legacy.3 new file mode 100644 index 00000000..e00cdf6f --- /dev/null +++ b/static/openbsd/man3/curs_legacy.3 @@ -0,0 +1,109 @@ +.\" $OpenBSD: curs_legacy.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2019-2022,2023 Thomas E. Dickey * +.\" Copyright 2007-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_legacy.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.TH curs_legacy 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +curs_legacy \- get \fBcurses\fP cursor and window coordinates, attributes +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint getattrs(const WINDOW *\fIwin\fB);\fR +.sp +\fBint getbegx(const WINDOW *\fIwin\fB);\fR +.br +\fBint getbegy(const WINDOW *\fIwin\fB);\fR +.sp +\fBint getcurx(const WINDOW *\fIwin\fB);\fR +.br +\fBint getcury(const WINDOW *\fIwin\fB);\fR +.sp +\fBint getmaxx(const WINDOW *\fIwin\fB);\fR +.br +\fBint getmaxy(const WINDOW *\fIwin\fB);\fR +.sp +\fBint getparx(const WINDOW *\fIwin\fB);\fR +.br +\fBint getpary(const WINDOW *\fIwin\fB);\fR +.SH DESCRIPTION +These legacy functions are simpler to use than the X/Open Curses functions: +.bP +The \fBgetattrs\fP function returns the same attribute data as \fBwattr_get\fP. +.IP +However, \fBgetattrs\fP returns an integer (actually a \fBchtype\fP), +while \fBwattr_get\fP returns the current color pair in a separate parameter. +In the wide-character library configuration, +color pairs may not fit into a \fBchtype\fP, +so \fBwattr_get\fP is the only way to obtain the color information. +.IP +Because \fBgetattrs\fP returns the attributes in a single parameter, +it would not be possible for an application to distinguish that from +\fBERR\fP (a \fI-1\fP). +If the window parameter is null, \fBgetattrs\fP returns \fBA_NORMAL\fP (zero). +.bP +The \fBgetbegy\fP and \fBgetbegx\fP functions return the same +data as \fBgetbegyx\fP. +.bP +The \fBgetcury\fP and \fBgetcurx\fP functions return the same +data as \fBgetyx\fP. +.bP +The \fBgetmaxy\fP and \fBgetmaxx\fP functions return the same +data as \fBgetmaxyx\fP. +.bP +The \fBgetpary\fP and \fBgetparx\fP functions return the same +data as \fBgetparyx\fP. +.SH RETURN VALUE +Except as noted, +these functions return an integer, +or \fBERR\fP if the window parameter is null. +.SH NOTES +All of these interfaces are provided as macros and functions. +The macros are suppressed (and only the functions provided) +when \fBNCURSES_OPAQUE\fP is defined. +The standard forms such as \fBgetyx\fP must be implemented as macros, +and (in this implementation) are defined in terms of the functions +described here, +to avoid reliance on internal details of the WINDOW structure. +.SH PORTABILITY +These functions were supported on Version 7, BSD or System V implementations. +None of those implementations checked the window parameter. +.PP +The \fBgetattrs\fP function and macro are defined to return a (signed) integer +for compatibility with those implementations +although an unsigned type would have been more appropriate. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_getyx\fP(3), +\fBcurs_opaque\fP(3) diff --git a/static/openbsd/man3/curs_memleaks.3 b/static/openbsd/man3/curs_memleaks.3 new file mode 100644 index 00000000..697d69ce --- /dev/null +++ b/static/openbsd/man3/curs_memleaks.3 @@ -0,0 +1,127 @@ +.\"*************************************************************************** +.\" Copyright 2019-2021,2022 Thomas E. Dickey * +.\" Copyright 2008-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_memleaks.3,v 1.1 2023/10/17 09:52:08 nicm Exp $ +.TH curs_memleaks 3 2022-06-04 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBexit_curses\fP, +\fBexit_terminfo\fP \- \fBcurses\fP memory-leak checking +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.br +\fBvoid exit_curses(int \fIcode\fB);\fR +.sp +\fB#include \fP +.br +\fBvoid exit_terminfo(int \fIcode\fB);\fR +.sp +/* deprecated (intentionally not declared in curses.h or term.h) */ +.br +\fBvoid _nc_freeall(void);\fP +.br +\fBvoid _nc_free_and_exit(int \fIcode\fB);\fR +.br +\fBvoid _nc_free_tinfo(int \fIcode\fB);\fR +.SH DESCRIPTION +These functions are used to simplify analysis of memory leaks in the ncurses +library. +.PP +Any implementation of curses must not free the memory associated with +a screen, since (even after calling \fBendwin\fP(3)), it must be available +for use in the next call to \fBrefresh\fP(3). +There are also chunks of memory held for performance reasons. +That makes it hard to analyze curses applications for memory leaks. +When using the specially configured debugging version of the ncurses library, +applications can call functions which free those chunks of memory, +simplifying the process of memory-leak checking. +.PP +Some of the functions are named with a \*(``_nc_\*('' prefix +because they are not intended for use in the non-debugging library: +.TP 5 +\fB_nc_freeall\fP +This frees (almost) all of the memory allocated by ncurses. +.TP 5 +\fB_nc_free_and_exit\fP +This frees the memory allocated by ncurses (like \fB_nc_freeall\fP), +and exits the program. +It is preferred over \fB_nc_freeall\fP since some of that memory +may be required to keep the application running. +Simply exiting (with the given exit-code) is safer. +.TP 5 +\fB_nc_free_tinfo\fP +Use this function if only the low-level terminfo functions (and +corresponding library) are used. +Like \fB_nc_free_and_exit\fP, it exits the program after freeing memory. +.PP +The functions prefixed \*(``_nc\*('' are normally not available; +they must be configured into the library +at build time using the \fB\-\-disable-leaks\fP option. +That compiles-in code that frees memory that normally would not be freed. +.PP +The \fBexit_curses\fP and \fBexit_terminfo\fP functions +call \fB_nc_free_and_exit\fP and \fB_nc_free_tinfo\fP if +the library is configured to support memory-leak checking. +If the library is not configured to support memory-leak checking, +they simply call \fBexit\fP. +.SH RETURN VALUE +These functions do not return a value. +.SH PORTABILITY +These functions are not part of X/Open Curses; +nor do other implementations of curses provide a similar feature. +.PP +In any implementation of X/Open Curses, an application can free part +of the memory allocated by curses: +.bP +The portable part of \fBexit_curses\fP can be freed using \fBdelscreen\fP, +passing the \fBSCREEN*\fP pointer returned by \fBnewterm\fP. +.IP +In some implementations, there is a global variable \fBsp\fP +which could be used, e.g., if the screen were only initialized +using \fBinitscr\fP. +.bP +The portable part of \fBexit_terminfo\fP can be freed using \fBdel_curterm\fP. +.IP +In this case, there is a global variable \fBcur_term\fP which can be +used as parameter. +.SH SEE ALSO +\fBcurs_initscr\fP(3), +\fBterminfo\fP(3). +\fBcurses\fP(3). diff --git a/static/openbsd/man3/curs_mouse.3 b/static/openbsd/man3/curs_mouse.3 new file mode 100644 index 00000000..3aca5e92 --- /dev/null +++ b/static/openbsd/man3/curs_mouse.3 @@ -0,0 +1,418 @@ +'\" t +.\" $OpenBSD: curs_mouse.3,v 1.5 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_mouse.3,v 1.5 2023/10/17 09:52:08 nicm Exp $ +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de NS +.ie n .sp +.el .sp .5 +.ie n .in +4 +.el .in +2 +.nf +.ft CR \" Courier +.. +.de NE +.fi +.ft R +.ie n .in -4 +.el .in -2 +.. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.TH curs_mouse 3 2023-07-01 "ncurses 6.4" "Library calls" +.na +.hy 0 +.SH NAME +\fBhas_mouse\fP, +\fBgetmouse\fP, \fBungetmouse\fP, +\fBmousemask\fP, \fBwenclose\fP, +\fBmouse_trafo\fP, \fBwmouse_trafo\fP, +\fBmouseinterval\fP \- mouse interface through curses +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.PP +\fBtypedef unsigned long mmask_t;\fP +.PP +.nf +\fBtypedef struct {\fP +\fB short id; \fI/* ID to distinguish multiple devices */\fR +\fB int x, y, z; \fI/* event coordinates */\fR +\fB mmask_t bstate; \fI/* button state bits */\fR +\fB} MEVENT;\fP +.fi +.PP +\fBbool has_mouse(void);\fP +.sp +\fBint getmouse(MEVENT *\fIevent\fB);\fR +.br +\fBint ungetmouse(MEVENT *\fIevent\fB);\fR +.sp +\fBmmask_t mousemask(mmask_t \fInewmask\fB, mmask_t *\fIoldmask\fB);\fR +.sp +\fBbool wenclose(const WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR +.sp +\fBbool mouse_trafo(int* \fIpY\fB, int* \fIpX\fB, bool \fIto_screen\fB);\fR +.br +\fBbool wmouse_trafo(const WINDOW* \fIwin\fB,\fR + \fBint* \fIpY\fB, int* \fIpX\fB, bool \fIto_screen\fB);\fR +.sp +\fBint mouseinterval(int \fIerval\fB);\fR +.br +.SH DESCRIPTION +These functions provide an interface to mouse events from +\fBncurses\fP(3). +Mouse events are represented by \fBKEY_MOUSE\fP +pseudo-key values in the \fBwgetch\fP(3) input stream. +.SS mousemask +To make mouse events visible, use the \fBmousemask\fP function. +This sets the mouse events to be reported. +By default, no mouse events are reported. +.bP +The function returns an updated copy of \fInewmask\fP +to indicate which of the specified mouse events can be reported. +.IP +If the screen has not been initialized, +or if the terminal does not support mouse-events, +this function returns 0. +.bP +If \fIoldmask\fP is non-NULL, +this function fills the indicated location with the previous value of the +current screen's mouse event mask. +.PP +As a side effect, setting a zero mousemask may turn off the mouse pointer; +setting a nonzero mask may turn it on. +Whether this happens is device-dependent. +.SS Mouse events +Here are the mouse event type masks which may be defined: +.PP +.TS +l l +_ _ +l l. +\fBName\fP \fBDescription\fP +BUTTON1_PRESSED mouse button 1 down +BUTTON1_RELEASED mouse button 1 up +BUTTON1_CLICKED mouse button 1 clicked +BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked +BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked +_ +BUTTON2_PRESSED mouse button 2 down +BUTTON2_RELEASED mouse button 2 up +BUTTON2_CLICKED mouse button 2 clicked +BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked +BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked +_ +BUTTON3_PRESSED mouse button 3 down +BUTTON3_RELEASED mouse button 3 up +BUTTON3_CLICKED mouse button 3 clicked +BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked +BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked +_ +BUTTON4_PRESSED mouse button 4 down +BUTTON4_RELEASED mouse button 4 up +BUTTON4_CLICKED mouse button 4 clicked +BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked +BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked +_ +BUTTON5_PRESSED mouse button 5 down +BUTTON5_RELEASED mouse button 5 up +BUTTON5_CLICKED mouse button 5 clicked +BUTTON5_DOUBLE_CLICKED mouse button 5 double clicked +BUTTON5_TRIPLE_CLICKED mouse button 5 triple clicked +_ +BUTTON_SHIFT shift was down during button state change +BUTTON_CTRL control was down during button state change +BUTTON_ALT alt was down during button state change +ALL_MOUSE_EVENTS report all button state changes +REPORT_MOUSE_POSITION report mouse movement +_ +.TE +.SS getmouse +Once a class of mouse events has been made visible in a window, +calling the \fBwgetch\fP function on that window may return +\fBKEY_MOUSE\fP as an indicator that a mouse event has been queued. +To read the event data and pop the event off the queue, call +\fBgetmouse\fP. +This function will return \fBOK\fP if a mouse event +is actually visible in the given window, \fBERR\fP otherwise. +When \fBgetmouse\fP returns \fBOK\fP, the data deposited as y and +x in the event structure coordinates will be screen-relative character-cell +coordinates. +The returned state mask will have exactly one bit set to +indicate the event type. +The corresponding data in the queue is marked invalid. +A subsequent call to \fBgetmouse\fP will retrieve the next older +item from the queue. +.SS ungetmouse +The \fBungetmouse\fP function behaves analogously to \fBungetch\fP. +It pushes +a \fBKEY_MOUSE\fP event onto the input queue, and associates with that event +the given state data and screen-relative character-cell coordinates. +.SS wenclose +The \fBwenclose\fP function tests whether a given pair of screen-relative +character-cell coordinates is enclosed by a given window, returning \fBTRUE\fP +if it is and \fBFALSE\fP otherwise. +It is useful for determining what subset of +the screen windows enclose the location of a mouse event. +.SS wmouse_trafo +The \fBwmouse_trafo\fP function transforms a given pair of coordinates +from stdscr-relative coordinates +to coordinates relative to the given window or vice versa. +The resulting stdscr-relative coordinates are not always identical +to window-relative coordinates due to the mechanism to reserve lines on top +or bottom of the screen for other purposes +(see the \fBripoffline\fP and \fBslk_init\fP(3) calls, for example). +.bP +If the parameter \fIto_screen\fP is \fBTRUE\fP, the pointers +\fIpY, pX\fP must reference the coordinates of a location +inside the window \fIwin\fP. +They are converted to window-relative coordinates and returned +through the pointers. +If the conversion was successful, the function returns \fBTRUE\fP. +.bP +If one of the parameters was NULL or the location is +not inside the window, \fBFALSE\fP is returned. +.bP +If \fIto_screen\fP is +\fBFALSE\fP, the pointers \fIpY, pX\fP must reference window-relative +coordinates. +They are converted to stdscr-relative coordinates if the +window \fIwin\fP encloses this point. +In this case the function returns \fBTRUE\fP. +.bP +If one of the parameters is NULL or the point is not inside the +window, \fBFALSE\fP is returned. +The referenced coordinates +are only replaced by the converted coordinates if the transformation was +successful. +.SS mouse_trafo +The \fBmouse_trafo\fP function performs the same translation +as \fBwmouse_trafo\fP, +using stdscr for \fIwin\fP. +.SS mouseinterval +The \fBmouseinterval\fP function sets the maximum time (in thousands of a +second) that can elapse between press and release events for them to +be recognized as a click. +Use \fBmouseinterval(0)\fP to disable click resolution. +This function returns the previous interval value. +Use \fBmouseinterval(\-1)\fP to obtain the interval without altering it. +The default is one sixth of a second. +.SS has_mouse +The \fBhas_mouse\fP function returns \fBTRUE\fP if the mouse driver has been +successfully initialized. +.PP +Note that mouse events will be ignored when input is in cooked mode, and will +cause an error beep when cooked mode is being simulated in a window by a +function such as \fBgetstr\fP that expects a linefeed for input-loop +termination. +.SH RETURN VALUE +\fBgetmouse\fP and \fBungetmouse\fP +return the integer \fBERR\fP upon failure or \fBOK\fP +upon successful completion: +.RS 3 +.TP 5 +\fBgetmouse\fP +returns an error. +.bP +If no mouse driver was initialized, or +if the mask parameter is zero, +.bP +It returns an error if a mouse event was detected which did not match the +current \fImousemask\fP. +.bP +It also returns an error if no more events remain in the queue. +.TP 5 +\fBungetmouse\fP +returns an error if the FIFO is full. +.RE +.PP +\fBmousemask\fP +returns the mask of reportable events. +.PP +\fBmouseinterval\fP +returns the previous interval value, unless +the terminal was not initialized. +In that case, it returns the maximum interval value (166). +.PP +\fBwenclose\fP and \fBwmouse_trafo\fP +are boolean functions returning \fBTRUE\fP or \fBFALSE\fP depending +on their test result. +.SH PORTABILITY +These calls were designed for \fBncurses\fP(3), and are not found in SVr4 +curses, 4.4BSD curses, or any other previous version of curses. +.PP +SVr4 curses had support for the mouse in a variant of \fBxterm\fP(1). +It is mentioned in a few places, but with no supporting documentation: +.bP +the \*(``libcurses\*('' manual page lists functions for this feature +which are prototyped in \fBcurses.h\fP: +.NS +extern int mouse_set(long int); +extern int mouse_on(long int); +extern int mouse_off(long int); +extern int request_mouse_pos(void); +extern int map_button(unsigned long); +extern void wmouse_position(WINDOW *, int *, int *); +extern unsigned long getmouse(void), getbmap(void); +.NE +.bP +the \*(``terminfo\*('' manual page lists capabilities for the feature +.NS +buttons btns BT Number of buttons on the mouse +get_mouse getm Gm Curses should get button events +key_mouse kmous Km 0631, Mouse event has occurred +mouse_info minfo Mi Mouse status information +req_mouse_pos reqmp RQ Request mouse position report +.NE +.bP +the interface made assumptions (as does ncurses) about the escape sequences +sent to and received from the terminal. +.IP +For instance +the SVr4 curses library used the \fBget_mouse\fP capability to tell the +terminal which mouse button events it should send, +passing the mouse-button bit-mask to the terminal. +Also, it could ask the terminal +where the mouse was using the \fBreq_mouse_pos\fP capability. +.IP +Those features required a terminal which had been modified to work with curses. +They were not part of the X Consortium's xterm. +.PP +When developing the xterm mouse support for ncurses in September 1995, +Eric Raymond was uninterested in using the same interface due to its +lack of documentation. +Later, in 1998, Mark Hesseling provided support in +PDCurses 2.3 using the SVr4 interface. +PDCurses, however, does not use video terminals, +making it unnecessary to be concerned about compatibility with the +escape sequences. +.PP +The feature macro \fBNCURSES_MOUSE_VERSION\fP is provided so the preprocessor +can be used to test whether these features are present. +If the interface is changed, the value of \fBNCURSES_MOUSE_VERSION\fP will be +incremented. +These values for \fBNCURSES_MOUSE_VERSION\fP may be +specified when configuring ncurses: +.RS 3 +.TP 3 +1 +has definitions for reserved events. +The mask uses 28 bits. +.TP 3 +2 +adds definitions for button 5, +removes the definitions for reserved events. +The mask uses 29 bits. +.RE +.PP +The order of the \fBMEVENT\fP structure members is not guaranteed. +Additional fields may be added to the structure in the future. +.PP +Under \fBncurses\fP(3), these calls are implemented using either +xterm's built-in mouse-tracking API or +platform-specific drivers including +.RS 3 +.bP +Alessandro Rubini's gpm server +.bP +FreeBSD sysmouse +.bP +OS/2 EMX +.RE +.PP +If you are using an unsupported configuration, +mouse events will not be visible to +\fBncurses\fP(3) (and the \fBmousemask\fP function will always +return \fB0\fP). +.PP +If the terminfo entry contains a \fBXM\fP string, +this is used in the xterm mouse driver to control the +way the terminal is initialized for mouse operation. +The default, if \fBXM\fP is not found, +corresponds to private mode 1000 of xterm: +.PP +.RS 3 +\\E[?1000%?%p1%{1}%=%th%el%; +.RE +.PP +The mouse driver also recognizes a newer xterm private mode 1006, e.g., +.PP +.RS 3 +\\E[?1006;1000%?%p1%{1}%=%th%el%; +.RE +.PP +The \fIz\fP member in the event structure is not presently used. +It is intended +for use with touch screens (which may be pressure-sensitive) or with +3D-mice/trackballs/power gloves. +.PP +The \fBALL_MOUSE_EVENTS\fP class does not include \fBREPORT_MOUSE_POSITION\fP. +They are distinct. +For example, in xterm, +wheel/scrolling mice send position reports as a sequence of +presses of buttons 4 or 5 without matching button-releases. +.SH BUGS +Mouse events under xterm will not in fact be ignored during cooked mode, +if they have been enabled by \fBmousemask\fP. +Instead, the xterm mouse +report sequence will appear in the string read. +.PP +Mouse events under xterm will not be detected correctly in a window with +its keypad bit off, since they are interpreted as a variety of function key. +Your terminfo description should have \fBkmous\fP set to \*(``\\E[M\*('' +(the beginning of the response from xterm for mouse clicks). +Other values for \fBkmous\fP are permitted, +but under the same assumption, +i.e., it is the beginning of the response. +.PP +Because there are no standard terminal responses that would serve to identify +terminals which support the xterm mouse protocol, \fBncurses\fP assumes that +if \fBkmous\fP is defined in the terminal description, +or if the terminal description's primary name or aliases +contain the string \*(``xterm\*('', +then the terminal may send mouse events. +The \fBkmous\fP capability is checked first, +allowing the use of newer xterm mouse protocols +such as xterm's private mode 1006. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_inopts\fP(3), +\fBcurs_kernel\fP(3), +\fBcurs_slk\fP(3), +\fBcurs_variables\fP(3). diff --git a/static/openbsd/man3/curs_move.3 b/static/openbsd/man3/curs_move.3 new file mode 100644 index 00000000..2db6287d --- /dev/null +++ b/static/openbsd/man3/curs_move.3 @@ -0,0 +1,67 @@ +.\" $OpenBSD: curs_move.3,v 1.7 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_move.3,v 1.7 2023/10/17 09:52:08 nicm Exp $ +.TH curs_move 3 2023-07-01 "ncurses 6.4" "Library calls" +.na +.hy 0 +.SH NAME +\fBmove\fP, +\fBwmove\fP \- move \fBcurses\fP window cursor +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint move(int \fIy\fB, int \fIx\fB);\fR +.br +\fBint wmove(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR +.SH DESCRIPTION +These routines move the cursor associated with the window to line \fIy\fP and +column \fIx\fP. +This routine does not move the physical cursor of the terminal +until \fBrefresh\fP(3) is called. +The position specified is relative to the upper +left-hand corner of the window, which is (0,0). +.SH RETURN VALUE +These routines return \fBERR\fP upon failure and \fBOK\fP (SVr4 +specifies only "an integer value other than \fBERR\fP") upon successful +completion. +.PP +Specifically, they return an error +if the window pointer is null, or +if the position is outside the window. +.SH NOTES +Note that \fBmove\fP may be a macro. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fP(3), \fBcurs_refresh\fP(3) diff --git a/static/openbsd/man3/curs_opaque.3 b/static/openbsd/man3/curs_opaque.3 new file mode 100644 index 00000000..f6a6629f --- /dev/null +++ b/static/openbsd/man3/curs_opaque.3 @@ -0,0 +1,156 @@ +.\" $OpenBSD: curs_opaque.3,v 1.3 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2020-2022,2023 Thomas E. Dickey * +.\" Copyright 2007-2014,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_opaque.3,v 1.3 2023/10/17 09:52:08 nicm Exp $ +.TH curs_opaque 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.na +.hy 0 +.SH NAME +\fBis_cleared\fP, +\fBis_idlok\fP, +\fBis_idcok\fP, +\fBis_immedok\fP, +\fBis_keypad\fP, +\fBis_leaveok\fP, +\fBis_nodelay\fP, +\fBis_notimeout\fP, +\fBis_pad\fP, +\fBis_scrollok\fP, +\fBis_subwin\fP, +\fBis_syncok\fP, +\fBwgetdelay\fP, +\fBwgetparent\fP, +\fBwgetscrreg\fP \- \fBcurses\fP window properties +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBbool is_cleared(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_idcok(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_idlok(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_immedok(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_keypad(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_leaveok(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_nodelay(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_notimeout(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_pad(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_scrollok(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_subwin(const WINDOW *\fIwin\fB);\fR +.br +\fBbool is_syncok(const WINDOW *\fIwin\fB);\fR +.br +\fBWINDOW * wgetparent(const WINDOW *\fIwin\fB);\fR +.br +\fBint wgetdelay(const WINDOW *\fIwin\fB);\fR +.br +\fBint wgetscrreg(const WINDOW *\fIwin\fB, int *\fItop\fB, int *\fIbottom\fB);\fR +.SH DESCRIPTION +This implementation provides functions which return properties +set in the WINDOW structure, allowing it to be \*(``opaque\*('' if +the symbol \fBNCURSES_OPAQUE\fP is defined: +.TP 5 +\fBis_cleared\fP +returns the value set in \fBclearok\fP(3) +.TP 5 +\fBis_idcok\fP +returns the value set in \fBidcok\fP(3) +.TP 5 +\fBis_idlok\fP +returns the value set in \fBidlok\fP(3) +.TP 5 +\fBis_immedok\fP +returns the value set in \fBimmedok\fP(3) +.TP 5 +\fBis_keypad\fP +returns the value set in \fBkeypad\fP(3) +.TP 5 +\fBis_leaveok\fP +returns the value set in \fBleaveok\fP(3) +.TP 5 +\fBis_nodelay\fP +returns the value set in \fBnodelay\fP(3) +.TP 5 +\fBis_notimeout\fP +returns the value set in \fBnotimeout\fP(3) +.TP 5 +\fBis_pad\fP +returns \fBTRUE\fP if the window is a pad +i.e., created by \fBnewpad\fP(3) +.TP 5 +\fBis_scrollok\fP +returns the value set in \fBscrollok\fP(3) +.TP 5 +\fBis_subwin\fP +returns \fBTRUE\fP if the window is a subwindow, +i.e., created by \fBsubwin\fP(3) or \fBderwin\fP(3) +.TP 5 +\fBis_syncok\fP +returns the value set in \fBsyncok\fP(3) +.TP 5 +\fBwgetdelay\fP +returns the delay timeout as set in \fBwtimeout\fP(3). +.TP 5 +\fBwgetparent\fP +returns the parent WINDOW pointer for subwindows, +or NULL for windows having no parent. +.TP 5 +\fBwgetscrreg\fP +returns the top and bottom rows for the scrolling margin +as set in \fBwsetscrreg\fP. +.SH RETURN VALUE +These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted. +.SH NOTES +Both a macro and a function are provided for each name. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on Version 7, BSD or System V implementations. +It is recommended that any code depending on ncurses extensions +be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_inopts\fP(3), +\fBcurs_outopts\fP(3), +\fBcurs_window\fP(3) diff --git a/static/openbsd/man3/curs_outopts.3 b/static/openbsd/man3/curs_outopts.3 new file mode 100644 index 00000000..b4a056bc --- /dev/null +++ b/static/openbsd/man3/curs_outopts.3 @@ -0,0 +1,215 @@ +.\" $OpenBSD: curs_outopts.3,v 1.13 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_outopts.3,v 1.13 2023/10/17 09:52:08 nicm Exp $ +.TH curs_outopts 3 2023-07-01 "ncurses 6.4" "Library calls" +.na +.hy 0 +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBclearok\fP, +\fBidlok\fP, +\fBidcok\fP, +\fBimmedok\fP, +\fBleaveok\fP, +\fBsetscrreg\fP, +\fBwsetscrreg\fP, +\fBscrollok\fP \- \fBcurses\fP output options +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint clearok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.br +\fBint idlok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.br +\fBvoid idcok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.br +\fBvoid immedok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.br +\fBint leaveok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.br +\fBint scrollok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.sp +\fBint setscrreg(int \fItop\fB, int \fIbot\fB);\fR +.br +\fBint wsetscrreg(WINDOW *\fIwin\fB, int \fItop\fB, int \fIbot\fB);\fR +.SH DESCRIPTION +These routines set options that change the style of output within +\fBcurses\fP. +All options are initially \fBFALSE\fP, unless otherwise stated. +It is not necessary to turn these options off before calling \fBendwin\fP(3). +.SS clearok +If \fBclearok\fP is called with \fBTRUE\fP as argument, the next +call to \fBwrefresh\fP with this window will clear the screen completely and +redraw the entire screen from scratch. +This is useful when the contents of the +screen are uncertain, or in some cases for a more pleasing visual effect. +If +the \fIwin\fP argument to \fBclearok\fP is the global variable \fBcurscr\fP, +the next call to \fBwrefresh\fP with any window causes the screen to be cleared +and repainted from scratch. +.SS idlok +If \fBidlok\fP is called with \fBTRUE\fP as second argument, \fBcurses\fP +considers using the hardware insert/delete line feature of terminals so +equipped. +Calling \fBidlok\fP with \fBFALSE\fP as second argument disables use +of line insertion and deletion. +This option should be enabled only if the +application needs insert/delete line, for example, for a screen editor. +It is +disabled by default because insert/delete line tends to be visually annoying +when used in applications where it is not really needed. +If insert/delete line +cannot be used, \fBcurses\fP redraws the changed portions of all lines. +.SS idcok +If \fBidcok\fP is called with \fBFALSE\fP as second argument, \fBcurses\fP +no longer considers using the hardware insert/delete character feature of +terminals so equipped. +Use of character insert/delete is enabled by default. +Calling \fBidcok\fP with \fBTRUE\fP as second argument re-enables use +of character insertion and deletion. +.SS immedok +If \fBimmedok\fP is called with \fBTRUE as argument\fP, any change +in the window image, such as the ones caused by \fBwaddch, wclrtobot, wscrl\fP, +etc., automatically cause a call to \fBwrefresh\fP. +However, it may +degrade performance considerably, due to repeated calls to \fBwrefresh\fP. +It is disabled by default. +.SS leaveok +Normally, the hardware cursor is left at the location of the window cursor +being refreshed. +The \fBleaveok\fP option allows the cursor to be left +wherever the update happens to leave it. +It is useful for applications where +the cursor is not used, since it reduces the need for cursor motions. +.SS scrollok +The \fBscrollok\fP option controls what happens when the cursor of a window is +moved off the edge of the window or scrolling region, either as a result of a +newline action on the bottom line, or typing the last character of the last +line. +If disabled, (\fIbf\fP is \fBFALSE\fP), the cursor is left on the bottom +line. +If enabled, (\fIbf\fP is \fBTRUE\fP), the window is scrolled up one line +(Note that to get the physical scrolling effect on the terminal, it is +also necessary to call \fBidlok\fP). +.SS setscrreg/wsetscrreg +The \fBsetscrreg\fP and \fBwsetscrreg\fP routines allow the application +programmer to set a software scrolling region in a window. +The \fItop\fP and +\fIbot\fP parameters +are the line numbers of the top and bottom margin of the scrolling +region. +(Line 0 is the top line of the window.) If this option and +\fBscrollok\fP are enabled, an attempt to move off the bottom margin line +causes all lines in the scrolling region to scroll one line in the direction +of the first line. +Only the text of the window is scrolled. +(Note that this +has nothing to do with the use of a physical scrolling region capability in the +terminal, like that in the VT100. +If \fBidlok\fP is enabled and the terminal +has either a scrolling region or insert/delete line capability, they will +probably be used by the output routines.) +.SH RETURN VALUE +The functions \fBsetscrreg\fP and \fBwsetscrreg\fP return \fBOK\fP upon success +and \fBERR\fP upon failure. +All other routines that return an integer always +return \fBOK\fP. +.PP +X/Open Curses does not define any error conditions. +.PP +In this implementation, +.bP +those functions that have a window pointer +will return an error if the window pointer is null +.bP +\fBwsetscrreg\fP +returns an error if the scrolling region limits extend outside the window. +.PP +X/Open does not define any error conditions. +This implementation returns an error +if the window pointer is null. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.PP +From the outset, ncurses used \fBnl\fP/\fBnonl\fP to control the conversion +of newlines to carriage return/line-feed on output as well as input. +XSI Curses documents only the use of these functions for input. +This difference arose from converting the \fIpcurses\fP source +(which used \fBioctl\fP calls with the \fBsgttyb\fP structure) +to termios (i.e., the POSIX terminal interface). +In the former, both input and output were controlled via a single +option \fBCRMOD\fP, +while the latter separates these features. +Because that conversion interferes with output optimization, +\fBnl\fP/\fBnonl\fP were amended after ncurses 6.2 +to eliminate their effect on output. +.PP +Some historic curses implementations had, as an undocumented feature, the +ability to do the equivalent of \fBclearok(..., 1)\fP by saying +\fBtouchwin(stdscr)\fP or \fBclear(stdscr)\fP. +This will not work under ncurses. +.PP +Earlier System V curses implementations specified that with \fBscrollok\fP +enabled, any window modification triggering a scroll also forced a physical +refresh. +XSI Curses does not require this, and \fBncurses\fP avoids doing +it to perform better vertical-motion optimization at \fBwrefresh\fP +time. +.PP +The XSI Curses standard does not mention that the cursor should be +made invisible as a side-effect of \fBleaveok\fP. +SVr4 curses documentation does this, but the code does not. +Use \fBcurs_set\fP to make the cursor invisible. +.SH NOTES +Note that +\fBclearok\fP, +\fBleaveok\fP, +\fBscrollok\fP, +\fBidcok\fP, and +\fBsetscrreg\fP may be macros. +.PP +The \fBimmedok\fP routine is useful for windows that are used as terminal +emulators. +.SH SEE ALSO +.na +\fBcurses\fP(3), +\fBcurs_addch\fP(3), +\fBcurs_clear\fP(3), +\fBcurs_initscr\fP(3), +\fBcurs_scroll\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_variables\fP(3). diff --git a/static/openbsd/man3/curs_overlay.3 b/static/openbsd/man3/curs_overlay.3 new file mode 100644 index 00000000..62de0d4e --- /dev/null +++ b/static/openbsd/man3/curs_overlay.3 @@ -0,0 +1,89 @@ +.\" $OpenBSD: curs_overlay.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2020-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2013,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_overlay.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.TH curs_overlay 3 2023-07-01 "ncurses 6.4" "Library calls" +.na +.hy 0 +.SH NAME +\fBoverlay\fP, +\fBoverwrite\fP, +\fBcopywin\fP \- overlay and manipulate overlapped \fBcurses\fP windows +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint overlay(const WINDOW *\fIsrcwin\fB, WINDOW *\fIdstwin\fB);\fR +.br +\fBint overwrite(const WINDOW *\fIsrcwin\fB, WINDOW *\fIdstwin\fB);\fR +.br +\fBint copywin(const WINDOW *\fIsrcwin\fB, WINDOW *\fIdstwin\fB, int \fIsminrow\fB,\fR + \fBint \fIsmincol\fB, int \fIdminrow\fB, int \fIdmincol\fB, int \fIdmaxrow\fB,\fR + \fBint \fIdmaxcol\fB, int \fIoverlay\fB);\fR +.SH DESCRIPTION +.SS overlay, overwrite +The \fBoverlay\fP and \fBoverwrite\fP routines overlay \fIsrcwin\fP on +top of \fIdstwin\fP. +\fIscrwin\fP and \fIdstwin\fP are not required +to be the same size; only text where the two windows overlap is copied. +The difference is that \fBoverlay\fP is non-destructive +(blanks are not copied) whereas \fBoverwrite\fP is destructive. +.SS copywin +The \fBcopywin\fP routine provides a finer granularity of control over the +\fBoverlay\fP and \fBoverwrite\fP routines. +As in the \fBprefresh\fP routine, +a rectangle is specified in the destination window, (\fIdminrow\fP, +\fIdmincol\fP) and (\fIdmaxrow\fP, \fIdmaxcol\fP), and the upper-left-corner +coordinates of the source window, (\fIsminrow\fP, \fIsmincol\fP). +If the argument \fIoverlay\fP is \fBtrue\fP, +then copying is non-destructive, +as in \fBoverlay\fP. +.SH RETURN VALUE +Routines that return an integer return \fBERR\fP upon failure, and \fBOK\fP +(SVr4 only specifies "an integer value other than \fBERR\fP") upon successful +completion. +.PP +X/Open defines no error conditions. +In this implementation, +\fBcopywin\fP, +\fBoverlay\fP and \fBoverwrite\fP return an error +if either of the window pointers are null, or +if some part of the window would be placed off-screen. +.SH NOTES +Note that \fBoverlay\fP and \fBoverwrite\fP may be macros. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions (adding the const +qualifiers). +It further specifies their behavior in the presence of characters +with multibyte renditions (not yet supported in this implementation). +.SH SEE ALSO +\fBcurses\fP(3), \fBcurs_pad\fP(3), \fBcurs_refresh\fP(3) diff --git a/static/openbsd/man3/curs_pad.3 b/static/openbsd/man3/curs_pad.3 new file mode 100644 index 00000000..57937d73 --- /dev/null +++ b/static/openbsd/man3/curs_pad.3 @@ -0,0 +1,240 @@ +.\" $OpenBSD: curs_pad.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_pad.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.TH curs_pad 3 2023-07-01 "ncurses 6.4" "Library calls" +.na +.hy 0 +.SH NAME +\fBnewpad\fP, +\fBsubpad\fP, +\fBprefresh\fP, +\fBpnoutrefresh\fP, +\fBpechochar\fP, +\fBpecho_wchar\fP \- create and display \fBcurses\fP pads +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBWINDOW *newpad(int \fInlines\fB, int \fIncols\fB);\fR +.br +\fBWINDOW *subpad(WINDOW *\fIorig\fB, int \fInlines\fB, int \fIncols\fB,\fR + \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR +.br +\fBint prefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR + \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR +.br +\fBint pnoutrefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR + \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR +.br +\fBint pechochar(WINDOW *\fIpad\fB, chtype \fIch\fB);\fR +.br +\fBint pecho_wchar(WINDOW *\fIpad\fB, const cchar_t *\fIwch\fB);\fR +.SH DESCRIPTION +.SS newpad +The \fBnewpad\fP routine creates and returns a pointer to a new pad data +structure with the given number of lines, \fInlines\fP, and columns, +\fIncols\fP. +A pad is like a window, except that it is not restricted by the +screen size, and is not necessarily associated with a particular part of the +screen. +Pads can be used when a large window is needed, and only a part of the +window will be on the screen at one time. +Automatic refreshes of pads +(e.g., from scrolling or echoing of input) do not occur. +.PP +It is not +legal to call \fBwrefresh\fP with a \fIpad\fP as an argument; the routines +\fBprefresh\fP or \fBpnoutrefresh\fP should be called instead. +Note that these +routines require additional parameters to specify the part of the pad to be +displayed and the location on the screen to be used for the display. +.SS subpad +The \fBsubpad\fP routine creates and returns a pointer to a subwindow within a +pad with the given number of lines, \fInlines\fP, and columns, \fIncols\fP. +Unlike \fBsubwin\fP, which uses screen coordinates, the window is at position +(\fIbegin\fR_\fIx\fB,\fR \fIbegin\fR_\fIy\fR) on the pad. +The window is +made in the middle of the window \fIorig\fP, so that changes made to one window +affect both windows. +During the use of this routine, it will often be +necessary to call \fBtouchwin\fP or \fBtouchline\fP on \fIorig\fP before +calling \fBprefresh\fP. +.SS prefresh, pnoutrefresh +The \fBprefresh\fP and \fBpnoutrefresh\fP routines are analogous to +\fBwrefresh\fP and \fBwnoutrefresh\fP except that they relate to pads instead +of windows. +The additional parameters are needed to indicate what part of the +pad and screen are involved. +.bP +The \fIpminrow\fP and \fIpmincol\fP parameters specify the upper +left-hand corner of the rectangle to be displayed in the pad. +.bP +The \fIsminrow\fP, +\fIsmincol\fP, \fIsmaxrow\fP, and \fIsmaxcol\fP +parameters specify the edges of the +rectangle to be displayed on the screen. +.PP +The lower right-hand corner of the +rectangle to be displayed in the pad is calculated from the screen coordinates, +since the rectangles must be the same size. +Both rectangles must be entirely +contained within their respective structures. +Negative values of +\fIpminrow\fP, \fIpmincol\fP, \fIsminrow\fP, or \fIsmincol\fP are treated as if +they were zero. +.SS pechochar +The \fBpechochar\fP routine is functionally equivalent to a call to \fBaddch\fP +followed by a call to \fBrefresh\fP(3), +a call to \fBwaddch\fP followed by a call +to \fBwrefresh\fP, or a call to \fBwaddch\fP followed by a call to +\fBprefresh\fP. +The knowledge that only a single character is being output is +taken into consideration and, for non-control characters, a considerable +performance gain might be seen by using these routines instead of their +equivalents. +In the case of \fBpechochar\fP, the last location of the pad on +the screen is reused for the arguments to \fBprefresh\fP. +.SS pecho_wchar +The \fBpecho_wchar\fP function is the analogous wide-character +form of \fBpechochar\fP. +It outputs one character to a pad and immediately refreshes the pad. +It does this by a call to \fBwadd_wch\fP followed by a call to \fBprefresh\fP. +.SH RETURN VALUE +Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +(SVr4 only specifies "an integer value other than \fBERR\fP") upon successful +completion. +.PP +Routines that return pointers return \fBNULL\fP on error, and set \fBerrno\fP +to \fBENOMEM\fP. +.PP +X/Open does not define any error conditions. +In this implementation +.RS 3 +.TP 5 +\fBprefresh\fP and \fBpnoutrefresh\fP +return an error +if the window pointer is null, or +if the window is not really a pad or +if the area to refresh extends off-screen or +if the minimum coordinates are greater than the maximum. +.TP 5 +\fBpechochar\fP +returns an error +if the window is not really a pad, and the associated call +to \fBwechochar\fP returns an error. +.TP 5 +\fBpecho_wchar\fP +returns an error +if the window is not really a pad, and the associated call +to \fBwecho_wchar\fP returns an error. +.RE +.SH NOTES +Note that \fBpechochar\fP may be a macro. +.SH PORTABILITY +BSD curses has no \fIpad\fP feature. +.PP +SVr2 curses (1986) provided the \fBnewpad\fP and related functions, +documenting them in a single line each. +SVr3 (1987) provided more extensive documentation. +.PP +The documentation does not explain the term \fIpad\fP. +However, the Apollo \fIAegis\fP workstation operating system +supported a graphical \fIpad\fP feature: +.bP +These graphical pads could be much larger than the computer's display. +.bP +The read-only output from a command could be scrolled back to inspect, +and select text from the pad. +.PP +The two uses may be related. +.PP +The XSI Curses standard, Issue 4 describes these functions, +without significant change from the SVr3 documentation. +It describes no error conditions. +The behavior of \fBsubpad\fP if the parent window is not +a pad is undocumented, +and is not checked by the vendor Unix implementations: +.bP +SVr4 curses sets a flag in the \fBWINDOW\fP structure in \fBnewpad\fP +which tells if the window is a \fIpad\fP. +.IP +However, it uses this information only in +\fBwaddch\fP (to decide if it should call \fBwrefresh\fP) and +\fBwscrl\fP (to avoid scrolling a pad), +and does not check in \fBwrefresh\fP to ensure that the pad +is refreshed properly. +.bP +Solaris X/Open Curses checks if a window is a pad in \fBwnoutrefresh\fP, +returning \fBERR\fP in that case. +.IP +However, it only sets the flag for subwindows if the parent window is a pad. +Its \fBnewpad\fP function does not set this information. +Consequently, the check will never fail. +.IP +It makes no comparable check in \fBpnoutrefresh\fP, +though interestingly enough, a comment in the source code +states that the lack of a check was an MKS extension. +.bP +NetBSD 7 curses +sets a flag in the \fBWINDOW\fP structure for \fBnewpad\fP and \fBsubpad\fP, +using this to help with the distinction between \fBwnoutrefresh\fP +and \fBpnoutrefresh\fP. +.IP +It does not check for the case where a subwindow is created in +a pad using \fBsubwin\fP or \fBderwin\fP. +.IP +The \fBdupwin\fP function returns a regular window when duplicating a pad. +Likewise, \fBgetwin\fP always returns a window, even if the saved +data was from a pad. +.PP +This implementation +.bP +sets a flag in the \fBWINDOW\fP structure for \fBnewpad\fP and \fBsubpad\fP, +.bP +allows a \fBsubwin\fP or \fBderwin\fP call to succeed having a pad parent by +forcing the subwindow to be a pad, +.bP +checks in both \fBwnoutrefresh\fP and \fBpnoutrefresh\fP to ensure +that pads and windows are handled distinctly, and +.bP +ensures that \fBdupwin\fP and \fBgetwin\fP treat +pads versus windows consistently. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_touch\fP(3), +\fBcurs_addch\fP(3). diff --git a/static/openbsd/man3/curs_print.3 b/static/openbsd/man3/curs_print.3 new file mode 100644 index 00000000..9e14d140 --- /dev/null +++ b/static/openbsd/man3/curs_print.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: curs_print.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_print.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.TH curs_print 3 2022-02-12 "ncurses 6.4" "Library calls" +.SH NAME +\fBmcprint\fP \- ship binary data to printer +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint mcprint(char *\fIdata\fB, int \fIlen\fB);\fR +.SH DESCRIPTION +This function uses the \fBmc5p\fP or \fBmc4\fP and \fBmc5\fP capabilities, +if they are present, to ship given data to a printer attached to the terminal. +.PP +Note that the \fBmcprint\fP code has no way to do flow control with the printer +or to know how much buffering it has. +Your application is responsible for +keeping the rate of writes to the printer below its continuous throughput rate +(typically about half of its nominal cps rating). +Dot-matrix printers and +6-page-per-minute lasers can typically handle 80cps, so a good conservative +rule of thumb is to sleep for a second after shipping each 80-character line. +. +.SH RETURN VALUE +The \fBmcprint\fP function returns \fBERR\fP if the write operation aborted +for some reason. +In this case, \fBerrno\fP will contain either an error associated +with \fBwrite\fP(2) or one of the following: +.TP 5 +ENODEV +Capabilities for printer redirection do not exist. +.TP 5 +ENOMEM +Couldn't allocate sufficient memory to buffer the printer write. +.PP +When \fBmcprint\fP succeeds, it returns the number of characters actually +sent to the printer. +.SH PORTABILITY +The \fBmcprint\fP call was designed for \fBncurses\fP(3), and is not found +in SVr4 curses, 4.4BSD curses, or any other previous version of curses. +.SH BUGS +Padding in the \fBmc5p\fP, \fBmc4\fP and \fBmc5\fP capabilities will not be +interpreted. +.SH SEE ALSO +\fBcurses\fP(3) diff --git a/static/openbsd/man3/curs_printw.3 b/static/openbsd/man3/curs_printw.3 new file mode 100644 index 00000000..68ea5b8b --- /dev/null +++ b/static/openbsd/man3/curs_printw.3 @@ -0,0 +1,156 @@ +.\" $OpenBSD: curs_printw.3,v 1.12 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_printw.3,v 1.12 2023/10/17 09:52:08 nicm Exp $ +.TH curs_printw 3 2022-02-12 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBprintw\fP, +\fBwprintw\fP, +\fBmvprintw\fP, +\fBmvwprintw\fP, +\fBvwprintw\fP, \fBvw_printw\fP \- print formatted output in \fBcurses\fP windows +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint printw(const char *\fIfmt\fB, ...);\fR +.br +\fBint wprintw(WINDOW *\fIwin\fB, const char *\fIfmt\fB, ...);\fR +.br +\fBint mvprintw(int \fIy\fB, int \fIx\fB, const char *\fIfmt\fB, ...);\fR +.br +\fBint mvwprintw(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const char *\fIfmt\fB, ...);\fR +.br +\fBint vw_printw(WINDOW *\fIwin\fB, const char *\fIfmt\fB, va_list \fIvarglist\fB);\fR +.sp +/* obsolete */ +.br +\fBint vwprintw(WINDOW *\fIwin\fB, const char *\fIfmt\fB, va_list \fIvarglist\fB);\fR +.SH DESCRIPTION +The \fBprintw\fP, \fBwprintw\fP, \fBmvprintw\fP and \fBmvwprintw\fP +routines are analogous to \fBprintf\fP [see \fBprintf\fP(3)]. +In +effect, the string that would be output by \fBprintf\fP is output +instead as though \fBwaddstr\fP were used on the given window. +.PP +The \fBvwprintw\fP and \fBvw_printw\fP routines are analogous +to \fBvprintf\fP [see \fBprintf\fP(3)] +and perform a \fBwprintw\fP using a variable argument list. +The third argument is a \fBva_list\fP, a pointer to a +list of arguments, as defined in \fB\fP. +.SH RETURN VALUE +Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +(SVr4 only specifies "an integer value other than \fBERR\fP") upon successful +completion. +.PP +X/Open defines no error conditions. +In this implementation, +an error may be returned if it cannot allocate enough memory for the +buffer used to format the results. +It will return an error if the window pointer is null. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH HISTORY +While \fBprintw\fP was implemented in 4BSD, +it was unused until 4.2BSD (which used it in games). +That early version of curses was before the ANSI C standard. +It did not use , though that was available. +In 1991 (a couple of years after SVr4 was generally available, +and after the C standard was published), +other developers updated the library, +using internally in 4.4BSD curses. +Even with this improvement, +BSD curses did not use function prototypes (or even declare +functions) in the header until 1992. +.PP +SVr2 documented +\fBprintw\fP, +\fBwprintw\fP +tersely as \*(``printf on \fIstdscr\fP\*('' and +tersely as \*(``printf on \fIwin\fP\*('', respectively. +.PP +SVr3 added +\fBmvprintw\fP, and +\fBmvwprintw\fP, with a three-line summary saying that they were analogous +to \fBprintf\fP(3), +explaining that the string which would be output from \fBprintf\fP(3) would +instead be output using \fBwaddstr\fP on the given window. +SVr3 also added \fBvwprintw\fP, saying that the third parameter +is a \fBva_list\fP, defined in , +and referring the reader to the manual pages for \fIvarargs\fP and +\fBvprintf\fP for detailed descriptions. +.PP +SVr4 added no new variations of \fBprintw\fP, +but provided for using or to define the \fBva_list\fP +type. +.PP +X/Open Curses added \fBvw_printw\fP to replace \fBvwprintw\fP, +stating that its \fBva_list\fP definition requires . +.SH PORTABILITY +In this implementation, \fBvw_printw\fP and \fBvwprintw\fP are equivalent, +to support legacy applications. +However, the latter (\fBvwprintw\fP) is obsolete: +.bP +The XSI Curses standard, Issue 4 described these functions. +The function +\fBvwprintw\fP is marked TO BE WITHDRAWN, and is to be replaced by a function +\fBvw_printw\fP using the \fB\fP interface. +.bP +The Single Unix Specification, Version 2 states that +\fBvw_printw\fP is preferred to \fBvwprintw\fP since the latter requires +including \fB\fP, which +cannot be used in the same file as \fB\fP. +This implementation uses \fB\fP for both, +because that header is included in \fB. +.bP +X/Open Curses, Issue 5 (December 2007) marked \fBvwprintw\fP (along with +\fBvwscanw\fP and the termcap interface) as withdrawn. +.SH SEE ALSO +.na +\fBcurses\fP(3), +\fBcurs_addstr\fP(3), +\fBcurs_scanw\fP(3), +\fBtermcap\fP(3), +\fBprintf\fP(3), +\fBvprintf\fP(3). diff --git a/static/openbsd/man3/curs_refresh.3 b/static/openbsd/man3/curs_refresh.3 new file mode 100644 index 00000000..705fe32c --- /dev/null +++ b/static/openbsd/man3/curs_refresh.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: curs_refresh.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2016 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_refresh.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.TH curs_refresh 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBdoupdate\fP, +\fBredrawwin\fP, +\fBrefresh\fP, +\fBwnoutrefresh\fP, +\fBwredrawln\fP, +\fBwrefresh\fP \- refresh \fBcurses\fP windows and lines +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint refresh(void);\fP +.br +\fBint wrefresh(WINDOW *\fIwin\fB);\fR +.br +\fBint wnoutrefresh(WINDOW *\fIwin\fB);\fR +.br +\fBint doupdate(void);\fP +.sp +\fBint redrawwin(WINDOW *\fIwin\fB);\fR +.br +\fBint wredrawln(WINDOW *\fIwin\fB, int \fIbeg_line\fB, int \fInum_lines\fB);\fR +.SH DESCRIPTION +.SS refresh/wrefresh +The \fBrefresh\fP and \fBwrefresh\fP routines (or \fBwnoutrefresh\fP and +\fBdoupdate\fP) must be called to get actual output to the terminal, +as other routines merely manipulate data structures. +The routine \fBwrefresh\fP copies +the named window to the \fIphysical screen\fP, +taking into account what is already there to do optimizations. +The \fBrefresh\fP routine is the +same, using \fBstdscr\fP as the default window. +Unless \fBleaveok\fP(3) has been +enabled, the physical cursor of the terminal is left at the location of the +cursor for that window. +.SS wnoutrefresh/doupdate +The \fBwnoutrefresh\fP and \fBdoupdate\fP routines allow multiple updates with +more efficiency than \fBwrefresh\fP alone. +In addition to all the window +structures, \fBcurses\fP keeps two data structures representing the terminal +screen: +.bP +a \fIphysical screen\fP, +describing what is actually on the screen, and +.bP +a \fIvirtual screen\fP, +describing what the programmer wants to have on the screen. +.PP +The routine \fBwrefresh\fP works by +.bP +first calling \fBwnoutrefresh\fP, +which copies the named window to the \fIvirtual screen\fP, and +.bP +then calling \fBdoupdate\fP, which compares +the \fIvirtual screen\fP to the \fIphysical screen\fP +and does the actual update. +.PP +If the programmer wishes to output several windows at once, a series +of calls to \fBwrefresh\fP results in alternating calls to \fBwnoutrefresh\fP +and \fBdoupdate\fP, causing several bursts of output to the screen. +By first +calling \fBwnoutrefresh\fP for each window, it is then possible to call +\fBdoupdate\fP once, resulting in only one burst of output, with fewer total +characters transmitted and less CPU time used. +.PP +If the \fIwin\fP argument to +\fBwrefresh\fP is the \fIphysical screen\fP +(i.e., the global variable \fBcurscr\fP), +the screen is immediately cleared and repainted from scratch. +.PP +The phrase \*(``copies the named window +to the virtual screen\*('' above is ambiguous. +What actually happens is that all \fItouched\fP (changed) lines in the window +are copied to the virtual screen. +This affects programs that use overlapping +windows; it means that if two windows overlap, you can refresh them in either +order and the overlap region will be modified only when it is explicitly +changed. +(But see the section on \fBPORTABILITY\fP below for a warning about +exploiting this behavior.) +.SS wredrawln/redrawwin +The \fBwredrawln\fP routine indicates to \fBcurses\fP that some screen lines +are corrupted and should be thrown away before anything is written over them. +It touches the indicated lines (marking them changed). +The routine \fBredrawwin\fP touches the entire window. +.SH RETURN VALUE +Routines that return an integer return \fBERR\fP upon failure, and \fBOK\fP +(SVr4 only specifies "an integer value other than \fBERR\fP") upon successful +completion. +.PP +X/Open does not define any error conditions. +In this implementation +.RS 3 +.TP 5 +\fBwnoutrefresh\fP +returns an error +if the window pointer is null, or +if the window is really a pad. +.TP 5 +\fBwredrawln\fP +returns an error +if the associated call to \fBtouchln\fP returns an error. +.RE +.SH NOTES +Note that \fBrefresh\fP and \fBredrawwin\fP may be macros. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +.PP +Whether \fBwnoutrefresh\fP copies to the virtual screen the entire contents +of a window or just its changed portions has never been well-documented in +historic curses versions (including SVr4). +It might be unwise to rely on +either behavior in programs that might have to be linked with other curses +implementations. +Instead, you can do an explicit \fBtouchwin\fP before the +\fBwnoutrefresh\fP call to guarantee an entire-contents copy anywhere. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_outopts\fP(3) +\fBcurs_variables\fP(3). diff --git a/static/openbsd/man3/curs_scanw.3 b/static/openbsd/man3/curs_scanw.3 new file mode 100644 index 00000000..1cb238bb --- /dev/null +++ b/static/openbsd/man3/curs_scanw.3 @@ -0,0 +1,171 @@ +.\" $OpenBSD: curs_scanw.3,v 1.12 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_scanw.3,v 1.12 2023/10/17 09:52:08 nicm Exp $ +.TH curs_scanw 3 2022-02-12 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBscanw\fP, +\fBwscanw\fP, +\fBmvscanw\fP, +\fBmvwscanw\fP, +\fBvwscanw\fP, \fBvw_scanw\fP \- convert formatted input from a \fBcurses\fP window +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint scanw(const char *\fIfmt\fB, ...);\fR +.br +\fBint wscanw(WINDOW *\fIwin\fB, const char *\fIfmt\fB, ...);\fR +.br +\fBint mvscanw(int \fIy\fB, int \fIx\fB, const char *\fIfmt\fB, ...);\fR +.br +\fBint mvwscanw(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const char *\fIfmt\fB, ...);\fR +.sp +\fBint vw_scanw(WINDOW *\fIwin\fB, const char *\fIfmt\fB, va_list \fIvarglist\fB);\fR +.sp +/* obsolete */ +.br +\fBint vwscanw(WINDOW *\fIwin\fB, const char *\fIfmt\fB, va_list \fIvarglist\fB);\fR +.SH DESCRIPTION +The \fBscanw\fP, \fBwscanw\fP and \fBmvscanw\fP routines are analogous to +\fBscanf\fP [see \fBscanf\fP(3)]. +The effect of these routines is as though +\fBwgetstr\fP were called on the window, and the resulting line used as input +for \fBsscanf\fP(3). +Fields which do not map to a variable in the \fIfmt\fP +field are lost. +.PP +The \fBvwscanw\fP and \fBvw_scanw\fP routines are analogous to \fBvscanf\fP(3). +They perform a \fBwscanw\fP using a variable argument list. +The third argument is a \fBva_list\fP, +a pointer to a list of arguments, as defined in \fB\fP. +.SH RETURN VALUE +\fBvwscanw\fP returns \fBERR\fP on failure and an integer equal to the +number of fields scanned on success. +.PP +Applications may use the return value from the \fBscanw\fP, \fBwscanw\fP, +\fBmvscanw\fP and \fBmvwscanw\fP routines to determine the number of fields +which were mapped in the call. +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.SH HISTORY +While \fBscanw\fP was implemented in 4BSD, +none of the BSD releases used it until 4.4BSD (in a game). +That early version of curses was before the ANSI C standard. +It did not use , though that was available. +In 1991 (a couple of years after SVr4 was generally available, +and after the C standard was published), +other developers updated the library, +using internally in 4.4BSD curses. +Even with this improvement, +BSD curses did not use function prototypes (or even declare +functions) in the header until 1992. +.PP +SVr2 documented +\fBscanw\fP, +\fBwscanw\fP +tersely as \*(``scanf through \fIstdscr\fP\*('' and +tersely as \*(``scanf through \fIwin\fP\*('', respectively. +.PP +SVr3 added +\fBmvscanw\fP, and +\fBmvwscanw\fP, with a three-line summary saying that they were analogous +to \fBscanf\fP(3), +explaining that the string which would be output from \fBscanf\fP(3) would +instead be output using \fBwaddstr\fP on the given window. +SVr3 also added \fBvwscanw\fP, saying that the third parameter +is a \fBva_list\fP, defined in , +and referring the reader to the manual pages for \fIvarargs\fP and +\fBvprintf\fP for detailed descriptions. +(Because the SVr3 documentation does not mention \fBvscanf\fP, +that reference to \fBvprintf\fP may not be an error). +.PP +SVr4 added no new variations of \fBscanw\fP, +but provided for using or to define the \fBva_list\fP +type. +.PP +X/Open Curses added \fBvw_scanw\fP to replace \fBvwscanw\fP, +stating that its \fBva_list\fP definition requires . +.SH PORTABILITY +In this implementation, \fBvw_scanw\fP and \fBvwscanw\fP are equivalent, +to support legacy applications. +However, the latter (\fBvwscanw\fP) is obsolete: +.bP +The XSI Curses standard, Issue 4 described these functions, +noting that the function +\fBvwscanw\fP is marked TO BE WITHDRAWN, and is to be replaced by a function +\fBvw_scanw\fP using the \fB\fP interface. +.bP +The Single Unix Specification, Version 2 states that +\fBvw_scanw\fP is preferred to \fBvwscanw\fP since the latter requires +including \fB\fP, which +cannot be used in the same file as \fB\fP. +This implementation uses \fB\fP for both, because that header +is included in \fB. +.bP +X/Open Curses, Issue 5 (December 2007) marked \fBvwscanw\fP (along with +\fBvwprintw\fP and the termcap interface) as withdrawn. +.LP +Both XSI and The Single Unix Specification, Version 2 state that these +functions return \fBERR\fP or \fBOK\fP. +.bP +Since the underlying \fBscanf\fP(3) can return the number of items scanned, +and the SVr4 code was documented to use this feature, +this is probably an editing error which was introduced in XSI, +rather than being done intentionally. +.bP +This implementation returns the number of items scanned, +for compatibility with SVr4 curses. +As of 2018, NetBSD curses also returns the number of items scanned. +Both ncurses and NetBSD curses call \fBvsscanf\fP to scan the string, +which returns \fBEOF\fP on error. +.bP +Portable applications should only test if the return value is \fBERR\fP, +since the \fBOK\fP value (zero) is likely to be misleading. +.IP +One possible way to get useful results would be to use a "%n" conversion +at the end of the format string to ensure that something was processed. +.SH SEE ALSO +.na +\fBcurses\fP(3), +\fBcurs_getstr\fP(3), +\fBcurs_printw\fP(3), +\fBtermcap\fP(3), +\fBscanf\fP(3). diff --git a/static/openbsd/man3/curs_scr_dump.3 b/static/openbsd/man3/curs_scr_dump.3 new file mode 100644 index 00000000..e91fda25 --- /dev/null +++ b/static/openbsd/man3/curs_scr_dump.3 @@ -0,0 +1,117 @@ +.\" $OpenBSD: curs_scr_dump.3,v 1.4 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_scr_dump.3,v 1.4 2023/10/17 09:52:08 nicm Exp $ +.TH curs_scr_dump 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBscr_dump\fP, +\fBscr_restore\fP, +\fBscr_init\fP, +\fBscr_set\fP \- read (write) a \fBcurses\fP screen from (to) a file +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint scr_dump(const char *\fIfilename\fB);\fR +.br +\fBint scr_restore(const char *\fIfilename\fB);\fR +.br +\fBint scr_init(const char *\fIfilename\fB);\fR +.br +\fBint scr_set(const char *\fIfilename\fB);\fR +.SH DESCRIPTION +.SS scr_dump +The \fBscr_dump\fP routine dumps the current contents +of the \fIvirtual screen\fP +to the file \fIfilename\fP. +.SS scr_restore +The \fBscr_restore\fP routine sets the \fIvirtual screen\fP to the contents +of \fIfilename\fP, which must have been written using \fBscr_dump\fP. +The next call to \fBdoupdate\fP restores +the \fIphysical screen\fP to the way it looked in the dump file. +.SS scr_init +The \fBscr_init\fP routine reads in the contents of \fIfilename\fP and uses +them to initialize the \fBcurses\fP data structures about what the terminal +currently has on its screen. +If the data is determined to be valid, +\fBcurses\fP bases its next update of the screen on this information rather +than clearing the screen and starting from scratch. +\fBscr_init\fP is used +after \fBinitscr\fP(3) or a \fBsystem\fP(3) call to share +the screen with another process which has done a \fBscr_dump\fP after its +\fBendwin\fP(3) call. +The data is declared invalid +.bP +if the terminfo capabilities \fBrmcup\fP and \fBnrrmc\fP exist, also +.bP +if the terminal has been written to since the preceding \fBscr_dump\fP call. +.SS scr_set +The \fBscr_set\fP routine is a combination of \fBscr_restore\fP and +\fBscr_init\fP. It tells the program that the information in \fIfilename\fP is +what is currently on the screen, and also what the program wants on the screen. +This can be thought of as a screen inheritance function. +.PP +To read (write) a window from (to) a file, use the \fBgetwin\fP and +\fBputwin\fP routines [see \fBcurs_util\fP(3)]. +.SH RETURN VALUE +All routines return the integer \fBERR\fP upon failure and \fBOK\fP +upon success. +.PP +X/Open defines no error conditions. +In this implementation, +each will return an error if the file cannot be opened. +.SH NOTES +Note that \fBscr_init\fP, \fBscr_set\fP, and \fBscr_restore\fP may be macros. +.SH PORTABILITY +The XSI Curses standard, Issue 4, describes these functions (adding the const +qualifiers). +.PP +The SVr4 docs merely say under \fBscr_init\fP that the dump data is also +considered invalid "if the time-stamp of the tty is old" but do not define +\*(``old\*(''. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_initscr\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_util\fP(3), +\fBscr_dump\fP(5), +\fBsystem\fP(3) diff --git a/static/openbsd/man3/curs_scroll.3 b/static/openbsd/man3/curs_scroll.3 new file mode 100644 index 00000000..84a818ec --- /dev/null +++ b/static/openbsd/man3/curs_scroll.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: curs_scroll.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2006,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_scroll.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.TH curs_scroll 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.na +.hy 0 +.SH NAME +\fBscroll\fP, +\fBscrl\fP, +\fBwscrl\fP \- scroll a \fBcurses\fP window +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint scroll(WINDOW *\fIwin\fB);\fR +.sp +\fBint scrl(int \fIn\fB);\fR +.br +\fBint wscrl(WINDOW *\fIwin\fB, int \fIn\fB);\fR +.SH DESCRIPTION +The \fBscroll\fP routine scrolls the window up one line. +This involves moving +the lines in the window data structure. +As an optimization, if the scrolling +region of the window is the entire screen, +the \fIphysical screen\fP may be scrolled at the same time. +.PP +For positive \fIn\fP, the \fBscrl\fP and \fBwscrl\fP routines scroll the +window up \fIn\fP lines (line \fIi\fP+\fIn\fP becomes \fIi\fP); otherwise +scroll the window down \fIn\fP lines. +This involves moving the lines in the +window character image structure. +The current cursor position is not changed. +.PP +For these functions to work, scrolling must be enabled via \fBscrollok\fP(3). +.SH RETURN VALUE +These routines return \fBERR\fP upon failure, and \fBOK\fP (SVr4 only specifies +"an integer value other than \fBERR\fP") upon successful completion. +.PP +X/Open defines no error conditions. +.PP +This implementation returns an error +if the window pointer is null, or +if scrolling is not enabled in the window, e.g., with \fBscrollok\fP(3). +.SH NOTES +Note that \fBscrl\fP and \fBscroll\fP may be macros. +.PP +The SVr4 documentation says that the optimization of physically scrolling +immediately if the scroll region is the entire screen \*(``is\*('' performed, +not \*(``may be\*('' performed. +This implementation deliberately does not guarantee +that this will occur, to leave open the possibility of smarter +optimization of multiple scroll actions on the next update. +.PP +Neither the SVr4 nor the XSI documentation specify whether the current +attribute or +current color-pair of blanks generated by the scroll function is zeroed. +Under this implementation it is. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +.SH SEE ALSO +\fBcurses\fP(3), \fBcurs_outopts\fP(3) diff --git a/static/openbsd/man3/curs_slk.3 b/static/openbsd/man3/curs_slk.3 new file mode 100644 index 00000000..a5017383 --- /dev/null +++ b/static/openbsd/man3/curs_slk.3 @@ -0,0 +1,354 @@ +.\" $OpenBSD: curs_slk.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_slk.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.TH curs_slk 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBslk_init\fP, +\fBslk_set\fP, +\fBslk_wset\fP, +\fBslk_refresh\fP, +\fBslk_noutrefresh\fP, +\fBslk_label\fP, +\fBslk_clear\fP, +\fBslk_restore\fP, +\fBslk_touch\fP, +\fBslk_attron\fP, +\fBslk_attrset\fP, +\fBslk_attroff\fP, +\fBslk_attr_on\fP, +\fBslk_attr_set\fP, +\fBslk_attr_off\fP, +\fBslk_attr\fP, +\fBslk_color\fP, +\fBextended_slk_color\fP \- \fBcurses\fP soft label routines +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint slk_init(int \fIfmt\fB);\fR +.sp +\fBint slk_set(int \fIlabnum\fB, const char *\fIlabel\fB, int \fIfmt\fB);\fR +.br +\fBint slk_wset(int \fIlabnum\fB, const wchar_t *\fIlabel\fB, int \fIfmt\fB);\fR +.sp +\fBchar *slk_label(int \fIlabnum\fB);\fR +.sp +\fBint slk_refresh(void);\fP +.br +\fBint slk_noutrefresh(void);\fP +.br +\fBint slk_clear(void);\fP +.br +\fBint slk_restore(void);\fP +.br +\fBint slk_touch(void);\fP +.sp +\fBint slk_attron(const chtype \fIattrs\fB);\fR +.br +\fBint slk_attroff(const chtype \fIattrs\fB);\fR +.br +\fBint slk_attrset(const chtype \fIattrs\fB);\fR +.br +\fBint slk_attr_on(attr_t \fIattrs\fB, void* \fIopts\fB);\fR +.br +\fBint slk_attr_off(const attr_t \fIattrs\fB, void * \fIopts\fB);\fR +.br +\fBint slk_attr_set(const attr_t \fIattrs\fB, short \fIpair\fB, void* \fIopts\fB);\fR +.br +/* extension */ +.br +\fBattr_t slk_attr(void);\fP +.sp +\fBint slk_color(short \fIpair\fB);\fR +.br +/* extension */ +.br +\fBint extended_slk_color(int \fIpair\fB);\fR +.SH DESCRIPTION +The slk* functions manipulate the set of soft function-key labels that exist on +many terminals. +For those terminals that do not have soft labels, +\fBcurses\fP takes over the bottom line of \fBstdscr\fP, reducing the size of +\fBstdscr\fP and the variable \fBLINES\fP. +\fBcurses\fP standardizes on eight +labels of up to eight characters each. +In addition to this, the ncurses +implementation supports a mode where it simulates 12 labels of up to five +characters each. +This is useful for PC-like enduser devices. +ncurses simulates this mode by taking over up to two lines at +the bottom of the screen; +it does not try to use any hardware support for this +mode. +.SS Initialization +The \fBslk_init\fP routine must be called before \fBinitscr\fP or \fBnewterm\fP +is called. +If \fBinitscr\fP eventually uses a line from \fBstdscr\fP to +emulate the soft labels, +then \fIfmt\fP determines how the labels are arranged on the screen: +.RS 3 +.TP 3 +.B 0 +indicates a 3\-2\-3 arrangement of +the labels. +.TP 3 +.B 1 +indicates a 4\-4 arrangement +.TP 3 +.B 2 +indicates the PC-like 4\-4\-4 mode. +.TP 3 +.B 3 +is again the PC-like 4\-4\-4 mode, +but in addition an index line is generated, helping the user to +identify the key numbers easily. +.RE +.SS Labels +The \fBslk_set\fP routine +(and the \fBslk_wset\fP routine for the wide-character library) +has three parameters: +.RS 3 +.TP 5 +.I labnum +is the label number, from \fB1\fP to \fB8\fP +(12 if \fIfmt\fP in \fBslk_init\fP is \fB2\fP or \fB3\fP); +.TP +.I label +is be the string to put on the label, +up to eight +(five if \fIfmt\fP in \fBslk_init\fP is \fB2\fP or \fB3\fP) +characters in length. +A null string or a null pointer sets up a blank label. +.TP +.I fmt +is either +\fB0\fP, \fB1\fP, or \fB2\fP, indicating whether the label is to be +left-justified, centered, or right-justified, respectively, within the +label. +.RE +.PP +The \fBslk_label\fP routine returns the current label for label number +\fIlabnum\fP, with leading and trailing blanks stripped. +.SS Screen updates +The \fBslk_refresh\fP and \fBslk_noutrefresh\fP routines correspond to +the \fBwrefresh\fP and \fBwnoutrefresh\fP routines. +.PP +The \fBslk_clear\fP routine clears the soft labels from the screen. +.PP +The \fBslk_restore\fP routine restores the soft labels to the screen +after a \fBslk_clear\fP has been performed. +.PP +The \fBslk_touch\fP routine forces all the soft labels to be output +the next time a \fBslk_noutrefresh\fP is performed. +.SS Video attributes +The +\fBslk_attron\fP, \fBslk_attrset\fP, \fBslk_attroff\fP and \fBslk_attr\fP +routines correspond to +\fBattron\fP, \fBattrset\fP, \fBattroff\fP and \fBattr_get\fP, respectively. +They have an effect only if soft labels are simulated on the bottom line of +the screen. +The default highlight for soft keys is A_STANDOUT (as in +System V curses, which does not document this fact). +.SS Colors +The \fBslk_color\fP routine corresponds to \fBcolor_set\fP. +It has an effect only +if soft labels are simulated on the bottom line of the screen. +.PP +Because \fBslk_color\fP accepts only \fBshort\fP (signed 16-bit integer) values, +this implementation provides +\fBextended_slk_color\fP which accepts an integer value, e.g., 32-bits. +. +.SH RETURN VALUE +These routines return \fBERR\fP upon failure +and \fBOK\fP (SVr4 specifies only "an integer value other than \fBERR\fP") +upon successful completion. +.PP +X/Open defines no error conditions. +In this implementation +.RS 3 +.TP 5 +\fBslk_attr\fP +returns the attribute used for the soft keys. +.TP 5 +.na +.hy 0 +\fBslk_attroff\fP, \fBslk_attron\fP, \fBslk_clear\fP, \fBslk_noutrefresh\fP, \fBslk_refresh\fP, \fBslk_touch\fP +.ad +.hy +return an error +if the terminal or the softkeys were not initialized. +.TP 5 +\fBslk_attrset\fP +returns an error +if the terminal or the softkeys were not initialized. +.TP 5 +\fBslk_attr_set\fP +returns an error +if the terminal or the softkeys were not initialized, or +the color pair is outside the range 0..COLOR_PAIRS\-1. +.TP 5 +\fBslk_color\fP +returns an error +if the terminal or the softkeys were not initialized, or +the color pair is outside the range 0..COLOR_PAIRS\-1. +.TP 5 +\fBslk_init\fP +returns an error +if the format parameter is outside the range 0..3. +.TP 5 +\fBslk_label\fP +returns \fBNULL\fP on error. +.TP 5 +\fBslk_set\fP +returns an error +if the terminal or the softkeys were not initialized, or +the \fIlabnum\fP parameter is outside the range of label counts, or +if the format parameter is outside the range 0..2, or if +memory for the labels cannot be allocated. +.RE +.SH HISTORY +SVr3 introduced these functions: + slk_clear + slk_init + slk_label + slk_noutrefresh + slk_refresh + slk_restore + slk_set + slk_touch +.PP +SVr4 added these functions: + slk_attroff + slk_attron + slk_attrset + slk_start +.PP +X/Open Curses added these: + slk_attr_off + slk_attr_on + slk_attr_set + slk_color + slk_wset +.SH EXTENSIONS +X/Open Curses documents the \fIopts\fP argument as reserved for future use, +saying that it must be null. +This implementation +uses that parameter in ABI 6 for the functions which have a color-pair +parameter to support extended color pairs. +.PP +For functions which modify the color, e.g., \fBslk_attr_set\fP, +if \fIopts\fP is set it is treated as a pointer to \fBint\fP, +and used to set the color pair instead of the \fBshort\fP pair parameter. +.SH NOTES +Most applications would use \fBslk_noutrefresh\fP because a +\fBwrefresh\fP is likely to follow soon. +.SH PORTABILITY +The XSI Curses standard, Issue 4, described the soft-key functions, +with some differences from SVr4 curses: +.bP +It added functions like the SVr4 +attribute-manipulation functions \fBslk_attron\fP, +\fBslk_attroff\fP, \fBslk_attrset\fP, +but which use \fBattr_t\fP parameters (rather than \fBchtype\fP), +along with a reserved \fIopts\fP parameter. +.IP +Two of these new functions (unlike the SVr4 functions) have no provision +for color: \fBslk_attr_on\fP and \fBslk_attr_off\fP. +.IP +The third function (\fBslk_attr_set\fP) has a color-pair parameter. +.bP +It added \fBconst\fP qualifiers to parameters (unnecessarily), and +.bP +It added \fBslk_color\fP. +.PP +Although \fBslk_start\fP is declared in the curses header file, +it was not documented by SVr4 other than its presence in a list +of libtermlib.so.1 symbols. +Reading the source code (i.e., Illumos): +.bP +\fBslk_start\fP has two parameters: +.RS +.bP +\fIng\fP (number of groups) and +.bP +\fIgp\fP (group pointer). +.RE +.bP +Soft-key groups are an array of \fIng\fP integers. +.bP +In SVr4, \fBslk_init\fP calls \fBslk_start\fP passing a null for \fIgp\fP. +For this case, \fBslk_start\fP uses the number of groups \fIng\fP +(3 for the 3-2-3 layout, 2 for the 4-4 layout) which \fBslk_init\fP provided. +.IP +If \fIng\fP is neither 2 or 3, +\fBslk_start\fP checks the terminfo \fIfln\fP (label_format) capability, +interpreting that as a comma-separated list of numbers, +e.g., \*(``3,2,3\*('' for the 3-2-3 layout. +.IP +Finally, if there is no \fIfln\fP capability, \fBslk_start\fP returns ERR. +.bP +If \fBslk_start\fP is given a non-null \fIgp\fP, +it copies the \fIng\fP elements of the group of soft-keys, up to 16. +.IP +If there are more than 16 elements, \fBslk_start\fP returns an error. +.bP +The format codes \fB2\fP and \fB3\fP for \fBslk_init\fP +were added by ncurses in 1996. +PDCurses 2.4 added this feature in 2001. +.PP +The function \fBslk_attr\fP was added by ncurses in 1996. +.PP +X/Open Curses does not specify a limit for the number of colors and +color pairs which a terminal can support. +However, in its use of \fBshort\fP for the parameters, +it carries over SVr4's implementation detail for the compiled +terminfo database, which uses signed 16-bit numbers. +This implementation provides extended versions of those functions +which use \fBint\fP parameters, +allowing applications to use larger color- and pair-numbers. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_attr\fP(3), +\fBcurs_initscr\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_variables\fP(3). diff --git a/static/openbsd/man3/curs_sp_funcs.3 b/static/openbsd/man3/curs_sp_funcs.3 new file mode 100644 index 00000000..1e0b6223 --- /dev/null +++ b/static/openbsd/man3/curs_sp_funcs.3 @@ -0,0 +1,286 @@ +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2010-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_sp_funcs.3,v 1.1 2023/10/17 09:52:08 nicm Exp $ +.TH curs_sp_funcs 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.na +.hy 0 +.SH NAME +curs_sp_funcs \- \fBcurses\fP screen-pointer extension +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.nf +.na +.sp +\fBint alloc_pair_sp(SCREEN* \fIsp\fB, int \fIfg\fB, int \fIbg\fB);\fR +\fBint assume_default_colors_sp(SCREEN* \fIsp\fB, int \fIfg\fB, int \fIbg\fB);\fR +\fBint baudrate_sp(SCREEN* \fIsp\fB);\fR +\fBint beep_sp(SCREEN* \fIsp\fB);\fR +\fBbool can_change_color_sp(SCREEN* \fIsp\fB);\fR +\fBint cbreak_sp(SCREEN* \fIsp\fB);\fR +\fBint color_content_sp(SCREEN* \fIsp\fB, short \fIcolor\fB, short* \fIr\fB, short* \fIg\fB, short* \fIb\fB);\fR +\fBint curs_set_sp(SCREEN* \fIsp\fB, int \fIvisibility\fR);\fR +\fBint def_prog_mode_sp(SCREEN* \fIsp\fB);\fR +\fBint def_shell_mode_sp(SCREEN* \fIsp\fB);\fR +.sp +\fBint define_key_sp(SCREEN* \fIsp\fB, const char * \fIdefinition\fB, int \fIkeycode\fB);\fR +\fBint delay_output_sp(SCREEN* \fIsp\fB, int \fIms\fB);\fR +\fBint doupdate_sp(SCREEN* \fIsp\fB);\fR +\fBint echo_sp(SCREEN* \fIsp\fB);\fR +\fBint endwin_sp(SCREEN* \fIsp\fB);\fR +\fBchar erasechar_sp(SCREEN* \fIsp\fB);\fR +\fBint erasewchar_sp(SCREEN* \fIsp\fB, wchar_t *\fIch\fB);\fR +\fBint extended_color_content_sp(SCREEN * \fIsp\fB, int \fIcolor\fB, int * \fIr\fB, int * \fIg\fB, int * \fIb\fB);\fR +\fBint extended_pair_content_sp(SCREEN* \fIsp\fB, int \fIpair\fB, int * \fIfg\fB, int * \fIbg\fB);\fR +\fBint extended_slk_color_sp(SCREEN* \fIsp\fB, int \fIpair\fB);\fR +.sp +\fBvoid filter_sp(SCREEN* \fIsp\fB);\fR +\fBint find_pair_sp(SCREEN* \fIsp\fB, int \fIfg\fB, int \fIbg\fB);\fR +\fBint flash_sp(SCREEN* \fIsp\fB);\fR +\fBint flushinp_sp(SCREEN* \fIsp\fB);\fR +\fBint free_pair_sp(SCREEN* \fIsp\fB, int \fIpair\fB);\fR +\fBint get_escdelay_sp(SCREEN* \fIsp\fB);\fR +\fBint getmouse_sp(SCREEN* \fIsp\fB, MEVENT* \fBevent\fB);\fR +\fBWINDOW* getwin_sp(SCREEN* \fIsp\fB, FILE* \fIfilep\fB);\fR +\fBint halfdelay_sp(SCREEN* \fIsp\fB, int \fItenths\fB);\fR +\fBbool has_colors_sp(SCREEN* \fIsp\fB);\fR +.sp +\fBbool has_ic_sp(SCREEN* \fIsp\fB);\fR +\fBbool has_il_sp(SCREEN* \fIsp\fB);\fR +\fBint has_key_sp(SCREEN* \fIsp\fB, int \fIch\fB);\fR +\fBbool has_mouse_sp(SCREEN* \fIsp\fB);\fR +\fBint init_color_sp(SCREEN* \fIsp\fB, short \fIcolor\fB, short \fIr\fB, short \fIg\fB, short \fIb\fB);\fR +\fBint init_extended_color_sp(SCREEN* \fIsp\fB, int \fIcolor\fB, int \fIr\fB, int \fIg\fB, int \fIb\fB);\fR +\fBint init_extended_pair_sp(SCREEN* \fIsp\fB, int \fIpair\fB, int \fIfg\fB, int \fIbg\fB);\fR +\fBint init_pair_sp(SCREEN* \fIsp\fB, short \fIpair\fB, short \fIfg\fB, short \fIbg\fB);\fR +\fBint intrflush_sp(SCREEN* \fIsp\fB, WINDOW* \fIwin\fB, bool \fIbf\fB);\fR +\fBint is_cbreak_sp(SCREEN* \fIsp\fB);\fR +.sp +\fBint is_echo_sp(SCREEN* \fIsp\fB);\fR +\fBint is_nl_sp(SCREEN* \fIsp\fB);\fR +\fBint is_raw_sp(SCREEN* \fIsp\fB);\fR +\fBbool is_term_resized_sp(SCREEN* \fIsp\fB, int \fIlines\fB, int \fIcolumns\fB);\fR +\fBbool isendwin_sp(SCREEN* \fIsp\fB);\fR +\fBint key_defined_sp(SCREEN* \fIsp\fB, const char *\fIdefinition\fB);\fR +\fBchar* keybound_sp(SCREEN* \fIsp\fB, int \fIkeycode\fB, int \fIcount\fB);\fR +\fBNCURSES_CONST char* keyname_sp(SCREEN* \fIsp\fB, int \fIc\fB);\fR +\fBint keyok_sp(SCREEN* \fIsp\fB, int \fIkeycode\fB, bool \fIenable\fB);\fR +\fBchar killchar_sp(SCREEN* \fIsp\fB);\fR +.sp +\fBint killwchar_sp(SCREEN* \fIsp\fB, wchar_t *\fIch\fB);\fR +\fBchar* longname_sp(SCREEN* \fIsp\fB);\fR +\fBint mcprint_sp(SCREEN* \fIsp\fB, char *\fIdata\fB, int \fIlen\fB);\fR +\fBint mouseinterval_sp(SCREEN* \fIsp\fB, int \fIerval\fB);\fR +\fBmmask_t mousemask_sp(SCREEN* \fIsp\fB, mmask_t \fInewmask\fB, mmask_t *\fIoldmask\fB);\fR +\fBint mvcur_sp(SCREEN* \fIsp\fB, int \fIoldrow\fB, int \fIoldcol\fB, int \fInewrow\fB, int \fInewcol\fB);\fR +\fBint napms_sp(SCREEN* \fIsp\fB, int \fIms\fB);\fR +\fBWINDOW* newpad_sp(SCREEN* \fIsp\fB, int \fInrows\fB, int \fIncols\fB);\fR +\fBSCREEN* new_prescr(void);\fP +\fBSCREEN* newterm_sp(SCREEN* \fIsp\fB, const char *\fItype\fB, FILE *\fIoutfd\fB, FILE *\fIinfd\fB);\fR +.sp +\fBWINDOW* newwin_sp(SCREEN* \fIsp\fB, int \fInlines\fB, int \fIncols\fB, int \fIbegin_y\fB, int \fIbegin_x\fB);\fR +\fBint nl_sp(SCREEN* \fIsp\fB);\fR +\fBint nocbreak_sp(SCREEN* \fIsp\fB);\fR +\fBint noecho_sp(SCREEN* \fIsp\fB);\fR +\fBvoid nofilter_sp(SCREEN* \fIsp\fB);\fR +\fBint nonl_sp(SCREEN* \fIsp\fB);\fR +\fBvoid noqiflush_sp(SCREEN* \fIsp\fB);\fR +\fBint noraw_sp(SCREEN* \fIsp\fB);\fR +\fBint pair_content_sp(SCREEN* \fIsp\fB, short \fIpair\fB, short* \fIfg\fB, short* \fIbg\fB);\fR +\fBvoid qiflush_sp(SCREEN* \fIsp\fB);\fR +.sp +\fBint raw_sp(SCREEN* \fIsp\fB);\fR +\fBvoid reset_color_pairs_sp(SCREEN* \fIsp\fB);\fR +\fBint reset_prog_mode_sp(SCREEN* \fIsp\fB);\fR +\fBint reset_shell_mode_sp(SCREEN* \fIsp\fB);\fR +\fBint resetty_sp(SCREEN* \fIsp\fB);\fR +\fBint resize_term_sp(SCREEN* \fIsp\fB, int \fIlines\fB, int \fIcolumns\fB);\fR +\fBint resizeterm_sp(SCREEN* \fIsp\fB, int \fIlines\fB, int \fIcolumns\fB);\fR +\fBint ripoffline_sp(SCREEN* \fIsp\fB, int \fIline\fB, int (*\fIinit\fB)(WINDOW* \fIwin\fB, int \fIfmt\fB));\fR +\fBint savetty_sp(SCREEN* \fIsp\fB);\fR +\fBint scr_init_sp(SCREEN* \fIsp\fB, const char *\fIfilename\fB);\fR +.sp +\fBint scr_restore_sp(SCREEN* \fIsp\fB, const char *\fIfilename\fB);\fR +\fBint scr_set_sp(SCREEN* \fIsp\fB, const char *\fIfilename\fB);\fR +\fBint set_escdelay_sp(SCREEN* \fIsp\fB, int \fIms\fB);\fR +\fBint set_tabsize_sp(SCREEN* \fIsp\fB, int \fIcols\fB);\fR +\fBint slk_attrset_sp(SCREEN* \fIsp\fB, const chtype \fIa\fB);\fR +\fBint slk_attr_set_sp(SCREEN* \fIsp\fB, const attr_t \fIattrs\fB, short \fIpair\fB, void*\fIopts\fB);\fR +\fBint slk_attroff_sp(SCREEN* \fIsp\fB, const chtype \fIa\fB);\fR +\fBint slk_attron_sp(SCREEN* \fIsp\fB, const chtype \fIa\fB);\fR +\fBattr_t slk_attr_sp(SCREEN* \fIsp\fB);\fR +\fBint slk_clear_sp(SCREEN* \fIsp\fB);\fR +.sp +\fBint slk_color_sp(SCREEN* \fIsp\fB, short \fIpair\fB);\fR +\fBint slk_init_sp(SCREEN* \fIsp\fB, int \fIfmt\fB);\fR +\fBchar* slk_label_sp(SCREEN* \fIsp\fB, int \fIlabnum\fB);\fR +\fBint slk_noutrefresh_sp(SCREEN* \fIsp\fB);\fR +\fBint slk_refresh_sp(SCREEN* \fIsp\fB);\fR +\fBint slk_restore_sp(SCREEN* \fIsp\fB);\fR +\fBint slk_set_sp(SCREEN* \fIsp\fB, int \fIlabnum\fB, const char * \fIlabel\fB, int \fIfmt\fB);\fR +\fBint slk_touch_sp(SCREEN* \fIsp\fB);\fR +\fBint start_color_sp(SCREEN* \fIsp\fB);\fR +\fBattr_t term_attrs_sp(SCREEN* \fIsp\fB);\fR +.sp +\fBchtype termattrs_sp(SCREEN* \fIsp\fB);\fR +\fBchar* termname_sp(SCREEN* \fIsp\fB);\fR +\fBint typeahead_sp(SCREEN* \fIsp\fB, int \fIfd\fB);\fR +\fBint unget_wch_sp(SCREEN* \fIsp\fB, const wchar_t \fIwch\fB);\fR +\fBint ungetch_sp(SCREEN* \fIsp\fB, int \fIch\fB);\fR +\fBint ungetmouse_sp(SCREEN* \fIsp\fB,MEVENT * \fBevent\fB);\fR +\fBint use_default_colors_sp(SCREEN* \fIsp\fB);\fR +\fBvoid use_env_sp(SCREEN* \fIsp\fB, bool \fIbf\fB);\fR +\fBint use_legacy_coding_sp(SCREEN* \fIsp\fB, int \fIlevel\fB);\fR +\fBvoid use_tioctl_sp(SCREEN *\fIsp\fB, bool \fIbf\fB);\fR +.sp +\fBint vid_attr_sp(SCREEN* \fIsp\fB, attr_t \fIattrs\fB, short \fIpair\fB, void * \fIopts\fB);\fR +\fBint vid_puts_sp(SCREEN* \fIsp\fB, attr_t \fIattrs\fB, short \fIpair\fB, void * \fIopts\fB, NCURSES_SP_OUTC \fIputc\fB);\fR +\fBint vidattr_sp(SCREEN* \fIsp\fB, chtype \fIattrs\fB);\fR +\fBint vidputs_sp(SCREEN* \fIsp\fB, chtype \fIattrs\fB, NCURSES_SP_OUTC \fIputc\fB);\fR +\fBwchar_t* wunctrl_sp(SCREEN* \fIsp\fB, cchar_t *\fIch\fB);\fR +.ad +.sp +\fB#include \fP +.sp +\fBFORM* new_form_sp(SCREEN* \fIsp\fB, FIELD **\fIfields\fB);\fR +.sp +\fB#include \fP +.sp +\fBMENU* new_menu_sp(SCREEN* \fIsp\fB, ITEM **\fIitems\fB);\fR +.sp +\fB#include \fP +.sp +\fBPANEL* ceiling_panel(SCREEN* \fIsp\fB);\fR +.br +\fBPANEL* ground_panel(SCREEN* \fIsp\fB);\fR +.br +\fBvoid update_panels_sp(SCREEN* \fIsp\fB);\fR +.sp +\fB#include \fP +.sp +.na +\fBint del_curterm_sp(SCREEN* \fIsp\fB, TERMINAL *\fIoterm\fB);\fR +\fBint putp_sp(SCREEN* \fIsp\fB, const char *\fIstr\fB);\fR +\fBint restartterm_sp(SCREEN* \fIsp\fB, NCURSES_CONST char*\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR +\fBTERMINAL* set_curterm_sp(SCREEN* \fIsp\fB, TERMINAL*\fInterm\fB);\fR +\fBint tgetent_sp(SCREEN* \fIsp\fB, char *\fIbp\fB, const char *\fIname\fB);\fR +\fBint tgetflag_sp(SCREEN* \fIsp\fB, const char *\fIcapname\fB);\fR +\fBint tgetnum_sp(SCREEN* \fIsp\fB, const char *\fIcapname\fB);\fR +\fBchar* tgetstr_sp(SCREEN* \fIsp\fB, const char *\fIcapname\fB, char **\fIarea\fB);\fR +\fBchar* tgoto_sp(SCREEN* \fIsp\fB, const char *\fIcapname\fB, int \fIcol\fB, int \fIrow\fB);\fR +\fBint tigetflag_sp(SCREEN* \fIsp\fB, const char *\fIcapname\fB);\fR +.sp +\fBint tigetnum_sp(SCREEN* \fIsp\fB, const char *\fIcapname\fB);\fR +\fBchar* tigetstr_sp(SCREEN* \fIsp\fB, const char *\fIcapname\fB);\fR +\fR/* may instead use 9 long parameters */\fR +\fBchar* tparm_sp(SCREEN* \fIsp\fB, const char *\fIstr\fB, ...);\fR +\fBint tputs_sp(SCREEN* \fIsp\fB, const char *\fIstr\fB, int \fIaffcnt\fB, NCURSES_SP_OUTC \fIputc\fB);\fR +.ad +.sp +\fB#include \fP +.sp +\fBNCURSES_CONST char* unctrl_sp(SCREEN* \fIsp\fB, chtype \fIc\fB);\fR +.ad +.SH DESCRIPTION +This implementation can be configured to provide a set of functions which +improve the ability to manage multiple screens. +This feature can be added to any of the configurations supported by ncurses; +it adds new entrypoints +without changing the meaning of any of the existing ones. +.\" *************************************************************************** +.SS IMPROVED FUNCTIONS +Most of the functions are new versions of existing functions. +A parameter is added at the front of the parameter list. +It is a SCREEN pointer. +.PP +The existing functions all use the current screen, +which is a static variable. +The extended functions use the specified screen, +thereby reducing the number of variables which must be modified +to update multiple screens. +.\" *************************************************************************** +.SS NEW FUNCTIONS +Here are the new functions: +.TP 5 +ceiling_panel +this returns a pointer to the topmost panel in the given screen. +.TP 5 +ground_panel +this returns a pointer to the lowest panel in the given screen. +.TP 5 +new_prescr +when creating a new screen, the library uses static variables which +have been preset, e.g., by \fBuse_env\fP(3), \fBfilter\fP(3), etc. +With the screen-pointer extension, +there are situations where it must create a current screen before +the unextended library does. +The \fBnew_prescr\fP function is used internally to handle these cases. +It is also provided as an entrypoint to allow applications to customize +the library initialization. +.\" *************************************************************************** +.SH NOTES +This extension introduces some new names: +.TP 5 +NCURSES_SP_FUNCS +This is set to the library patch-level number. +In the unextended library, this is zero (0), +to make it useful for checking if the extension is provided. +.TP 5 +NCURSES_SP_NAME +The new functions are named using the macro \fINCURSES_SP_NAME\fP, +which hides the actual implementation. +Currently this adds a \*(``_sp\*('' suffix +to the name of the unextended function. +This manual page indexes the extensions showing the full name. +However the proper usage of these functions uses the macro, +to provide for the possibility of changing the naming convention +for specific library configurations. +.TP 5 +NCURSES_SP_OUTC +This is a new function-pointer type to use in the screen-pointer functions +where an \fINCURSES_OUTC\fP is used in the unextended library. +.TP 5 +NCURSES_OUTC +This is a function-pointer type used for the cases where a function passes +characters to the output stream, e.g., \fBvidputs\fP(3). +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on Version 7, BSD or System V implementations. +It is recommended that any code depending on ncurses extensions +be conditioned using \fINCURSES_SP_FUNCS\fP. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_opaque\fP(3), +\fBcurs_threads\fP(3). diff --git a/static/openbsd/man3/curs_termattrs.3 b/static/openbsd/man3/curs_termattrs.3 new file mode 100644 index 00000000..4b39e24e --- /dev/null +++ b/static/openbsd/man3/curs_termattrs.3 @@ -0,0 +1,137 @@ +.\" $OpenBSD: curs_termattrs.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_termattrs.3,v 1.9 2023/10/17 09:52:08 nicm Exp $ +.TH curs_termattrs 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBbaudrate\fP, +\fBerasechar\fP, +\fBerasewchar\fP, +\fBhas_ic\fP, +\fBhas_il\fP, +\fBkillchar\fP, +\fBkillwchar\fP, +\fBlongname\fP, +\fBterm_attrs\fP, +\fBtermattrs\fP, +\fBtermname\fP \- \fBcurses\fP environment query routines +.SH SYNOPSIS +\fB#include \fP +.PP +\fBint baudrate(void);\fP +.br +\fBchar erasechar(void);\fP +.br +\fBint erasewchar(wchar_t *\fIch\fB);\fR +.br +\fBbool has_ic(void);\fP +.br +\fBbool has_il(void);\fP +.br +\fBchar killchar(void);\fP +.br +\fBint killwchar(wchar_t *\fIch\fB);\fR +.br +\fBchar *longname(void);\fP +.br +\fBattr_t term_attrs(void);\fP +.br +\fBchtype termattrs(void);\fP +.br +\fBchar *termname(void);\fP +.br +.SH DESCRIPTION +.SS baudrate +The \fBbaudrate\fP routine returns the output speed of the terminal. +The +number returned is in bits per second, for example \fB9600\fP, and is an +integer. +.SS erasechar, erasewchar +The \fBerasechar\fP routine returns the user's current erase character. +.PP +The \fBerasewchar\fP routine stores the current erase character +in the location referenced by \fIch\fP. +If no erase character has been defined, the routine fails +and the location referenced by \fIch\fP is not changed. +.SS has_is, has_il +The \fBhas_ic\fP routine is true if the terminal has insert- and delete- +character capabilities. +.PP +The \fBhas_il\fP routine is true if the terminal has insert- and delete-line +capabilities, or can simulate them using scrolling regions. +This might +be used to determine if it would be appropriate to turn on physical +scrolling using \fBscrollok\fP(3). +.SS killchar, killwchar +The \fBkillchar\fP routine returns the user's current line kill character. +.PP +The \fBkillwchar\fP routine stores the current line-kill character +in the location referenced by \fIch\fP. +If no line-kill character has been defined, +the routine fails and the location referenced by \fIch\fP is not changed. +.SS longname +The \fBlongname\fP routine returns a pointer to a static area +containing a verbose description of the current terminal. +The maximum +length of a verbose description is 128 characters. +It is defined only +after the call to \fBinitscr\fP or \fBnewterm\fP. The area is +overwritten by each call to \fBnewterm\fP and is not restored by +\fBset_term\fP, so the value should be saved between calls to +\fBnewterm\fP if \fBlongname\fP is going to be used with multiple +terminals. +.SS termattrs, term_attrs +If a given terminal does not support a video attribute that an +application program is trying to use, \fBcurses\fP may substitute a +different video attribute for it. +The \fBtermattrs\fP and \fBterm_attrs\fP functions +return a logical \fBOR\fP of all video attributes supported by the +terminal using \fBA_\fP and \fBWA_\fP constants respectively. +This information is useful when a \fBcurses\fP program +needs complete control over the appearance of the screen. +.SS termname +The \fBtermname\fP routine returns the terminal name used by \fBsetupterm\fP. +.SH RETURN VALUE +\fBlongname\fP and \fBtermname\fP return \fBNULL\fP on error. +.PP +Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +(SVr4 only specifies "an integer value other than \fBERR\fP") upon successful +completion. +.SH NOTES +Note that \fBtermattrs\fP may be a macro. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +It changes the +return type of \fBtermattrs\fP to the new type \fBattr_t\fP. +Most versions of curses truncate the result returned by \fBtermname\fP to +14 characters. +.SH SEE ALSO +\fBcurses\fP(3), \fBcurs_initscr\fP(3), \fBcurs_outopts\fP(3) diff --git a/static/openbsd/man3/curs_threads.3 b/static/openbsd/man3/curs_threads.3 new file mode 100644 index 00000000..9d1b49c3 --- /dev/null +++ b/static/openbsd/man3/curs_threads.3 @@ -0,0 +1,604 @@ +'\" t +.\"*************************************************************************** +.\" Copyright 2021-2022,2023 Thomas E. Dickey * +.\" Copyright 2008-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_threads.3,v 1.1 2023/10/17 09:52:08 nicm Exp $ +.TH curs_threads 3 2023-08-19 "ncurses 6.4" "Library calls" +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBcurs_threads\fP \- \fBcurses\fP thread support +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fP +.br +\fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fP +.sp +\fBint get_escdelay(void);\fP +.br +\fBint set_escdelay(int \fIms\fB);\fR +.br +\fBint set_tabsize(int \fIcols\fB);\fR +.sp +\fBint use_screen(SCREEN *\fIscr\fB, NCURSES_SCREEN_CB \fIfunc\fB, void *\fIdata\fB);\fR +.br +\fBint use_window(WINDOW *\fIwin\fB, NCURSES_WINDOW_CB \fIfunc\fB, void *\fIdata\fB);\fR +.SH DESCRIPTION +This implementation can be configured to provide rudimentary support +for multi-threaded applications. +This makes a different set of libraries, e.g., \fBlibncursest\fP since +the binary interfaces are different. +.PP +Rather than modify the interfaces to pass a thread specifier to +each function, it adds a few functions which can be used in any +configuration which hide the mutex's needed to prevent concurrent +use of the global variables when configured for threading. +.PP +In addition to forcing access to members of the \fBWINDOW\fP structure +to be via functions (see \fBcurs_opaque\fP(3)), +it makes functions of the common global variables, +e.g., +COLORS, +COLOR_PAIRS, +COLS, +ESCDELAY, +LINES, +TABSIZE +curscr, +newscr and +ttytype. +Those variables are maintained as read-only values, stored in the \fBSCREEN\fP +structure. +.PP +Even this is not enough to make a thread-safe application using curses. +A multi-threaded application would be expected to have threads updating +separate windows (within the same device), +or updating on separate screens (on different devices). +Also, a few of the global variables are considered writable by some +applications. +The functions described here address these special situations. +.PP +The ESCDELAY and TABSIZE global variables are modified by some applications. +To modify them in any configuration, +use the \fBset_escdelay\fP or \fBset_tabsize\fP functions. +Other global variables are not modifiable. +.PP +The \fBget_escdelay\fP function returns the value for ESCDELAY. +.PP +The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse +granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP +parameters, and call a user-supplied function, +passing it a \fIdata\fP parameter, +and returning the value from the user-supplied function to the application. +.\" *************************************************************************** +.SS USAGE +All of the ncurses library functions assume that the locale is not +altered during operation. +In addition, +they use data which is maintained within a hierarchy of scopes. +.RS 3 +.bP +global data, e.g., used in the low-level terminfo or termcap interfaces. +.bP +terminal data, e.g., associated with a call to \fBset_curterm\fP. +The terminal data are initialized when screens are created. +.bP +screen data, e.g., associated with a call to \fBnewterm\fP or \fBinitscr\fP. +.bP +window data, e.g., associated with a call to \fBnewwin\fP or \fBsubwin\fP. +Windows are associated with screens. +Pads are not necessarily associated with a particular screen. +.IP +Most curses applications operate on one or more windows within a single screen. +.bP +reentrant, i.e., it uses only the data passed as parameters. +.RE +.PP +This table lists the scope of data used for each symbol in the +ncurses library when it is configured to support threading: +.PP +.TS +center tab(/); +l l +l l . +Symbol/Scope += +BC/global +COLORS/screen (readonly) +COLOR_PAIR/reentrant +COLOR_PAIRS/screen (readonly) +COLS/screen (readonly) +ESCDELAY/screen (readonly, see \fBset_escdelay\fP) +LINES/screen (readonly) +PAIR_NUMBER/reentrant +PC/global +SP/global +TABSIZE/screen (readonly) +UP/global +acs_map/screen (readonly) +add_wch/window (stdscr) +add_wchnstr/window (stdscr) +add_wchstr/window (stdscr) +addch/window (stdscr) +addchnstr/window (stdscr) +addchstr/window (stdscr) +addnstr/window (stdscr) +addnwstr/window (stdscr) +addstr/window (stdscr) +addwstr/window (stdscr) +assume_default_colors/screen +attr_get/window (stdscr) +attr_off/window (stdscr) +attr_on/window (stdscr) +attr_set/window (stdscr) +attroff/window (stdscr) +attron/window (stdscr) +attrset/window (stdscr) +baudrate/screen +beep/screen +bkgd/window (stdscr) +bkgdset/window (stdscr) +bkgrnd/window (stdscr) +bkgrndset/window (stdscr) +boolcodes/global (readonly) +boolfnames/global (readonly) +boolnames/global (readonly) +border/window (stdscr) +border_set/window (stdscr) +box/window (stdscr) +box_set/window (stdscr) +can_change_color/terminal +cbreak/screen +chgat/window (stdscr) +clear/window (stdscr) +clearok/window +clrtobot/window (stdscr) +clrtoeol/window (stdscr) +color_content/screen +color_set/window (stdscr) +copywin/window locks(source, target) +cur_term/terminal +curs_set/screen +curscr/screen (readonly) +curses_version/global (readonly) +def_prog_mode/terminal +def_shell_mode/terminal +define_key/screen +del_curterm/screen +delay_output/screen +delch/window (stdscr) +deleteln/window (stdscr) +delscreen/global locks(screenlist, screen) +delwin/global locks(windowlist) +derwin/screen +doupdate/screen +dupwin/screen locks(window) +echo/screen +echo_wchar/window (stdscr) +echochar/window (stdscr) +endwin/screen +erase/window (stdscr) +erasechar/window (stdscr) +erasewchar/window (stdscr) +filter/global +flash/terminal +flushinp/screen +get_wch/screen (input-operation) +get_wstr/screen (input-operation) +getattrs/window +getbegx/window +getbegy/window +getbkgd/window +getbkgrnd/window +getcchar/reentrant +getch/screen (input-operation) +getcurx/window +getcury/window +getmaxx/window +getmaxy/window +getmouse/screen (input-operation) +getn_wstr/screen (input-operation) +getnstr/screen (input-operation) +getparx/window +getpary/window +getstr/screen (input-operation) +getwin/screen (input-operation) +halfdelay/screen +has_colors/terminal +has_ic/terminal +has_il/terminal +has_key/screen +hline/window (stdscr) +hline_set/window (stdscr) +idcok/window +idlok/window +immedok/window +in_wch/window (stdscr) +in_wchnstr/window (stdscr) +in_wchstr/window (stdscr) +inch/window (stdscr) +inchnstr/window (stdscr) +inchstr/window (stdscr) +init_color/screen +init_pair/screen +initscr/global locks(screenlist) +innstr/window (stdscr) +innwstr/window (stdscr) +ins_nwstr/window (stdscr) +ins_wch/window (stdscr) +ins_wstr/window (stdscr) +insch/window (stdscr) +insdelln/window (stdscr) +insertln/window (stdscr) +insnstr/window (stdscr) +insstr/window (stdscr) +instr/window (stdscr) +intrflush/terminal +inwstr/window (stdscr) +is_cleared/window +is_idcok/window +is_idlok/window +is_immedok/window +is_keypad/window +is_leaveok/window +is_linetouched/window +is_nodelay/window +is_notimeout/window +is_scrollok/window +is_syncok/window +is_term_resized/terminal +is_wintouched/window +isendwin/screen +key_defined/screen +key_name/global (static data) +keybound/screen +keyname/global (static data) +keyok/screen +keypad/window +killchar/terminal +killwchar/terminal +leaveok/window +longname/screen +mcprint/terminal +meta/screen +mouse_trafo/window (stdscr) +mouseinterval/screen +mousemask/screen +move/window (stdscr) +mvadd_wch/window (stdscr) +mvadd_wchnstr/window (stdscr) +mvadd_wchstr/window (stdscr) +mvaddch/window (stdscr) +mvaddchnstr/window (stdscr) +mvaddchstr/window (stdscr) +mvaddnstr/window (stdscr) +mvaddnwstr/window (stdscr) +mvaddstr/window (stdscr) +mvaddwstr/window (stdscr) +mvchgat/window (stdscr) +mvcur/screen +mvdelch/window (stdscr) +mvderwin/window (stdscr) +mvget_wch/screen (input-operation) +mvget_wstr/screen (input-operation) +mvgetch/screen (input-operation) +mvgetn_wstr/screen (input-operation) +mvgetnstr/screen (input-operation) +mvgetstr/screen (input-operation) +mvhline/window (stdscr) +mvhline_set/window (stdscr) +mvin_wch/window (stdscr) +mvin_wchnstr/window (stdscr) +mvin_wchstr/window (stdscr) +mvinch/window (stdscr) +mvinchnstr/window (stdscr) +mvinchstr/window (stdscr) +mvinnstr/window (stdscr) +mvinnwstr/window (stdscr) +mvins_nwstr/window (stdscr) +mvins_wch/window (stdscr) +mvins_wstr/window (stdscr) +mvinsch/window (stdscr) +mvinsnstr/window (stdscr) +mvinsstr/window (stdscr) +mvinstr/window (stdscr) +mvinwstr/window (stdscr) +mvprintw/window (stdscr) +mvscanw/screen +mvvline/window (stdscr) +mvvline_set/window (stdscr) +mvwadd_wch/window +mvwadd_wchnstr/window +mvwadd_wchstr/window +mvwaddch/window +mvwaddchnstr/window +mvwaddchstr/window +mvwaddnstr/window +mvwaddnwstr/window +mvwaddstr/window +mvwaddwstr/window +mvwchgat/window +mvwdelch/window +mvwget_wch/screen (input-operation) +mvwget_wstr/screen (input-operation) +mvwgetch/screen (input-operation) +mvwgetn_wstr/screen (input-operation) +mvwgetnstr/screen (input-operation) +mvwgetstr/screen (input-operation) +mvwhline/window +mvwhline_set/window +mvwin/window +mvwin_wch/window +mvwin_wchnstr/window +mvwin_wchstr/window +mvwinch/window +mvwinchnstr/window +mvwinchstr/window +mvwinnstr/window +mvwinnwstr/window +mvwins_nwstr/window +mvwins_wch/window +mvwins_wstr/window +mvwinsch/window +mvwinsnstr/window +mvwinsstr/window +mvwinstr/window +mvwinwstr/window +mvwprintw/window +mvwscanw/screen +mvwvline/window +mvwvline_set/window +napms/reentrant +newpad/global locks(windowlist) +newscr/screen (readonly) +newterm/global locks(screenlist) +newwin/global locks(windowlist) +nl/screen +nocbreak/screen +nodelay/window +noecho/screen +nofilter/global +nonl/screen +noqiflush/terminal +noraw/screen +notimeout/window +numcodes/global (readonly) +numfnames/global (readonly) +numnames/global (readonly) +ospeed/global +overlay/window locks(source, target) +overwrite/window locks(source, target) +pair_content/screen +pecho_wchar/screen +pechochar/screen +pnoutrefresh/screen +prefresh/screen +printw/window +putp/global +putwin/window +qiflush/terminal +raw/screen +redrawwin/window +refresh/screen +reset_prog_mode/screen +reset_shell_mode/screen +resetty/terminal +resize_term/screen locks(windowlist) +resizeterm/screen +restartterm/screen +ripoffline/global (static data) +savetty/terminal +scanw/screen +scr_dump/screen +scr_init/screen +scr_restore/screen +scr_set/screen +scrl/window (stdscr) +scroll/window +scrollok/window +set_curterm/screen +set_escdelay/screen +set_tabsize/screen +set_term/global locks(screenlist, screen) +setcchar/reentrant +setscrreg/window (stdscr) +setupterm/global +slk_attr/screen +slk_attr_off/screen +slk_attr_on/screen +slk_attr_set/screen +slk_attroff/screen +slk_attron/screen +slk_attrset/screen +slk_clear/screen +slk_color/screen +slk_init/screen +slk_label/screen +slk_noutrefresh/screen +slk_refresh/screen +slk_restore/screen +slk_set/screen +slk_touch/screen +slk_wset/screen +standend/window +standout/window +start_color/screen +stdscr/screen (readonly) +strcodes/global (readonly) +strfnames/global (readonly) +strnames/global (readonly) +subpad/window +subwin/window +syncok/window +term_attrs/screen +termattrs/screen +termname/terminal +tgetent/global +tgetflag/global +tgetnum/global +tgetstr/global +tgoto/global +tigetflag/terminal +tigetnum/terminal +tigetstr/terminal +timeout/window (stdscr) +touchline/window +touchwin/window +tparm/global (static data) +tputs/screen +trace/global (static data) +ttytype/screen (readonly) +typeahead/screen +unctrl/screen +unget_wch/screen (input-operation) +ungetch/screen (input-operation) +ungetmouse/screen (input-operation) +untouchwin/window +use_default_colors/screen +use_env/global (static data) +use_extended_names/global (static data) +use_legacy_coding/screen +use_screen/global locks(screenlist, screen) +use_window/global locks(windowlist, window) +vid_attr/screen +vid_puts/screen +vidattr/screen +vidputs/screen +vline/window (stdscr) +vline_set/window (stdscr) +vw_printw/window +vw_scanw/screen +vwprintw/window +vwscanw/screen +wadd_wch/window +wadd_wchnstr/window +wadd_wchstr/window +waddch/window +waddchnstr/window +waddchstr/window +waddnstr/window +waddnwstr/window +waddstr/window +waddwstr/window +wattr_get/window +wattr_off/window +wattr_on/window +wattr_set/window +wattroff/window +wattron/window +wattrset/window +wbkgd/window +wbkgdset/window +wbkgrnd/window +wbkgrndset/window +wborder/window +wborder_set/window +wchgat/window +wclear/window +wclrtobot/window +wclrtoeol/window +wcolor_set/window +wcursyncup/screen (affects window plus parents) +wdelch/window +wdeleteln/window +wecho_wchar/window +wechochar/window +wenclose/window +werase/window +wget_wch/screen (input-operation) +wget_wstr/screen (input-operation) +wgetbkgrnd/window +wgetch/screen (input-operation) +wgetdelay/window +wgetn_wstr/screen (input-operation) +wgetnstr/screen (input-operation) +wgetparent/window +wgetscrreg/window +wgetstr/screen (input-operation) +whline/window +whline_set/window +win_wch/window +win_wchnstr/window +win_wchstr/window +winch/window +winchnstr/window +winchstr/window +winnstr/window +winnwstr/window +wins_nwstr/window +wins_wch/window +wins_wstr/window +winsch/window +winsdelln/window +winsertln/window +winsnstr/window +winsstr/window +winstr/window +winwstr/window +wmouse_trafo/window +wmove/window +wnoutrefresh/screen +wprintw/window +wredrawln/window +wrefresh/screen +wresize/window locks(windowlist) +wscanw/screen +wscrl/window +wsetscrreg/window +wstandend/window +wstandout/window +wsyncdown/screen (affects window plus parents) +wsyncup/screen (affects window plus parents) +wtimeout/window +wtouchln/window +wunctrl/global (static data) +wvline/window +wvline_set/window +.TE +.\" *************************************************************************** +.SH RETURN VALUE +These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted. +.SH NOTES +Both a macro and a function are provided for each name. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on Version 7, BSD or System V implementations. +It is recommended that any code depending on ncurses extensions +be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_opaque\fP(3), +\fBcurs_variables\fP(3). diff --git a/static/openbsd/man3/curs_touch.3 b/static/openbsd/man3/curs_touch.3 new file mode 100644 index 00000000..19f42032 --- /dev/null +++ b/static/openbsd/man3/curs_touch.3 @@ -0,0 +1,129 @@ +.\" $OpenBSD: curs_touch.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_touch.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.TH curs_touch 3 2023-07-01 "ncurses 6.4" "Library calls" +.na +.hy 0 +.SH NAME +\fBtouchwin\fP, +\fBtouchline\fP, +\fBuntouchwin\fP, +\fBwtouchln\fP, +\fBis_linetouched\fP, +\fBis_wintouched\fP \- \fBcurses\fP refresh control routines +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint touchline(WINDOW *\fIwin\fB, int \fIstart\fB, int \fIcount\fB);\fR +.sp +\fBint touchwin(WINDOW *\fIwin\fB);\fR +.br +\fBint wtouchln(WINDOW *\fIwin\fB, int \fIy\fB, int \fIn\fB, int \fIchanged\fB);\fR +.sp +\fBint untouchwin(WINDOW *\fIwin\fB);\fR +.sp +\fBbool is_linetouched(WINDOW *\fIwin\fB, int \fIline\fB);\fR +.br +\fBbool is_wintouched(WINDOW *\fIwin\fB);\fR +.SH DESCRIPTION +The \fBtouchwin\fP and \fBtouchline\fP routines throw away all +optimization information about which parts of the window have been +touched, by pretending that the entire window has been drawn on. +This +is sometimes necessary when using overlapping windows, since a change +to one window affects the other window, but the records of which lines +have been changed in the other window do not reflect the change. +The +routine \fBtouchline\fP only pretends that \fIcount\fP lines have been +changed, beginning with line \fIstart\fP. +.PP +The \fBuntouchwin\fP routine marks all lines in the window as unchanged since +the last call to \fBwrefresh\fP. +.PP +The \fBwtouchln\fP routine makes \fIn\fP lines in the window, starting +at line \fIy\fR, look as if they have (\fIchanged\fB=1\fR) or have +not (\fIchanged\fB=0\fR) been changed since the last call to +\fBwrefresh\fP. +.PP +The \fBis_linetouched\fP and \fBis_wintouched\fP routines return +\fBTRUE\fP if the specified line/window was modified since the last +call to \fBwrefresh\fP; otherwise they return \fBFALSE\fP. In +addition, \fBis_linetouched\fP returns \fBERR\fP if \fIline\fP is not +valid for the given window. +.SH RETURN VALUE +All routines return the integer \fBERR\fP upon failure and an integer value +other than \fBERR\fP upon successful completion, unless otherwise noted in the +preceding routine descriptions. +.PP +X/Open does not define any error conditions. +In this implementation +.RS 3 +.TP 5 +\fBis_linetouched\fP +returns an error +if the window pointer is null, or +if the line number is outside the window. +.IP +The constant \fBERR\fP is distinct from \fBTRUE\fP and \fBFALSE\fP, +which are the normal return values of this function. +Because the function returns a \fBbool\fP, +returning \fBERR\fP (which is neither \fBTRUE\fP nor \fBFALSE\fP) +may not be supported by the compiler. +.IP +To provide error-checking and also match the X/Open function prototype, +the \fBERR\fP is provided by a macro named \fBis_linetouched\fP. +The actual function returns \fBFALSE\fP when it detects an error. +.TP 5 +\fBwtouchln\fP +returns an error +if the window pointer is null, or +if the line number is outside the window. +.RE +.SH PORTABILITY +These functions were introduced by SVr4. +The Solaris curses header file, +for instance, defines both an actual function and macro for each. +The macros give the same result as the actual functions. +SVr4 curses does not check the window parameter \fIwin\fP to ensure +that it is not \fBNULL\fP; +otherwise this implementation behaves the same as SVr4. +.PP +The XSI Curses standard, Issue 4 describes these functions, +but defines no error conditions. +.SH NOTES +All of these routines except \fBwtouchln\fP may be macros. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_variables\fP(3). diff --git a/static/openbsd/man3/curs_util.3 b/static/openbsd/man3/curs_util.3 new file mode 100644 index 00000000..01a69466 --- /dev/null +++ b/static/openbsd/man3/curs_util.3 @@ -0,0 +1,411 @@ +'\" t +.\" $OpenBSD: curs_util.3,v 1.7 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_util.3,v 1.7 2023/10/17 09:52:08 nicm Exp $ +.TH curs_util 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBdelay_output\fP, +\fBfilter\fP, +\fBflushinp\fP, +\fBgetwin\fP, +\fBkey_name\fP, +\fBkeyname\fP, +\fBnofilter\fP, +\fBputwin\fP, +\fBunctrl\fP, +\fBuse_env\fP, +\fBuse_tioctl\fP, +\fBwunctrl\fP \- miscellaneous \fBcurses\fP utility routines +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBconst char *unctrl(chtype \fIc\fB);\fR +.br +\fBwchar_t *wunctrl(cchar_t *\fIc\fB);\fR +.sp +\fBconst char *keyname(int \fIc\fB);\fR +.br +\fBconst char *key_name(wchar_t \fIw\fB);\fR +.sp +\fBvoid filter(void);\fP +.sp +\fBvoid use_env(bool \fIf\fB);\fR +.sp +\fBint putwin(WINDOW *\fIwin\fB, FILE *\fIfilep\fB);\fR +.br +\fBWINDOW *getwin(FILE *\fIfilep\fB);\fR +.sp +\fBint delay_output(int \fIms\fB);\fR +.br +\fBint flushinp(void);\fP +.sp +/* extensions */ +.br +\fBvoid nofilter(void);\fP +.br +\fBvoid use_tioctl(bool \fIf\fB);\fR +.SH DESCRIPTION +.SS unctrl +The \fBunctrl\fP routine returns a character string which is a printable +representation of the character \fIc\fP: +.bP +Printable characters are displayed as themselves, +e.g., a one-character string containing the key. +.bP +Control characters are displayed in the \fB^\fIX\fR notation. +.bP +Printing characters are displayed as is. +.bP +DEL (character 127) is displayed as \fB^?\fP. +.bP +Values above 128 are either meta characters +(if the screen has not been initialized, +or if \fBmeta\fP(3) has been called with a \fBTRUE\fP parameter), +shown in the \fBM\-\fIX\fR notation, +or are displayed as themselves. +In the latter case, the values may not be printable; +this follows the X/Open specification. +.PP +The corresponding \fBwunctrl\fP returns a printable representation of +a complex character \fIc\fP. +.PP +In both \fBunctrl\fP and \fBwunctrl\fP the attributes and color associated +with the character parameter are ignored. +.SS keyname/key_name +The \fBkeyname\fP routine returns a character string +corresponding to the key \fIc\fP. +Key codes are different from character codes. +.bP +Key codes below 256 are characters. +They are displayed using \fBunctrl\fP. +.bP +Values above 256 may be the codes for function keys. +The function key name is displayed. +.bP +Otherwise (if there is no corresponding name and the key is not a character) +the function returns null, to denote an error. +X/Open also lists an \*(``UNKNOWN KEY\*('' return value, +which some implementations return rather than null. +.LP +The corresponding \fBkey_name\fP returns +a multibyte character string corresponding +to the wide-character value \fIw\fP. +The two functions (\fBkeyname\fP and \fBkey_name\fP) +do not return the same set of strings: +.bP +\fBkeyname\fP returns null where \fBkey_name\fP would display a meta character. +.bP +\fBkey_name\fP does not return the name of a function key. +.SS filter/nofilter +The \fBfilter\fP routine, if used, must be called before \fBinitscr\fP or +\fBnewterm\fP are called. +Calling \fBfilter\fP causes these changes in initialization: +.bP +\fBLINES\fP is set to 1; +.bP +the capabilities +\fBclear\fP, +\fBcud1\fP, +\fBcud\fP, +\fBcup\fP, +\fBcuu1\fP, +\fBcuu\fP, +\fBvpa\fP +are disabled; +.bP +the capability \fBed\fP is disabled if \fBbce\fP is set; +.bP +and the \fBhome\fP string is set to the value of \fBcr\fP. +.PP +The \fBnofilter\fP routine cancels the effect of a preceding \fBfilter\fP +call. +That allows the caller to initialize a screen on a different device, +using a different value of \fB$TERM\fP. +The limitation arises because the \fBfilter\fP routine modifies the +in-memory copy of the terminal information. +.SS use_env +The \fBuse_env\fP routine, if used, +should be called before \fBinitscr\fP or +\fBnewterm\fP are called +(because those compute the screen size). +It modifies the way \fBncurses\fP treats environment variables +when determining the screen size. +.bP +Normally \fBncurses\fP looks first at the terminal database for the screen size. +.IP +If \fBuse_env\fP was called with \fBFALSE\fP for parameter, +it stops here unless +\fBuse_tioctl\fP was also called with \fBTRUE\fP for parameter. +.bP +Then it asks for the screen size via operating system calls. +If successful, +it overrides the values from the terminal database. +.bP +Finally (unless \fBuse_env\fP was called with \fBFALSE\fP parameter), +\fBncurses\fP examines the \fBLINES\fP or \fBCOLUMNS\fP environment variables, +using a value in those to override the results +from the operating system or terminal database. +.IP +\fBNcurses\fP also updates the screen size in response to \fBSIGWINCH\fP, +unless overridden by the \fBLINES\fP or \fBCOLUMNS\fP environment variables, +.SS use_tioctl +The \fBuse_tioctl\fP routine, if used, +should be called before \fBinitscr\fP or \fBnewterm\fP are called +(because those compute the screen size). +After \fBuse_tioctl\fP is called with \fBTRUE\fP as an argument, +\fBncurses\fP modifies the last step in its computation +of screen size as follows: +.bP +checks if the \fBLINES\fP and \fBCOLUMNS\fP environment variables +are set to a number greater than zero. +.bP +for each, \fBncurses\fP updates the corresponding environment variable +with the value that it has obtained via operating system call +or from the terminal database. +.bP +\fBncurses\fP re-fetches the value of the environment variables so that +it is still the environment variables which set the screen size. +.PP +The \fBuse_env\fP and \fBuse_tioctl\fP routines combine as +summarized here: +.PP +.TS +center tab(/); +l l l +_ _ _ +lw7 lw7 lw40. +\fBuse_env\fP/\fBuse_tioctl\fP/\fBSummary\fP +TRUE/FALSE/T{ +This is the default behavior. +\fBncurses\fP uses operating system calls +unless overridden by $LINES or $COLUMNS environment variables. +T} +TRUE/TRUE/T{ +\fBncurses\fP updates $LINES and $COLUMNS based on operating system calls. +T} +FALSE/TRUE/T{ +\fBncurses\fP ignores $LINES and $COLUMNS, +uses operating system calls to obtain size. +T} +FALSE/FALSE/T{ +\fBncurses\fP relies on the terminal database to determine size. +T} +.TE +.SS putwin/getwin +The \fBputwin\fP routine writes all data associated +with window (or pad) \fIwin\fP into +the file to which \fIfilep\fP points. +This information can be later retrieved +using the \fBgetwin\fP function. +.PP +The \fBgetwin\fP routine reads window related data stored in the file by +\fBputwin\fP. +The routine then creates and initializes a new window using that +data. +It returns a pointer to the new window. +There are a few caveats: +.bP +the data written is a copy of the \fBWINDOW\fP structure, +and its associated character cells. +The format differs between the wide-character (\fBncursesw\fP) and +non-wide (\fBncurses\fP) libraries. +You can transfer data between the two, however. +.bP +the retrieved window is always created as a top-level window (or pad), +rather than a subwindow. +.bP +the window's character cells contain the color pair \fIvalue\fP, +but not the actual color \fInumbers\fP. +If cells in the retrieved window use color pairs which have not been +created in the application using \fBinit_pair\fP, +they will not be colored when the window is refreshed. +.SS delay_output +The \fBdelay_output\fP routine inserts an \fIms\fP millisecond pause +in output. +This routine should not be used extensively because +padding characters are used rather than a CPU pause. +If no padding character is specified, +this uses \fBnapms\fP to perform the delay. +.SS flushinp +The \fBflushinp\fP routine throws away any typeahead that has been typed by the +user and has not yet been read by the program. +.SH RETURN VALUE +Except for \fBflushinp\fP, routines that return an integer return \fBERR\fP +upon failure and \fBOK\fP (SVr4 specifies only "an integer value other than +\fBERR\fP") upon successful completion. +.PP +Routines that return pointers return \fBNULL\fP on error. +.PP +X/Open does not define any error conditions. +In this implementation +.RS 3 +.TP 5 +\fBflushinp\fP +returns an error if the terminal was not initialized. +.TP 5 +\fBputwin\fP +returns an error if the associated \fBfwrite\fP calls return an error. +.RE +.SH PORTABILITY +.SS filter +The SVr4 documentation describes the action of \fBfilter\fP only in the vaguest +terms. +The description here is adapted from the XSI Curses standard (which +erroneously fails to describe the disabling of \fBcuu\fP). +.SS keyname +The \fBkeyname\fP function may return the names of user-defined +string capabilities which are defined in the terminfo entry via the \fB\-x\fP +option of \fBtic\fP. +This implementation automatically assigns at run-time keycodes to +user-defined strings which begin with \*(``k\*(''. +The keycodes start at KEY_MAX, but are not guaranteed to be +the same value for different runs because user-defined codes are +merged from all terminal descriptions which have been loaded. +The \fBuse_extended_names\fP(3) function controls whether this data is +loaded when the terminal description is read by the library. +.SS nofilter/use_tioctl +The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to \fBncurses\fP. +They were not supported on Version 7, BSD or System V implementations. +It is recommended that any code depending on \fBncurses\fP extensions +be conditioned using NCURSES_VERSION. +.SS putwin/getwin file-format +The \fBputwin\fP and \fBgetwin\fP functions have several issues with +portability: +.bP +The files written and read by these functions +use an implementation-specific format. +Although the format is an obvious target for standardization, +it has been overlooked. +.IP +Interestingly enough, according to the copyright dates in Solaris source, +the functions (along with \fBscr_init\fP, etc.) originated with +the University of California, Berkeley (in 1982) +and were later (in 1988) incorporated into SVr4. +Oddly, there are no such functions in the 4.3BSD curses sources. +.bP +Most implementations simply dump the binary \fBWINDOW\fP structure to the file. +These include SVr4 curses, NetBSD and PDCurses, +as well as older \fBncurses\fP versions. +This implementation +(as well as the X/Open variant of Solaris curses, dated 1995) +uses textual dumps. +.IP +The implementations which use binary dumps use block-I/O +(the \fBfwrite\fP and \fBfread\fP functions). +Those that use textual dumps use buffered-I/O. +A few applications may happen to write extra data in the file using +these functions. +Doing that can run into problems mixing block- and buffered-I/O. +This implementation reduces the problem on writes by flushing the output. +However, reading from a file written using mixed schemes may not be successful. +.SS unctrl/wunctrl +The XSI Curses standard, Issue 4 describes these functions. +It states that \fBunctrl\fP and \fBwunctrl\fP will return a null pointer if +unsuccessful, but does not define any error conditions. +This implementation checks for three cases: +.bP +the parameter is a 7-bit US\-ASCII code. +This is the case that X/Open Curses documented. +.bP +the parameter is in the range 128\-159, i.e., a C1 control code. +If \fBuse_legacy_coding\fP(3) has been called with a \fB2\fP parameter, +\fBunctrl\fP returns the parameter, i.e., a one-character string with +the parameter as the first character. +Otherwise, it returns \*(``~@\*('', \*(``~A\*('', etc., +analogous to \*(``^@\*('', \*(``^A\*('', C0 controls. +.IP +X/Open Curses does not document whether \fBunctrl\fP can be called before +initializing curses. +This implementation permits that, +and returns the \*(``~@\*('', etc., values in that case. +.bP +parameter values outside the 0 to 255 range. +\fBunctrl\fP returns a null pointer. +.PP +The strings returned by \fBunctrl\fP in this implementation are determined +at compile time, +showing C1 controls from the upper-128 codes +with a \*(``~\*('' prefix rather than \*(``^\*(''. +Other implementations have different conventions. +For example, they may show both sets of control characters with \*(``^\*('', +and strip the parameter to 7 bits. +Or they may ignore C1 controls and treat all of the upper-128 codes as +printable. +This implementation uses 8 bits but does not modify the string to reflect +locale. +The \fBuse_legacy_coding\fP(3) function allows the caller to +change the output of \fBunctrl\fP. +.PP +Likewise, the \fBmeta\fP(3) function allows the caller to change the +output of \fBkeyname\fP, i.e., +it determines whether to use the \*(``M\-\*('' prefix +for \*(``meta\*('' keys (codes in the range 128 to 255). +Both \fBuse_legacy_coding\fP(3) and \fBmeta\fP(3) succeed only after +curses is initialized. +X/Open Curses does not document the treatment of codes 128 to 159. +When treating them as \*(``meta\*('' keys +(or if \fBkeyname\fP is called before initializing curses), +this implementation returns strings \*(``M\-^@\*('', \*(``M\-^A\*('', etc. +.PP +X/Open Curses documents \fBunctrl\fP as declared in \fB\fP, +which \fBncurses\fP does. +However, \fBncurses\fP' \fB\fP includes \fB\fP, +matching the behavior of SVr4 curses. +Other implementations may not do that. +.SS use_env/use_tioctl +If \fBncurses\fP is configured to provide the sp-functions extension, +the state of \fBuse_env\fP and \fBuse_tioctl\fP may be updated before +creating each \fIscreen\fP rather than once only +(\fBcurs_sp_funcs\fP(3)). +This feature of \fBuse_env\fP +is not provided by other implementations of curses. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_initscr\fP(3), +\fBcurs_inopts\fP(3), +\fBcurs_kernel\fP(3), +\fBcurs_scr_dump\fP(3), +\fBcurs_sp_funcs\fP(3), +\fBcurs_variables\fP(3), +\fBlegacy_coding\fP(3). diff --git a/static/openbsd/man3/curs_variables.3 b/static/openbsd/man3/curs_variables.3 new file mode 100644 index 00000000..658502b2 --- /dev/null +++ b/static/openbsd/man3/curs_variables.3 @@ -0,0 +1,188 @@ +.\"*************************************************************************** +.\" Copyright 2018-2020,2021 Thomas E. Dickey * +.\" Copyright 2010-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_variables.3,v 1.1 2023/10/17 09:52:08 nicm Exp $ +.TH curs_variables 3 2021-12-25 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.ds n 5 +.na +.hy 0 +.SH NAME +\fBCOLORS\fP, +\fBCOLOR_PAIRS\fP, +\fBCOLS\fP, +\fBESCDELAY\fP, +\fBLINES\fP, +\fBTABSIZE\fP, +\fBcurscr\fP, +\fBnewscr\fP, +\fBstdscr\fP +\- \fBcurses\fP global variables +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +.PP +\fBint COLOR_PAIRS;\fP +.br +\fBint COLORS;\fP +.br +\fBint COLS;\fP +.br +\fBint ESCDELAY;\fP +.br +\fBint LINES;\fP +.br +\fBint TABSIZE;\fP +.br +\fBWINDOW * curscr;\fP +.br +\fBWINDOW * newscr;\fP +.br +\fBWINDOW * stdscr;\fP +.fi +.SH DESCRIPTION +This page summarizes variables provided by the \fBcurses\fP library. +A more complete description is given in the \fBcurses\fP(3) manual page. +.PP +Depending on the configuration, these may be actual variables, +or macros (see \fBcurs_threads\fP(3) and \fBcurs_opaque\fP(3)) +which provide read-only access to \fIcurses\fP's state. +In either case, applications should treat them as read-only to avoid +confusing the library. +.SS COLOR_PAIRS +After initializing curses, this variable contains the number of color pairs +which the terminal can support. +Usually the number of color pairs will be the product \fBCOLORS\fP*\fBCOLORS\fP, +however this is not always true: +.bP +a few terminals use HLS colors, which do not follow this rule +.bP +terminals supporting a large number of colors are limited by the number +of color pairs that can be represented in a \fIsigned short\fP value. +.SS COLORS +After initializing curses, this variable contains the number of colors +which the terminal can support. +.SS COLS +After initializing curses, this variable contains the width of the screen, +i.e., the number of columns. +.SS ESCDELAY +This variable holds the number of milliseconds to wait after reading an +escape character, +to distinguish between an individual escape character entered on the +keyboard from escape sequences sent by cursor- and function-keys +(see curses(3)). +.SS LINES +After initializing curses, this variable contains the height of the screen, +i.e., the number of lines. +.SS TABSIZE +This variable holds the number of columns used by the \fIcurses\fP library +when converting a tab character to spaces as it adds the tab to a window +(see \fBcurs_addch\fP(3). +.SS The Current Screen +This implementation of curses uses a special window \fBcurscr\fP to +record its updates to the terminal screen. +.PP +This is referred to as the \*(``physical screen\*('' in the +\fBcurs_refresh\fP(3) and +\fBcurs_outopts\fP(3) manual pages. +.SS The New Screen +This implementation of curses uses a special window \fBnewscr\fP to +hold updates to the terminal screen before applying them to \fBcurscr\fP. +.PP +This is referred to as the \*(``virtual screen\*('' in the +\fBcurs_kernel\fP(3), +\fBcurs_refresh\fP(3) and +\fBcurs_outopts\fP(3) manual pages. +.SS The Standard Screen +Upon initializing curses, +a default window called \fBstdscr\fP, +which is the size of the terminal screen, is created. +Many curses functions use this window. +.SH NOTES +The curses library is initialized using either \fBinitscr\fP(3), +or \fBnewterm\fP(3). +.PP +If \fBcurses\fP is configured to use separate curses/terminfo libraries, +most of these variables reside in the curses library. +.SH PORTABILITY +\fBTABSIZE\fP is a feature of SVr4 curses +which is not documented by X/Open curses. +.bP +In SVr4 curses, \fBTABSIZE\fP is initially set from the terminal description's +\fBinit_tabs\fP capability. +After that, it can be altered by the applications using SVr4 curses. +.IP +SVr4 curses uses the current value of \fBTABSIZE\fP to +compute the position of tabstops for updating both +the virtual screen with \fBaddch\fP(3) as well as +the physical screen with \fBmvcur\fP(3). +.bP +This implementation uses the current value of \fBTABSIZE\fP only for +updating the virtual screen. +It uses the terminal description's \fBit\fP (\fBinit_tabs\fP) capability for +computing hardware tabs (i.e., tab stops on the physical screen). +.bP +Other implementations differ. +For instance, NetBSD curses allows \fBTABSIZE\fP to be set through +an environment variable. +This implementation does not. +.IP +NetBSD curses does not support hardware tabs; +it uses the \fBinit_tabs\fP capability and the \fBTABSIZE\fP variable +only for updating the virtual screen. +.PP +\fBESCDELAY\fP is an extension in AIX curses: +.bP +In AIX, the units for \fBESCDELAY\fP are \fIfifths\fP of a millisecond. +.bP +The default value for AIX's \fBESCDELAY\fP is 0.1 seconds. +.bP +AIX also enforces a limit of 10,000 seconds for \fBESCDELAY\fP; +this implementation currently has no upper limit. +.PP +This implementation has long used \fBESCDELAY\fP with units of milliseconds, +making it impossible to be completely compatible with AIX. +Likewise, most users have either decided to override the value, +or rely upon its default value. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_opaque\fP(3), +\fBterminfo\fP(3), +\fBcurs_threads\fP(3), +\fBterm_variables\fP(3), +\fBterminfo\fP(\*n). diff --git a/static/openbsd/man3/curs_window.3 b/static/openbsd/man3/curs_window.3 new file mode 100644 index 00000000..845b2523 --- /dev/null +++ b/static/openbsd/man3/curs_window.3 @@ -0,0 +1,275 @@ +.\" $OpenBSD: curs_window.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2020-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2016 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_window.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.TH curs_window 3 2023-07-01 "ncurses 6.4" "Library calls" +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.SH NAME +\fBnewwin\fP, +\fBdelwin\fP, +\fBmvwin\fP, +\fBsubwin\fP, +\fBderwin\fP, +\fBmvderwin\fP, +\fBdupwin\fP, +\fBwsyncup\fP, +\fBsyncok\fP, +\fBwcursyncup\fP, +\fBwsyncdown\fP \- create \fBcurses\fP windows +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.sp +\fBWINDOW *newwin(\fP + \fBint \fInlines\fB, int \fIncols\fB,\fR + \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR +.br +\fBint delwin(WINDOW *\fIwin\fB);\fR +.br +\fBint mvwin(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR +.br +\fBWINDOW *subwin(WINDOW *\fIorig\fB,\fR + \fBint \fInlines\fB, int \fIncols\fB,\fR + \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR +.br +\fBWINDOW *derwin(WINDOW *\fIorig\fB,\fR + \fBint \fInlines\fB, int \fIncols\fB,\fR + \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR +.br +\fBint mvderwin(WINDOW *\fIwin\fB, int \fIpar_y\fB, int \fIpar_x\fB);\fR +.br +\fBWINDOW *dupwin(WINDOW *\fIwin\fB);\fR +.br +\fBvoid wsyncup(WINDOW *\fIwin\fB);\fR +.br +\fBint syncok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.br +\fBvoid wcursyncup(WINDOW *\fIwin\fB);\fR +.br +\fBvoid wsyncdown(WINDOW *\fIwin\fB);\fR +.SH DESCRIPTION +.SS newwin +Calling \fBnewwin\fP creates and returns a pointer to a new window with the +given number of lines and columns. +The upper left-hand corner of the window is +at +.RS +line \fIbegin\fR_\fIy\fP, +.br +column \fIbegin\fR_\fIx\fP +.RE +.PP +If either +\fInlines\fP or \fIncols\fP is zero, they default to +.RS +\fBLINES \-\fP \fIbegin\fR_\fIy\fP and +.br +\fBCOLS \-\fP \fIbegin\fR_\fIx\fP. +.RE +.PP +A new full-screen window is created by calling \fBnewwin(0,0,0,0)\fP. +.PP +Regardless of the function used for creating a new window +(e.g., \fBnewwin\fP, \fBsubwin\fP, \fBderwin\fP, \fBnewpad\fP), +rather than a duplicate (with \fBdupwin\fP), +all of the window modes are initialized to the default values. +These functions set window modes after a window is created: +.RS +.na +.PP +idcok, +idlok, +immedok, +keypad, +leaveok, +nodelay, +scrollok, +setscrreg, +syncok, +wbkgdset, +wbkgrndset, and +wtimeout +.RE +.ad +.SS delwin +Calling \fBdelwin\fP deletes the named window, freeing all memory +associated with it (it does not actually erase the window's screen +image). +Subwindows must be deleted before the main window can be deleted. +.SS mvwin +Calling \fBmvwin\fP moves the window so that the upper left-hand +corner is at position (\fIx\fP, \fIy\fP). +If the move would cause the window to be off the screen, +it is an error and the window is not moved. +Moving subwindows is allowed, but should be avoided. +.SS subwin +Calling \fBsubwin\fP creates and returns a pointer to a new window +with the given number of lines, \fInlines\fP, and columns, \fIncols\fP. +The window is at position (\fIbegin\fR_\fIy\fP, +\fIbegin\fR_\fIx\fP) on the screen. +The subwindow shares memory with the window \fIorig\fP, +so that changes made to one window +will affect both windows. +When using this routine, it is necessary to call +\fBtouchwin\fP or \fBtouchline\fP on \fIorig\fP before calling +\fBwrefresh\fP on the subwindow. +.SS derwin +Calling \fBderwin\fP is the same as calling \fBsubwin,\fP except that +\fIbegin\fR_\fIy\fP and \fIbegin\fR_\fIx\fP are relative to the origin +of the window \fIorig\fP rather than the screen. +There is no difference between the subwindows and the derived windows. +.PP +Calling \fBmvderwin\fP moves a derived window (or subwindow) +inside its parent window. +The screen-relative parameters of the window are not changed. +This routine is used to display different +parts of the parent window at the same physical position on the +screen. +.SS dupwin +Calling \fBdupwin\fP creates an exact duplicate of the window \fIwin\fP. +.SS wsyncup +Calling \fBwsyncup\fP touches all locations in ancestors of \fIwin\fP that are +changed in \fIwin\fP. +If \fBsyncok\fP is called with second argument +\fBTRUE\fP then \fBwsyncup\fP is called automatically whenever there is a +change in the window. +.SS wsyncdown +The \fBwsyncdown\fP routine touches each location in \fIwin\fP that has been +touched in any of its ancestor windows. +This routine is called by +\fBwrefresh\fP, so it should almost never be necessary to call it manually. +.SS wcursyncup +The routine \fBwcursyncup\fP updates the current cursor position of all the +ancestors of the window to reflect the current cursor position of the +window. +.SH RETURN VALUE +Routines that return an integer return the integer \fBERR\fP upon failure and +\fBOK\fP (SVr4 only specifies "an integer value other than \fBERR\fP") upon +successful completion. +.PP +Routines that return pointers return \fBNULL\fP on error. +.PP +X/Open defines no error conditions. +In this implementation +.TP 5 +\fBdelwin\fP +returns an error if the window pointer is null, or +if the window is the parent of another window. +.TP 5 +\fBderwin\fP +returns an error if the parent window pointer is null, or +if any of its ordinates or dimensions is negative, or +if the resulting window does not fit inside the parent window. +.TP 5 +\fBdupwin\fP +returns an error if the window pointer is null. +.IP +This implementation also maintains a list of windows, +and checks that the pointer passed to \fBdelwin\fP is one that +it created, returning an error if it was not.. +.TP 5 +\fBmvderwin\fP +returns an error +if the window pointer is null, or +if some part of the window would be placed off-screen. +.TP 5 +\fBmvwin\fP +returns an error +if the window pointer is null, or +if the window is really a pad, or +if some part of the window would be placed off-screen. +.TP 5 +\fBnewwin\fP +will fail if either of its beginning ordinates is negative, or +if either the number of lines or columns is negative. +.TP 5 +\fBsyncok\fP +returns an error +if the window pointer is null. +.TP 5 +\fBsubwin\fP +returns an error if the parent window pointer is null, or +if any of its ordinates or dimensions is negative, or +if the resulting window does not fit inside the parent window. +.PP +The functions which return a window pointer +may also fail if there is insufficient memory for its data structures. +Any of these functions will fail if the screen has not been initialized, +i.e., with \fBinitscr\fP or \fBnewterm\fP. +.SH NOTES +If many small changes are made to the window, the \fBwsyncup\fP option could +degrade performance. +.PP +Note that \fBsyncok\fP may be a macro. +.SH BUGS +The subwindow functions (\fBsubwin\fP, \fBderwin\fP, \fBmvderwin\fP, +\fBwsyncup\fP, \fBwsyncdown\fP, \fBwcursyncup\fP, \fBsyncok\fP) are flaky, +incompletely implemented, and not well tested. +.PP +The System V curses documentation is very unclear about what \fBwsyncup\fP +and \fBwsyncdown\fP actually do. +It seems to imply that they are only +supposed to touch exactly those lines that are affected by ancestor changes. +The language here, and the behavior of the \fBcurses\fP implementation, +is patterned on the XPG4 curses standard. +The weaker XPG4 spec may result in slower updates. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +.PP +X/Open Curses states regarding \fBdelwin\fP: +.bP +It must delete subwindows before deleting their parent. +.bP +If \fBdelwin\fP is asked to delete a parent window, +it can only succeed if the curses library keeps a list of the subwindows. +SVr4 curses kept a count of the number of subwindows rather than a list. +It simply returned \fBERR\fP when asked to delete a subwindow. +Solaris X/Open curses does not even make that check, +and will delete a parent window which still has subwindows. +.bP +Since release 4.0 (1996), ncurses maintains a list of windows for each screen, +to ensure that a window has no subwindows before allowing deletion. +.bP +NetBSD copied this feature of ncurses in 2003. +.br +PDCurses follows the scheme used in Solaris X/Open curses. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_initscr\fP(3), +\fBcurs_refresh\fP(3), +\fBcurs_touch\fP(3), +\fBcurs_variables\fP(3) diff --git a/static/openbsd/man3/curses.3 b/static/openbsd/man3/curses.3 new file mode 100644 index 00000000..e696cc92 --- /dev/null +++ b/static/openbsd/man3/curses.3 @@ -0,0 +1,1537 @@ +'\" t +.\" $OpenBSD: curses.3,v 1.6 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curses.3,v 1.6 2023/10/17 09:52:08 nicm Exp $ +.hy 0 +.TH ncurses 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.de NS +.ie n .sp +.el .sp .5 +.ie n .in +4 +.el .in +2 +.nf +.ft CR \" Courier +.. +.de NE +.fi +.ft R +.ie n .in -4 +.el .in -2 +.. +.ds n 5 +.ds d /usr/share/terminfo +.SH NAME +\fBncurses\fP \- CRT screen handling and optimization package +.SH SYNOPSIS +\fB#include \fP +.SH DESCRIPTION +The \fBncurses\fP library routines give the user a terminal-independent method +of updating character screens with reasonable optimization. +This implementation is \*(``new curses\*('' (ncurses) and +is the approved replacement for +4.4BSD classic curses, which has been discontinued. +This describes \fBncurses\fP +version 6.4 (patch 20230826). +.PP +The \fBncurses\fP library emulates the curses library of +System V Release 4 UNIX, +and XPG4 (X/Open Portability Guide) curses (also known as XSI curses). +XSI stands for X/Open System Interfaces Extension. +The \fBncurses\fP library is freely redistributable in source form. +Differences from the SVr4 +curses are summarized under the +\fIEXTENSIONS\fP and \fIPORTABILITY\fP sections below and +described in detail in the respective +\fIEXTENSIONS\fP, \fIPORTABILITY\fP and \fIBUGS\fP sections +of individual man pages. +.PP +The \fBncurses\fP library also provides many useful extensions, +i.e., features which cannot be implemented by a simple add-on library +but which require access to the internals of the library. +.PP +A program using these routines must be linked with the \fB\-lncurses\fP option, +or (if it has been generated) with the debugging library \fB\-lncurses_g\fP. +(Your system integrator may also have installed these libraries under +the names \fB\-lcurses\fP and \fB\-lcurses_g\fP.) +The ncurses_g library generates trace logs +(in a file called \*(``trace\*('' in the current directory) +that describe curses actions. +See also the section on \fBALTERNATE CONFIGURATIONS\fP. +.PP +The \fBncurses\fP package supports: overall screen, window and pad +manipulation; output to windows and pads; reading terminal input; control over +terminal and \fBcurses\fP input and output options; environment query +routines; color manipulation; use of soft label keys; terminfo capabilities; +and access to low-level terminal-manipulation routines. +.SS Initialization +The library uses the locale which the calling program has initialized. +That is normally done with \fBsetlocale\fP(3): +.NS +\fBsetlocale(LC_ALL, "");\fP +.NE +.PP +If the locale is not initialized, +the library assumes that characters are printable as in ISO\-8859\-1, +to work with certain legacy programs. +You should initialize the locale and not rely on specific details of +the library when the locale has not been setup. +.PP +The function \fBinitscr\fP or \fBnewterm\fP +must be called to initialize the library +before any of the other routines that deal with windows +and screens are used. +The routine \fBendwin\fP(3) must be called before exiting. +.PP +To get character-at-a-time input without echoing (most +interactive, screen oriented programs want this), the following +sequence should be used: +.NS +\fBinitscr(); cbreak(); noecho();\fP +.NE +.PP +Most programs would additionally use the sequence: +.NS +\fBintrflush(stdscr, FALSE);\fP +\fBkeypad(stdscr, TRUE);\fP +.NE +.PP +Before a \fBcurses\fP program is run, the tab stops of the terminal +should be set and its initialization strings, if defined, must be output. +This can be done by executing the \fBtput init\fP command +after the shell environment variable \fBTERM\fP has been exported. +\fBtset(1)\fP is usually responsible for doing this. +[See \fBterminfo\fP(\*n) for further details.] +.SS Datatypes +The \fBncurses\fP library permits manipulation of data structures, +called \fIwindows\fP, which can be thought of as two-dimensional +arrays of characters representing all or part of a CRT screen. +A default window called \fBstdscr\fP, which is the size of the terminal +screen, is supplied. +Others may be created with \fBnewwin\fP. +.PP +Note that \fBcurses\fP does not handle overlapping windows, that's done by +the \fBpanel\fP(3) library. +This means that you can either use +\fBstdscr\fP or divide the screen into tiled windows and not using +\fBstdscr\fP at all. +Mixing the two will result in unpredictable, and undesired, effects. +.PP +Windows are referred to by variables declared as \fBWINDOW *\fP. +These data structures are manipulated with routines described here and +elsewhere in the \fBncurses\fP manual pages. +Among those, the most basic +routines are \fBmove\fP and \fBaddch\fP. +More general versions of +these routines are included with names beginning with \fBw\fP, +allowing the user to specify a window. +The routines not beginning +with \fBw\fP affect \fBstdscr\fP. +.PP +After using routines to manipulate a window, \fBrefresh\fP(3) is called, +telling \fBcurses\fP to make the user's CRT screen look like +\fBstdscr\fP. +The characters in a window are actually of type +\fBchtype\fP, (character and attribute data) so that other information +about the character may also be stored with each character. +.PP +Special windows called \fIpads\fP may also be manipulated. +These are windows +which are not constrained to the size of the screen and whose contents need not +be completely displayed. +See \fBcurs_pad\fP(3) for more information. +.PP +In addition to drawing characters on the screen, video attributes and colors +may be supported, causing the characters to show up in such modes as +underlined, in reverse video, or in color on terminals that support such +display enhancements. +Line drawing characters may be specified to be output. +On input, \fBcurses\fP is also able to translate arrow and function keys that +transmit escape sequences into single values. +The video attributes, line +drawing characters, and input values use names, defined in \fB\fP, +such as \fBA_REVERSE\fP, \fBACS_HLINE\fP, and \fBKEY_LEFT\fP. +.SS Environment variables +If the environment variables \fBLINES\fP and \fBCOLUMNS\fP are set, or if the +program is executing in a window environment, line and column information in +the environment will override information read by \fIterminfo\fP. +This would affect a program running in an AT&T 630 layer, +for example, where the size of a +screen is changeable (see \fBENVIRONMENT\fP). +.PP +If the environment variable \fBTERMINFO\fP is defined, any program using +\fBcurses\fP checks for a local terminal definition before checking in the +standard place. +For example, if \fBTERM\fP is set to \fBatt4424\fP, then the +compiled terminal definition is found in +.NS +\fB\*d/a/att4424\fP. +.NE +.PP +(The \fBa\fP is copied from the first letter of \fBatt4424\fP to avoid +creation of huge directories.) However, if \fBTERMINFO\fP is set to +\fB$HOME/myterms\fP, \fBcurses\fP first checks +.NS +\fB$HOME/myterms/a/att4424\fP, +.NE +.PP +and if that fails, it then checks +.NS +\fB\*d/a/att4424\fP. +.NE +.PP +This is useful for developing experimental definitions or when write +permission in \fB\*d\fP is not available. +.PP +The integer variables \fBLINES\fP and \fBCOLS\fP are defined in +\fB\fP and will be filled in by \fBinitscr\fP with the size of the +screen. +The constants \fBTRUE\fP and \fBFALSE\fP have the values \fB1\fP and +\fB0\fP, respectively. +.PP +The \fBcurses\fP routines also define the \fBWINDOW *\fP variable \fBcurscr\fP +which is used for certain low-level operations like clearing and redrawing a +screen containing garbage. +The \fBcurscr\fP can be used in only a few routines. +.\" +.SS Routine and Argument Names +Many \fBcurses\fP routines have two or more versions. +The routines prefixed with \fIw\fP require a window argument. +The routines prefixed with \fIp\fP require a pad argument. +Those without a prefix generally use \fBstdscr\fP. +.PP +The routines prefixed with \fBmv\fP require a \fIy\fP and \fIx\fP +coordinate to move to before performing the appropriate action. +The \fBmv\fP routines imply a call to \fBmove\fP before the call to the +other routine. +The coordinate \fIy\fP always refers to the row (of +the window), and \fIx\fP always refers to the column. +The upper left-hand corner is always (0,0), not (1,1). +.PP +The routines prefixed with \fBmvw\fP take both a window argument and +\fIx\fP and \fIy\fP coordinates. +The window argument is always specified before the coordinates. +.PP +In each case, \fIwin\fP is the window affected, and \fIpad\fP is the +pad affected; \fIwin\fP and \fIpad\fP are always pointers to type +\fBWINDOW\fP. +.PP +Option setting routines require a Boolean flag \fIbf\fP with the value +\fBTRUE\fP or \fBFALSE\fP; \fIbf\fP is always of type \fBbool\fP. +Most of the data types used in the library routines, +such as \fBWINDOW\fP, \fBSCREEN\fP, \fBbool\fP, and \fBchtype\fP +are defined in \fB\fP. +Types used for the terminfo routines such as +\fBTERMINAL\fP are defined in \fB\fP. +.PP +This manual page describes functions which may appear in any configuration +of the library. +There are two common configurations of the library: +.RS 3 +.TP 5 +.I ncurses +the \*(``normal\*('' library, which handles 8-bit characters. +The normal (8-bit) library stores characters combined with attributes +in \fBchtype\fP data. +.IP +Attributes alone (no corresponding character) may be stored in \fBchtype\fP +or the equivalent \fBattr_t\fP data. +In either case, the data is stored in something like an integer. +.IP +Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBchtype\fP. +.TP 5 +.I ncursesw +the so-called \*(``wide\*('' library, which handles multibyte characters +(see the section on \fBALTERNATE CONFIGURATIONS\fP). +The \*(``wide\*('' library includes all of the calls +from the \*(``normal\*('' library. +It adds about one third more calls using data types which store +multibyte characters: +.RS 5 +.TP 5 +.B cchar_t +corresponds to \fBchtype\fP. +However it is a structure, because more data is stored than can fit into +an integer. +The characters are large enough to require a full integer value \- and there +may be more than one character per cell. +The video attributes and color are stored in separate fields of the structure. +.IP +Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBcchar_t\fP. +.IP +The \fBsetcchar\fP(3) and \fBgetcchar\fP(3) +functions store and retrieve the data from +a \fBcchar_t\fP structure. +.TP 5 +.B wchar_t +stores a \*(``wide\*('' character. +Like \fBchtype\fP, this may be an integer. +.TP 5 +.B wint_t +stores a \fBwchar_t\fP or \fBWEOF\fP \- not the same, though both may have +the same size. +.RE +.IP +The \*(``wide\*('' library provides new functions which are analogous to +functions in the \*(``normal\*('' library. +There is a naming convention which relates many of the normal/wide variants: +a \*(``_w\*('' is inserted into the name. +For example, \fBwaddch\fP becomes \fBwadd_wch\fP. +.RE +.\" +.SS Routine Name Index +The following table lists the \fBcurses\fP routines provided in +the \*(``normal\*('' and \*(``wide\*('' libraries and the names of +the manual pages on which they are described. +Routines flagged with \*(``*\*('' +are ncurses-specific, not described by XPG4 or present in SVr4. +.PP +.TS +center tab(/); +l l +l l . +\fBcurses\fP Routine Name/Manual Page Name += +COLOR_PAIR/\fBcurs_color\fP(3) +PAIR_NUMBER/\fBcurs_attr\fP(3) +add_wch/\fBcurs_add_wch\fP(3) +add_wchnstr/\fBcurs_add_wchstr\fP(3) +add_wchstr/\fBcurs_add_wchstr\fP(3) +addch/\fBcurs_addch\fP(3) +addchnstr/\fBcurs_addchstr\fP(3) +addchstr/\fBcurs_addchstr\fP(3) +addnstr/\fBcurs_addstr\fP(3) +addnwstr/\fBcurs_addwstr\fP(3) +addstr/\fBcurs_addstr\fP(3) +addwstr/\fBcurs_addwstr\fP(3) +alloc_pair/\fBnew_pair\fP(3)* +assume_default_colors/\fBdefault_colors\fP(3)* +attr_get/\fBcurs_attr\fP(3) +attr_off/\fBcurs_attr\fP(3) +attr_on/\fBcurs_attr\fP(3) +attr_set/\fBcurs_attr\fP(3) +attroff/\fBcurs_attr\fP(3) +attron/\fBcurs_attr\fP(3) +attrset/\fBcurs_attr\fP(3) +baudrate/\fBcurs_termattrs\fP(3) +beep/\fBcurs_beep\fP(3) +bkgd/\fBcurs_bkgd\fP(3) +bkgdset/\fBcurs_bkgd\fP(3) +bkgrnd/\fBcurs_bkgrnd\fP(3) +bkgrndset/\fBcurs_bkgrnd\fP(3) +border/\fBcurs_border\fP(3) +border_set/\fBcurs_border_set\fP(3) +box/\fBcurs_border\fP(3) +box_set/\fBcurs_border_set\fP(3) +can_change_color/\fBcurs_color\fP(3) +cbreak/\fBcurs_inopts\fP(3) +chgat/\fBcurs_attr\fP(3) +clear/\fBcurs_clear\fP(3) +clearok/\fBcurs_outopts\fP(3) +clrtobot/\fBcurs_clear\fP(3) +clrtoeol/\fBcurs_clear\fP(3) +color_content/\fBcurs_color\fP(3) +color_set/\fBcurs_attr\fP(3) +copywin/\fBcurs_overlay\fP(3) +curs_set/\fBcurs_kernel\fP(3) +curses_trace/\fBcurs_trace\fP(3)* +curses_version/\fBcurs_extend\fP(3)* +def_prog_mode/\fBcurs_kernel\fP(3) +def_shell_mode/\fBcurs_kernel\fP(3) +define_key/\fBdefine_key\fP(3)* +del_curterm/\fBterminfo\fP(3) +delay_output/\fBcurs_util\fP(3) +delch/\fBcurs_delch\fP(3) +deleteln/\fBcurs_deleteln\fP(3) +delscreen/\fBcurs_initscr\fP(3) +delwin/\fBcurs_window\fP(3) +derwin/\fBcurs_window\fP(3) +doupdate/\fBcurs_refresh\fP(3) +dupwin/\fBcurs_window\fP(3) +echo/\fBcurs_inopts\fP(3) +echo_wchar/\fBcurs_add_wch\fP(3) +echochar/\fBcurs_addch\fP(3) +endwin/\fBcurs_initscr\fP(3) +erase/\fBcurs_clear\fP(3) +erasechar/\fBcurs_termattrs\fP(3) +erasewchar/\fBcurs_termattrs\fP(3) +exit_curses/\fBcurs_memleaks\fP(3)* +exit_terminfo/\fBcurs_memleaks\fP(3)* +extended_color_content/\fBcurs_color\fP(3)* +extended_pair_content/\fBcurs_color\fP(3)* +extended_slk_color/\fBcurs_slk\fP(3)* +filter/\fBcurs_util\fP(3) +find_pair/\fBnew_pair\fP(3)* +flash/\fBcurs_beep\fP(3) +flushinp/\fBcurs_util\fP(3) +free_pair/\fBnew_pair\fP(3)* +get_wch/\fBcurs_get_wch\fP(3) +get_wstr/\fBcurs_get_wstr\fP(3) +getattrs/\fBcurs_attr\fP(3) +getbegx/\fBcurs_legacy\fP(3)* +getbegy/\fBcurs_legacy\fP(3)* +getbegyx/\fBcurs_getyx\fP(3) +getbkgd/\fBcurs_bkgd\fP(3) +getbkgrnd/\fBcurs_bkgrnd\fP(3) +getcchar/\fBcurs_getcchar\fP(3) +getch/\fBcurs_getch\fP(3) +getcurx/\fBcurs_legacy\fP(3)* +getcury/\fBcurs_legacy\fP(3)* +getmaxx/\fBcurs_legacy\fP(3)* +getmaxy/\fBcurs_legacy\fP(3)* +getmaxyx/\fBcurs_getyx\fP(3) +getmouse/\fBcurs_mouse\fP(3)* +getn_wstr/\fBcurs_get_wstr\fP(3) +getnstr/\fBcurs_getstr\fP(3) +getparx/\fBcurs_legacy\fP(3)* +getpary/\fBcurs_legacy\fP(3)* +getparyx/\fBcurs_getyx\fP(3) +getstr/\fBcurs_getstr\fP(3) +getsyx/\fBcurs_kernel\fP(3) +getwin/\fBcurs_util\fP(3) +getyx/\fBcurs_getyx\fP(3) +halfdelay/\fBcurs_inopts\fP(3) +has_colors/\fBcurs_color\fP(3) +has_ic/\fBcurs_termattrs\fP(3) +has_il/\fBcurs_termattrs\fP(3) +has_key/\fBcurs_getch\fP(3)* +has_mouse/\fBcurs_mouse\fP(3)* +hline/\fBcurs_border\fP(3) +hline_set/\fBcurs_border_set\fP(3) +idcok/\fBcurs_outopts\fP(3) +idlok/\fBcurs_outopts\fP(3) +immedok/\fBcurs_outopts\fP(3) +in_wch/\fBcurs_in_wch\fP(3) +in_wchnstr/\fBcurs_in_wchstr\fP(3) +in_wchstr/\fBcurs_in_wchstr\fP(3) +inch/\fBcurs_inch\fP(3) +inchnstr/\fBcurs_inchstr\fP(3) +inchstr/\fBcurs_inchstr\fP(3) +init_color/\fBcurs_color\fP(3) +init_extended_color/\fBcurs_color\fP(3)* +init_extended_pair/\fBcurs_color\fP(3)* +init_pair/\fBcurs_color\fP(3) +initscr/\fBcurs_initscr\fP(3) +innstr/\fBcurs_instr\fP(3) +innwstr/\fBcurs_inwstr\fP(3) +ins_nwstr/\fBcurs_ins_wstr\fP(3) +ins_wch/\fBcurs_ins_wch\fP(3) +ins_wstr/\fBcurs_ins_wstr\fP(3) +insch/\fBcurs_insch\fP(3) +insdelln/\fBcurs_deleteln\fP(3) +insertln/\fBcurs_deleteln\fP(3) +insnstr/\fBcurs_insstr\fP(3) +insstr/\fBcurs_insstr\fP(3) +instr/\fBcurs_instr\fP(3) +intrflush/\fBcurs_inopts\fP(3) +inwstr/\fBcurs_inwstr\fP(3) +is_cbreak/\fBcurs_inopts\fP(3)* +is_cleared/\fBcurs_opaque\fP(3)* +is_echo/\fBcurs_inopts\fP(3)* +is_idcok/\fBcurs_opaque\fP(3)* +is_idlok/\fBcurs_opaque\fP(3)* +is_immedok/\fBcurs_opaque\fP(3)* +is_keypad/\fBcurs_opaque\fP(3)* +is_leaveok/\fBcurs_opaque\fP(3)* +is_linetouched/\fBcurs_touch\fP(3) +is_nl/\fBcurs_inopts\fP(3)* +is_nodelay/\fBcurs_opaque\fP(3)* +is_notimeout/\fBcurs_opaque\fP(3)* +is_pad/\fBcurs_opaque\fP(3)* +is_raw/\fBcurs_inopts\fP(3)* +is_scrollok/\fBcurs_opaque\fP(3)* +is_subwin/\fBcurs_opaque\fP(3)* +is_syncok/\fBcurs_opaque\fP(3)* +is_term_resized/\fBresizeterm\fP(3)* +is_wintouched/\fBcurs_touch\fP(3) +isendwin/\fBcurs_initscr\fP(3) +key_defined/\fBkey_defined\fP(3)* +key_name/\fBcurs_util\fP(3) +keybound/\fBkeybound\fP(3)* +keyname/\fBcurs_util\fP(3) +keyok/\fBkeyok\fP(3)* +keypad/\fBcurs_inopts\fP(3) +killchar/\fBcurs_termattrs\fP(3) +killwchar/\fBcurs_termattrs\fP(3) +leaveok/\fBcurs_outopts\fP(3) +longname/\fBcurs_termattrs\fP(3) +mcprint/\fBcurs_print\fP(3)* +meta/\fBcurs_inopts\fP(3) +mouse_trafo/\fBcurs_mouse\fP(3)* +mouseinterval/\fBcurs_mouse\fP(3)* +mousemask/\fBcurs_mouse\fP(3)* +move/\fBcurs_move\fP(3) +mvadd_wch/\fBcurs_add_wch\fP(3) +mvadd_wchnstr/\fBcurs_add_wchstr\fP(3) +mvadd_wchstr/\fBcurs_add_wchstr\fP(3) +mvaddch/\fBcurs_addch\fP(3) +mvaddchnstr/\fBcurs_addchstr\fP(3) +mvaddchstr/\fBcurs_addchstr\fP(3) +mvaddnstr/\fBcurs_addstr\fP(3) +mvaddnwstr/\fBcurs_addwstr\fP(3) +mvaddstr/\fBcurs_addstr\fP(3) +mvaddwstr/\fBcurs_addwstr\fP(3) +mvchgat/\fBcurs_attr\fP(3) +mvcur/\fBterminfo\fP(3) +mvdelch/\fBcurs_delch\fP(3) +mvderwin/\fBcurs_window\fP(3) +mvget_wch/\fBcurs_get_wch\fP(3) +mvget_wstr/\fBcurs_get_wstr\fP(3) +mvgetch/\fBcurs_getch\fP(3) +mvgetn_wstr/\fBcurs_get_wstr\fP(3) +mvgetnstr/\fBcurs_getstr\fP(3) +mvgetstr/\fBcurs_getstr\fP(3) +mvhline/\fBcurs_border\fP(3) +mvhline_set/\fBcurs_border_set\fP(3) +mvin_wch/\fBcurs_in_wch\fP(3) +mvin_wchnstr/\fBcurs_in_wchstr\fP(3) +mvin_wchstr/\fBcurs_in_wchstr\fP(3) +mvinch/\fBcurs_inch\fP(3) +mvinchnstr/\fBcurs_inchstr\fP(3) +mvinchstr/\fBcurs_inchstr\fP(3) +mvinnstr/\fBcurs_instr\fP(3) +mvinnwstr/\fBcurs_inwstr\fP(3) +mvins_nwstr/\fBcurs_ins_wstr\fP(3) +mvins_wch/\fBcurs_ins_wch\fP(3) +mvins_wstr/\fBcurs_ins_wstr\fP(3) +mvinsch/\fBcurs_insch\fP(3) +mvinsnstr/\fBcurs_insstr\fP(3) +mvinsstr/\fBcurs_insstr\fP(3) +mvinstr/\fBcurs_instr\fP(3) +mvinwstr/\fBcurs_inwstr\fP(3) +mvprintw/\fBcurs_printw\fP(3) +mvscanw/\fBcurs_scanw\fP(3) +mvvline/\fBcurs_border\fP(3) +mvvline_set/\fBcurs_border_set\fP(3) +mvwadd_wch/\fBcurs_add_wch\fP(3) +mvwadd_wchnstr/\fBcurs_add_wchstr\fP(3) +mvwadd_wchstr/\fBcurs_add_wchstr\fP(3) +mvwaddch/\fBcurs_addch\fP(3) +mvwaddchnstr/\fBcurs_addchstr\fP(3) +mvwaddchstr/\fBcurs_addchstr\fP(3) +mvwaddnstr/\fBcurs_addstr\fP(3) +mvwaddnwstr/\fBcurs_addwstr\fP(3) +mvwaddstr/\fBcurs_addstr\fP(3) +mvwaddwstr/\fBcurs_addwstr\fP(3) +mvwchgat/\fBcurs_attr\fP(3) +mvwdelch/\fBcurs_delch\fP(3) +mvwget_wch/\fBcurs_get_wch\fP(3) +mvwget_wstr/\fBcurs_get_wstr\fP(3) +mvwgetch/\fBcurs_getch\fP(3) +mvwgetn_wstr/\fBcurs_get_wstr\fP(3) +mvwgetnstr/\fBcurs_getstr\fP(3) +mvwgetstr/\fBcurs_getstr\fP(3) +mvwhline/\fBcurs_border\fP(3) +mvwhline_set/\fBcurs_border_set\fP(3) +mvwin/\fBcurs_window\fP(3) +mvwin_wch/\fBcurs_in_wch\fP(3) +mvwin_wchnstr/\fBcurs_in_wchstr\fP(3) +mvwin_wchstr/\fBcurs_in_wchstr\fP(3) +mvwinch/\fBcurs_inch\fP(3) +mvwinchnstr/\fBcurs_inchstr\fP(3) +mvwinchstr/\fBcurs_inchstr\fP(3) +mvwinnstr/\fBcurs_instr\fP(3) +mvwinnwstr/\fBcurs_inwstr\fP(3) +mvwins_nwstr/\fBcurs_ins_wstr\fP(3) +mvwins_wch/\fBcurs_ins_wch\fP(3) +mvwins_wstr/\fBcurs_ins_wstr\fP(3) +mvwinsch/\fBcurs_insch\fP(3) +mvwinsnstr/\fBcurs_insstr\fP(3) +mvwinsstr/\fBcurs_insstr\fP(3) +mvwinstr/\fBcurs_instr\fP(3) +mvwinwstr/\fBcurs_inwstr\fP(3) +mvwprintw/\fBcurs_printw\fP(3) +mvwscanw/\fBcurs_scanw\fP(3) +mvwvline/\fBcurs_border\fP(3) +mvwvline_set/\fBcurs_border_set\fP(3) +napms/\fBcurs_kernel\fP(3) +newpad/\fBcurs_pad\fP(3) +newterm/\fBcurs_initscr\fP(3) +newwin/\fBcurs_window\fP(3) +nl/\fBcurs_inopts\fP(3) +nocbreak/\fBcurs_inopts\fP(3) +nodelay/\fBcurs_inopts\fP(3) +noecho/\fBcurs_inopts\fP(3) +nofilter/\fBcurs_util\fP(3)* +nonl/\fBcurs_inopts\fP(3) +noqiflush/\fBcurs_inopts\fP(3) +noraw/\fBcurs_inopts\fP(3) +notimeout/\fBcurs_inopts\fP(3) +overlay/\fBcurs_overlay\fP(3) +overwrite/\fBcurs_overlay\fP(3) +pair_content/\fBcurs_color\fP(3) +pecho_wchar/\fBcurs_pad\fP(3)* +pechochar/\fBcurs_pad\fP(3) +pnoutrefresh/\fBcurs_pad\fP(3) +prefresh/\fBcurs_pad\fP(3) +printw/\fBcurs_printw\fP(3) +putp/\fBterminfo\fP(3) +putwin/\fBcurs_util\fP(3) +qiflush/\fBcurs_inopts\fP(3) +raw/\fBcurs_inopts\fP(3) +redrawwin/\fBcurs_refresh\fP(3) +refresh/\fBcurs_refresh\fP(3) +reset_color_pairs/\fBcurs_color\fP(3)* +reset_prog_mode/\fBcurs_kernel\fP(3) +reset_shell_mode/\fBcurs_kernel\fP(3) +resetty/\fBcurs_kernel\fP(3) +resize_term/\fBresizeterm\fP(3)* +resizeterm/\fBresizeterm\fP(3)* +restartterm/\fBterminfo\fP(3) +ripoffline/\fBcurs_kernel\fP(3) +savetty/\fBcurs_kernel\fP(3) +scanw/\fBcurs_scanw\fP(3) +scr_dump/\fBcurs_scr_dump\fP(3) +scr_init/\fBcurs_scr_dump\fP(3) +scr_restore/\fBcurs_scr_dump\fP(3) +scr_set/\fBcurs_scr_dump\fP(3) +scrl/\fBcurs_scroll\fP(3) +scroll/\fBcurs_scroll\fP(3) +scrollok/\fBcurs_outopts\fP(3) +set_curterm/\fBterminfo\fP(3) +set_term/\fBcurs_initscr\fP(3) +setcchar/\fBcurs_getcchar\fP(3) +setscrreg/\fBcurs_outopts\fP(3) +setsyx/\fBcurs_kernel\fP(3) +setupterm/\fBterminfo\fP(3) +slk_attr/\fBcurs_slk\fP(3)* +slk_attr_off/\fBcurs_slk\fP(3) +slk_attr_on/\fBcurs_slk\fP(3) +slk_attr_set/\fBcurs_slk\fP(3) +slk_attroff/\fBcurs_slk\fP(3) +slk_attron/\fBcurs_slk\fP(3) +slk_attrset/\fBcurs_slk\fP(3) +slk_clear/\fBcurs_slk\fP(3) +slk_color/\fBcurs_slk\fP(3) +slk_init/\fBcurs_slk\fP(3) +slk_label/\fBcurs_slk\fP(3) +slk_noutrefresh/\fBcurs_slk\fP(3) +slk_refresh/\fBcurs_slk\fP(3) +slk_restore/\fBcurs_slk\fP(3) +slk_set/\fBcurs_slk\fP(3) +slk_touch/\fBcurs_slk\fP(3) +slk_wset/\fBcurs_slk\fP(3)* +standend/\fBcurs_attr\fP(3) +standout/\fBcurs_attr\fP(3) +start_color/\fBcurs_color\fP(3) +subpad/\fBcurs_pad\fP(3) +subwin/\fBcurs_window\fP(3) +syncok/\fBcurs_window\fP(3) +term_attrs/\fBcurs_termattrs\fP(3) +termattrs/\fBcurs_termattrs\fP(3) +termname/\fBcurs_termattrs\fP(3) +tgetent/\fBtermcap\fP(3) +tgetflag/\fBtermcap\fP(3) +tgetnum/\fBtermcap\fP(3) +tgetstr/\fBtermcap\fP(3) +tgoto/\fBtermcap\fP(3) +tigetflag/\fBterminfo\fP(3) +tigetnum/\fBterminfo\fP(3) +tigetstr/\fBterminfo\fP(3) +timeout/\fBcurs_inopts\fP(3) +tiparm/\fBterminfo\fP(3)* +tiparm_s/\fBterminfo\fP(3)* +tiscan_s/\fBterminfo\fP(3)* +touchline/\fBcurs_touch\fP(3) +touchwin/\fBcurs_touch\fP(3) +tparm/\fBterminfo\fP(3) +tputs/\fBtermcap\fP(3) +tputs/\fBterminfo\fP(3) +trace/\fBcurs_trace\fP(3)* +typeahead/\fBcurs_inopts\fP(3) +unctrl/\fBcurs_util\fP(3) +unget_wch/\fBcurs_get_wch\fP(3) +ungetch/\fBcurs_getch\fP(3) +ungetmouse/\fBcurs_mouse\fP(3)* +untouchwin/\fBcurs_touch\fP(3) +use_default_colors/\fBdefault_colors\fP(3)* +use_env/\fBcurs_util\fP(3) +use_extended_names/\fBcurs_extend\fP(3)* +use_legacy_coding/\fBlegacy_coding\fP(3)* +use_tioctl/\fBcurs_util\fP(3)* +vid_attr/\fBterminfo\fP(3) +vid_puts/\fBterminfo\fP(3) +vidattr/\fBterminfo\fP(3) +vidputs/\fBterminfo\fP(3) +vline/\fBcurs_border\fP(3) +vline_set/\fBcurs_border_set\fP(3) +vw_printw/\fBcurs_printw\fP(3) +vw_scanw/\fBcurs_scanw\fP(3) +vwprintw/\fBcurs_printw\fP(3) +vwscanw/\fBcurs_scanw\fP(3) +wadd_wch/\fBcurs_add_wch\fP(3) +wadd_wchnstr/\fBcurs_add_wchstr\fP(3) +wadd_wchstr/\fBcurs_add_wchstr\fP(3) +waddch/\fBcurs_addch\fP(3) +waddchnstr/\fBcurs_addchstr\fP(3) +waddchstr/\fBcurs_addchstr\fP(3) +waddnstr/\fBcurs_addstr\fP(3) +waddnwstr/\fBcurs_addwstr\fP(3) +waddstr/\fBcurs_addstr\fP(3) +waddwstr/\fBcurs_addwstr\fP(3) +wattr_get/\fBcurs_attr\fP(3) +wattr_off/\fBcurs_attr\fP(3) +wattr_on/\fBcurs_attr\fP(3) +wattr_set/\fBcurs_attr\fP(3) +wattroff/\fBcurs_attr\fP(3) +wattron/\fBcurs_attr\fP(3) +wattrset/\fBcurs_attr\fP(3) +wbkgd/\fBcurs_bkgd\fP(3) +wbkgdset/\fBcurs_bkgd\fP(3) +wbkgrnd/\fBcurs_bkgrnd\fP(3) +wbkgrndset/\fBcurs_bkgrnd\fP(3) +wborder/\fBcurs_border\fP(3) +wborder_set/\fBcurs_border_set\fP(3) +wchgat/\fBcurs_attr\fP(3) +wclear/\fBcurs_clear\fP(3) +wclrtobot/\fBcurs_clear\fP(3) +wclrtoeol/\fBcurs_clear\fP(3) +wcolor_set/\fBcurs_attr\fP(3) +wcursyncup/\fBcurs_window\fP(3) +wdelch/\fBcurs_delch\fP(3) +wdeleteln/\fBcurs_deleteln\fP(3) +wecho_wchar/\fBcurs_add_wch\fP(3) +wechochar/\fBcurs_addch\fP(3) +wenclose/\fBcurs_mouse\fP(3)* +werase/\fBcurs_clear\fP(3) +wget_wch/\fBcurs_get_wch\fP(3) +wget_wstr/\fBcurs_get_wstr\fP(3) +wgetbkgrnd/\fBcurs_bkgrnd\fP(3) +wgetch/\fBcurs_getch\fP(3) +wgetdelay/\fBcurs_opaque\fP(3)* +wgetn_wstr/\fBcurs_get_wstr\fP(3) +wgetnstr/\fBcurs_getstr\fP(3) +wgetparent/\fBcurs_opaque\fP(3)* +wgetscrreg/\fBcurs_opaque\fP(3)* +wgetstr/\fBcurs_getstr\fP(3) +whline/\fBcurs_border\fP(3) +whline_set/\fBcurs_border_set\fP(3) +win_wch/\fBcurs_in_wch\fP(3) +win_wchnstr/\fBcurs_in_wchstr\fP(3) +win_wchstr/\fBcurs_in_wchstr\fP(3) +winch/\fBcurs_inch\fP(3) +winchnstr/\fBcurs_inchstr\fP(3) +winchstr/\fBcurs_inchstr\fP(3) +winnstr/\fBcurs_instr\fP(3) +winnwstr/\fBcurs_inwstr\fP(3) +wins_nwstr/\fBcurs_ins_wstr\fP(3) +wins_wch/\fBcurs_ins_wch\fP(3) +wins_wstr/\fBcurs_ins_wstr\fP(3) +winsch/\fBcurs_insch\fP(3) +winsdelln/\fBcurs_deleteln\fP(3) +winsertln/\fBcurs_deleteln\fP(3) +winsnstr/\fBcurs_insstr\fP(3) +winsstr/\fBcurs_insstr\fP(3) +winstr/\fBcurs_instr\fP(3) +winwstr/\fBcurs_inwstr\fP(3) +wmouse_trafo/\fBcurs_mouse\fP(3)* +wmove/\fBcurs_move\fP(3) +wnoutrefresh/\fBcurs_refresh\fP(3) +wprintw/\fBcurs_printw\fP(3) +wredrawln/\fBcurs_refresh\fP(3) +wrefresh/\fBcurs_refresh\fP(3) +wresize/\fBwresize\fP(3)* +wscanw/\fBcurs_scanw\fP(3) +wscrl/\fBcurs_scroll\fP(3) +wsetscrreg/\fBcurs_outopts\fP(3) +wstandend/\fBcurs_attr\fP(3) +wstandout/\fBcurs_attr\fP(3) +wsyncdown/\fBcurs_window\fP(3) +wsyncup/\fBcurs_window\fP(3) +wtimeout/\fBcurs_inopts\fP(3) +wtouchln/\fBcurs_touch\fP(3) +wunctrl/\fBcurs_util\fP(3) +wvline/\fBcurs_border\fP(3) +wvline_set/\fBcurs_border_set\fP(3) +.TE +.PP +Depending on the configuration, +additional sets of functions may be available: +.RS 3 +.TP 5 +\fBcurs_memleaks\fP(3) - curses memory-leak checking +.TP 5 +\fBcurs_sp_funcs\fP(3) - curses screen-pointer extension +.TP 5 +\fBcurs_threads\fP(3) - curses thread support +.TP 5 +\fBcurs_trace\fP(3) - curses debugging routines +.RE +.SH RETURN VALUE +Routines that return an integer return \fBERR\fP upon failure and an +integer value other than \fBERR\fP upon successful completion, unless +otherwise noted in the routine descriptions. +.PP +As a general rule, routines check for null pointers passed as parameters, +and handle this as an error. +.PP +All macros return the value of the \fBw\fP version, except \fBsetscrreg\fP, +\fBwsetscrreg\fP, \fBgetyx\fP, \fBgetbegyx\fP, and \fBgetmaxyx\fP. +The return values of +\fBsetscrreg\fP, +\fBwsetscrreg\fP, +\fBgetyx\fP, +\fBgetbegyx\fP, and +\fBgetmaxyx\fP are undefined (i.e., these should not be used as the +right-hand side of assignment statements). +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +Most \*(``mv\*(''-prefixed functions +(except variadic functions such as \fBmvprintw\fP) +are provided both as macros and functions. +.PP +Routines that return pointers return \fBNULL\fP on error. +.SH ENVIRONMENT +The following environment symbols are useful for customizing the +runtime behavior of the \fBncurses\fP library. +The most important ones have been already discussed in detail. +.SS CC command-character +When set, change occurrences of the command_character +(i.e., the \fBcmdch\fP capability) +of the loaded terminfo entries to the value of this variable. +Very few terminfo entries provide this feature. +.PP +Because this name is also used in development environments to represent +the C compiler's name, \fBncurses\fP ignores it if it does not happen to +be a single character. +.SS BAUDRATE +The debugging library checks this environment variable when the application +has redirected output to a file. +The variable's numeric value is used for the baudrate. +If no value is found, \fBncurses\fP uses 9600. +This allows testers to construct repeatable test-cases +that take into account costs that depend on baudrate. +.SS COLUMNS +Specify the width of the screen in characters. +Applications running in a windowing environment usually are able to +obtain the width of the window in which they are executing. +If neither the \fBCOLUMNS\fP value nor the terminal's screen size is available, +\fBncurses\fP uses the size which may be specified in the terminfo database +(i.e., the \fBcols\fP capability). +.PP +It is important that your application use a correct size for the screen. +This is not always possible because your application may be +running on a host which does not honor NAWS (Negotiations About Window +Size), or because you are temporarily running as another user. +However, setting \fBCOLUMNS\fP and/or \fBLINES\fP overrides the library's +use of the screen size obtained from the operating system. +.PP +Either \fBCOLUMNS\fP or \fBLINES\fP symbols may be specified independently. +This is mainly useful to circumvent legacy misfeatures of terminal descriptions, +e.g., xterm which commonly specifies a 65 line screen. +For best results, \fBlines\fP and \fBcols\fP should not be specified in +a terminal description for terminals which are run as emulations. +.PP +Use the \fBuse_env\fP function to disable all use of external environment +(but not including system calls) to determine the screen size. +Use the \fBuse_tioctl\fP function to update \fBCOLUMNS\fP or \fBLINES\fP +to match the screen size obtained from system calls or the terminal database. +.SS ESCDELAY +Specifies the total time, in milliseconds, for which ncurses will +await a character sequence, e.g., a function key. +The default value, 1000 milliseconds, is enough for most uses. +However, it is made a variable to accommodate unusual applications. +.PP +The most common instance where you may wish to change this value +is to work with slow hosts, e.g., running on a network. +If the host cannot read characters rapidly enough, it will have the same +effect as if the terminal did not send characters rapidly enough. +The library will still see a timeout. +.PP +Note that xterm mouse events are built up from character sequences +received from the xterm. +If your application makes heavy use of multiple-clicking, you may +wish to lengthen this default value because the timeout applies +to the composed multi-click event as well as the individual clicks. +.PP +In addition to the environment variable, +this implementation provides a global variable with the same name. +Portable applications should not rely upon the presence of ESCDELAY +in either form, +but setting the environment variable rather than the global variable +does not create problems when compiling an application. +.SS HOME +Tells \fBncurses\fP where your home directory is. +That is where it may read and write auxiliary terminal descriptions: +.NS +$HOME/.termcap +$HOME/.terminfo +.NE +.SS LINES +Like COLUMNS, specify the height of the screen in characters. +See COLUMNS for a detailed description. +.SS MOUSE_BUTTONS_123 +This applies only to the OS/2 EMX port. +It specifies the order of buttons on the mouse. +OS/2 numbers a 3-button mouse inconsistently from other +platforms: +.NS +1 = left +.br +2 = right +.br +3 = middle. +.NE +.PP +This variable lets you customize the mouse. +The variable must be three numeric digits 1\-3 in any order, e.g., 123 or 321. +If it is not specified, \fBncurses\fP uses 132. +.SS NCURSES_ASSUMED_COLORS +Override the compiled-in assumption that the +terminal's default colors are white-on-black +(see \fBdefault_colors\fP(3)). +You may set the foreground and background color values with this environment +variable by proving a 2-element list: foreground,background. +For example, to tell ncurses to not assume anything +about the colors, set this to "\-1,\-1". +To make it green-on-black, set it to "2,0". +Any positive value from zero to the terminfo \fBmax_colors\fP value is allowed. +.SS NCURSES_CONSOLE2 +This applies only to the MinGW port of ncurses. +.PP +The \fBConsole2\fP program's handling of the Microsoft Console API call +\fBCreateConsoleScreenBuffer\fP is defective. +Applications which use this will hang. +However, it is possible to simulate the action of this call by +mapping coordinates, +explicitly saving and restoring the original screen contents. +Setting the environment variable \fBNCGDB\fP has the same effect. +.SS NCURSES_GPM_TERMS +This applies only to ncurses configured to use the GPM interface. +.PP +If present, +the environment variable is a list of one or more terminal names +against which the \fBTERM\fP environment variable is matched. +Setting it to an empty value disables the GPM interface; +using the built-in support for xterm, etc. +.PP +If the environment variable is absent, +ncurses will attempt to open GPM if \fBTERM\fP contains \*(``linux\*(''. +.SS NCURSES_NO_HARD_TABS +\fBNcurses\fP may use tabs as part of the cursor movement optimization. +In some cases, +your terminal driver may not handle these properly. +Set this environment variable to disable the feature. +You can also adjust your \fBstty\fP(1) settings to avoid the problem. +.SS NCURSES_NO_MAGIC_COOKIE +Some terminals use a magic-cookie feature which requires special handling +to make highlighting and other video attributes display properly. +You can suppress the highlighting entirely for these terminals by +setting this environment variable. +.SS NCURSES_NO_PADDING +Most of the terminal descriptions in the terminfo database are written +for real \*(``hardware\*('' terminals. +Many people use terminal emulators +which run in a windowing environment and use curses-based applications. +Terminal emulators can duplicate +all of the important aspects of a hardware terminal, but they do not +have the same limitations. +The chief limitation of a hardware terminal from the standpoint +of your application is the management of dataflow, i.e., timing. +Unless a hardware terminal is interfaced into a terminal concentrator +(which does flow control), +it (or your application) must manage dataflow, preventing overruns. +The cheapest solution (no hardware cost) +is for your program to do this by pausing after +operations that the terminal does slowly, such as clearing the display. +.PP +As a result, many terminal descriptions (including the vt100) +have delay times embedded. +You may wish to use these descriptions, +but not want to pay the performance penalty. +.PP +Set the NCURSES_NO_PADDING environment variable to disable all but mandatory +padding. +Mandatory padding is used as a part of special control +sequences such as \fBflash\fP. +.SS NCURSES_NO_SETBUF +This setting is obsolete. +Before changes +.RS 3 +.bP +started with 5.9 patch 20120825 +and +.bP +continued +though 5.9 patch 20130126 +.RE +.PP +\fBncurses\fP enabled buffered output during terminal initialization. +This was done (as in SVr4 curses) for performance reasons. +For testing purposes, both of \fBncurses\fP and certain applications, +this feature was made optional. +Setting the NCURSES_NO_SETBUF variable +disabled output buffering, leaving the output in the original (usually +line buffered) mode. +.PP +In the current implementation, +ncurses performs its own buffering and does not require this workaround. +It does not modify the buffering of the standard output. +.PP +The reason for the change was to make the behavior for interrupts and +other signals more robust. +One drawback is that certain nonconventional programs would mix +ordinary stdio calls with ncurses calls and (usually) work. +This is no longer possible since ncurses is not using +the buffered standard output but its own output (to the same file descriptor). +As a special case, the low-level calls such as \fBputp\fP still use the +standard output. +But high-level curses calls do not. +.SS NCURSES_NO_UTF8_ACS +During initialization, the \fBncurses\fP library +checks for special cases where VT100 line-drawing (and the corresponding +alternate character set capabilities) described in the terminfo are known +to be missing. +Specifically, when running in a UTF\-8 locale, +the Linux console emulator and the GNU screen program ignore these. +Ncurses checks the \fBTERM\fP environment variable for these. +For other special cases, you should set this environment variable. +Doing this tells ncurses to use Unicode values which correspond to +the VT100 line-drawing glyphs. +That works for the special cases cited, +and is likely to work for terminal emulators. +.PP +When setting this variable, you should set it to a nonzero value. +Setting it to zero (or to a nonnumber) +disables the special check for \*(``linux\*('' and \*(``screen\*(''. +.PP +As an alternative to the environment variable, +ncurses checks for an extended terminfo capability \fBU8\fP. +This is a numeric capability which can be compiled using \fBtic\ \-x\fP. +For example +.RS 3 +.ft CW +.sp +.nf +# linux console, if patched to provide working +# VT100 shift-in/shift-out, with corresponding font. +linux-vt100|linux console with VT100 line-graphics, + U8#0, use=linux, +.sp +# uxterm with vt100Graphics resource set to false +xterm-utf8|xterm relying on UTF-8 line-graphics, + U8#1, use=xterm, +.fi +.ft +.RE +.PP +The name \*(``U8\*('' is chosen to be two characters, +to permit it to be used by applications that use ncurses' +termcap interface. +.SS NCURSES_TRACE +During initialization, the \fBncurses\fP debugging library +checks the NCURSES_TRACE environment variable. +If it is defined, to a numeric value, \fBncurses\fP calls the \fBtrace\fP +function, using that value as the argument. +.PP +The argument values, which are defined in \fBcurses.h\fP, provide several +types of information. +When running with traces enabled, your application will write the +file \fBtrace\fP to the current directory. +.PP +See \fBcurs_trace\fP(3) for more information. +.SS TERM +Denotes your terminal type. +Each terminal type is distinct, though many are similar. +.PP +\fBTERM\fP is commonly set by terminal emulators to help +applications find a workable terminal description. +Some of those choose a popular approximation, e.g., +\*(``ansi\*('', \*(``vt100\*('', \*(``xterm\*('' rather than an exact fit. +Not infrequently, your application will have problems with that approach, +e.g., incorrect function-key definitions. +.PP +If you set \fBTERM\fP in your environment, +it has no effect on the operation of the terminal emulator. +It only affects the way applications work within the terminal. +Likewise, as a general rule (\fBxterm\fP(1) being a rare exception), +terminal emulators which allow you to +specify \fBTERM\fP as a parameter or configuration value do +not change their behavior to match that setting. +.SS TERMCAP +If the \fBncurses\fP library has been configured with \fItermcap\fP +support, \fBncurses\fP will check for a terminal's description in +termcap form if it is not available in the terminfo database. +.PP +The \fBTERMCAP\fP environment variable contains +either a terminal description (with newlines stripped out), +or a file name telling where the information denoted by +the \fBTERM\fP environment variable exists. +In either case, setting it directs \fBncurses\fP to ignore +the usual place for this information, e.g., /etc/termcap. +.SS TERMINFO +\fBncurses\fP can be configured to read from multiple terminal databases. +The \fBTERMINFO\fP variable overrides the location for +the default terminal database. +Terminal descriptions (in terminal format) are stored in terminal databases: +.bP +Normally these are stored in a directory tree, +using subdirectories named by the first letter of the terminal names therein. +.IP +This is the scheme used in System V, which legacy Unix systems use, +and the \fBTERMINFO\fP variable is used by \fIcurses\fP applications on those +systems to override the default location of the terminal database. +.bP +If \fBncurses\fP is built to use hashed databases, +then each entry in this list may be the path of a hashed database file, e.g., +.NS +/usr/share/terminfo.db +.NE +.IP +rather than +.NS +/usr/share/terminfo/ +.NE +.IP +The hashed database uses less disk-space and is a little faster than the +directory tree. +However, +some applications assume the existence of the directory tree, +reading it directly +rather than using the terminfo library calls. +.bP +If \fBncurses\fP is built with a support for reading termcap files +directly, then an entry in this list may be the path of a termcap file. +.bP +If the \fBTERMINFO\fP variable begins with +\*(``hex:\*('' or \*(``b64:\*('', +\fBncurses\fP uses the remainder of that variable as a compiled terminal +description. +You might produce the base64 format using \fBinfocmp\fP(1): +.NS +TERMINFO="$(infocmp -0 -Q2 -q)" +export TERMINFO +.NE +.IP +The compiled description is used if it corresponds to the terminal identified +by the \fBTERM\fP variable. +.PP +Setting \fBTERMINFO\fP is the simplest, +but not the only way to set location of the default terminal database. +The complete list of database locations in order follows: +.RS 3 +.bP +the last terminal database to which \fBncurses\fP wrote, +if any, is searched first +.bP +the location specified by the TERMINFO environment variable +.bP +$HOME/.terminfo +.bP +locations listed in the TERMINFO_DIRS environment variable +.bP +one or more locations whose names are configured and compiled into the +ncurses library, i.e., +.RS 3 +.bP +? (corresponding to the TERMINFO_DIRS variable) +.bP +/usr/share/terminfo (corresponding to the TERMINFO variable) +.RE +.RE +.SS TERMINFO_DIRS +Specifies a list of locations to search for terminal descriptions. +Each location in the list is a terminal database as described in +the section on the \fBTERMINFO\fP variable. +The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX. +.PP +There is no corresponding feature in System V terminfo; +it is an extension developed for \fBncurses\fP. +.SS TERMPATH +If \fBTERMCAP\fP does not hold a file name then \fBncurses\fP checks +the \fBTERMPATH\fP environment variable. +This is a list of filenames separated by spaces or colons (i.e., ":") on Unix, +semicolons on OS/2 EMX. +.PP +If the \fBTERMPATH\fP environment variable is not set, +\fBncurses\fP looks in the files +.NS +/etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, +.NE +.PP +in that order. +.PP +The library may be configured to disregard the following variables when the +current user is the superuser (root), or if the application uses setuid or +setgid permissions: +.NS +$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME. +.NE +.SH ALTERNATE CONFIGURATIONS +Several different configurations are possible, +depending on the configure script options used when building \fBncurses\fP. +There are a few main options whose effects are visible to the applications +developer using \fBncurses\fP: +.TP 5 +\-\-disable\-overwrite +The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP: +.NS +\fB#include \fP +.NE +.IP +This option is used to avoid filename conflicts when \fBncurses\fP +is not the main implementation of curses of the computer. +If \fBncurses\fP is installed disabling overwrite, it puts its headers in +a subdirectory, e.g., +.NS +\fB#include \fP +.NE +.IP +It also omits a symbolic link which would allow you to use \fB\-lcurses\fP +to build executables. +.TP 5 +\-\-enable\-widec +The configure script renames the library and +(if the \fB\-\-disable\-overwrite\fP option is used) +puts the header files in a different subdirectory. +All of the library names have a \*(``w\*('' appended to them, +i.e., instead of +.NS +\fB\-lncurses\fP +.NE +.IP +you link with +.NS +\fB\-lncursesw\fP +.NE +.IP +You must also enable the wide-character features in the header file +when compiling for the wide-character library +to use the extended (wide-character) functions. +The symbol which enables these features has changed since XSI Curses, Issue 4: +.RS +.bP +Originally, the wide-character feature required the symbol +\fB_XOPEN_SOURCE_EXTENDED\fP +but that was only valid for XPG4 (1996). +.bP +Later, that was deemed conflicting with \fB_XOPEN_SOURCE\fP defined to 500. +.bP +As of mid-2018, +none of the features in this implementation require a \fB_XOPEN_SOURCE\fP +feature greater than 600. +However, X/Open Curses, Issue 7 (2009) recommends defining it to 700. +.bP +Alternatively, you can enable the feature by defining \fBNCURSES_WIDECHAR\fP +with the caveat that some other header file than \fBcurses.h\fP +may require a specific value for \fB_XOPEN_SOURCE\fP +(or a system-specific symbol). +.RE +.IP +The \fBcurses.h\fP file which is installed for the wide-character +library is designed to be compatible with the normal library's header. +Only the size of the \fBWINDOW\fP structure differs, and very few +applications require more than a pointer to \fBWINDOW\fPs. +.IP +If the headers are installed allowing overwrite, +the wide-character library's headers should be installed last, +to allow applications to be built using either library +from the same set of headers. +.TP 5 +\-\-with\-pthread +The configure script renames the library. +All of the library names have a \*(``t\*('' appended to them +(before any \*(``w\*('' added by \fB\-\-enable\-widec\fP). +.IP +The global variables such as \fBLINES\fP are replaced by macros to +allow read-only access. +At the same time, setter-functions are provided to set these values. +Some applications (very few) may require changes to work with this convention. +.TP 5 +\-\-with\-shared +.TP +\-\-with\-normal +.TP +\-\-with\-debug +.TP +\-\-with\-profile +The shared and normal (static) library names differ by their suffixes, +e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP. +The debug and profiling libraries add a \*(``_g\*('' +and a \*(``_p\*('' to the root names respectively, +e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP. +.TP 5 +\-\-with\-termlib +Low-level functions which do not depend upon whether the library +supports wide-characters, are provided in the tinfo library. +.IP +By doing this, it is possible to share the tinfo library between +wide/normal configurations as well as reduce the size of the library +when only low-level functions are needed. +.IP +Those functions are described in these pages: +.RS +.bP +\fBcurs_extend\fP(3) \- miscellaneous curses extensions +.bP +\fBcurs_inopts\fP(3) \- \fBcurses\fP input options +.bP +\fBcurs_kernel\fP(3) \- low-level \fBcurses\fP routines +.bP +\fBcurs_termattrs\fP(3) \- \fBcurses\fP environment query routines +.bP +\fBtermcap\fP(3) \- \fBcurses\fP emulation of termcap +.bP +\fBterminfo\fP(3) \- \fBcurses\fP interfaces to terminfo database +.bP +\fBcurs_util\fP(3) \- miscellaneous \fBcurses\fP utility routines +.RE +.TP 5 +\-\-with\-trace +The \fBtrace\fP function normally resides in the debug library, +but it is sometimes useful to configure this in the shared library. +Configure scripts should check for the function's existence rather +than assuming it is always in the debug library. +.SH FILES +.TP 5 +/usr/share/tabset +directory containing initialization files for the terminal capability database +/usr/share/terminfo +terminal capability database +.SH SEE ALSO +\fBterminfo\fP(\*n) and related pages whose names begin +\*(``curs_\*('' for detailed routine descriptions. +.br +\fBcurs_variables\fP(3) +.br +\fBuser_caps\fP(5) for user-defined capabilities +.SH EXTENSIONS +The \fBncurses\fP library can be compiled with an option (\fB\-DUSE_GETCAP\fP) +that falls back to the old-style /etc/termcap file if the terminal setup code +cannot find a terminfo entry corresponding to \fBTERM\fP. +Use of this feature +is not recommended, as it essentially includes an entire termcap compiler in +the \fBncurses\fP startup code, at significant cost in core and startup cycles. +.PP +The \fBncurses\fP library includes facilities for capturing mouse events on +certain terminals (including xterm). +See the \fBcurs_mouse\fP(3) +manual page for details. +.PP +The \fBncurses\fP library includes facilities for responding to window +resizing events, e.g., when running in an xterm. +See the \fBresizeterm\fP(3) +and \fBwresize\fP(3) manual pages for details. +In addition, the library may be configured with a \fBSIGWINCH\fP handler. +.PP +The \fBncurses\fP library extends the fixed set of function key capabilities +of terminals by allowing the application designer to define additional +key sequences at runtime. +See the \fBdefine_key\fP(3) +\fBkey_defined\fP(3), +and \fBkeyok\fP(3) manual pages for details. +.PP +The \fBncurses\fP library can exploit the capabilities of terminals which +implement the ISO\-6429 SGR 39 and SGR 49 controls, which allow an application +to reset the terminal to its original foreground and background colors. +From the users' perspective, the application is able to draw colored +text on a background whose color is set independently, providing better +control over color contrasts. +See the \fBdefault_colors\fP(3) manual page for details. +.PP +The \fBncurses\fP library includes a function for directing application output +to a printer attached to the terminal device. +See the \fBcurs_print\fP(3) manual page for details. +.SH PORTABILITY +The \fBncurses\fP library is intended to be BASE-level conformant with XSI +Curses. +The EXTENDED XSI Curses functionality +(including color support) is supported. +.PP +A small number of local differences (that is, individual differences between +the XSI Curses and \fBncurses\fP calls) are described in \fBPORTABILITY\fP +sections of the library man pages. +.SS Error checking +In many cases, X/Open Curses is vague about error conditions, +omitting some of the SVr4 documentation. +.PP +Unlike other implementations, this one checks parameters such as pointers +to WINDOW structures to ensure they are not null. +The main reason for providing this behavior is to guard against programmer +error. +The standard interface does not provide a way for the library +to tell an application which of several possible errors were detected. +Relying on this (or some other) extension will adversely affect the +portability of curses applications. +.SS Extensions versus portability +Most of the extensions provided by ncurses have not been standardized. +Some have been incorporated into other implementations, such as +PDCurses or NetBSD curses. +Here are a few to consider: +.bP +The routine \fBhas_key\fP is not part of XPG4, nor is it present in SVr4. +See the \fBcurs_getch\fP(3) manual page for details. +.bP +The routine \fBslk_attr\fP is not part of XPG4, nor is it present in SVr4. +See the \fBcurs_slk\fP(3) manual page for details. +.bP +The routines \fBgetmouse\fP, \fBmousemask\fP, \fBungetmouse\fP, +\fBmouseinterval\fP, and \fBwenclose\fP relating to mouse interfacing are not +part of XPG4, nor are they present in SVr4. +See the \fBcurs_mouse\fP(3) manual page for details. +.bP +The routine \fBmcprint\fP was not present in any previous curses implementation. +See the \fBcurs_print\fP(3) manual page for details. +.bP +The routine \fBwresize\fP is not part of XPG4, nor is it present in SVr4. +See the \fBwresize\fP(3) manual page for details. +.bP +The WINDOW structure's internal details can be hidden from application +programs. +See \fBcurs_opaque\fP(3) for the discussion of \fBis_scrollok\fP, etc. +.bP +This implementation can be configured to provide rudimentary support +for multi-threaded applications. +See \fBcurs_threads\fP(3) for details. +.bP +This implementation can also be configured to provide a set of functions which +improve the ability to manage multiple screens. +See \fBcurs_sp_funcs\fP(3) for details. +.SS Padding differences +In historic curses versions, delays embedded in the capabilities \fBcr\fP, +\fBind\fP, \fBcub1\fP, \fBff\fP and \fBtab\fP activated corresponding delay +bits in the UNIX tty driver. +In this implementation, all padding is done by sending NUL bytes. +This method is slightly more expensive, but narrows the interface +to the UNIX kernel significantly and increases the package's portability +correspondingly. +.SS Header files +The header file \fB\fP automatically includes the header files +\fB\fP and \fB\fP. +.PP +X/Open Curses has more to say, +but does not finish the story: +.RS 4 +.PP +The inclusion of may make visible all symbols +from the headers , , , and . +.RE +.PP +Here is a more complete story: +.bP +Starting with BSD curses, all implementations have included . +.IP +BSD curses included and from an internal header +"curses.ext" ("ext" was a short name for \fIexterns\fP). +.IP +BSD curses used internally (for \fBprintw\fP and \fBscanw\fP), +but nothing in itself relied upon . +.bP +SVr2 curses added \fBnewterm\fP(3), which relies upon . +That is, the function prototype uses \fBFILE\fP. +.IP +SVr4 curses added \fBputwin\fP and \fBgetwin\fP, which also use . +.IP +X/Open Curses documents all three of these functions. +.IP +SVr4 curses and X/Open Curses do not require the developer to +include before including . +Both document curses showing as the only required header. +.IP +As a result, standard will always include . +.bP +X/Open Curses is inconsistent with respect to SVr4 regarding . +.IP +As noted in \fBcurs_util\fP(3), ncurses includes from + (like SVr4). +.bP +X/Open's comments about and may refer to HP-UX and AIX: +.IP +HP-UX curses includes from +to declare \fBsetupterm\fP in curses.h, +but ncurses (and Solaris curses) do not. +.IP +AIX curses includes and . +Again, ncurses (and Solaris curses) do not. +.bP +X/Open says that \fImay\fP include , +but there is no requirement that it do that. +.IP +Some programs use functions declared in both and , +and must include both headers in the same module. +Very old versions of AIX curses required including +before including . +.IP +Because ncurses header files include the headers needed to +define datatypes used in the headers, +ncurses header files can be included in any order. +But for portability, you should include before . +.bP +X/Open Curses says \fI"may make visible"\fP +because including a header file does not necessarily make all symbols +in it visible (there are ifdef's to consider). +.IP +For instance, in ncurses \fImay\fP be included if +the proper symbol is defined, and if ncurses is configured for +wide-character support. +If the header is included, its symbols may be made visible. +That depends on the value used for \fB_XOPEN_SOURCE\fP +feature test macro. +.bP +X/Open Curses documents one required header, +in a special case: before to prototype +the \fBvw_printw\fP and \fBvw_scanw\fP functions +(as well as the obsolete +the \fBvwprintw\fP and \fBvwscanw\fP functions). +Each of those uses a \fBva_list\fP parameter. +.IP +The two obsolete functions were introduced in SVr3. +The other functions were introduced in X/Open Curses. +In between, SVr4 curses provided for the possibility that +an application might include either or . +Initially, that was done by using \fBvoid*\fP for the \fBva_list\fP +parameter. +Later, a special type (defined in ) was introduced, +to allow for compiler type-checking. +That special type is always available, +because is always included by . +.IP +None of the X/Open Curses implementations require an application +to include before because they either +have allowed for a special type, or (like ncurses) include +directly to provide a portable interface. +.SH NOTES +If standard output from a \fBncurses\fP program is re-directed to something +which is not a tty, screen updates will be directed to standard error. +This was an undocumented feature of AT&T System V Release 3 curses. +.SH AUTHORS +Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. +Based on \fIpcurses\fP by Pavel Curtis. diff --git a/static/openbsd/man3/d2i_ASN1_NULL.3 b/static/openbsd/man3/d2i_ASN1_NULL.3 new file mode 100644 index 00000000..06aafc08 --- /dev/null +++ b/static/openbsd/man3/d2i_ASN1_NULL.3 @@ -0,0 +1,93 @@ +.\" $OpenBSD: d2i_ASN1_NULL.3,v 1.6 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_ASN1_NULL 3 +.Os +.Sh NAME +.Nm d2i_ASN1_NULL , +.Nm i2d_ASN1_NULL +.Nd decode and encode an ASN.1 NULL type +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_NULL * +.Fo d2i_ASN1_NULL +.Fa "ASN1_NULL **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_NULL +.Fa "ASN1_NULL *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode the ASN.1 value NULL of type NULL. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_ASN1_NULL +verifies that the BER-encoded value at +.Pf * Fa der_in +is NULL and of type NULL. +It fails if +.Fa length +is less than 2 or if the first two bytes of +.Pf * Fa der_in +differ from 0x05 and 0x00. +In case of success, +.Pf * Fa der_in +is advanced by two bytes and +.Pf * Fa val_out +is set to a specific invalid pointer representing the unique +.Vt ASN1_NULL +object. +.Pp +.Fn i2d_ASN1_NULL +ignores +.Fa val_in +and encodes the ASN.1 value NULL of type NULL using DER. +Specifically, it writes the identifier octet for the type NULL, +0x05, followed by the length octet 0x00, and no content or +end-of-content octets. +.Sh RETURN VALUES +.Fn d2i_ASN1_NULL +returns a specific invalid pointer representing the unique +.Vt ASN1_NULL +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_ASN1_NULL +returns 2 if successful or 0 if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr ASN1_item_new 3 , +.Xr ASN1_NULL_new 3 , +.Xr ASN1_TYPE_get 3 +.Sh STANDARDS +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules: +Specification of Basic Encoding Rules (BER), Canonical Encoding +Rules (CER) and Distinguished Encoding Rules (DER), +section 8.8: Encoding of a null value +.Sh HISTORY +.Fn d2i_ASN1_NULL +and +.Fn i2d_ASN1_NULL +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/d2i_ASN1_OBJECT.3 b/static/openbsd/man3/d2i_ASN1_OBJECT.3 new file mode 100644 index 00000000..3d90c60e --- /dev/null +++ b/static/openbsd/man3/d2i_ASN1_OBJECT.3 @@ -0,0 +1,165 @@ +.\" $OpenBSD: d2i_ASN1_OBJECT.3,v 1.16 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2017, 2022, 2023 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 $Mdocdate: June 8 2025 $ +.Dt D2I_ASN1_OBJECT 3 +.Os +.Sh NAME +.Nm d2i_ASN1_OBJECT , +.Nm i2d_ASN1_OBJECT , +.Nm OBJ_get0_data , +.Nm OBJ_length +.Nd decode and encode ASN.1 object identifiers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_OBJECT * +.Fo d2i_ASN1_OBJECT +.Fa "ASN1_OBJECT **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_OBJECT +.Fa "const ASN1_OBJECT *val_in" +.Fa "unsigned char **der_out" +.Fc +.In openssl/objects.h +.Ft const unsigned char * +.Fn OBJ_get0_data "const ASN1_OBJECT *val_in" +.Ft size_t +.Fn OBJ_length "const ASN1_OBJECT *val_in" +.Sh DESCRIPTION +These functions decode and encode ASN.1 object identifiers. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +The LibreSSL implementation of +.Fn d2i_ASN1_OBJECT +always calls +.Xr ASN1_OBJECT_free 3 +if an existing object is passed in via +.Fa val_out +and it always creates a new object from scratch. +Other implementations may attempt to reuse an existing object, +which is fragile and prone to bugs. +Consequently, always passing +.Dv NULL +for the +.Fa val_out +argument is recommended. +.Pp +The objects returned from +.Fn d2i_ASN1_OBJECT +and the data contained in them are always marked as dynamically +allocated, so when they are no longer needed, +.Xr ASN1_OBJECT_free 3 +can be called on them. +.Pp +.Fn i2d_ASN1_OBJECT +encodes the object identifier pointed to by +.Fa val_in +into DER format. +.Fn OBJ_get0_data +and +.Fn OBJ_length +only deal with the content octets of that DER encoding, +without taking the identifier and length octets into account. +.Sh RETURN VALUES +.Fn d2i_ASN1_OBJECT +returns a pointer to the new +.Vt ASN1_OBJECT +object or +.Dv NULL +if an error occurs. +With other implementations, it might return a pointer to the reused +.Vt ASN1_OBJECT . +.Pp +.Fn i2d_ASN1_OBJECT +returns the number of octets successfully encoded +or a value <= 0 if an error occurs. +.Pp +.Fn OBJ_get0_data +returns an internal pointer to the first content octet of the DER +encoding of +.Fa val_in . +The other content octets follow the returned pointer contiguously. +.Fn OBJ_length +returns the number of content octets contained in the DER encoding of +.Fa val_in . +This number is always smaller than the total length of the encoding +returned by +.Xr ASN1_object_size 3 . +.Pp +If +.Fa val_in +is a +.Dv NULL +pointer or points to an empty object, for example one freshly created with +.Xr ASN1_OBJECT_new 3 , +.Fn OBJ_get0_data +returns +.Dv NULL +and +.Fn OBJ_length +returns zero. +.Sh SEE ALSO +.Xr a2d_ASN1_OBJECT 3 , +.Xr ASN1_item_d2i 3 , +.Xr ASN1_OBJECT_new 3 , +.Xr ASN1_put_object 3 , +.Xr OBJ_nid2obj 3 +.Sh STANDARDS +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules: +Specification of Basic Encoding Rules (BER), Canonical Encoding +Rules (CER) and Distinguished Encoding Rules (DER), +section 8.19: Encoding of an object identifier value +.Sh HISTORY +.Fn d2i_ASN1_OBJECT +and +.Fn i2d_ASN1_OBJECT +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn OBJ_get0_data +and +.Fn OBJ_length +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . +.Sh CAVEATS +.Fn d2i_ASN1_OBJECT +never sets the long and short names of the object, not even if the +object identifier matches one that is built into the library. +To find the names of an object identifier parsed from DER or BER +input, call +.Xr OBJ_obj2nid 3 +on the returned object, and then +.Xr OBJ_nid2sn 3 +and +.Xr OBJ_nid2ln 3 +on the result. +.Pp +Calling +.Fn OBJ_get0_data +and then accessing memory in front of the returned pointer +results in undefined behaviour. +In particular, it is not possible to find the identifier or +length octets in that way; use +.Xr ASN1_put_object 3 +or +.Fn i2d_ASN1_OBJECT +instead. diff --git a/static/openbsd/man3/d2i_ASN1_OCTET_STRING.3 b/static/openbsd/man3/d2i_ASN1_OCTET_STRING.3 new file mode 100644 index 00000000..bd4b9001 --- /dev/null +++ b/static/openbsd/man3/d2i_ASN1_OCTET_STRING.3 @@ -0,0 +1,462 @@ +.\" $OpenBSD: d2i_ASN1_OCTET_STRING.3,v 1.21 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 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 $Mdocdate: June 8 2025 $ +.Dt D2I_ASN1_OCTET_STRING 3 +.Os +.Sh NAME +.Nm d2i_ASN1_OCTET_STRING , +.Nm i2d_ASN1_OCTET_STRING , +.Nm d2i_ASN1_BIT_STRING , +.Nm i2d_ASN1_BIT_STRING , +.Nm d2i_ASN1_INTEGER , +.Nm i2d_ASN1_INTEGER , +.Nm d2i_ASN1_UINTEGER , +.Nm d2i_ASN1_ENUMERATED , +.Nm i2d_ASN1_ENUMERATED , +.Nm d2i_ASN1_UTF8STRING , +.Nm i2d_ASN1_UTF8STRING , +.Nm d2i_ASN1_IA5STRING , +.Nm i2d_ASN1_IA5STRING , +.Nm d2i_ASN1_UNIVERSALSTRING , +.Nm i2d_ASN1_UNIVERSALSTRING , +.Nm d2i_ASN1_BMPSTRING , +.Nm i2d_ASN1_BMPSTRING , +.Nm d2i_ASN1_GENERALSTRING , +.Nm i2d_ASN1_GENERALSTRING , +.Nm d2i_ASN1_T61STRING , +.Nm i2d_ASN1_T61STRING , +.Nm d2i_ASN1_VISIBLESTRING , +.Nm i2d_ASN1_VISIBLESTRING , +.Nm d2i_ASN1_PRINTABLESTRING , +.Nm i2d_ASN1_PRINTABLESTRING , +.Nm d2i_ASN1_PRINTABLE , +.Nm i2d_ASN1_PRINTABLE , +.Nm d2i_DIRECTORYSTRING , +.Nm i2d_DIRECTORYSTRING , +.Nm d2i_DISPLAYTEXT , +.Nm i2d_DISPLAYTEXT , +.Nm d2i_ASN1_GENERALIZEDTIME , +.Nm i2d_ASN1_GENERALIZEDTIME , +.Nm d2i_ASN1_UTCTIME , +.Nm i2d_ASN1_UTCTIME , +.Nm d2i_ASN1_TIME , +.Nm i2d_ASN1_TIME +.Nd decode and encode ASN1_STRING objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_OCTET_STRING * +.Fo d2i_ASN1_OCTET_STRING +.Fa "ASN1_OCTET_STRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_OCTET_STRING +.Fa "ASN1_OCTET_STRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_BIT_STRING * +.Fo d2i_ASN1_BIT_STRING +.Fa "ASN1_BIT_STRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_BIT_STRING +.Fa "ASN1_BIT_STRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_INTEGER * +.Fo d2i_ASN1_INTEGER +.Fa "ASN1_INTEGER **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_INTEGER +.Fa "ASN1_INTEGER *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_INTEGER * +.Fo d2i_ASN1_UINTEGER +.Fa "ASN1_INTEGER **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft ASN1_ENUMERATED * +.Fo d2i_ASN1_ENUMERATED +.Fa "ASN1_ENUMERATED **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_ENUMERATED +.Fa "ASN1_ENUMERATED *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_UTF8STRING * +.Fo d2i_ASN1_UTF8STRING +.Fa "ASN1_UTF8STRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_UTF8STRING +.Fa "ASN1_UTF8STRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_IA5STRING * +.Fo d2i_ASN1_IA5STRING +.Fa "ASN1_IA5STRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_IA5STRING +.Fa "ASN1_IA5STRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_UNIVERSALSTRING * +.Fo d2i_ASN1_UNIVERSALSTRING +.Fa "ASN1_UNIVERSALSTRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_UNIVERSALSTRING +.Fa "ASN1_UNIVERSALSTRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_BMPSTRING * +.Fo d2i_ASN1_BMPSTRING +.Fa "ASN1_BMPSTRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_BMPSTRING +.Fa "ASN1_BMPSTRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_GENERALSTRING * +.Fo d2i_ASN1_GENERALSTRING +.Fa "ASN1_GENERALSTRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_GENERALSTRING +.Fa "ASN1_GENERALSTRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_T61STRING * +.Fo d2i_ASN1_T61STRING +.Fa "ASN1_T61STRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_T61STRING +.Fa "ASN1_T61STRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_VISIBLESTRING * +.Fo d2i_ASN1_VISIBLESTRING +.Fa "ASN1_VISIBLESTRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_VISIBLESTRING +.Fa "ASN1_VISIBLESTRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_PRINTABLESTRING * +.Fo d2i_ASN1_PRINTABLESTRING +.Fa "ASN1_PRINTABLESTRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_PRINTABLESTRING +.Fa "ASN1_PRINTABLESTRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_STRING * +.Fo d2i_ASN1_PRINTABLE +.Fa "ASN1_STRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_PRINTABLE +.Fa "ASN1_STRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_STRING * +.Fo d2i_DIRECTORYSTRING +.Fa "ASN1_STRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DIRECTORYSTRING +.Fa "ASN1_STRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_STRING * +.Fo d2i_DISPLAYTEXT +.Fa "ASN1_STRING **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DISPLAYTEXT +.Fa "ASN1_STRING *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_GENERALIZEDTIME * +.Fo d2i_ASN1_GENERALIZEDTIME +.Fa "ASN1_GENERALIZEDTIME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_GENERALIZEDTIME +.Fa "ASN1_GENERALIZEDTIME *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_UTCTIME * +.Fo d2i_ASN1_UTCTIME +.Fa "ASN1_UTCTIME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_UTCTIME +.Fa "ASN1_UTCTIME *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_TIME * +.Fo d2i_ASN1_TIME +.Fa "ASN1_TIME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_TIME +.Fa "ASN1_TIME *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode various ASN.1 built-in types +that can be represented by +.Vt ASN1_STRING +objects. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +The format consists of one identifier byte, one or more length bytes, +and one or more content bytes. +The identifier bytes and corresponding ASN.1 types are as follows: +.Bl -column ASN1_GENERALIZEDTIME identifier +.It Em OpenSSL type Ta Em identifier Ta Em ASN.1 type +.It Ta +.It Vt ASN1_OCTET_STRING Ta 0x04 Ta OCTET STRING +.It Vt ASN1_BIT_STRING Ta 0x03 Ta BIT STRING +.It Vt ASN1_INTEGER Ta 0x02 Ta INTEGER +.It Vt ASN1_ENUMERATED Ta 0x0a Ta ENUMERATED +.It Vt ASN1_UTF8STRING Ta 0x0c Ta UTF8String +.It Vt ASN1_IA5STRING Ta 0x16 Ta IA5String +.It Vt ASN1_UNIVERSALSTRING Ta 0x1c Ta UniversalString +.It Vt ASN1_BMPSTRING Ta 0x1e Ta BMPString +.It Vt ASN1_GENERALSTRING Ta 0x1b Ta GeneralString +.It Vt ASN1_T61STRING Ta 0x14 Ta T61String +.It Vt ASN1_VISIBLESTRING Ta 0x1a Ta VisibleString +.It Vt ASN1_PRINTABLESTRING Ta 0x13 Ta PrintableString +.It Vt ASN1_GENERALIZEDTIME Ta 0x18 Ta GeneralizedTime +.It Vt ASN1_UTCTIME Ta 0x17 Ta UTCTime +.El +.Pp +.Fn d2i_DIRECTORYSTRING +and +.Fn i2d_DIRECTORYSTRING +decode and encode an ASN.1 +.Vt DirectoryString +structure defined in RFC 5280 section 4.1.2.4 +and used for ASN.1 +.Vt EDIPartyName +structures; see +.Xr EDIPARTYNAME_new 3 . +When decoding, it accepts any of the types UTF8String, UniversalString, +BMPString, T61String, or PrintableString. +When encoding, +it writes out the character string type that is actually passed in. +.Pp +.Fn d2i_ASN1_PRINTABLE +and +.Fn i2d_ASN1_PRINTABLE +are non-standard variants of +.Fn d2i_DIRECTORYSTRING +and +.Fn i2d_DIRECTORYSTRING +that also accept IA5String, NumericString, BIT STRING, and SEQUENCE +ASN.1 values as well as ASN.1 values with unknown identifier +bytes (0x07, 0x08, 0x09, 0x0b, 0x0d, 0x0e, 0x0f, 0x1d, and 0x1f). +Even though the standard requires the use of +.Vt DirectoryString +in the relative distinguished names described in +.Xr X509_NAME_ENTRY_new 3 , +the library accepts this wider range of choices. +.Pp +.Fn d2i_DISPLAYTEXT +and +.Fn i2d_DISPLAYTEXT +decode and encode an ASN.1 +.Vt DisplayText +structure defined in RFC 5280 section 4.2.1.4 +and used for ASN.1 +.Vt UserNotice +structures in certificate policies; see +.Xr USERNOTICE_new 3 . +When decoding, it accepts any of the types UTF8String, IA5String, +BMPString, or VisibleString. +When encoding, +it writes out the character string type that is actually passed in. +.Pp +.Fn d2i_ASN1_TIME +and +.Fn i2d_ASN1_TIME +decode and encode an ASN.1 +.Vt Time +structure defined in RFC 5280 section 4.1 +and used for ASN.1 +.Vt Validity +structures in certificates; see +.Xr X509_VAL_new 3 . +They are also used for certificate revocation lists; see +.Xr X509_CRL_INFO_new 3 . +When decoding, it accepts either GeneralizedTime or UTCTime. +When encoding, it writes out the time type that is actually passed in. +.Pp +The following constants describe the ASN.1 tags that are valid +when decoding with the above functions. +See +.Xr ASN1_tag2bit 3 +for more details about the +.Dv B_ASN1_* +constants. +.Bl -column d2i_DIRECTORYSTRING() B_ASN1_DIRECTORYSTRING -offset indent +.It decoding function Ta mask constant +.It Fn d2i_DIRECTORYSTRING Ta Dv B_ASN1_DIRECTORYSTRING +.It Fn d2i_ASN1_PRINTABLE Ta Dv B_ASN1_PRINTABLE +.It Fn d2i_DISPLAYTEXT Ta Dv B_ASN1_DISPLAYTEXT +.It Fn d2i_ASN1_TIME Ta Dv B_ASN1_TIME +.El +.Pp +.Fn d2i_ASN1_UINTEGER +is similar to +.Fn d2i_ASN1_INTEGER +except that it ignores the sign bit in the BER encoding and treats +all integers as positive. +It helps to process BER input produced by broken software +that neglects adding a leading NUL content byte where required. +.Sh RETURN VALUES +The +.Fn d2i_* +decoding functions return an +.Vt ASN1_STRING +object or +.Dv NULL +if an error occurs. +.Pp +The +.Fn i2d_* +encoding functions return the number of bytes successfully encoded +or a negative value if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr ASN1_STRING_new 3 +.Sh STANDARDS +ITU-T Recommendation X.680, also known as ISO/IEC 8824-1: +Information technology - Abstract Syntax Notation One (ASN.1): +Specification of basic notation +.Pp +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn d2i_ASN1_OCTET_STRING , +.Fn i2d_ASN1_OCTET_STRING , +.Fn d2i_ASN1_BIT_STRING , +.Fn i2d_ASN1_BIT_STRING , +.Fn d2i_ASN1_INTEGER , +.Fn i2d_ASN1_INTEGER , +.Fn d2i_ASN1_IA5STRING , +.Fn i2d_ASN1_IA5STRING , +.Fn d2i_ASN1_T61STRING , +.Fn i2d_ASN1_T61STRING , +.Fn d2i_ASN1_PRINTABLESTRING , +.Fn i2d_ASN1_PRINTABLESTRING , +.Fn d2i_ASN1_PRINTABLE , +.Fn i2d_ASN1_PRINTABLE , +.Fn d2i_ASN1_UTCTIME , +and +.Fn i2d_ASN1_UTCTIME +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn d2i_ASN1_BMPSTRING +and +.Fn i2d_ASN1_BMPSTRING +first appeared in SSLeay 0.9.1. +.Fn d2i_ASN1_ENUMERATED , +.Fn i2d_ASN1_ENUMERATED , +.Fn d2i_ASN1_GENERALIZEDTIME , +.Fn i2d_ASN1_GENERALIZEDTIME , +.Fn d2i_ASN1_TIME , +and +.Fn i2d_ASN1_TIME +first appeared in OpenSSL 0.9.2b. +.Fn d2i_ASN1_UINTEGER , +.Fn d2i_ASN1_UTF8STRING , +.Fn i2d_ASN1_UTF8STRING , +.Fn d2i_ASN1_VISIBLESTRING , +.Fn i2d_ASN1_VISIBLESTRING , +.Fn d2i_DIRECTORYSTRING , +.Fn i2d_DIRECTORYSTRING , +.Fn d2i_DISPLAYTEXT +and +.Fn i2d_DISPLAYTEXT +first appeared in OpenSSL 0.9.3. +These functions have been available since +.Ox 2.6 . +.Pp +.Fn d2i_ASN1_UNIVERSALSTRING , +.Fn i2d_ASN1_UNIVERSALSTRING , +.Fn d2i_ASN1_GENERALSTRING , +and +.Fn i2d_ASN1_GENERALSTRING +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Sh CAVEATS +Other implementations may accept or emit invalid DER encodings of +GeneralizedTime and UTCTime. +Portable applications should use +.Fn ASN1_STRING_length +to double check whether a given GeneralizedTime or UTCTime object is at least +15 or 13 bytes, respectively. diff --git a/static/openbsd/man3/d2i_ASN1_SEQUENCE_ANY.3 b/static/openbsd/man3/d2i_ASN1_SEQUENCE_ANY.3 new file mode 100644 index 00000000..bd545200 --- /dev/null +++ b/static/openbsd/man3/d2i_ASN1_SEQUENCE_ANY.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: d2i_ASN1_SEQUENCE_ANY.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2017, 2021 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 $Mdocdate: June 8 2025 $ +.Dt D2I_ASN1_SEQUENCE_ANY 3 +.Os +.Sh NAME +.Nm d2i_ASN1_SEQUENCE_ANY , +.Nm i2d_ASN1_SEQUENCE_ANY , +.Nm d2i_ASN1_SET_ANY , +.Nm i2d_ASN1_SET_ANY +.Nd decode and encode ASN.1 sequences and sets +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft ASN1_SEQUENCE_ANY * +.Fo d2i_ASN1_SEQUENCE_ANY +.Fa "ASN1_SEQUENCE_ANY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_SEQUENCE_ANY +.Fa "const ASN1_SEQUENCE_ANY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ASN1_SEQUENCE_ANY * +.Fo d2i_ASN1_SET_ANY +.Fa "ASN1_SEQUENCE_ANY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ASN1_SET_ANY +.Fa "const ASN1_SEQUENCE_ANY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode ASN.1 sequences and sets, +which are also represented by the +.Dv V_ASN1_SEQUENCE +and +.Dv V_ASN1_SET +type identifier constants, respectively. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +The type +.Vt ASN1_SEQUENCE_ANY +is defined as +.Vt STACK_OF(ASN1_TYPE) . +Whether such an object represents a sequence or a set is not stored +in the object itself but needs to be remembered separately. +.Pp +Like for +.Xr d2i_ASN1_TYPE 3 +and +.Xr i2d_ASN1_TYPE 3 , +the type of the individual values contained in the sequence or set +is not specified when calling the functions. +It might vary among the members, and it is stored together with +each value in each +.Vt ASN1_TYPE +object contained in the sequence or set. +.Sh RETURN VALUES +.Fn d2i_ASN1_SEQUENCE_ANY +returns an +.Vt ASN1_SEQUENCE_ANY +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_ASN1_SEQUENCE_ANY +returns the number of bytes written or a negative value if an error +occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr ASN1_TYPE_new 3 +.Sh HISTORY +.Fn d2i_ASN1_SEQUENCE_ANY , +.Fn i2d_ASN1_SEQUENCE_ANY , +.Fn d2i_ASN1_SET_ANY , +and +.Fn i2d_ASN1_SET_ANY +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/d2i_AUTHORITY_KEYID.3 b/static/openbsd/man3/d2i_AUTHORITY_KEYID.3 new file mode 100644 index 00000000..de1acfb6 --- /dev/null +++ b/static/openbsd/man3/d2i_AUTHORITY_KEYID.3 @@ -0,0 +1,76 @@ +.\" $OpenBSD: d2i_AUTHORITY_KEYID.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_AUTHORITY_KEYID 3 +.Os +.Sh NAME +.Nm d2i_AUTHORITY_KEYID , +.Nm i2d_AUTHORITY_KEYID +.Nd decode and encode X.509 authority key identifiers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft AUTHORITY_KEYID * +.Fo d2i_AUTHORITY_KEYID +.Fa "AUTHORITY_KEYID **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_AUTHORITY_KEYID +.Fa "AUTHORITY_KEYID *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +.Fn d2i_AUTHORITY_KEYID +and +.Fn i2d_AUTHORITY_KEYID +decode and encode an ASN.1 +.Vt AuthorityKeyIdentifier +structure defined in RFC 5280 section 4.2.1.1. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Sh RETURN VALUES +.Fn d2i_AUTHORITY_KEYID +returns an +.Vt AUTHORITY_KEYID +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_AUTHORITY_KEYID +returns the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr AUTHORITY_KEYID_new 3 , +.Xr X509_EXTENSION_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile: +.Bl -dash -compact +.It +section 4.2.1.1: Certificate Extensions: Authority Key Identifier +.It +section 5.2.1: CRL Extensions: Authority Key Identifier +.El +.Sh HISTORY +.Fn d2i_AUTHORITY_KEYID +and +.Fn i2d_AUTHORITY_KEYID +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/d2i_BASIC_CONSTRAINTS.3 b/static/openbsd/man3/d2i_BASIC_CONSTRAINTS.3 new file mode 100644 index 00000000..b90c13df --- /dev/null +++ b/static/openbsd/man3/d2i_BASIC_CONSTRAINTS.3 @@ -0,0 +1,107 @@ +.\" $OpenBSD: d2i_BASIC_CONSTRAINTS.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_BASIC_CONSTRAINTS 3 +.Os +.Sh NAME +.Nm d2i_BASIC_CONSTRAINTS , +.Nm i2d_BASIC_CONSTRAINTS , +.Nm d2i_EXTENDED_KEY_USAGE , +.Nm i2d_EXTENDED_KEY_USAGE +.Nd decode and encode X.509 key usage purposes +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft BASIC_CONSTRAINTS * +.Fo d2i_BASIC_CONSTRAINTS +.Fa "BASIC_CONSTRAINTS **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_BASIC_CONSTRAINTS +.Fa "BASIC_CONSTRAINTS *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft EXTENDED_KEY_USAGE * +.Fo d2i_EXTENDED_KEY_USAGE +.Fa "EXTENDED_KEY_USAGE **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_EXTENDED_KEY_USAGE +.Fa "EXTENDED_KEY_USAGE *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode data structures describing the +intended purposes that the key contained in an X.509 certificate +is to be used for. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_BASIC_CONSTRAINTS +and +.Fn i2d_BASIC_CONSTRAINTS +decode and encode an ASN.1 +.Vt BasicConstraints +structure defined in RFC 5280 section 4.2.1.9. +.Pp +.Fn d2i_EXTENDED_KEY_USAGE +and +.Fn i2d_EXTENDED_KEY_USAGE +decode and encode an ASN.1 +.Vt ExtKeyUsageSyntax +structure defined in RFC 5280 section 4.2.1.12. +.Sh RETURN VALUES +.Fn d2i_BASIC_CONSTRAINTS +and +.Fn d2i_EXTENDED_KEY_USAGE +return a +.Vt BASIC_CONSTRAINTS +or +.Vt EXTENDED_KEY_USAGE +object, respectively, or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_BASIC_CONSTRAINTS +and +.Fn i2d_EXTENDED_KEY_USAGE +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr BASIC_CONSTRAINTS_new 3 , +.Xr EXTENDED_KEY_USAGE_new 3 , +.Xr X509_EXTENSION_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn d2i_BASIC_CONSTRAINTS +and +.Fn i2d_BASIC_CONSTRAINTS +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . +.Pp +.Fn d2i_EXTENDED_KEY_USAGE +and +.Fn i2d_EXTENDED_KEY_USAGE +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/d2i_CMS_ContentInfo.3 b/static/openbsd/man3/d2i_CMS_ContentInfo.3 new file mode 100644 index 00000000..f4238d66 --- /dev/null +++ b/static/openbsd/man3/d2i_CMS_ContentInfo.3 @@ -0,0 +1,129 @@ +.\" $OpenBSD: d2i_CMS_ContentInfo.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" Copyright (c) 2019 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 $Mdocdate: June 8 2025 $ +.Dt D2I_CMS_CONTENTINFO 3 +.Os +.Sh NAME +.Nm d2i_CMS_ContentInfo , +.Nm i2d_CMS_ContentInfo , +.Nm d2i_CMS_bio , +.Nm i2d_CMS_bio , +.Nm d2i_CMS_ReceiptRequest , +.Nm i2d_CMS_ReceiptRequest +.Nd decode and encode Cryptographic Message Syntax data +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo d2i_CMS_ContentInfo +.Fa "CMS_ContentInfo **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_CMS_ContentInfo +.Fa "CMS_ContentInfo *val_in" +.Fa "unsigned char **out" +.Fc +.Ft CMS_ContentInfo * +.Fo d2i_CMS_bio +.Fa "BIO *in_bio" +.Fa "CMS_ContentInfo **val_out" +.Fc +.Ft int +.Fo i2d_CMS_bio +.Fa "BIO *out_bio" +.Fa "CMS_ContentInfo *val_in" +.Fc +.Ft CMS_ReceiptRequest * +.Fo d2i_CMS_ReceiptRequest +.Fa "CMS_ReceiptRequest **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_CMS_ReceiptRequest +.Fa "CMS_ReceiptRequest *val_in" +.Fa "unsigned char **out" +.Fc +.Sh DESCRIPTION +These functions decode and encode Cryptographic Message Syntax +data structures. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_CMS_ContentInfo +and +.Fn i2d_CMS_ContentInfo +decode and encode a +.Vt CMS_ContentInfo +structure defined in RFC 5652 section 3. +.Fn d2i_CMS_bio +and +.Fn i2d_CMS_bio +are similar except that they decode or encode using a +.Vt BIO +pointer. +.Pp +.Fn d2i_CMS_ReceiptRequest +and +.Fn i2d_CMS_ReceiptRequest +decode and encode a +.Vt CMS_ReceiptRequest +structure defined in RFC 2634 section 2.7. +.Sh RETURN VALUES +.Fn d2i_CMS_ContentInfo +and +.Fn d2i_CMS_bio +return a valid +.Vt CMS_ContentInfo +structure or +.Dv NULL +if an error occurs. +.Pp +.Fn d2i_CMS_ReceiptRequest +returns a valid +.Vt CMS_ReceiptRequest +structure or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_CMS_ContentInfo +and +.Fn i2d_CMS_ReceiptRequest +return the number of bytes successfully encoded +or a negative value if an error occurs. +.Pp +.Fn i2d_CMS_bio +returns 1 for success or 0 if an error occurs. +.Pp +For all functions, the error code can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_get0_type 3 , +.Xr CMS_ReceiptRequest_create0 3 , +.Xr i2d_CMS_bio_stream 3 +.Sh STANDARDS +RFC 5652: Cryptographic Message Syntax, section 3: General Syntax +.Pp +RFC 2634: Enhanced Security Services for S/MIME, +section 2.7: Receipt Request Syntax +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8h +and have been available since +.Ox 6.7 . diff --git a/static/openbsd/man3/d2i_DHparams.3 b/static/openbsd/man3/d2i_DHparams.3 new file mode 100644 index 00000000..f3cbd21f --- /dev/null +++ b/static/openbsd/man3/d2i_DHparams.3 @@ -0,0 +1,100 @@ +.\" $OpenBSD: d2i_DHparams.3,v 1.9 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Ulf Moeller and +.\" Dr. Stephen Henson . +.\" Copyright (c) 2000, 2002, 2015, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt D2I_DHPARAMS 3 +.Os +.Sh NAME +.Nm d2i_DHparams , +.Nm i2d_DHparams +.Nd PKCS#3 DH parameter functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dh.h +.Ft DH * +.Fo d2i_DHparams +.Fa "DH **a" +.Fa "unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DHparams +.Fa "DH *a" +.Fa "unsigned char **pp" +.Fc +.Sh DESCRIPTION +These functions decode and encode PKCS#3 DH parameters using the +DHparameter structure described in PKCS#3. +They otherwise behave in a way similar to +.Xr d2i_X509 3 +and +.Xr i2d_X509 3 . +.Sh RETURN VALUES +.Fn d2i_DHparams +returns a +.Vt DH +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_DHparams +returns the number of bytes successfully encoded or a value <= 0 +if an error occurs. +.Sh SEE ALSO +.Xr d2i_X509 3 , +.Xr DH_new 3 +.Sh HISTORY +.Fn d2i_DHparams +and +.Fn i2d_DHparams +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/d2i_DIST_POINT.3 b/static/openbsd/man3/d2i_DIST_POINT.3 new file mode 100644 index 00000000..0e49dfee --- /dev/null +++ b/static/openbsd/man3/d2i_DIST_POINT.3 @@ -0,0 +1,202 @@ +.\" $OpenBSD: d2i_DIST_POINT.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_DIST_POINT 3 +.Os +.Sh NAME +.Nm d2i_DIST_POINT , +.Nm i2d_DIST_POINT , +.Nm d2i_CRL_DIST_POINTS , +.Nm i2d_CRL_DIST_POINTS , +.Nm d2i_DIST_POINT_NAME , +.Nm i2d_DIST_POINT_NAME , +.Nm d2i_ISSUING_DIST_POINT , +.Nm i2d_ISSUING_DIST_POINT , +.Nm d2i_ACCESS_DESCRIPTION , +.Nm i2d_ACCESS_DESCRIPTION , +.Nm d2i_AUTHORITY_INFO_ACCESS , +.Nm i2d_AUTHORITY_INFO_ACCESS +.Nd decode and encode X.509 data access extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft DIST_POINT * +.Fo d2i_DIST_POINT +.Fa "DIST_POINT_NAME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DIST_POINT +.Fa "DIST_POINT *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft CRL_DIST_POINTS * +.Fo d2i_CRL_DIST_POINTS +.Fa "CRL_DIST_POINTS_NAME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_CRL_DIST_POINTS +.Fa "CRL_DIST_POINTS *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft DIST_POINT_NAME * +.Fo d2i_DIST_POINT_NAME +.Fa "DIST_POINT_NAME_NAME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DIST_POINT_NAME +.Fa "DIST_POINT_NAME *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ISSUING_DIST_POINT * +.Fo d2i_ISSUING_DIST_POINT +.Fa "ISSUING_DIST_POINT_NAME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ISSUING_DIST_POINT +.Fa "ISSUING_DIST_POINT *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ACCESS_DESCRIPTION * +.Fo d2i_ACCESS_DESCRIPTION +.Fa "ACCESS_DESCRIPTION_NAME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ACCESS_DESCRIPTION +.Fa "ACCESS_DESCRIPTION *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft AUTHORITY_INFO_ACCESS * +.Fo d2i_AUTHORITY_INFO_ACCESS +.Fa "AUTHORITY_INFO_ACCESS_NAME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_AUTHORITY_INFO_ACCESS +.Fa "AUTHORITY_INFO_ACCESS *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode X.509 extensions that communicate +where to retrieve additional information online. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_DIST_POINT +and +.Fn i2d_DIST_POINT +decode and encode an ASN.1 +.Vt DistributionPoint +structure defined in RFC 5280 section 4.2.1.13. +.Pp +.Fn d2i_CRL_DIST_POINTS +and +.Fn i2d_CRL_DIST_POINTS +decode and encode an ASN.1 +.Vt CRLDistributionPoints +structure defined in RFC 5280 section 4.2.1.13. +.Pp +.Fn d2i_DIST_POINT_NAME +and +.Fn i2d_DIST_POINT_NAME +decode and encode an ASN.1 +.Vt DistributionPointName +structure defined in RFC 5280 section 4.2.1.13. +.Pp +.Fn d2i_ISSUING_DIST_POINT +and +.Fn i2d_ISSUING_DIST_POINT +decode and encode an ASN.1 +.Vt IssuingDistributionPoint +structure defined in RFC 5280 section 5.2.5. +.Pp +.Fn d2i_ACCESS_DESCRIPTION +and +.Fn i2d_ACCESS_DESCRIPTION +decode and encode an ASN.1 +.Vt AccessDescription +structure defined in RFC 5280 section 4.2.2.1. +.Pp +.Fn d2i_AUTHORITY_INFO_ACCESS +and +.Fn i2d_AUTHORITY_INFO_ACCESS +decode and encode an ASN.1 +.Vt AuthorityInfoAccessSyntax +structure defined in RFC 5280 section 4.2.2.1. +.Sh RETURN VALUES +.Fn d2i_DIST_POINT , +.Fn d2i_CRL_DIST_POINTS , +.Fn d2i_DIST_POINT_NAME , +.Fn d2i_ISSUING_DIST_POINT , +.Fn d2i_ACCESS_DESCRIPTION , +and +.Fn d2i_AUTHORITY_INFO_ACCESS +return an object of the respective type or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_DIST_POINT , +.Fn i2d_CRL_DIST_POINTS , +.Fn i2d_DIST_POINT_NAME , +.Fn i2d_ISSUING_DIST_POINT , +.Fn i2d_ACCESS_DESCRIPTION , +and +.Fn i2d_AUTHORITY_INFO_ACCESS +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ACCESS_DESCRIPTION_new 3 , +.Xr ASN1_item_d2i 3 , +.Xr DIST_POINT_new 3 , +.Xr X509_EXTENSION_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn d2i_DIST_POINT , +.Fn i2d_DIST_POINT , +.Fn d2i_CRL_DIST_POINTS , +.Fn i2d_CRL_DIST_POINTS , +.Fn d2i_DIST_POINT_NAME , +and +.Fn i2d_DIST_POINT_NAME +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . +.Pp +.Fn d2i_ACCESS_DESCRIPTION , +.Fn i2d_ACCESS_DESCRIPTION , +.Fn d2i_AUTHORITY_INFO_ACCESS , +and +.Fn i2d_AUTHORITY_INFO_ACCESS +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn d2i_ISSUING_DIST_POINT +and +.Fn i2d_ISSUING_DIST_POINT +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/d2i_DSAPublicKey.3 b/static/openbsd/man3/d2i_DSAPublicKey.3 new file mode 100644 index 00000000..62dcc450 --- /dev/null +++ b/static/openbsd/man3/d2i_DSAPublicKey.3 @@ -0,0 +1,413 @@ +.\" $OpenBSD: d2i_DSAPublicKey.3,v 1.15 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2003, 2013, 2015, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt D2I_DSAPUBLICKEY 3 +.Os +.Sh NAME +.Nm d2i_DSAPublicKey , +.Nm i2d_DSAPublicKey , +.Nm d2i_DSA_PUBKEY , +.Nm i2d_DSA_PUBKEY , +.Nm d2i_DSA_PUBKEY_bio , +.Nm d2i_DSA_PUBKEY_fp , +.Nm i2d_DSA_PUBKEY_bio , +.Nm i2d_DSA_PUBKEY_fp , +.Nm d2i_DSAPrivateKey , +.Nm i2d_DSAPrivateKey , +.Nm d2i_DSAPrivateKey_bio , +.Nm d2i_DSAPrivateKey_fp , +.Nm i2d_DSAPrivateKey_bio , +.Nm i2d_DSAPrivateKey_fp , +.Nm d2i_DSAparams , +.Nm i2d_DSAparams , +.Nm d2i_DSAparams_bio , +.Nm i2d_DSAparams_bio , +.Nm d2i_DSAparams_fp , +.Nm i2d_DSAparams_fp , +.Nm DSAparams_dup , +.Nm d2i_DSA_SIG , +.Nm i2d_DSA_SIG +.Nd decode and encode DSA keys +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/dsa.h +.Ft DSA * +.Fo d2i_DSAPublicKey +.Fa "DSA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSAPublicKey +.Fa "const DSA *val_in" +.Fa "unsigned char **der_out" +.Fc +.In openssl/x509.h +.Ft DSA * +.Fo d2i_DSA_PUBKEY +.Fa "DSA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSA_PUBKEY +.Fa "const DSA *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft DSA * +.Fo d2i_DSA_PUBKEY_bio +.Fa "BIO *in_bio" +.Fa "DSA **val_out" +.Fc +.Ft DSA * +.Fo d2i_DSA_PUBKEY_fp +.Fa "FILE *in_fp" +.Fa "DSA **val_out" +.Fc +.Ft int +.Fo i2d_DSA_PUBKEY_bio +.Fa "BIO *out_bio" +.Fa "DSA *val_in" +.Fc +.Ft int +.Fo i2d_DSA_PUBKEY_fp +.Fa "FILE *out_fp" +.Fa "DSA *val_in" +.Fc +.In openssl/dsa.h +.Ft DSA * +.Fo d2i_DSAPrivateKey +.Fa "DSA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSAPrivateKey +.Fa "const DSA *val_in" +.Fa "unsigned char **der_out" +.Fc +.In openssl/x509.h +.Ft DSA * +.Fo d2i_DSAPrivateKey_bio +.Fa "BIO *in_bio" +.Fa "DSA **val_out" +.Fc +.Ft DSA * +.Fo d2i_DSAPrivateKey_fp +.Fa "FILE *in_fp" +.Fa "DSA **val_out" +.Fc +.Ft int +.Fo i2d_DSAPrivateKey_bio +.Fa "BIO *out_bio" +.Fa "DSA *val_in" +.Fc +.Ft int +.Fo i2d_DSAPrivateKey_fp +.Fa "FILE *out_fp" +.Fa "DSA *val_in" +.Fc +.In openssl/dsa.h +.Ft DSA * +.Fo d2i_DSAparams +.Fa "DSA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSAparams +.Fa "const DSA *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft DSA * +.Fo d2i_DSAparams_bio +.Fa "BIO *in_bio" +.Fa "DSA **val_out" +.Fc +.Ft int +.Fo i2d_DSAparams_bio +.Fa "BIO *out_bio" +.Fa "DSA *val_in" +.Fc +.Ft DSA * +.Fo d2i_DSAparams_fp +.Fa "FILE *in_fp" +.Fa "DSA **val_out" +.Fc +.Ft int +.Fo i2d_DSAparams_fp +.Fa FILE *out_fp +.Fa "DSA *val_in" +.Fc +.Ft DSA * +.Fo DSAparams_dup +.Fa "DSA *val_in" +.Fc +.Ft DSA_SIG * +.Fo d2i_DSA_SIG +.Fa "DSA_SIG **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSA_SIG +.Fa "const DSA_SIG *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode DSA keys and parameters. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_DSAPublicKey +and +.Fn i2d_DSAPublicKey +decode and encode the DSA public key components using a non-standard +format, so consider using +.Fn d2i_DSA_PUBKEY +and +.Fn i2d_DSA_PUBKEY +instead. +The actual data encoded depends on the value of +.Fa val_in->write_params . +If +.Fa val_in->write_params +is zero, only the +.Fa val_in->pub_key +field is encoded as an ASN.1 INTEGER. +If +.Fa val_in->write_params +is 1, then a SEQUENCE consisting of the +.Fa val_in->p , +.Fa val_in->q , +.Fa val_in->g , +and +.Fa val_in->pub_key +fields is encoded. +.Pp +.Fn d2i_DSA_PUBKEY +and +.Fn i2d_DSA_PUBKEY +decode and encode a DSA public key using an ASN.1 +.Vt SubjectPublicKeyInfo +structure defined in RFC 5280 section 4.1 +and documented in +.Xr X509_PUBKEY_new 3 . +.Fn d2i_DSA_PUBKEY_bio , +.Fn d2i_DSA_PUBKEY_fp , +.Fn i2d_DSA_PUBKEY_bio , +and +.Fn i2d_DSA_PUBKEY_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_DSAPrivateKey +and +.Fn i2d_DSAPrivateKey +decode and encode the DSA private key components. +The +.Vt DSA +object passed to the private key encoding functions should have all +the private key components present. +These functions use a non-standard structure consisting of a +SEQUENCE containing the +.Fa val_in->p , +.Fa val_in->q , +.Fa val_in->g , +.Fa val_in->pub_key , +and +.Fa val_in->priv_key +fields. +This data format is unencrypted. +For private key security when writing private keys to files, +consider using +.Xr PEM_write_DSAPrivateKey 3 +instead. +.Fn d2i_DSAPrivateKey_bio , +.Fn d2i_DSAPrivateKey_fp , +.Fn i2d_DSAPrivateKey_bio , +and +.Fn i2d_DSAPrivateKey_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_DSAparams +and +.Fn i2d_DSAparams +decode and encode the DSA parameters using an ASN.1 +.Vt Dss-Parms +structure defined in RFC 3279 section 2.3.2 +and used for the parameters field of the ASN.1 +.Vt AlgorithmIdentifier +structure defined in RFC 5280 section 4.1.1.2. +.Fn d2i_DSAparams_bio , +.Fn i2d_DSAparams_bio , +.Fn d2i_DSAparams_fp , +.Fn i2d_DSAparams_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn DSAparams_dup +allocates and initializes an empty +.Vt DSA +object and copies the DSA parameters from +.Fa val_in +to it by calling +.Fn i2d_DSAparams +and +.Fn d2i_DSAparams . +If a private or public key are present in +.Fa val_in , +they are not copied. +.Pp +.Fn d2i_DSA_SIG +and +.Fn i2d_DSA_SIG +decode and encode a DSA signature using an ASN.1 +.Vt Dss-Sig-Value +structure as defined in RFC 3279 section 2.2.2 +and used for the signatureValue field of the ASN.1 +.Vt Certificate +structure described in RFC 5280 sections 4.1.1.3 and 5.1.1.3. +.Sh RETURN VALUES +.Fn d2i_DSAPublicKey , +.Fn d2i_DSA_PUBKEY , +.Fn d2i_DSA_PUBKEY_bio , +.Fn d2i_DSA_PUBKEY_fp , +.Fn d2i_DSAPrivateKey , +.Fn d2i_DSAPrivateKey_bio , +.Fn d2i_DSAPrivateKey_fp , +.Fn d2i_DSAparams , +.Fn d2i_DSAparams_bio , +.Fn d2i_DSAparams_fp , +and +.Fn DSAparams_dup +return a valid +.Vt DSA +object or +.Dv NULL +if an error occurs. +.Pp +.Fn d2i_DSA_SIG +returns a valid +.Vt DSA_SIG +object or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr DSA_new 3 , +.Xr DSA_SIG_new 3 , +.Xr EVP_PKEY_set1_DSA 3 , +.Xr PEM_write_DSAPrivateKey 3 , +.Xr X509_PUBKEY_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 4.1: Basic Certificate Fields +.Pp +RFC 3279: Algorithms and Identifiers for the Internet X.509 Public +Key Infrastructure Certificate and Certificate Revocation List (CRL) +Profile: +.Bl -dash -compact +.It +section 2.2.2: DSA Signature Algorithm +.It +section 2.3.2: DSA Signature Keys +.El +.Sh HISTORY +.Fn d2i_DSAPublicKey , +.Fn i2d_DSAPublicKey , +.Fn d2i_DSAPrivateKey , +and +.Fn i2d_DSAPrivateKey +first appeared in SSLeay 0.6.0. +.Fn d2i_DSAPrivateKey_bio , +.Fn d2i_DSAPrivateKey_fp , +.Fn i2d_DSAPrivateKey_bio , +.Fn i2d_DSAPrivateKey_fp , +.Fn d2i_DSAparams , +.Fn i2d_DSAparams , +.Fn d2i_DSAparams_bio , +.Fn i2d_DSAparams_bio , +.Fn d2i_DSAparams_fp , +.Fn i2d_DSAparams_fp , +and +.Fn DSAparams_dup +first appeared in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn d2i_DSA_SIG +and +.Fn i2d_DSA_SIG +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . +.Pp +.Fn d2i_DSA_PUBKEY , +.Fn i2d_DSA_PUBKEY , +.Fn d2i_DSA_PUBKEY_bio , +.Fn d2i_DSA_PUBKEY_fp , +.Fn i2d_DSA_PUBKEY_bio , +and +.Fn i2d_DSA_PUBKEY_fp +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/d2i_ECPKParameters.3 b/static/openbsd/man3/d2i_ECPKParameters.3 new file mode 100644 index 00000000..8e824951 --- /dev/null +++ b/static/openbsd/man3/d2i_ECPKParameters.3 @@ -0,0 +1,467 @@ +.\" $OpenBSD: d2i_ECPKParameters.3,v 1.15 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 05ea606a May 20 20:52:46 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016 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. +.\" +.\" The original file was written by Matt Caswell . +.\" Copyright (c) 2013, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt D2I_ECPKPARAMETERS 3 +.Os +.Sh NAME +.Nm d2i_ECPKParameters , +.Nm i2d_ECPKParameters , +.Nm d2i_ECPKParameters_bio , +.Nm i2d_ECPKParameters_bio , +.Nm d2i_ECPKParameters_fp , +.Nm i2d_ECPKParameters_fp , +.Nm d2i_ECParameters , +.Nm i2d_ECParameters , +.Nm ECParameters_dup , +.Nm d2i_ECPrivateKey , +.Nm i2d_ECPrivateKey , +.Nm d2i_ECPrivateKey_bio , +.Nm i2d_ECPrivateKey_bio , +.Nm d2i_ECPrivateKey_fp , +.Nm i2d_ECPrivateKey_fp , +.Nm o2i_ECPublicKey , +.Nm i2o_ECPublicKey , +.Nm ECPKParameters_print , +.Nm ECPKParameters_print_fp , +.Nm ECParameters_print , +.Nm ECParameters_print_fp , +.Nm d2i_EC_PUBKEY , +.Nm i2d_EC_PUBKEY , +.Nm d2i_EC_PUBKEY_bio , +.Nm i2d_EC_PUBKEY_bio , +.Nm d2i_EC_PUBKEY_fp , +.Nm i2d_EC_PUBKEY_fp +.Nd decode and encode ASN.1 representations of elliptic curve entities +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ec.h +.Ft EC_GROUP * +.Fo d2i_ECPKParameters +.Fa "EC_GROUP **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ECPKParameters +.Fa "const EC_GROUP *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft EC_GROUP * +.Fo d2i_ECPKParameters_bio +.Fa "BIO *in_bio" +.Fa "EC_GROUP **val_out" +.Fc +.Ft int +.Fo i2d_ECPKParameters_bio +.Fa "BIO *out_bio" +.Fa "EC_GROUP *val_in" +.Fc +.Ft EC_GROUP * +.Fo d2i_ECPKParameters_fp +.Fa "FILE *in_fp" +.Fa "EC_GROUP **val_out" +.Fc +.Ft int +.Fo i2d_ECPKParameters_fp +.Fa "FILE *out_fp" +.Fa "EC_GROUP *val_in" +.Fc +.Ft EC_KEY * +.Fo d2i_ECParameters +.Fa "EC_KEY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ECParameters +.Fa "EC_KEY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft EC_KEY * +.Fo ECParameters_dup +.Fa "EC_KEY *val_in" +.Fc +.Ft EC_KEY * +.Fo d2i_ECPrivateKey +.Fa "EC_KEY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ECPrivateKey +.Fa "EC_KEY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft EC_KEY * +.Fo d2i_ECPrivateKey_bio +.Fa "BIO *in_bio" +.Fa "EC_KEY **val_out" +.Fc +.Ft int +.Fo i2d_ECPrivateKey_bio +.Fa "BIO *out_bio" +.Fa "EC_KEY *val_in" +.Fc +.Ft EC_KEY * +.Fo d2i_ECPrivateKey_fp +.Fa "FILE *in_fp" +.Fa "EC_KEY **val_out" +.Fc +.Ft int +.Fo i2d_ECPrivateKey_fp +.Fa "FILE *out_fp" +.Fa "EC_KEY *val_in" +.Fc +.Ft EC_KEY * +.Fo o2i_ECPublicKey +.Fa "EC_KEY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2o_ECPublicKey +.Fa "const EC_KEY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft int +.Fo ECPKParameters_print +.Fa "BIO *out_bio" +.Fa "const EC_GROUP *val_in" +.Fa "int indent" +.Fc +.Ft int +.Fo ECPKParameters_print_fp +.Fa "FILE *out_fp" +.Fa "const EC_GROUP *val_in" +.Fa "int indent" +.Fc +.Ft int +.Fo ECParameters_print +.Fa "BIO *out_bio" +.Fa "const EC_KEY *val_in" +.Fc +.Ft int +.Fo ECParameters_print_fp +.Fa "FILE *out_fp" +.Fa "const EC_KEY *val_in" +.Fc +.In openssl/x509.h +.Ft EC_KEY * +.Fo d2i_EC_PUBKEY +.Fa "EC_KEY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_EC_PUBKEY +.Fa "EC_KEY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft EC_KEY * +.Fo d2i_EC_PUBKEY_bio +.Fa "BIO *in_bio" +.Fa "EC_KEY **val_out" +.Fc +.Ft int +.Fo i2d_EC_PUBKEY_bio +.Fa "BIO *out_bio" +.Fa "EC_KEY *val_in" +.Fc +.Ft EC_KEY * +.Fo d2i_EC_PUBKEY_fp +.Fa "FILE *in_fp" +.Fa "EC_KEY **val_out" +.Fc +.Ft int +.Fo i2d_EC_PUBKEY_fp +.Fa "FILE *out_fp" +.Fa "EC_KEY *val_in" +.Fc +.Sh DESCRIPTION +These functions decode and encode elliptic curve keys and parameters. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_ECPKParameters +and +.Fn i2d_ECPKParameters +decode and encode the parameters of an elliptic curve. +.Fn d2i_ECPKParameters_bio , +.Fn i2d_ECPKParameters_bio , +.Fn d2i_ECPKParameters_fp , +and +.Fn i2d_ECPKParameters_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +These four functions are currently implemented as macros. +.Pp +.Fn d2i_ECParameters +does the same parsing as +.Fn d2i_ECPKParameters +but saves the result in the +.Fa group +field of an +.Vt EC_KEY +structure. +.Pp +.Fn i2d_ECParameters +produces the same output as +.Fn i2d_ECPKParameters +but uses +.Fa val_in->group +for input instead of +.Fa val_in . +.Pp +.Fn ECParameters_dup +allocates and initializes an empty +.Vt EC_KEY +object and copies the EC parameters from +.Fa val_in +to it by calling +.Fn i2d_ECParameters +and +.Fn d2i_ECParameters . +If a private or public key or any flags are present in +.Fa val_in , +they are not copied. +.Pp +.Fn d2i_ECPrivateKey +and +.Fn i2d_ECPrivateKey +decode and encode an EC private key using an ASN.1 +.Vt ECPrivateKey +structure defined in RFC 5915 section 3 and used for the privateKey +field of the ASN.1 +.Vt PrivateKeyInfo +structure defined in RFC 5208 section 5, see +.Xr PKCS8_PRIV_KEY_INFO_new 3 . +.Fn d2i_ECPrivateKey_bio , +.Fn i2d_ECPrivateKey_bio , +.Fn d2i_ECPrivateKey_fp , +and +.Fn i2d_ECPrivateKey_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn o2i_ECPublicKey +and +.Fn i2o_ECPublicKey +decode and encode an EC public key. +In contrast to +.Xr ASN1_item_d2i 3 , +.Fn o2i_ECPublicKey +requires +.Fa val_out , +.Pf * Fa val_out , +and +.Po Pf * Fa val_out Pc Ns -> Ns Fa group +to be +.Pf non- Dv NULL . +.Pp +.Fn ECPKParameters_print +and +.Fn ECPKParameters_print_fp +print human-readable output of the public parameters of the +.Vt EC_GROUP +to +.Fa out_bio +or +.Fa out_fp . +The output lines are indented by +.Fa indent +spaces. +.Pp +.Fn ECParameters_print +and +.Fn ECParameters_print_fp +print the parameter components of +.Fa val_in +to +.Fa out_bio +or +.Fa out_fp . +.Pp +.Fn d2i_EC_PUBKEY +and +.Fn i2d_EC_PUBKEY +decode and encode an EC public key using an ASN.1 +.Vt SubjectPublicKeyInfo +structure defined in RFC 5280 section 4.1 and documented in +.Xr X509_PUBKEY_new 3 . +.Fn d2i_EC_PUBKEY_bio , +.Fn i2d_EC_PUBKEY_bio , +.Fn d2i_EC_PUBKEY_fp , +and +.Fn i2d_EC_PUBKEY_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Sh RETURN VALUES +.Fn d2i_ECPKParameters , +.Fn d2i_ECPKParameters_bio , +and +.Fn d2i_ECPKParameters_fp +return a valid +.Vt EC_GROUP +structure or +.Dv NULL +if an error occurs. +.Pp +.Fn d2i_ECParameters , +.Fn ECParameters_dup , +.Fn d2i_ECPrivateKey , +.Fn d2i_ECPrivateKey_bio , +.Fn d2i_ECPrivateKey_fp , +.Fn o2i_ECPublicKey , +.Fn d2i_EC_PUBKEY , +.Fn d2i_EC_PUBKEY_bio , +and +.Fn d2i_EC_PUBKEY_fp +return a valid +.Vt EC_KEY +structure or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_ECPKParameters , +.Fn i2d_ECParameters , +.Fn i2d_ECPrivateKey , +.Fn i2o_ECPublicKey , +and +.Fn i2d_EC_PUBKEY +return the number of bytes successfully encoded or a negative value if +an error occurs. +.Pp +.Fn i2d_ECPKParameters_bio , +.Fn i2d_ECPKParameters_fp , +.Fn i2d_ECPrivateKey_bio , +.Fn i2d_ECPrivateKey_fp , +.Fn ECPKParameters_print , +.Fn ECPKParameters_print_fp , +.Fn ECParameters_print , +.Fn ECParameters_print_fp , +.Fn i2d_EC_PUBKEY_bio , +and +.Fn i2d_EC_PUBKEY_fp +return 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr EC_GROUP_new_by_curve_name 3 , +.Xr EC_KEY_new 3 , +.Xr EVP_PKEY_set1_EC_KEY 3 , +.Xr PEM_write_ECPrivateKey 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 , +.Xr X509_PUBKEY_new 3 +.Sh STANDARDS +RFC 5915: Elliptic Curve Private Key Structure +.Pp +RFC 5208: Public-Key Cryptography Standards (PKCS) #8: +Private-Key Information Syntax Specification +.Pp +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 4.1: Basic Certificate Fields +.Sh HISTORY +.Fn d2i_ECPKParameters , +.Fn i2d_ECPKParameters , +.Fn d2i_ECPKParameters_bio , +.Fn i2d_ECPKParameters_bio , +.Fn d2i_ECPKParameters_fP , +.Fn i2d_ECPKParameters_fp , +.Fn d2i_ECParameters , +.Fn i2d_ECParameters , +.Fn ECParameters_dup , +.Fn d2i_ECPrivateKey , +.Fn i2d_ECPrivateKey , +.Fn d2i_ECPrivateKey_bio , +.Fn i2d_ECPrivateKey_bio , +.Fn d2i_ECPrivateKey_fp , +.Fn i2d_ECPrivateKey_fp , +.Fn o2i_ECPublicKey , +.Fn i2o_ECPublicKey , +.Fn ECPKParameters_print , +.Fn ECPKParameters_print_fp , +.Fn ECParameters_print , +.Fn ECParameters_print_fp , +.Fn d2i_EC_PUBKEY , +.Fn i2d_EC_PUBKEY , +.Fn d2i_EC_PUBKEY_bio , +.Fn i2d_EC_PUBKEY_bio , +.Fn d2i_EC_PUBKEY_fp , +and +.Fn i2d_EC_PUBKEY_fp +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/d2i_ESS_SIGNING_CERT.3 b/static/openbsd/man3/d2i_ESS_SIGNING_CERT.3 new file mode 100644 index 00000000..0305ca78 --- /dev/null +++ b/static/openbsd/man3/d2i_ESS_SIGNING_CERT.3 @@ -0,0 +1,119 @@ +.\" $OpenBSD: d2i_ESS_SIGNING_CERT.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_ESS_SIGNING_CERT 3 +.Os +.Sh NAME +.Nm d2i_ESS_SIGNING_CERT , +.Nm i2d_ESS_SIGNING_CERT , +.Nm d2i_ESS_CERT_ID , +.Nm i2d_ESS_CERT_ID , +.Nm d2i_ESS_ISSUER_SERIAL , +.Nm i2d_ESS_ISSUER_SERIAL +.Nd decode and encode signing certificates for S/MIME +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ts.h +.Ft ESS_SIGNING_CERT * +.Fo d2i_ESS_SIGNING_CERT +.Fa "ESS_SIGNING_CERT **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ESS_SIGNING_CERT +.Fa "const ESS_SIGNING_CERT *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ESS_CERT_ID * +.Fo d2i_ESS_CERT_ID +.Fa "ESS_CERT_ID **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ESS_CERT_ID +.Fa "const ESS_CERT_ID *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft ESS_ISSUER_SERIAL * +.Fo d2i_ESS_ISSUER_SERIAL +.Fa "ESS_ISSUER_SERIAL **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_ESS_ISSUER_SERIAL +.Fa "const ESS_ISSUER_SERIAL *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode signing certificate attribute +structures. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_ESS_SIGNING_CERT +and +.Fn i2d_ESS_SIGNING_CERT +decode and encode an ASN.1 +.Vt SigningCertificate +structure defined in RFC 2634 section 5.4. +.Pp +.Fn d2i_ESS_CERT_ID +and +.Fn i2d_ESS_CERT_ID +decode and encode an ASN.1 +.Vt ESSCertID +structure defined in RFC 2634 section 5.4.1. +.Pp +.Fn d2i_ESS_ISSUER_SERIAL +and +.Fn i2d_ESS_ISSUER_SERIAL +decode and encode an ASN.1 +.Vt IssuerSerial +structure defined in RFC 2634 section 5.4.1. +.Sh RETURN VALUES +.Fn d2i_ESS_SIGNING_CERT , +.Fn d2i_ESS_CERT_ID , +and +.Fn d2i_ESS_ISSUER_SERIAL +return an +.Vt ESS_SIGNING_CERT , +.Vt ESS_CERT_ID , +or +.Vt ESS_ISSUER_SERIAL +object, respectively, or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_ESS_SIGNING_CERT , +.Fn i2d_ESS_CERT_ID , +and +.Fn i2d_ESS_ISSUER_SERIAL +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr ESS_SIGNING_CERT_new 3 +.Sh STANDARDS +RFC 2634: Enhanced Security Services for S/MIME, +section 5: Signing Certificate Attribute +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.0 +and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/d2i_GENERAL_NAME.3 b/static/openbsd/man3/d2i_GENERAL_NAME.3 new file mode 100644 index 00000000..557e5ce3 --- /dev/null +++ b/static/openbsd/man3/d2i_GENERAL_NAME.3 @@ -0,0 +1,161 @@ +.\" $OpenBSD: d2i_GENERAL_NAME.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_GENERAL_NAME 3 +.Os +.Sh NAME +.Nm d2i_GENERAL_NAME , +.Nm i2d_GENERAL_NAME , +.Nm d2i_GENERAL_NAMES , +.Nm i2d_GENERAL_NAMES , +.Nm d2i_EDIPARTYNAME , +.Nm i2d_EDIPARTYNAME , +.Nm d2i_OTHERNAME , +.Nm i2d_OTHERNAME +.Nd decode and encode names for use in X.509 extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft GENERAL_NAME * +.Fo d2i_GENERAL_NAME +.Fa "GENERAL_NAME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_GENERAL_NAME +.Fa "GENERAL_NAME *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft GENERAL_NAMES * +.Fo d2i_GENERAL_NAMES +.Fa "GENERAL_NAMES **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_GENERAL_NAMES +.Fa "GENERAL_NAMES *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft EDIPARTYNAME * +.Fo d2i_EDIPARTYNAME +.Fa "EDIPARTYNAME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_EDIPARTYNAME +.Fa "EDIPARTYNAME *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OTHERNAME * +.Fo d2i_OTHERNAME +.Fa "OTHERNAME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OTHERNAME +.Fa "OTHERNAME *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode names that can be used in X.509 +extensions. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_GENERAL_NAME +and +.Fn i2d_GENERAL_NAME +decode and encode an ASN.1 +.Vt GeneralName +structure defined in RFC 5280 section 4.2.1.6. +.Pp +.Fn d2i_GENERAL_NAMES +and +.Fn i2d_GENERAL_NAMES +decode and encode an ASN.1 +.Vt GeneralNames +structure defined in RFC 5280 section 4.2.1.6. +.Pp +.Fn d2i_EDIPARTYNAME +and +.Fn i2d_EDIPARTYNAME +decode and encode an ASN.1 +.Vt EDIPartyName +structure defined in RFC 5280 section 4.2.1.6. +.Pp +.Fn d2i_OTHERNAME +and +.Fn i2d_OTHERNAME +decode and encode an ASN.1 +.Vt OtherName +structure defined in RFC 5280 section 4.2.1.6. +.Sh RETURN VALUES +.Fn d2i_GENERAL_NAME , +.Fn d2i_GENERAL_NAMES , +.Fn d2i_EDIPARTYNAME , +and +.Fn d2i_OTHERNAME +return a +.Vt GENERAL_NAME , +.Vt GENERAL_NAMES , +.Vt EDIPARTYNAME , +or +.Vt OTHERNAME +object, respectively, or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_GENERAL_NAME , +.Fn i2d_GENERAL_NAMES , +.Fn i2d_EDIPARTYNAME , +and +.Fn i2d_OTHERNAME +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr d2i_X509_NAME 3 , +.Xr GENERAL_NAME_new 3 , +.Xr X509_EXTENSION_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 4.2: Certificate Extensions +.Sh HISTORY +.Fn d2i_GENERAL_NAME , +.Fn i2d_GENERAL_NAME , +.Fn d2i_GENERAL_NAMES , +and +.Fn i2d_GENERAL_NAMES +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . +.Pp +.Fn d2i_OTHERNAME +and +.Fn i2d_OTHERNAME +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn d2i_EDIPARTYNAME +and +.Fn i2d_EDIPARTYNAME +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/d2i_OCSP_REQUEST.3 b/static/openbsd/man3/d2i_OCSP_REQUEST.3 new file mode 100644 index 00000000..7d27d2b4 --- /dev/null +++ b/static/openbsd/man3/d2i_OCSP_REQUEST.3 @@ -0,0 +1,182 @@ +.\" $OpenBSD: d2i_OCSP_REQUEST.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_OCSP_REQUEST 3 +.Os +.Sh NAME +.Nm d2i_OCSP_REQUEST , +.Nm i2d_OCSP_REQUEST , +.Nm d2i_OCSP_SIGNATURE , +.Nm i2d_OCSP_SIGNATURE , +.Nm d2i_OCSP_REQINFO , +.Nm i2d_OCSP_REQINFO , +.Nm d2i_OCSP_ONEREQ , +.Nm i2d_OCSP_ONEREQ , +.Nm d2i_OCSP_CERTID , +.Nm i2d_OCSP_CERTID , +.Nm d2i_OCSP_SERVICELOC , +.Nm i2d_OCSP_SERVICELOC +.Nd decode and encode OCSP requests +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ocsp.h +.Ft OCSP_REQUEST * +.Fo d2i_OCSP_REQUEST +.Fa "OCSP_REQUEST **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_REQUEST +.Fa "OCSP_REQUEST *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_SIGNATURE * +.Fo d2i_OCSP_SIGNATURE +.Fa "OCSP_SIGNATURE **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_SIGNATURE +.Fa "OCSP_SIGNATURE *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_REQINFO * +.Fo d2i_OCSP_REQINFO +.Fa "OCSP_REQINFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_REQINFO +.Fa "OCSP_REQINFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_ONEREQ * +.Fo d2i_OCSP_ONEREQ +.Fa "OCSP_ONEREQ **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_ONEREQ +.Fa "OCSP_ONEREQ *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_CERTID * +.Fo d2i_OCSP_CERTID +.Fa "OCSP_CERTID **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_CERTID +.Fa "OCSP_CERTID *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_SERVICELOC * +.Fo d2i_OCSP_SERVICELOC +.Fa "OCSP_SERVICELOC **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_SERVICELOC +.Fa "OCSP_SERVICELOC *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode ASN.1 structures used for OCSP +requests. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_OCSP_REQUEST +and +.Fn i2d_OCSP_REQUEST +decode and encode an ASN.1 +.Vt OCSPRequest +structure defined in RFC 6960 section 4.1.1. +.Pp +.Fn d2i_OCSP_SIGNATURE +and +.Fn i2d_OCSP_SIGNATURE +decode and encode an ASN.1 +.Vt Signature +structure defined in RFC 6960 section 4.1.1. +.Pp +.Fn d2i_OCSP_REQINFO +and +.Fn i2d_OCSP_REQINFO +decode and encode an ASN.1 +.Vt TBSRequest +structure defined in RFC 6960 section 4.1.1. +.Pp +.Fn d2i_OCSP_ONEREQ +and +.Fn i2d_OCSP_ONEREQ +decode and encode an ASN.1 +.Vt Request +structure defined in RFC 6960 section 4.1.1. +.Pp +.Fn d2i_OCSP_CERTID +and +.Fn i2d_OCSP_CERTID +decode and encode an ASN.1 +.Vt CertID +structure defined in RFC 6960 section 4.1.1. +.Pp +.Fn d2i_OCSP_SERVICELOC +and +.Fn i2d_OCSP_SERVICELOC +decode and encode an ASN.1 +.Vt ServiceLocator +structure defined in RFC 6960 section 4.4.6. +.Sh RETURN VALUES +.Fn d2i_OCSP_REQUEST , +.Fn d2i_OCSP_SIGNATURE , +.Fn d2i_OCSP_REQINFO , +.Fn d2i_OCSP_ONEREQ , +.Fn d2i_OCSP_CERTID , +and +.Fn d2i_OCSP_SERVICELOC +return an object of the respective type or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_OCSP_REQUEST , +.Fn i2d_OCSP_SIGNATURE , +.Fn i2d_OCSP_REQINFO , +.Fn i2d_OCSP_ONEREQ , +.Fn i2d_OCSP_CERTID , +and +.Fn i2d_OCSP_SERVICELOC +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr OCSP_CERTID_new 3 , +.Xr OCSP_REQUEST_new 3 , +.Xr OCSP_SERVICELOC_new 3 +.Sh STANDARDS +RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate +Status Protocol, section 4.1: Request Syntax +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/d2i_OCSP_RESPONSE.3 b/static/openbsd/man3/d2i_OCSP_RESPONSE.3 new file mode 100644 index 00000000..a89c566c --- /dev/null +++ b/static/openbsd/man3/d2i_OCSP_RESPONSE.3 @@ -0,0 +1,249 @@ +.\" $OpenBSD: d2i_OCSP_RESPONSE.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_OCSP_RESPONSE 3 +.Os +.Sh NAME +.Nm d2i_OCSP_RESPONSE , +.Nm i2d_OCSP_RESPONSE , +.Nm d2i_OCSP_RESPBYTES , +.Nm i2d_OCSP_RESPBYTES , +.Nm d2i_OCSP_BASICRESP , +.Nm i2d_OCSP_BASICRESP , +.Nm d2i_OCSP_RESPDATA , +.Nm i2d_OCSP_RESPDATA , +.Nm d2i_OCSP_RESPID , +.Nm i2d_OCSP_RESPID , +.Nm d2i_OCSP_SINGLERESP , +.Nm i2d_OCSP_SINGLERESP , +.Nm d2i_OCSP_CERTSTATUS , +.Nm i2d_OCSP_CERTSTATUS , +.Nm d2i_OCSP_REVOKEDINFO , +.Nm i2d_OCSP_REVOKEDINFO , +.Nm d2i_OCSP_CRLID , +.Nm i2d_OCSP_CRLID +.Nd decode and encode OCSP responses +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ocsp.h +.Ft OCSP_RESPONSE * +.Fo d2i_OCSP_RESPONSE +.Fa "OCSP_RESPONSE **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_RESPONSE +.Fa "OCSP_RESPONSE *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_RESPBYTES * +.Fo d2i_OCSP_RESPBYTES +.Fa "OCSP_RESPBYTES **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_RESPBYTES +.Fa "OCSP_RESPBYTES *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_BASICRESP * +.Fo d2i_OCSP_BASICRESP +.Fa "OCSP_BASICRESP **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_BASICRESP +.Fa "OCSP_BASICRESP *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_RESPDATA * +.Fo d2i_OCSP_RESPDATA +.Fa "OCSP_RESPDATA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_RESPDATA +.Fa "OCSP_RESPDATA *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_RESPID * +.Fo d2i_OCSP_RESPID +.Fa "OCSP_RESPID **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_RESPID +.Fa "OCSP_RESPID *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_SINGLERESP * +.Fo d2i_OCSP_SINGLERESP +.Fa "OCSP_SINGLERESP **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_SINGLERESP +.Fa "OCSP_SINGLERESP *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_CERTSTATUS * +.Fo d2i_OCSP_CERTSTATUS +.Fa "OCSP_CERTSTATUS **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_CERTSTATUS +.Fa "OCSP_CERTSTATUS *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_REVOKEDINFO * +.Fo d2i_OCSP_REVOKEDINFO +.Fa "OCSP_REVOKEDINFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_REVOKEDINFO +.Fa "OCSP_REVOKEDINFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft OCSP_CRLID * +.Fo d2i_OCSP_CRLID +.Fa "OCSP_CRLID **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_OCSP_CRLID +.Fa "OCSP_CRLID *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode ASN.1 structures used for OCSP +responses. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_OCSP_RESPONSE +and +.Fn i2d_OCSP_RESPONSE +decode and encode an ASN.1 +.Vt OCSPResponse +structure defined in RFC 6960 section 4.2.1. +.Pp +.Fn d2i_OCSP_RESPBYTES +and +.Fn i2d_OCSP_RESPBYTES +decode and encode an ASN.1 +.Vt ResponseBytes +structure defined in RFC 6960 section 4.2.1. +.Pp +.Fn d2i_OCSP_BASICRESP +and +.Fn i2d_OCSP_BASICRESP +decode and encode an ASN.1 +.Vt BasicOCSPResponse +structure defined in RFC 6960 section 4.2.1. +.Pp +.Fn d2i_OCSP_RESPDATA +and +.Fn i2d_OCSP_RESPDATA +decode and encode an ASN.1 +.Vt ResponseData +structure defined in RFC 6960 section 4.2.1. +.Pp +.Fn d2i_OCSP_RESPID +and +.Fn i2d_OCSP_RESPID +decode and encode an ASN.1 +.Vt ResponderID +structure defined in RFC 6960 section 4.2.1. +.Pp +.Fn d2i_OCSP_SINGLERESP +and +.Fn i2d_OCSP_SINGLERESP +decode and encode an ASN.1 +.Vt SingleResponse +structure defined in RFC 6960 section 4.2.1. +.Pp +.Fn d2i_OCSP_CERTSTATUS +and +.Fn i2d_OCSP_CERTSTATUS +decode and encode an ASN.1 +.Vt CertStatus +structure defined in RFC 6960 section 4.2.1. +.Pp +.Fn d2i_OCSP_REVOKEDINFO +and +.Fn i2d_OCSP_REVOKEDINFO +decode and encode an ASN.1 +.Vt RevokedInfo +structure defined in RFC 6960 section 4.2.1. +.Pp +.Fn d2i_OCSP_CRLID +and +.Fn i2d_OCSP_CRLID +decode and encode an ASN.1 +.Vt CrlID +structure defined in RFC 6960 section 4.4.2. +.Sh RETURN VALUES +.Fn d2i_OCSP_RESPONSE , +.Fn d2i_OCSP_RESPBYTES , +.Fn d2i_OCSP_BASICRESP , +.Fn d2i_OCSP_RESPDATA , +.Fn d2i_OCSP_RESPID , +.Fn d2i_OCSP_SINGLERESP , +.Fn d2i_OCSP_CERTSTATUS , +.Fn d2i_OCSP_REVOKEDINFO , +and +.Fn d2i_OCSP_CRLID +return an object of the respective type or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_OCSP_RESPONSE , +.Fn i2d_OCSP_RESPBYTES , +.Fn i2d_OCSP_BASICRESP , +.Fn i2d_OCSP_RESPDATA , +.Fn i2d_OCSP_RESPID , +.Fn i2d_OCSP_SINGLERESP , +.Fn i2d_OCSP_CERTSTATUS , +.Fn i2d_OCSP_REVOKEDINFO , +and +.Fn i2d_OCSP_CRLID +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr OCSP_CRLID_new 3 , +.Xr OCSP_REQUEST_new 3 , +.Xr OCSP_RESPONSE_new 3 , +.Xr OCSP_SINGLERESP_new 3 +.Sh STANDARDS +RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate +Status Protocol, section 4.2: Response Syntax +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.7 +and have been available since +.Ox 3.2 . diff --git a/static/openbsd/man3/d2i_PKCS12.3 b/static/openbsd/man3/d2i_PKCS12.3 new file mode 100644 index 00000000..2dda946a --- /dev/null +++ b/static/openbsd/man3/d2i_PKCS12.3 @@ -0,0 +1,203 @@ +.\" $OpenBSD: d2i_PKCS12.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_PKCS12 3 +.Os +.Sh NAME +.Nm d2i_PKCS12 , +.Nm i2d_PKCS12 , +.Nm d2i_PKCS12_bio , +.Nm i2d_PKCS12_bio , +.Nm d2i_PKCS12_fp , +.Nm i2d_PKCS12_fp , +.Nm d2i_PKCS12_MAC_DATA , +.Nm i2d_PKCS12_MAC_DATA , +.Nm d2i_PKCS12_SAFEBAG , +.Nm i2d_PKCS12_SAFEBAG , +.Nm d2i_PKCS12_BAGS , +.Nm i2d_PKCS12_BAGS +.Nd decode and encode PKCS#12 structures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs12.h +.Ft PKCS12 * +.Fo d2i_PKCS12 +.Fa "PKCS12 **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS12 +.Fa "PKCS12 *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS12 * +.Fo d2i_PKCS12_bio +.Fa "BIO *in_bio" +.Fa "PKCS12 **val_out" +.Fc +.Ft int +.Fo i2d_PKCS12_bio +.Fa "BIO *out_bio" +.Fa "PKCS12 *val_in" +.Fc +.Ft PKCS12 * +.Fo d2i_PKCS12_fp +.Fa "FILE *in_fp" +.Fa "PKCS12 **val_out" +.Fc +.Ft int +.Fo i2d_PKCS12_fp +.Fa "FILE *out_fp" +.Fa "PKCS12 *val_in" +.Fc +.Ft PKCS12_MAC_DATA * +.Fo d2i_PKCS12_MAC_DATA +.Fa "PKCS12_MAC_DATA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS12_MAC_DATA +.Fa "PKCS12_MAC_DATA *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS12_SAFEBAG * +.Fo d2i_PKCS12_SAFEBAG +.Fa "PKCS12_SAFEBAG **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS12_SAFEBAG +.Fa "PKCS12_SAFEBAG *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS12_BAGS * +.Fo d2i_PKCS12_BAGS +.Fa "PKCS12_BAGS **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS12_BAGS +.Fa "PKCS12_BAGS *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode PKCS#12 structures. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_PKCS12 +and +.Fn i2d_PKCS12 +decode and encode an ASN.1 +.Vt PFX +.Pq personal information exchange +structure defined in RFC 7292 section 4. +.Fn d2i_PKCS12_bio , +.Fn i2d_PKCS12_bio , +.Fn d2i_PKCS12_fp , +and +.Fn i2d_PKCS12_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_PKCS12_MAC_DATA +and +.Fn i2d_PKCS12_MAC_DATA +decode and encode an ASN.1 +.Vt MacData +structure defined in RFC 7292 section 4. +.Pp +.Fn d2i_PKCS12_SAFEBAG +and +.Fn i2d_PKCS12_SAFEBAG +decode and encode an ASN.1 +.Vt SafeBag +structure defined in RFC 7292 section 4.2. +.Pp +.Fn d2i_PKCS12_BAGS +and +.Fn i2d_PKCS12_BAGS +decode and encode the bagValue field of an ASN.1 +.Vt SafeBag +structure. +.Sh RETURN VALUES +.Fn d2i_PKCS12 , +.Fn d2i_PKCS12_bio , +and +.Fn d2i_PKCS12_fp +return a +.Vt PKCS12 +object or +.Dv NULL +if an error occurs. +.Pp +.Fn d2i_PKCS12_MAC_DATA , +.Fn d2i_PKCS12_SAFEBAG , +and +.Fn d2i_PKCS12_BAGS +return a +.Vt PKCS12_MAC_DATA , +.Vt PKCS12_SAFEBAG , +or +.Vt PKCS12_BAGS +object, respectively, or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_PKCS12 , +.Fn i2d_PKCS12_MAC_DATA , +.Fn i2d_PKCS12_SAFEBAG , +and +.Fn i2d_PKCS12_BAGS +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Pp +.Fn i2d_PKCS12_bio +and +.Fn i2d_PKCS12_fp +return 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr PKCS12_create 3 , +.Xr PKCS12_new 3 , +.Xr PKCS12_parse 3 , +.Xr PKCS12_SAFEBAG_new 3 +.Sh STANDARDS +RFC 7292: PKCS #12: Personal Information Exchange Syntax +.Sh HISTORY +.Fn d2i_PKCS12 , +.Fn i2d_PKCS12 , +.Fn d2i_PKCS12_bio , +.Fn i2d_PKCS12_bio , +.Fn d2i_PKCS12_fp , +.Fn i2d_PKCS12_fp , +.Fn d2i_PKCS12_MAC_DATA , +.Fn i2d_PKCS12_MAC_DATA , +.Fn d2i_PKCS12_SAFEBAG , +.Fn i2d_PKCS12_SAFEBAG , +.Fn d2i_PKCS12_BAGS , +and +.Fn i2d_PKCS12_BAGS +first appeared in OpenSSL 0.9.3 and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/d2i_PKCS7.3 b/static/openbsd/man3/d2i_PKCS7.3 new file mode 100644 index 00000000..6d72433b --- /dev/null +++ b/static/openbsd/man3/d2i_PKCS7.3 @@ -0,0 +1,342 @@ +.\" $OpenBSD: d2i_PKCS7.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_PKCS7 3 +.Os +.Sh NAME +.Nm d2i_PKCS7 , +.Nm i2d_PKCS7 , +.Nm d2i_PKCS7_bio , +.Nm i2d_PKCS7_bio , +.Nm d2i_PKCS7_fp , +.Nm i2d_PKCS7_fp , +.Nm d2i_PKCS7_DIGEST , +.Nm i2d_PKCS7_DIGEST , +.Nm d2i_PKCS7_ENCRYPT , +.Nm i2d_PKCS7_ENCRYPT , +.Nm d2i_PKCS7_ENC_CONTENT , +.Nm i2d_PKCS7_ENC_CONTENT , +.Nm d2i_PKCS7_ENVELOPE , +.Nm i2d_PKCS7_ENVELOPE , +.Nm d2i_PKCS7_ISSUER_AND_SERIAL , +.Nm i2d_PKCS7_ISSUER_AND_SERIAL , +.Nm d2i_PKCS7_RECIP_INFO , +.Nm i2d_PKCS7_RECIP_INFO , +.Nm d2i_PKCS7_SIGNED , +.Nm i2d_PKCS7_SIGNED , +.Nm d2i_PKCS7_SIGNER_INFO , +.Nm i2d_PKCS7_SIGNER_INFO , +.Nm d2i_PKCS7_SIGN_ENVELOPE , +.Nm i2d_PKCS7_SIGN_ENVELOPE +.Nd decode and encode PKCS#7 data structures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft PKCS7 * +.Fo d2i_PKCS7 +.Fa "PKCS7 **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS7 +.Fa "PKCS7 *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS7 * +.Fo d2i_PKCS7_bio +.Fa "BIO *in_bio" +.Fa "PKCS7 **val_out" +.Fc +.Ft int +.Fo i2d_PKCS7_bio +.Fa "BIO *out_bio" +.Fa "PKCS7 *val_in" +.Fc +.Ft PKCS7 * +.Fo d2i_PKCS7_fp +.Fa "FILE *in_fp" +.Fa "PKCS7 **val_out" +.Fc +.Ft int +.Fo i2d_PKCS7_fp +.Fa "FILE *out_fp" +.Fa "PKCS7 *val_in" +.Fc +.Ft PKCS7_DIGEST * +.Fo d2i_PKCS7_DIGEST +.Fa "PKCS7_DIGEST **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS7_DIGEST +.Fa "PKCS7_DIGEST *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS7_ENCRYPT * +.Fo d2i_PKCS7_ENCRYPT +.Fa "PKCS7_ENCRYPT **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS7_ENCRYPT +.Fa "PKCS7_ENCRYPT *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS7_ENC_CONTENT * +.Fo d2i_PKCS7_ENC_CONTENT +.Fa "PKCS7_ENC_CONTENT **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS7_ENC_CONTENT +.Fa "PKCS7_ENC_CONTENT *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS7_ENVELOPE * +.Fo d2i_PKCS7_ENVELOPE +.Fa "PKCS7_ENVELOPE **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS7_ENVELOPE +.Fa "PKCS7_ENVELOPE *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS7_ISSUER_AND_SERIAL * +.Fo d2i_PKCS7_ISSUER_AND_SERIAL +.Fa "PKCS7_ISSUER_AND_SERIAL **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS7_ISSUER_AND_SERIAL +.Fa "PKCS7_ISSUER_AND_SERIAL *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS7_RECIP_INFO * +.Fo d2i_PKCS7_RECIP_INFO +.Fa "PKCS7_RECIP_INFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS7_RECIP_INFO +.Fa "PKCS7_RECIP_INFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS7_SIGNED * +.Fo d2i_PKCS7_SIGNED +.Fa "PKCS7_SIGNED **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS7_SIGNED +.Fa "PKCS7_SIGNED *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS7_SIGNER_INFO * +.Fo d2i_PKCS7_SIGNER_INFO +.Fa "PKCS7_SIGNER_INFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS7_SIGNER_INFO +.Fa "PKCS7_SIGNER_INFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS7_SIGN_ENVELOPE * +.Fo d2i_PKCS7_SIGN_ENVELOPE +.Fa "PKCS7_SIGN_ENVELOPE **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS7_SIGN_ENVELOPE +.Fa "PKCS7_SIGN_ENVELOPE *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode PKCS#7 data structures. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_PKCS7 +and +.Fn i2d_PKCS7 +decode and encode an ASN.1 +.Vt ContentInfo +structure defined in RFC 2315 section 7. +.Fn d2i_PKCS7_bio , +.Fn i2d_PKCS7_bio , +.Fn d2i_PKCS7_fp , +and +.Fn i2d_PKCS7_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_PKCS7_DIGEST +and +.Fn i2d_PKCS7_DIGEST +decode and encode an ASN.1 +.Vt DigestedData +structure defined in RFC 2315 section 12. +.Pp +.Fn d2i_PKCS7_ENCRYPT +and +.Fn i2d_PKCS7_ENCRYPT +decode and encode an ASN.1 +.Vt EncryptedData +structure defined in RFC 2315 section 13. +.Pp +.Fn d2i_PKCS7_ENC_CONTENT +and +.Fn i2d_PKCS7_ENC_CONTENT +decode and encode an ASN.1 +.Vt EncryptedContentInfo +structure defined in RFC 2315 section 10.1. +.Pp +.Fn d2i_PKCS7_ENVELOPE +and +.Fn i2d_PKCS7_ENVELOPE +decode and encode an ASN.1 +.Vt EnvelopedData +structure defined in RFC 2315 section 10. +.Pp +.Fn d2i_PKCS7_ISSUER_AND_SERIAL +and +.Fn i2d_PKCS7_ISSUER_AND_SERIAL +decode and encode an ASN.1 +.Vt IssuerAndSerialNumber +structure defined in RFC 2315 section 6.7. +.Pp +.Fn d2i_PKCS7_RECIP_INFO +and +.Fn i2d_PKCS7_RECIP_INFO +decode and encode an ASN.1 +.Vt RecipientInfo +structure defined in RFC 2315 section 10.2. +.Pp +.Fn d2i_PKCS7_SIGNED +and +.Fn i2d_PKCS7_SIGNED +decode and encode an ASN.1 +.Vt SignedData +structure defined in RFC 2315 section 9. +.Pp +.Fn d2i_PKCS7_SIGNER_INFO +and +.Fn i2d_PKCS7_SIGNER_INFO +decode and encode an ASN.1 +.Vt SignerInfo +structure defined in RFC 2315 section 9.2. +.Pp +.Fn d2i_PKCS7_SIGN_ENVELOPE +and +.Fn i2d_PKCS7_SIGN_ENVELOPE +decode and encode an ASN.1 +.Vt SignedAndEnvelopedData +structure defined in RFC 2315 section 11. +.Sh RETURN VALUES +.Fn d2i_PKCS7 , +.Fn d2i_PKCS7_bio , +and +.Fn d2i_PKCS7_fp +return a +.Vt PKCS7 +object or +.Dv NULL +if an error occurs. +.Pp +.Fn d2i_PKCS7_DIGEST , +.Fn d2i_PKCS7_ENCRYPT , +.Fn d2i_PKCS7_ENC_CONTENT , +.Fn d2i_PKCS7_ENVELOPE , +.Fn d2i_PKCS7_ISSUER_AND_SERIAL , +.Fn d2i_PKCS7_RECIP_INFO , +.Fn d2i_PKCS7_SIGNED , +.Fn d2i_PKCS7_SIGNER_INFO , +and +.Fn d2i_PKCS7_SIGN_ENVELOPE +return an object of the respective type or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_PKCS7 , +.Fn i2d_PKCS7_DIGEST , +.Fn i2d_PKCS7_ENCRYPT , +.Fn i2d_PKCS7_ENC_CONTENT , +.Fn i2d_PKCS7_ENVELOPE , +.Fn i2d_PKCS7_ISSUER_AND_SERIAL , +.Fn i2d_PKCS7_RECIP_INFO , +.Fn i2d_PKCS7_SIGNED , +.Fn i2d_PKCS7_SIGNER_INFO , +and +.Fn i2d_PKCS7_SIGN_ENVELOPE +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Pp +.Fn i2d_PKCS7_bio +and +.Fn i2d_PKCS7_fp +return 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr i2d_PKCS7_bio_stream 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +.Xr PEM_write_PKCS7 3 , +.Xr PKCS7_new 3 , +.Xr SMIME_write_PKCS7 3 +.Sh STANDARDS +RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5 +.Sh HISTORY +.Fn d2i_PKCS7 , +.Fn i2d_PKCS7 , +.Fn d2i_PKCS7_bio , +.Fn i2d_PKCS7_bio , +.Fn d2i_PKCS7_fp , +.Fn i2d_PKCS7_fp , +.Fn d2i_PKCS7_DIGEST , +.Fn i2d_PKCS7_DIGEST , +.Fn d2i_PKCS7_ENCRYPT , +.Fn i2d_PKCS7_ENCRYPT , +.Fn d2i_PKCS7_ENC_CONTENT , +.Fn i2d_PKCS7_ENC_CONTENT , +.Fn d2i_PKCS7_ENVELOPE , +.Fn i2d_PKCS7_ENVELOPE , +.Fn d2i_PKCS7_ISSUER_AND_SERIAL , +.Fn i2d_PKCS7_ISSUER_AND_SERIAL , +.Fn d2i_PKCS7_RECIP_INFO , +.Fn i2d_PKCS7_RECIP_INFO , +.Fn d2i_PKCS7_SIGNED , +.Fn i2d_PKCS7_SIGNED , +.Fn d2i_PKCS7_SIGNER_INFO , +.Fn i2d_PKCS7_SIGNER_INFO , +.Fn d2i_PKCS7_SIGN_ENVELOPE , +and +.Fn i2d_PKCS7_SIGN_ENVELOPE +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/d2i_PKCS8PrivateKey_bio.3 b/static/openbsd/man3/d2i_PKCS8PrivateKey_bio.3 new file mode 100644 index 00000000..41ab7ebc --- /dev/null +++ b/static/openbsd/man3/d2i_PKCS8PrivateKey_bio.3 @@ -0,0 +1,173 @@ +.\" $OpenBSD: d2i_PKCS8PrivateKey_bio.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2002, 2016, 2017 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt D2I_PKCS8PRIVATEKEY_BIO 3 +.Os +.Sh NAME +.Nm d2i_PKCS8PrivateKey_bio , +.Nm d2i_PKCS8PrivateKey_fp , +.Nm i2d_PKCS8PrivateKey_bio , +.Nm i2d_PKCS8PrivateKey_fp , +.Nm i2d_PKCS8PrivateKey_nid_bio , +.Nm i2d_PKCS8PrivateKey_nid_fp +.Nd PKCS#8 format private key functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft EVP_PKEY * +.Fo d2i_PKCS8PrivateKey_bio +.Fa "BIO *bp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EVP_PKEY * +.Fo d2i_PKCS8PrivateKey_fp +.Fa "FILE *fp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo i2d_PKCS8PrivateKey_bio +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo i2d_PKCS8PrivateKey_fp +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo i2d_PKCS8PrivateKey_nid_bio +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fa "int nid" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo i2d_PKCS8PrivateKey_nid_fp +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fa "int nid" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Sh 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 functions described in +.Xr PEM_read_PrivateKey 3 . +.Pp +These functions are currently the only way to store encrypted private +keys using DER format. +.Pp +Currently all the functions use +.Vt BIO +or +.Vt FILE +pointers. +There are no functions which work directly on memory, +though this can be readily worked around +by converting the buffers to memory BIOs; +see +.Xr BIO_s_mem 3 +for details. +.Sh RETURN VALUES +.Fn d2i_PKCS8PrivateKey_bio +and +.Fn d2i_PKCS8PrivateKey_fp +return a +.Vt EVP_PKEY +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_PKCS8PrivateKey_bio , +.Fn i2d_PKCS8PrivateKey_fp , +.Fn i2d_PKCS8PrivateKey_nid_bio , +and +.Fn i2d_PKCS8PrivateKey_nid_fp +return 1 on success or 0 on error. +.Sh SEE ALSO +.Xr d2i_X509_SIG 3 , +.Xr PEM_write_PKCS8PrivateKey 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.5 +and have been available since +.Ox 2.7 . +.Sh CAVEATS +Do not confuse these functions with +.Xr i2d_PKCS8PrivateKeyInfo_bio 3 +and +.Xr i2d_PKCS8PrivateKeyInfo_fp 3 , +which write out private keys in +.Sy unencrypted +DER format. diff --git a/static/openbsd/man3/d2i_PKCS8_PRIV_KEY_INFO.3 b/static/openbsd/man3/d2i_PKCS8_PRIV_KEY_INFO.3 new file mode 100644 index 00000000..583fd536 --- /dev/null +++ b/static/openbsd/man3/d2i_PKCS8_PRIV_KEY_INFO.3 @@ -0,0 +1,128 @@ +.\" $OpenBSD: d2i_PKCS8_PRIV_KEY_INFO.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_PKCS8_PRIV_KEY_INFO 3 +.Os +.Sh NAME +.Nm d2i_PKCS8_PRIV_KEY_INFO , +.Nm i2d_PKCS8_PRIV_KEY_INFO , +.Nm d2i_PKCS8_PRIV_KEY_INFO_bio , +.Nm i2d_PKCS8_PRIV_KEY_INFO_bio , +.Nm d2i_PKCS8_PRIV_KEY_INFO_fp , +.Nm i2d_PKCS8_PRIV_KEY_INFO_fp +.Nd decode and encode PKCS#8 private key +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft PKCS8_PRIV_KEY_INFO * +.Fo d2i_PKCS8_PRIV_KEY_INFO +.Fa "PKCS8_PRIV_KEY_INFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKCS8_PRIV_KEY_INFO +.Fa "PKCS8_PRIV_KEY_INFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft PKCS8_PRIV_KEY_INFO * +.Fo d2i_PKCS8_PRIV_KEY_INFO_bio +.Fa "BIO *in_bio" +.Fa "PKCS8_PRIV_KEY_INFO **val_out" +.Fc +.Ft int +.Fo i2d_PKCS8_PRIV_KEY_INFO_bio +.Fa "BIO *out_bio" +.Fa "PKCS8_PRIV_KEY_INFO *val_in" +.Fc +.Ft PKCS8_PRIV_KEY_INFO * +.Fo d2i_PKCS8_PRIV_KEY_INFO_fp +.Fa "FILE *in_fp" +.Fa "PKCS8_PRIV_KEY_INFO **val_out" +.Fc +.Ft int +.Fo i2d_PKCS8_PRIV_KEY_INFO_fp +.Fa "BIO *out_fp" +.Fa "PKCS8_PRIV_KEY_INFO *val_in" +.Fc +.Sh DESCRIPTION +.Fn d2i_PKCS8_PRIV_KEY_INFO +and +.Fn i2d_PKCS8_PRIV_KEY_INFO +decode and encode an ASN.1 +.Vt PrivateKeyInfo +structure defined in RFC 5208 section 5. +.Pp +.Fn d2i_PKCS8_PRIV_KEY_INFO_bio , +.Fn i2d_PKCS8_PRIV_KEY_INFO_bio , +.Fn d2i_PKCS8_PRIV_KEY_INFO_fp , +and +.Fn i2d_PKCS8_PRIV_KEY_INFO_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +These functions all use unencrypted DER format. +To store private keys in encrypted form, consider +.Xr d2i_PKCS8PrivateKey_bio 3 +or +.Xr PEM_write_PKCS8PrivateKey 3 . +.Sh RETURN VALUES +.Fn d2i_PKCS8_PRIV_KEY_INFO , +.Fn d2i_PKCS8_PRIV_KEY_INFO_bio , +and +.Fn d2i_PKCS8_PRIV_KEY_INFO_fp +return a +.Vt PKCS8_PRIV_KEY_INFO +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_PKCS8_PRIV_KEY_INFO +returns the number of bytes successfully encoded or a negative value +if an error occurs. +.Pp +.Fn i2d_PKCS8_PRIV_KEY_INFO_bio +and +.Fn i2d_PKCS8_PRIV_KEY_INFO_fp +return 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr d2i_PKCS8PrivateKey_bio 3 , +.Xr d2i_PrivateKey 3 , +.Xr PEM_write_PKCS8_PRIV_KEY_INFO 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 +.Sh STANDARDS +RFC 5208: PKCS#8: Private-Key Information Syntax Specification +.Sh HISTORY +.Fn d2i_PKCS8_PRIV_KEY_INFO +and +.Fn i2d_PKCS8_PRIV_KEY_INFO +first appeared in OpenSSL 0.9.3. +.Fn d2i_PKCS8_PRIV_KEY_INFO_bio , +.Fn i2d_PKCS8_PRIV_KEY_INFO_bio , +.Fn d2i_PKCS8_PRIV_KEY_INFO_fp , +and +.Fn i2d_PKCS8_PRIV_KEY_INFO_fp +first appeared in OpenSSL 0.9.4. +All these functions have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/d2i_PKEY_USAGE_PERIOD.3 b/static/openbsd/man3/d2i_PKEY_USAGE_PERIOD.3 new file mode 100644 index 00000000..1c3a215a --- /dev/null +++ b/static/openbsd/man3/d2i_PKEY_USAGE_PERIOD.3 @@ -0,0 +1,75 @@ +.\" $OpenBSD: d2i_PKEY_USAGE_PERIOD.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_PKEY_USAGE_PERIOD 3 +.Os +.Sh NAME +.Nm d2i_PKEY_USAGE_PERIOD , +.Nm i2d_PKEY_USAGE_PERIOD +.Nd decode and encode X.509 key usage period extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft PKEY_USAGE_PERIOD * +.Fo d2i_PKEY_USAGE_PERIOD +.Fa "PKEY_USAGE_PERIOD **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PKEY_USAGE_PERIOD +.Fa "PKEY_USAGE_PERIOD *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +.Fn d2i_PKEY_USAGE_PERIOD +and +.Fn i2d_PKEY_USAGE_PERIOD +decode and encode an ASN.1 +.Vt PrivateKeyUsagePeriod +structure defined in RFC 3280 section 4.2.1.4. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Sh RETURN VALUES +.Fn d2i_PKEY_USAGE_PERIOD +returns a +.Vt PKEY_USAGE_PERIOD +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_PKEY_USAGE_PERIOD +returns the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr PKEY_USAGE_PERIOD_new 3 , +.Xr X509_EXTENSION_new 3 +.Sh STANDARDS +RFC 3280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 4.2.1.4: Private Key Usage Period +.Pp +RFC 3280 was obsoleted by RFC 5280; see +.Xr PKEY_USAGE_PERIOD_new 3 +for details. +.Sh HISTORY +.Fn d2i_PKEY_USAGE_PERIOD +and +.Fn i2d_PKEY_USAGE_PERIOD +first appeared in OpenSSL 0.9.2b and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/d2i_POLICYINFO.3 b/static/openbsd/man3/d2i_POLICYINFO.3 new file mode 100644 index 00000000..c335edc1 --- /dev/null +++ b/static/openbsd/man3/d2i_POLICYINFO.3 @@ -0,0 +1,166 @@ +.\" $OpenBSD: d2i_POLICYINFO.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_POLICYINFO 3 +.Os +.Sh NAME +.Nm d2i_POLICYINFO , +.Nm i2d_POLICYINFO , +.Nm d2i_CERTIFICATEPOLICIES , +.Nm i2d_CERTIFICATEPOLICIES , +.Nm d2i_POLICYQUALINFO , +.Nm i2d_POLICYQUALINFO , +.Nm d2i_USERNOTICE , +.Nm i2d_USERNOTICE , +.Nm d2i_NOTICEREF , +.Nm i2d_NOTICEREF +.Nd decode and encode X.509 certificate policies +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft POLICYINFO * +.Fo d2i_POLICYINFO +.Fa "POLICYINFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_POLICYINFO +.Fa "POLICYINFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft CERTIFICATEPOLICIES * +.Fo d2i_CERTIFICATEPOLICIES +.Fa "CERTIFICATEPOLICIES **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_CERTIFICATEPOLICIES +.Fa "CERTIFICATEPOLICIES *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft POLICYQUALINFO * +.Fo d2i_POLICYQUALINFO +.Fa "POLICYQUALINFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_POLICYQUALINFO +.Fa "POLICYQUALINFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft USERNOTICE * +.Fo d2i_USERNOTICE +.Fa "USERNOTICE **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_USERNOTICE +.Fa "USERNOTICE *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft NOTICEREF * +.Fo d2i_NOTICEREF +.Fa "NOTICEREF **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_NOTICEREF +.Fa "NOTICEREF *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode X.509 certificate policies. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_POLICYINFO +and +.Fn i2d_POLICYINFO +decode and encode an ASN.1 +.Vt PolicyInformation +structure defined in RFC 5280 section 4.2.1.4. +.Pp +.Fn d2i_CERTIFICATEPOLICIES +and +.Fn i2d_CERTIFICATEPOLICIES +decode and encode an ASN.1 +.Vt CertificatePolicies +structure defined in RFC 5280 section 4.2.1.4. +.Pp +.Fn d2i_POLICYQUALINFO +and +.Fn i2d_POLICYQUALINFO +decode and encode an ASN.1 +.Vt PolicyQualifierInfo +structure defined in RFC 5280 section 4.2.1.4. +.Pp +.Fn d2i_USERNOTICE +and +.Fn i2d_USERNOTICE +decode and encode an ASN.1 +.Vt UserNotice +structure defined in RFC 5280 section 4.2.1.4. +.Pp +.Fn d2i_NOTICEREF +and +.Fn i2d_NOTICEREF +decode and encode an ASN.1 +.Vt NoticeReference +structure defined in RFC 5280 section 4.2.1.4. +.Sh RETURN VALUES +.Fn d2i_POLICYINFO , +.Fn d2i_CERTIFICATEPOLICIES , +.Fn d2i_POLICYQUALINFO , +.Fn d2i_USERNOTICE , +and +.Fn d2i_NOTICEREF +return a +.Vt POLICYINFO , +.Vt CERTIFICATEPOLICIES , +.Vt POLICYQUALINFO , +.Vt USERNOTICE , +or +.Vt NOTICEREF +object, respectively, or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_POLICYINFO , +.Fn i2d_CERTIFICATEPOLICIES , +.Fn i2d_POLICYQUALINFO , +.Fn i2d_USERNOTICE , +and +.Fn i2d_NOTICEREF +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr POLICYINFO_new 3 , +.Xr X509_EXTENSION_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 4.2.1.4: Certificate Policies +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.3 +and have been available since +.Ox 2.6 . diff --git a/static/openbsd/man3/d2i_PrivateKey.3 b/static/openbsd/man3/d2i_PrivateKey.3 new file mode 100644 index 00000000..48f1b93a --- /dev/null +++ b/static/openbsd/man3/d2i_PrivateKey.3 @@ -0,0 +1,313 @@ +.\" $OpenBSD: d2i_PrivateKey.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016, 2021 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. +.\" +.\" The original file was written by Dr. Stephen Henson . +.\" Copyright (c) 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt D2I_PRIVATEKEY 3 +.Os +.Sh NAME +.Nm d2i_PrivateKey , +.Nm d2i_AutoPrivateKey , +.Nm d2i_PrivateKey_bio , +.Nm d2i_PrivateKey_fp , +.Nm i2d_PrivateKey , +.Nm i2d_PrivateKey_bio , +.Nm i2d_PrivateKey_fp , +.Nm i2d_PKCS8PrivateKeyInfo_bio , +.Nm i2d_PKCS8PrivateKeyInfo_fp , +.Nm d2i_PublicKey , +.Nm i2d_PublicKey +.Nd decode and encode EVP_PKEY objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft EVP_PKEY * +.Fo d2i_PrivateKey +.Fa "int type" +.Fa "EVP_PKEY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft EVP_PKEY * +.Fo d2i_AutoPrivateKey +.Fa "EVP_PKEY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft EVP_PKEY * +.Fo d2i_PrivateKey_bio +.Fa "BIO *in_bio" +.Fa "EVP_PKEY **val_out" +.Fc +.Ft EVP_PKEY * +.Fo d2i_PrivateKey_fp +.Fa "FILE *in_fp" +.Fa "EVP_PKEY **val_out" +.Fc +.Ft int +.Fo i2d_PrivateKey +.Fa "EVP_PKEY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft int +.Fo i2d_PrivateKey_bio +.Fa "BIO *out_bio" +.Fa "EVP_PKEY *val_in" +.Fc +.Ft int +.Fo i2d_PrivateKey_fp +.Fa "FILE *out_fp" +.Fa "EVP_PKEY *val_in" +.Fc +.Ft int +.Fo i2d_PKCS8PrivateKeyInfo_bio +.Fa "BIO *out_bio" +.Fa "EVP_PKEY *val_in" +.Fc +.Ft int +.Fo i2d_PKCS8PrivateKeyInfo_fp +.Fa "FILE *out_fp" +.Fa "EVP_PKEY *val_in" +.Fc +.Ft EVP_PKEY * +.Fo d2i_PublicKey +.Fa "int type" +.Fa "EVP_PKEY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PublicKey +.Fa "EVP_PKEY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These are algorithm-independent interfaces to decode and encode +private and public keys. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_PrivateKey +decodes a private key using algorithm +.Fa type . +It attempts to use any algorithm specific format or the PKCS#8 unencrypted +.Vt PrivateKeyInfo +format defined in RFC 5208 section 5. +The +.Fa type +parameter should be a public key algorithm constant such as +.Dv EVP_PKEY_RSA . +An error occurs if the decoded key does not match +.Fa type . +.Pp +.Fn d2i_AutoPrivateKey +is similar to +.Fn d2i_PrivateKey +except that it attempts to automatically detect the algorithm. +.Pp +.Fn d2i_PrivateKey_bio +and +.Fn d2i_PrivateKey_fp +are similar to +.Fn d2i_PrivateKey +except that they read from a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn i2d_PrivateKey +encodes +.Fa val_in . +It uses an algorithm specific format or, if none is defined for +that key type, the PKCS#8 unencrypted +.Vt PrivateKeyInfo +format. +.Pp +.Fn i2d_PrivateKey_bio +and +.Fn i2d_PrivateKey_fp +are similar to +.Fn i2d_PrivateKey +except that they write to a +.Vt BIO +or +.Vt FILE +pointer and use a different convention for their return values. +.Pp +.Fn i2d_PKCS8PrivateKeyInfo_bio +and +.Fn i2d_PKCS8PrivateKeyInfo_fp +encode +.Fa val_in +in PKCS#8 unencrypted +.Vt PrivateKeyInfo +format. +They are similar to +.Fn i2d_PrivateKey +except that they don't use any algorithm-specific formats +and that they write to a +.Vt BIO +or +.Vt FILE +pointer rather than to a buffer. +.Pp +All these functions use DER format and unencrypted keys. +Applications wishing to encrypt or decrypt private keys should use other +functions such as +.Xr d2i_PKCS8PrivateKey_bio 3 +instead. +.Pp +If +.Pf * Fa val_out +is not +.Dv NULL +when calling +.Fn d2i_PrivateKey +or +.Fn d2i_AutoPrivateKey +(i.e. an existing structure is being reused) and the key format is +PKCS#8, then +.Pf * Fa val_out +will be freed and replaced on a successful call. +.Pp +.Fn d2i_PublicKey +calls +.Xr d2i_DSAPublicKey 3 , +.Xr o2i_ECPublicKey 3 , +or +.Xr d2i_RSAPublicKey 3 +depending on +.Fa type +and stores the result in the returned +.Vt EVP_PKEY +object. +.Pp +.Fn i2d_PublicKey +calls +.Xr i2d_DSAPublicKey 3 , +.Xr i2o_ECPublicKey 3 , +or +.Xr i2d_RSAPublicKey 3 +depending on the algorithm used by +.Fa val_in . +.Sh RETURN VALUES +.Fn d2i_PrivateKey , +.Fn d2i_AutoPrivateKey , +.Fn d2i_PrivateKey_bio , +.Fn d2i_PrivateKey_fp , +and +.Fn d2i_PublicKey +return a valid +.Vt EVP_PKEY +structure or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_PrivateKey +and +.Fn i2d_PublicKey +return the number of bytes successfully encoded or a negative value if +an error occurs. +.Pp +.Fn i2d_PrivateKey_bio , +.Fn i2d_PrivateKey_fp , +.Fn i2d_PKCS8PrivateKeyInfo_bio , +and +.Fn i2d_PKCS8PrivateKeyInfo_fp +return 1 for success or 0 if an error occurs. +.Pp +For all functions, the error code can be obtained by calling +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr d2i_PKCS8_PRIV_KEY_INFO 3 , +.Xr d2i_PKCS8PrivateKey_bio 3 , +.Xr EVP_PKEY_new 3 , +.Xr EVP_PKEY_type 3 , +.Xr PEM_write_PrivateKey 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 +.Sh STANDARDS +RFC 5208: Public-Key Cryptography Standards (PKCS) #8: Private-Key +Information Syntax Specification +.Sh HISTORY +.Fn d2i_PrivateKey , +.Fn i2d_PrivateKey , +.Fn d2i_PublicKey , +and +.Fn i2d_PublicKey +first appeared in SSLeay 0.6.0 and have been available since +.Ox 2.4 . +.Pp +.Fn d2i_AutoPrivateKey , +.Fn d2i_PrivateKey_bio , +.Fn d2i_PrivateKey_fp , +.Fn i2d_PrivateKey_bio , +.Fn i2d_PrivateKey_fp , +.Fn i2d_PKCS8PrivateKeyInfo_bio , +and +.Fn i2d_PKCS8PrivateKeyInfo_fp +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . diff --git a/static/openbsd/man3/d2i_RSAPublicKey.3 b/static/openbsd/man3/d2i_RSAPublicKey.3 new file mode 100644 index 00000000..3f738641 --- /dev/null +++ b/static/openbsd/man3/d2i_RSAPublicKey.3 @@ -0,0 +1,390 @@ +.\" $OpenBSD: d2i_RSAPublicKey.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016 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. +.\" +.\" The original file was written by Ulf Moeller and +.\" Dr. Stephen Henson . +.\" Copyright (c) 2000, 2002, 2003, 2009, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt D2I_RSAPUBLICKEY 3 +.Os +.Sh NAME +.Nm d2i_RSAPublicKey , +.Nm i2d_RSAPublicKey , +.Nm d2i_RSAPrivateKey , +.Nm i2d_RSAPrivateKey , +.Nm d2i_Netscape_RSA , +.Nm i2d_Netscape_RSA , +.Nm d2i_RSA_PSS_PARAMS , +.Nm i2d_RSA_PSS_PARAMS , +.Nm d2i_RSAPublicKey_bio , +.Nm d2i_RSAPublicKey_fp , +.Nm i2d_RSAPublicKey_bio , +.Nm i2d_RSAPublicKey_fp , +.Nm d2i_RSAPrivateKey_bio , +.Nm d2i_RSAPrivateKey_fp , +.Nm i2d_RSAPrivateKey_bio , +.Nm i2d_RSAPrivateKey_fp , +.Nm d2i_RSA_PUBKEY , +.Nm i2d_RSA_PUBKEY , +.Nm d2i_RSA_PUBKEY_bio , +.Nm d2i_RSA_PUBKEY_fp , +.Nm i2d_RSA_PUBKEY_bio , +.Nm i2d_RSA_PUBKEY_fp +.Nd decode and encode RSA keys and parameters +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/rsa.h +.Ft RSA * +.Fo d2i_RSAPublicKey +.Fa "RSA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_RSAPublicKey +.Fa "RSA *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft RSA * +.Fo d2i_RSAPrivateKey +.Fa "RSA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_RSAPrivateKey +.Fa "RSA *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft RSA * +.Fo d2i_Netscape_RSA +.Fa "RSA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fa "int (*cb)()" +.Fc +.Ft int +.Fo i2d_Netscape_RSA +.Fa "RSA *val_in" +.Fa "unsigned char **der_out" +.Fa "int (*cb)()" +.Fc +.Ft RSA_PSS_PARAMS * +.Fo d2i_RSA_PSS_PARAMS +.Fa "RSA_PSS_PARAMS **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_RSA_PSS_PARAMS +.Fa "RSA_PSS_PARAMS *val_in" +.Fa "unsigned char **der_out" +.Fc +.In openssl/x509.h +.Ft RSA * +.Fo d2i_RSAPublicKey_bio +.Fa "BIO *in_bio" +.Fa "RSA **val_out" +.Fc +.Ft RSA * +.Fo d2i_RSAPublicKey_fp +.Fa "FILE *in_fp" +.Fa "RSA **val_out" +.Fc +.Ft int +.Fo i2d_RSAPublicKey_bio +.Fa "BIO *out_bio" +.Fa "RSA *val_in" +.Fc +.Ft int +.Fo i2d_RSAPublicKey_fp +.Fa "FILE *out_fp" +.Fa "RSA *val_in" +.Fc +.Ft RSA * +.Fo d2i_RSAPrivateKey_bio +.Fa "BIO *in_bio" +.Fa "RSA **val_out" +.Fc +.Ft RSA * +.Fo d2i_RSAPrivateKey_fp +.Fa "FILE *in_fp" +.Fa "RSA **val_out" +.Fc +.Ft int +.Fo i2d_RSAPrivateKey_bio +.Fa "BIO *out_bio" +.Fa "RSA *val_in" +.Fc +.Ft int +.Fo i2d_RSAPrivateKey_fp +.Fa "FILE *out_fp" +.Fa "RSA *val_in" +.Fc +.Ft RSA * +.Fo d2i_RSA_PUBKEY +.Fa "RSA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_RSA_PUBKEY +.Fa "RSA *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft RSA * +.Fo d2i_RSA_PUBKEY_bio +.Fa "BIO *in_bio" +.Fa "RSA **val_out" +.Fc +.Ft RSA * +.Fo d2i_RSA_PUBKEY_fp +.Fa "FILE *in_fp" +.Fa "RSA **val_out" +.Fc +.Ft int +.Fo i2d_RSA_PUBKEY_bio +.Fa "BIO *out_bio" +.Fa "RSA *val_in" +.Fc +.Ft int +.Fo i2d_RSA_PUBKEY_fp +.Fa "FILE *out_fp" +.Fa "RSA *val_in" +.Fc +.Sh DESCRIPTION +These functions decode and encode RSA private and public keys. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_RSAPublicKey +and +.Fn i2d_RSAPublicKey +decode and encode a PKCS#1 +.Vt RSAPublicKey +structure defined in RFC 8017 appendix A.1.1. +.Fn d2i_RSAPublicKey_bio , +.Fn d2i_RSAPublicKey_fp , +.Fn i2d_RSAPublicKey_bio , +and +.Fn i2d_RSAPublicKey_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_RSAPrivateKey +and +.Fn i2d_RSAPrivateKey +decode and encode a PKCS#1 +.Vt RSAPrivateKey +structure defined in RFC 8017 appendix A.1.2. +The +.Vt RSA +structure passed to the private key encoding functions should have +all the PKCS#1 private key components present. +The data encoded by the private key functions is unencrypted and +therefore offers no private key security. +.Fn d2i_RSAPrivateKey_bio , +.Fn d2i_RSAPrivateKey_fp , +.Fn i2d_RSAPrivateKey_bio , +and +.Fn i2d_RSAPrivateKey_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_Netscape_RSA +and +.Fn i2d_Netscape_RSA +decode and encode an RSA private key in NET format. +These functions are present to provide compatibility with +certain very old software. +The NET format has some severe security weaknesses and should be +avoided if possible. +.Pp +.Fn d2i_RSA_PSS_PARAMS +and +.Fn i2d_RSA_PSS_PARAMS +decode and encode a PKCS#1 +.Vt RSASSA-PSS-params +structure defined in RFC 8017 appendix A.2.3 and documented in +.Xr RSA_PSS_PARAMS_new 3 . +.Pp +.Fn d2i_RSA_PUBKEY +and +.Fn i2d_RSA_PUBKEY +decode and encode an RSA public key using an ASN.1 +.Vt SubjectPublicKeyInfo +structure defined in RFC 5280 section 4.1 and documented in +.Xr X509_PUBKEY_new 3 . +.Fn d2i_RSA_PUBKEY_bio , +.Fn d2i_RSA_PUBKEY_fp , +.Fn i2d_RSA_PUBKEY_bio , +and +.Fn i2d_RSA_PUBKEY_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Sh RETURN VALUES +.Fn d2i_RSAPublicKey , +.Fn d2i_RSAPublicKey_bio , +.Fn d2i_RSAPublicKey_fp , +.Fn d2i_RSAPrivateKey , +.Fn d2i_RSAPrivateKey_bio , +.Fn d2i_RSAPrivateKey_fp , +.Fn d2i_Netscape_RSA , +.Fn d2i_RSA_PUBKEY , +.Fn d2i_RSA_PUBKEY_bio , +and +.Fn d2i_RSA_PUBKEY_fp +return a valid +.Vt RSA +object or +.Dv NULL +if an error occurs. +.Pp +.Fn d2i_RSA_PSS_PARAMS +returns a valid +.Vt RSA_PSS_PARAMS +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_RSAPublicKey , +.Fn i2d_RSAPrivateKey , +.Fn i2d_Netscape_RSA , +.Fn i2d_RSA_PSS_PARAMS , +and +.Fn i2d_RSA_PUBKEY +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Pp +.Fn i2d_RSAPublicKey_bio , +.Fn i2d_RSAPublicKey_fp , +.Fn i2d_RSAPrivateKey_bio , +.Fn i2d_RSAPrivateKey_fp , +.Fn i2d_RSA_PUBKEY_bio , +and +.Fn i2d_RSA_PUBKEY_fp +return 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr EVP_PKEY_set1_RSA 3 , +.Xr PEM_write_RSAPrivateKey 3 , +.Xr RSA_new 3 , +.Xr RSA_PSS_PARAMS_new 3 , +.Xr X509_PUBKEY_new 3 +.Sh STANDARDS +RFC 8017: PKCS #1: RSA Cryptography Specifications +.Pp +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 4.1: Basic Certificate Fields +.Sh HISTORY +.Fn d2i_RSAPublicKey , +.Fn i2d_RSAPublicKey , +.Fn d2i_RSAPrivateKey , +.Fn i2d_RSAPrivateKey , +.Fn d2i_RSAPrivateKey_fp , +.Fn i2d_RSAPrivateKey_fp , +.Fn d2i_Netscape_RSA , +and +.Fn i2d_Netscape_RSA +first appeared in SSLeay 0.5.1. +.Fn d2i_RSAPrivateKey_bio +and +.Fn i2d_RSAPrivateKey_bio +first appeared in SSLeay 0.6.0. +.Fn d2i_RSAPublicKey_bio , +.Fn d2i_RSAPublicKey_fp , +.Fn i2d_RSAPublicKey_bio , +and +.Fn i2d_RSAPublicKey_fp +first appeared in SSLeay 0.8.1. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn d2i_RSA_PUBKEY , +.Fn i2d_RSA_PUBKEY , +.Fn d2i_RSA_PUBKEY_bio , +.Fn d2i_RSA_PUBKEY_fp , +.Fn i2d_RSA_PUBKEY_bio , +and +.Fn i2d_RSA_PUBKEY_fp +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn d2i_RSA_PSS_PARAMS +and +.Fn i2d_RSA_PSS_PARAMS +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . diff --git a/static/openbsd/man3/d2i_SSL_SESSION.3 b/static/openbsd/man3/d2i_SSL_SESSION.3 new file mode 100644 index 00000000..6b0dfc86 --- /dev/null +++ b/static/openbsd/man3/d2i_SSL_SESSION.3 @@ -0,0 +1,182 @@ +.\" $OpenBSD: d2i_SSL_SESSION.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" +.\" This file was written by Lutz Jaenicke . +.\" Copyright (c) 2001, 2005, 2014 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt D2I_SSL_SESSION 3 +.Os +.Sh NAME +.Nm d2i_SSL_SESSION , +.Nm i2d_SSL_SESSION +.Nd convert SSL_SESSION object from/to ASN1 representation +.Sh SYNOPSIS +.Lb libssl libcrypto +.In openssl/ssl.h +.Ft SSL_SESSION * +.Fn d2i_SSL_SESSION "SSL_SESSION **a" "const unsigned char **pp" "long length" +.Ft int +.Fn i2d_SSL_SESSION "SSL_SESSION *in" "unsigned char **pp" +.Sh DESCRIPTION +.Fn d2i_SSL_SESSION +transforms the external ASN1 representation of an SSL/TLS session, +stored as binary data at location +.Fa pp +with length +.Fa length , +into +an +.Vt SSL_SESSION +object. +.Pp +.Fn i2d_SSL_SESSION +transforms the +.Vt SSL_SESSION +object +.Fa in +into the ASN1 representation and stores it into the memory location pointed to +by +.Fa pp . +The length of the resulting ASN1 representation is returned. +If +.Fa pp +is the +.Dv NULL +pointer, only the length is calculated and returned. +.Pp +The +.Vt SSL_SESSION +object is built from several +.Xr malloc 3 Ns +-ed parts; it can therefore not be moved, copied or stored directly. +In order to store session data on disk or into a database, +it must be transformed into a binary ASN1 representation. +.Pp +When using +.Fn d2i_SSL_SESSION , +the +.Vt SSL_SESSION +object is automatically allocated. +The reference count is 1, so that the session must be explicitly removed using +.Xr SSL_SESSION_free 3 , +unless the +.Vt SSL_SESSION +object is completely taken over, when being called inside the +.Fn get_session_cb , +see +.Xr SSL_CTX_sess_set_get_cb 3 . +.Pp +.Vt SSL_SESSION +objects keep internal link information about the session cache list when being +inserted into one +.Vt SSL_CTX +object's session cache. +One +.Vt SSL_SESSION +object, regardless of its reference count, must therefore only be used with one +.Vt SSL_CTX +object (and the +.Vt SSL +objects created from this +.Vt SSL_CTX +object). +.Pp +When using +.Fn i2d_SSL_SESSION , +the memory location pointed to by +.Fa pp +must be large enough to hold the binary representation of the session. +There is no known limit on the size of the created ASN1 representation, +so call +.Fn i2d_SSL_SESSION +first with +.Fa pp Ns = Ns Dv NULL +to obtain the encoded size, before allocating the required amount of memory and +calling +.Fn i2d_SSL_SESSION +again. +Note that this will advance the value contained in +.Fa *pp +so it is necessary to save a copy of the original allocation. +For example: +.Bd -literal -offset indent +char *p, *pp; +int elen, len; + +elen = i2d_SSL_SESSION(sess, NULL); +p = pp = malloc(elen); +if (p != NULL) { + len = i2d_SSL_SESSION(sess, &pp); + assert(elen == len); + assert(p + len == pp); +} +.Ed +.Sh RETURN VALUES +.Fn d2i_SSL_SESSION +returns a pointer to the newly allocated +.Vt SSL_SESSION +object. +In case of failure a +.Dv NULL +pointer is returned and the error message can be retrieved from the error +stack. +.Pp +.Fn i2d_SSL_SESSION +returns the size of the ASN1 representation in bytes. +When the session is not valid, 0 is returned and no operation is performed. +.Sh SEE ALSO +.Xr d2i_X509 3 , +.Xr ssl 3 , +.Xr SSL_CTX_sess_set_get_cb 3 , +.Xr SSL_SESSION_free 3 +.Sh HISTORY +.Fn d2i_SSL_SESSION +and +.Fn i2d_SSL_SESSION +first appeared in SSLeay 0.5.2 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/d2i_TS_REQ.3 b/static/openbsd/man3/d2i_TS_REQ.3 new file mode 100644 index 00000000..87e9a402 --- /dev/null +++ b/static/openbsd/man3/d2i_TS_REQ.3 @@ -0,0 +1,334 @@ +.\" $OpenBSD: d2i_TS_REQ.3,v 1.3 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_TS_REQ 3 +.Os +.Sh NAME +.Nm d2i_TS_REQ , +.Nm i2d_TS_REQ , +.Nm d2i_TS_REQ_bio , +.Nm i2d_TS_REQ_bio , +.Nm d2i_TS_REQ_fp , +.Nm i2d_TS_REQ_fp , +.Nm d2i_TS_RESP , +.Nm i2d_TS_RESP , +.Nm d2i_TS_RESP_bio , +.Nm i2d_TS_RESP_bio , +.Nm d2i_TS_RESP_fp , +.Nm i2d_TS_RESP_fp , +.Nm d2i_TS_STATUS_INFO , +.Nm i2d_TS_STATUS_INFO , +.Nm d2i_TS_TST_INFO , +.Nm i2d_TS_TST_INFO , +.Nm d2i_TS_TST_INFO_bio , +.Nm i2d_TS_TST_INFO_bio , +.Nm d2i_TS_TST_INFO_fp , +.Nm i2d_TS_TST_INFO_fp , +.Nm d2i_TS_ACCURACY , +.Nm i2d_TS_ACCURACY , +.Nm d2i_TS_MSG_IMPRINT , +.Nm i2d_TS_MSG_IMPRINT , +.Nm d2i_TS_MSG_IMPRINT_bio , +.Nm i2d_TS_MSG_IMPRINT_bio , +.Nm d2i_TS_MSG_IMPRINT_fp , +.Nm i2d_TS_MSG_IMPRINT_fp +.Nd decode and encode X.509 time-stamp protocol structures +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/ts.h +.Ft TS_REQ * +.Fo d2i_TS_REQ +.Fa "TS_REQ **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_TS_REQ +.Fa "const TS_REQ *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft TS_REQ * +.Fo d2i_TS_REQ_bio +.Fa "BIO *in_bio" +.Fa "TS_REQ **val_out" +.Fc +.Ft int +.Fo i2d_TS_REQ_bio +.Fa "BIO *out_bio" +.Fa "TS_REQ *val_in" +.Fc +.Ft TS_REQ * +.Fo d2i_TS_REQ_fp +.Fa "FILE *in_fp" +.Fa "TS_REQ **val_out" +.Fc +.Ft int +.Fo i2d_TS_REQ_fp +.Fa "FILE *out_fp" +.Fa "TS_REQ *val_in" +.Fc +.Ft TS_RESP * +.Fo d2i_TS_RESP +.Fa "TS_RESP **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_TS_RESP +.Fa "const TS_RESP *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft TS_RESP * +.Fo d2i_TS_RESP_bio +.Fa "BIO *in_bio" +.Fa "TS_RESP **val_out" +.Fc +.Ft int +.Fo i2d_TS_RESP_bio +.Fa "BIO *out_bio" +.Fa "TS_RESP *val_in" +.Fc +.Ft TS_RESP * +.Fo d2i_TS_RESP_fp +.Fa "FILE *in_fp" +.Fa "TS_RESP **val_out" +.Fc +.Ft int +.Fo i2d_TS_RESP_fp +.Fa "FILE *out_fp" +.Fa "TS_RESP *val_in" +.Fc +.Ft TS_STATUS_INFO * +.Fo d2i_TS_STATUS_INFO +.Fa "TS_STATUS_INFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_TS_STATUS_INFO +.Fa "const TS_STATUS_INFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft TS_TST_INFO * +.Fo d2i_TS_TST_INFO +.Fa "TS_TST_INFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_TS_TST_INFO +.Fa "const TS_TST_INFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft TS_TST_INFO * +.Fo d2i_TS_TST_INFO_bio +.Fa "BIO *in_bio" +.Fa "TS_TST_INFO **val_out" +.Fc +.Ft int +.Fo i2d_TS_TST_INFO_bio +.Fa "BIO *out_bio" +.Fa "TS_TST_INFO *val_in" +.Fc +.Ft TS_TST_INFO * +.Fo d2i_TS_TST_INFO_fp +.Fa "FILE *in_fp" +.Fa "TS_TST_INFO **val_out" +.Fc +.Ft int +.Fo i2d_TS_TST_INFO_fp +.Fa "FILE *out_fp" +.Fa "TS_TST_INFO *val_in" +.Fc +.Ft TS_ACCURACY * +.Fo d2i_TS_ACCURACY +.Fa "TS_ACCURACY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_TS_ACCURACY +.Fa "const TS_ACCURACY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft TS_MSG_IMPRINT * +.Fo d2i_TS_MSG_IMPRINT +.Fa "TS_MSG_IMPRINT **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_TS_MSG_IMPRINT +.Fa "const TS_MSG_IMPRINT *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft TS_MSG_IMPRINT * +.Fo d2i_TS_MSG_IMPRINT_bio +.Fa "BIO *in_bio" +.Fa "TS_MSG_IMPRINT **val_out" +.Fc +.Ft int +.Fo i2d_TS_MSG_IMPRINT_bio +.Fa "BIO *out_bio" +.Fa "TS_MSG_IMPRINT *val_in" +.Fc +.Ft TS_MSG_IMPRINT * +.Fo d2i_TS_MSG_IMPRINT_fp +.Fa "FILE *in_fp" +.Fa "TS_MSG_IMPRINT **val_out" +.Fc +.Ft int +.Fo i2d_TS_MSG_IMPRINT_fp +.Fa "FILE *out_fp" +.Fa "TS_MSG_IMPRINT *val_in" +.Fc +.Sh DESCRIPTION +These functions decode and encode X.509 structures used for the +time-stamp protocol. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_TS_REQ +and +.Fn i2d_TS_REQ +decode and encode an ASN.1 +.Vt TimeStampReq +structure defined in RFC 3161 section 2.4.1. +.Fn d2i_TS_REQ_bio , +.Fn i2d_TS_REQ_bio , +.Fn d2i_TS_REQ_fp , +and +.Fn i2d_TS_REQ_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_TS_RESP +and +.Fn i2d_TS_RESP +decode and encode an ASN.1 +.Vt TimeStampResp +structure defined in RFC 3161 section 2.4.2. +.Fn d2i_TS_RESP_bio , +.Fn i2d_TS_RESP_bio , +.Fn d2i_TS_RESP_fp , +and +.Fn i2d_TS_RESP_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_TS_STATUS_INFO +and +.Fn i2d_TS_STATUS_INFO +decode and encode an ASN.1 +.Vt PKIStatusInfo +structure defined in RFC 3161 section 2.4.2. +.Pp +.Fn d2i_TS_TST_INFO +and +.Fn i2d_TS_TST_INFO +decode and encode an ASN.1 +.Vt TSTInfo +structure defined in RFC 3161 section 2.4.2. +.Fn d2i_TS_TST_INFO_bio , +.Fn i2d_TS_TST_INFO_bio , +.Fn d2i_TS_TST_INFO_fp , +and +.Fn i2d_TS_TST_INFO_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_TS_ACCURACY +and +.Fn i2d_TS_ACCURACY +decode and encode an ASN.1 +.Vt Accuracy +structure defined in RFC 3161 section 2.4.2. +.Pp +.Fn d2i_TS_MSG_IMPRINT +and +.Fn i2d_TS_MSG_IMPRINT +decode and encode an ASN.1 +.Vt MessageImprint +structure defined in RFC 3161 section 2.4.1. +.Fn d2i_TS_MSG_IMPRINT_bio , +.Fn i2d_TS_MSG_IMPRINT_bio , +.Fn d2i_TS_MSG_IMPRINT_fp , +and +.Fn i2d_TS_MSG_IMPRINT_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Sh RETURN VALUES +.Fn d2i_TS_REQ , +.Fn d2i_TS_REQ_bio , +.Fn d2i_TS_REQ_fp , +.Fn d2i_TS_RESP , +.Fn d2i_TS_RESP_bio , +.Fn d2i_TS_RESP_fp , +.Fn d2i_TS_STATUS_INFO , +.Fn d2i_TS_TST_INFO , +.Fn d2i_TS_TST_INFO_bio , +.Fn d2i_TS_TST_INFO_fp , +.Fn d2i_TS_ACCURACY , +.Fn d2i_TS_MSG_IMPRINT , +.Fn d2i_TS_MSG_IMPRINT_bio , +and +.Fn d2i_TS_MSG_IMPRINT_fp +return an object of the respective type or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_TS_REQ , +.Fn i2d_TS_RESP , +.Fn i2d_TS_STATUS_INFO , +.Fn i2d_TS_TST_INFO , +.Fn i2d_TS_ACCURACY , +and +.Fn i2d_TS_MSG_IMPRINT +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Pp +.Fn i2d_TS_REQ_bio , +.Fn i2d_TS_REQ_fp , +.Fn i2d_TS_RESP_bio , +.Fn i2d_TS_RESP_fp , +.Fn i2d_TS_TST_INFO_bio , +.Fn i2d_TS_TST_INFO_fp , +.Fn i2d_TS_MSG_IMPRINT_bio , +and +.Fn i2d_TS_MSG_IMPRINT_fp +return 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr TS_REQ_new 3 +.Sh STANDARDS +RFC 3161: Internet X.509 Public Key Infrastructure Time-Stamp Protocol +.Sh HISTORY +These functions first appeared in OpenSSL 1.0.0 +and have been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/d2i_X509.3 b/static/openbsd/man3/d2i_X509.3 new file mode 100644 index 00000000..2905e49a --- /dev/null +++ b/static/openbsd/man3/d2i_X509.3 @@ -0,0 +1,363 @@ +.\" $OpenBSD: d2i_X509.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL d2i_X509.pod checked up to: +.\" 256989ce4 Jun 19 15:00:32 2020 +0200 +.\" OpenSSL i2d_re_X509_tbs.pod checked up to: +.\" 61f805c1 Jan 16 01:01:46 2018 +0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016 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. +.\" +.\" The original files were written by Dr. Stephen Henson , +.\" Emilia Kasper , Viktor Dukhovni , +.\" and Rich Salz . +.\" Copyright (c) 2002, 2014, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt D2I_X509 3 +.Os +.Sh NAME +.Nm d2i_X509 , +.Nm i2d_X509 , +.Nm d2i_X509_bio , +.Nm d2i_X509_fp , +.Nm i2d_X509_bio , +.Nm i2d_X509_fp , +.Nm d2i_X509_AUX , +.Nm i2d_X509_AUX , +.Nm d2i_X509_CERT_AUX , +.Nm i2d_X509_CERT_AUX , +.Nm d2i_X509_CINF , +.Nm i2d_X509_CINF , +.Nm d2i_X509_VAL , +.Nm i2d_X509_VAL , +.Nm i2d_re_X509_tbs , +.Nm i2d_re_X509_CRL_tbs , +.Nm i2d_re_X509_REQ_tbs +.Nd decode and encode X.509 certificates +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509 * +.Fo d2i_X509 +.Fa "X509 **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509 +.Fa "X509 *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509 * +.Fo d2i_X509_bio +.Fa "BIO *in_bio" +.Fa "X509 **val_out" +.Fc +.Ft X509 * +.Fo d2i_X509_fp +.Fa "FILE *in_fp" +.Fa "X509 **val_out" +.Fc +.Ft int +.Fo i2d_X509_bio +.Fa "BIO *out_bio" +.Fa "X509 *val_in" +.Fc +.Ft int +.Fo i2d_X509_fp +.Fa "FILE *out_fp" +.Fa "X509 *val_in" +.Fc +.Ft X509 * +.Fo d2i_X509_AUX +.Fa "X509 **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_AUX +.Fa "X509 *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_CERT_AUX * +.Fo d2i_X509_CERT_AUX +.Fa "X509_CERT_AUX **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_CERT_AUX +.Fa "X509_CERT_AUX *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_CINF * +.Fo d2i_X509_CINF +.Fa "X509_CINF **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_CINF +.Fa "X509_CINF *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_VAL * +.Fo d2i_X509_VAL +.Fa "X509_VAL **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_VAL +.Fa "X509_VAL *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft int +.Fo i2d_re_X509_tbs +.Fa "X509 *x" +.Fa "unsigned char **out" +.Fc +.Ft int +.Fo i2d_re_X509_CRL_tbs +.Fa "X509_CRL *crl" +.Fa "unsigned char **pp" +.Fc +.Ft int +.Fo i2d_re_X509_REQ_tbs +.Fa "X509_REQ *req" +.Fa "unsigned char **pp" +.Fc +.Sh DESCRIPTION +These functions decode and encode X.509 certificates +and some of their substructures. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_X509 +and +.Fn i2d_X509 +decode and encode an ASN.1 +.Vt Certificate +structure defined in RFC 5280 section 4.1. +.Pp +.Fn d2i_X509_bio , +.Fn d2i_X509_fp , +.Fn i2d_X509_bio , +and +.Fn i2d_X509_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_X509_AUX +is similar to +.Fn d2i_X509 , +but the input is expected to consist of an X.509 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 +.Fn i2d_X509_AUX +is similar to +.Fn i2d_X509 , +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 +.Fn d2i_X509_CERT_AUX +and +.Fn i2d_X509_CERT_AUX +decode and encode optional non-standard auxiliary data appended to +a certificate, for example friendly alias names and trust data. +.Pp +.Fn d2i_X509_CINF +and +.Fn i2d_X509_CINF +decode and encode an ASN.1 +.Vt TBSCertificate +structure defined in RFC 5280 section 4.1. +.Pp +.Fn d2i_X509_VAL +and +.Fn i2d_X509_VAL +decode and encode an ASN.1 +.Vt Validity +structure defined in RFC 5280 section 4.1. +.Pp +.Fn i2d_re_X509_tbs +is similar to +.Fn i2d_X509 , +except it encodes only the TBSCertificate portion of the certificate. +.Fn i2d_re_X509_CRL_tbs +and +.Fn i2d_re_X509_REQ_tbs +are analogous for CRL and certificate request, respectively. +The "re" in +.Fn i2d_re_X509_tbs +stands for "re-encode", and ensures that a fresh encoding is generated +in case the object has been modified after creation. +.Pp +The encoding of the TBSCertificate portion of a certificate is cached in +the +.Vt X509 +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 +.Vt X509 +object is re-signed with +.Xr X509_sign 3 , +the encoding is automatically renewed. +Otherwise, the encoding of the TBSCertificate portion of the +.Vt X509 +can be manually renewed by calling +.Fn i2d_re_X509_tbs . +.Sh RETURN VALUES +.Fn d2i_X509 , +.Fn d2i_X509_bio , +.Fn d2i_X509_fp , +and +.Fn d2i_X509_AUX +return a valid +.Vt X509 +structure or +.Dv NULL +if an error occurs. +.Pp +.Fn d2i_X509_CERT_AUX , +.Fn d2i_X509_CINF , +and +.Fn d2i_X509_VAL +return an +.Vt X509_CERT_AUX , +.Vt X509_CINF , +or +.Vt X509_VAL +object, respectively, or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_X509 , +.Fn i2d_X509_AUX , +.Fn i2d_X509_CERT_AUX , +.Fn i2d_X509_CINF , +and +.Fn i2d_X509_VAL +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Pp +.Fn i2d_X509_bio +and +.Fn i2d_X509_fp +return 1 for success or 0 if an error occurs. +.Pp +.Fn i2d_re_X509_tbs , +.Fn i2d_re_X509_CRL_tbs , +and +.Fn i2d_re_X509_REQ_tbs +return the number of bytes successfully encoded or 0 if an error occurs. +.Pp +For all functions, the error code can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr X509_CINF_new 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn d2i_X509 , +.Fn i2d_X509 , +.Fn d2i_X509_fp , +.Fn i2d_X509_fp , +.Fn d2i_X509_CINF , +.Fn i2d_X509_CINF , +.Fn d2i_X509_VAL , +and +.Fn i2d_X509_VAL +first appeared in SSLeay 0.5.1. +.Fn d2i_X509_bio +and +.Fn i2d_X509_bio +first appeared in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn d2i_X509_AUX , +.Fn i2d_X509_AUX , +.Fn d2i_X509_CERT_AUX , +and +.Fn i2d_X509_CERT_AUX +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn i2d_re_X509_tbs , +.Fn i2d_re_X509_CRL_tbs , +and +.Fn i2d_re_X509_REQ_tbs +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . diff --git a/static/openbsd/man3/d2i_X509_ALGOR.3 b/static/openbsd/man3/d2i_X509_ALGOR.3 new file mode 100644 index 00000000..2691ceda --- /dev/null +++ b/static/openbsd/man3/d2i_X509_ALGOR.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: d2i_X509_ALGOR.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016, 2021 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 $Mdocdate: June 8 2025 $ +.Dt D2I_X509_ALGOR 3 +.Os +.Sh NAME +.Nm d2i_X509_ALGOR , +.Nm i2d_X509_ALGOR , +.Nm d2i_X509_ALGORS , +.Nm i2d_X509_ALGORS +.Nd decode and encode algorithm identifiers +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_ALGOR * +.Fo d2i_X509_ALGOR +.Fa "X509_ALGOR **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_ALGOR +.Fa "X509_ALGOR *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_ALGORS * +.Fo d2i_X509_ALGORS +.Fa "X509_ALGORS **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_ALGORS +.Fa "X509_ALGORS *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +.Fn d2i_X509_ALGOR +and +.Fn i2d_X509_ALGOR +decode and encode an ASN.1 +.Vt AlgorithmIdentifier +structure defined in RFC 5280 section 4.1.1.2. +.Pp +.Fn d2i_X509_ALGORS +and +.Fn i2d_X509_ALGORS +decode and encode an ASN.1 sequence of +.Vt AlgorithmIdentifier +structures. +The data type +.Vt X509_ALGORS +is defined as +.Vt STACK_OF(X509_ALGOR) . +.Pp +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr STACK_OF 3 , +.Xr X509_ALGOR_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn d2i_X509_ALGOR +and +.Fn i2d_X509_ALGOR +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn d2i_X509_ALGORS +and +.Fn i2d_X509_ALGORS +first appeared in OpenSSL 0.9.8h and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/d2i_X509_ATTRIBUTE.3 b/static/openbsd/man3/d2i_X509_ATTRIBUTE.3 new file mode 100644 index 00000000..be4924d3 --- /dev/null +++ b/static/openbsd/man3/d2i_X509_ATTRIBUTE.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: d2i_X509_ATTRIBUTE.3,v 1.4 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_X509_ATTRIBUTE 3 +.Os +.Sh NAME +.Nm d2i_X509_ATTRIBUTE , +.Nm i2d_X509_ATTRIBUTE +.\" In the following line, "X.501" and "Attribute" are not typos. +.\" The "Attribute" type is defined in X.501, not in X.509. +.\" The type in called "Attribute" with capital "A", not "attribute". +.Nd decode and encode generic X.501 Attribute +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_ATTRIBUTE * +.Fo d2i_X509_ATTRIBUTE +.Fa "X509_ATTRIBUTE **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_ATTRIBUTE +.Fa "X509_ATTRIBUTE *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +.Fn d2i_X509_ATTRIBUTE +and +.Fn i2d_X509_ATTRIBUTE +decode and encode a generic ASN.1 +.Vt Attribute +structure defined in X.501 section 8.2. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Sh RETURN VALUES +.Fn d2i_X509_ATTRIBUTE +returns an +.Vt X509_ATTRIBUTE +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_X509_ATTRIBUTE +returns the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr d2i_PKCS12 3 , +.Xr d2i_PKCS8_PRIV_KEY_INFO 3 , +.Xr d2i_X509_EXTENSION 3 , +.Xr d2i_X509_REQ 3 , +.Xr X509_ATTRIBUTE_new 3 +.Sh STANDARDS +ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: Information +Technology Open Systems Interconnection The Directory: Models, +section 8.2: Overall structure +.Sh HISTORY +.Fn d2i_X509_ATTRIBUTE +and +.Fn i2d_X509_ATTRIBUTE +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/d2i_X509_CRL.3 b/static/openbsd/man3/d2i_X509_CRL.3 new file mode 100644 index 00000000..040ac039 --- /dev/null +++ b/static/openbsd/man3/d2i_X509_CRL.3 @@ -0,0 +1,149 @@ +.\" $OpenBSD: d2i_X509_CRL.3,v 1.11 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016, 2021 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 $Mdocdate: June 8 2025 $ +.Dt D2I_X509_CRL 3 +.Os +.Sh NAME +.Nm d2i_X509_CRL , +.Nm i2d_X509_CRL , +.Nm d2i_X509_CRL_bio , +.Nm d2i_X509_CRL_fp , +.Nm i2d_X509_CRL_bio , +.Nm i2d_X509_CRL_fp , +.Nm d2i_X509_CRL_INFO , +.Nm i2d_X509_CRL_INFO , +.Nm d2i_X509_REVOKED , +.Nm i2d_X509_REVOKED +.Nd decode and encode X.509 certificate revocation lists +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_CRL * +.Fo d2i_X509_CRL +.Fa "X509_CRL **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_CRL +.Fa "X509_CRL *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_CRL * +.Fo d2i_X509_CRL_bio +.Fa "BIO *in_bio" +.Fa "X509_CRL **val_out" +.Fc +.Ft X509_CRL * +.Fo d2i_X509_CRL_fp +.Fa "FILE *in_fp" +.Fa "X509_CRL **val_out" +.Fc +.Ft int +.Fo i2d_X509_CRL_bio +.Fa "BIO *out_bio" +.Fa "X509_CRL *val_in" +.Fc +.Ft int +.Fo i2d_X509_CRL_fp +.Fa "FILE *out_fp" +.Fa "X509_CRL *val_in" +.Fc +.Ft X509_CRL_INFO * +.Fo d2i_X509_CRL_INFO +.Fa "X509_CRL_INFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_CRL_INFO +.Fa "X509_CRL_INFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_REVOKED * +.Fo d2i_X509_REVOKED +.Fa "X509_REVOKED **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_REVOKED +.Fa "X509_REVOKED *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode X.509 certificate revocation lists. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_X509_CRL +and +.Fn i2d_X509_CRL +decode and encode an ASN.1 +.Vt CertificateList +structure defined in RFC 5280 section 5.1. +.Pp +.Fn d2i_X509_CRL_bio , +.Fn d2i_X509_CRL_fp , +.Fn i2d_X509_CRL_bio , +and +.Fn i2d_X509_CRL_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_X509_CRL_INFO +and +.Fn i2d_X509_CRL_INFO +decode and encode an ASN.1 +.Vt TBSCertList +structure defined in RFC 5280 section 5.1. +.Pp +.Fn d2i_X509_REVOKED +and +.Fn i2d_X509_REVOKED +decode and encode an ASN.1 structure representing one element of +the revokedCertificates field of the ASN.1 +.Vt TBSCertList +structure. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr X509_CRL_new 3 , +.Xr X509_REVOKED_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile, +section 5: CRL and CRL Extensions Profile +.Sh HISTORY +.Fn d2i_X509_CRL , +.Fn i2d_X509_CRL , +.Fn d2i_X509_CRL_fp , +.Fn i2d_X509_CRL_fp , +.Fn d2i_X509_CRL_INFO , +.Fn i2d_X509_CRL_INFO , +.Fn d2i_X509_REVOKED , +and +.Fn i2d_X509_REVOKED +first appeared in SSLeay 0.5.1. +.Fn d2i_X509_CRL_bio +and +.Fn i2d_X509_CRL_bio +first appeared in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/d2i_X509_EXTENSION.3 b/static/openbsd/man3/d2i_X509_EXTENSION.3 new file mode 100644 index 00000000..3e1011d1 --- /dev/null +++ b/static/openbsd/man3/d2i_X509_EXTENSION.3 @@ -0,0 +1,105 @@ +.\" $OpenBSD: d2i_X509_EXTENSION.3,v 1.5 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_X509_EXTENSION 3 +.Os +.Sh NAME +.Nm d2i_X509_EXTENSION , +.Nm i2d_X509_EXTENSION , +.Nm d2i_X509_EXTENSIONS , +.Nm i2d_X509_EXTENSIONS +.\" In the next line, the capital "E" is not a typo. +.\" The ASN.1 structure is called "Extensions", not "extensions". +.Nd decode and encode X.509 Extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_EXTENSION * +.Fo d2i_X509_EXTENSION +.Fa "X509_EXTENSION **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_EXTENSION +.Fa "X509_EXTENSION *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_EXTENSIONS * +.Fo d2i_X509_EXTENSIONS +.Fa "X509_EXTENSIONS **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_EXTENSIONS +.Fa "X509_EXTENSIONS *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +.Fn d2i_X509_EXTENSION +and +.Fn i2d_X509_EXTENSION +decode and encode an ASN.1 +.Vt Extension +structure defined in RFC 5280 section 4.1. +.Pp +.Fn d2i_X509_EXTENSIONS +and +.Fn i2d_X509_EXTENSIONS +decode and encode an ASN.1 +.Vt Extensions +structure defined in RFC 5280 section 4.1, +which is a SEQUENCE OF +.Vt Extension . +.Sh RETURN VALUES +.Fn d2i_X509_EXTENSION +and +.Fn d2i_X509_EXTENSIONS +return an +.Vt X509_EXTENSION +or +.Vt X509_EXTENSIONS +object, respectively, or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_X509_EXTENSION +and +.Fn i2d_X509_EXTENSIONS +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr X509_EXTENSION_new 3 , +.Xr X509V3_get_d2i 3 , +.Xr X509v3_get_ext_by_NID 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Sh HISTORY +.Fn d2i_X509_EXTENSION +and +.Fn i2d_X509_EXTENSION +first appeared in SSLeay 0.6.2 and have been available since +.Ox 2.4 . +.Pp +.Fn d2i_X509_EXTENSIONS +and +.Fn i2d_X509_EXTENSIONS +first appeared in OpenSSL 0.9.8h and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/d2i_X509_NAME.3 b/static/openbsd/man3/d2i_X509_NAME.3 new file mode 100644 index 00000000..c8df55f1 --- /dev/null +++ b/static/openbsd/man3/d2i_X509_NAME.3 @@ -0,0 +1,214 @@ +.\" $OpenBSD: d2i_X509_NAME.3,v 1.19 2025/06/08 22:40:30 schwarze Exp $ +.\" checked up to: +.\" OpenSSL crypto/d2i_X509_NAME 4692340e Jun 7 15:49:08 2016 -0400 and +.\" OpenSSL man3/X509_NAME_get0_der 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" +.\" Copyright (c) 2016, 2018 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 $Mdocdate: June 8 2025 $ +.Dt D2I_X509_NAME 3 +.Os +.Sh NAME +.Nm d2i_X509_NAME , +.Nm i2d_X509_NAME , +.Nm X509_NAME_get0_der , +.Nm X509_NAME_dup , +.Nm X509_NAME_set , +.Nm d2i_X509_NAME_ENTRY , +.Nm i2d_X509_NAME_ENTRY , +.Nm X509_NAME_ENTRY_dup +.\" In the following line, "X.501" and "Name" are not typos. +.\" The "Name" type is defined in X.501, not in X.509. +.\" The type is called "Name" with capital "N", not "name". +.Nd decode and encode X.501 Name objects +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_NAME * +.Fo d2i_X509_NAME +.Fa "X509_NAME **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_NAME +.Fa "X509_NAME *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft int +.Fo X509_NAME_get0_der +.Fa "X509_NAME *val_in" +.Fa "const unsigned char **der_out" +.Fa "size_t *out_len" +.Fc +.Ft X509_NAME * +.Fo X509_NAME_dup +.Fa "X509_NAME *val_in" +.Fc +.Ft int +.Fo X509_NAME_set +.Fa "X509_NAME **val_out" +.Fa "X509_NAME *val_in" +.Fc +.Ft X509_NAME_ENTRY * +.Fo d2i_X509_NAME_ENTRY +.Fa "X509_NAME_ENTRY **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_NAME_ENTRY +.Fa "X509_NAME_ENTRY *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_ENTRY_dup +.Fa "X509_NAME_ENTRY *val_in" +.Fc +.Sh DESCRIPTION +These functions decode and encode X.501 +.Vt Name +objects using DER format. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_X509_NAME +and +.Fn i2d_X509_NAME +decode and encode an ASN.1 +.Vt Name +structure defined in RFC 5280 section 4.1.2.4. +.Pp +.Fn X509_NAME_get0_der +is a variant of +.Fn i2d_X509_NAME +that does not copy the encoded output but instead returns a pointer +to the internally cached DER-encoded version of the name. +Also, it does not return the length of the output in bytes, +but instead stores it in +.Fa out_len . +If the cached encoded form happens to be out of date, both functions +update it before copying it or returning a pointer to it. +.Pp +.Fn X509_NAME_dup +copies +.Fa val_in +by calling +.Fn i2d_X509_NAME +and +.Fn d2i_X509_NAME . +.Pp +.Fn X509_NAME_set +makes sure that +.Pf * Fa val_out +contains the same data as +.Fa val_in +after the call, except that it fails if +.Fa val_in +is +.Dv NULL . +If +.Pf * Fa val_out +is the same pointer as +.Fa val_in , +the function succeeds without changing anything. +Otherwise, it copies +.Fa val_in +using +.Fn X509_NAME_dup , +and in case of success, it frees +.Pf * Fa val_out +and sets it to a pointer to the new object. +When the function fails, it never changes anything. +In any case, +.Fa val_in +remains valid and may or may not be the same pointer as +.Pf * Fa val_out +after the call. +.Pp +.Fn d2i_X509_NAME_ENTRY +and +.Fn i2d_X509_NAME_ENTRY +decode and encode an ASN.1 +.Vt RelativeDistinguishedName +structure defined in RFC 5280 section 4.1.2.4. +.Pp +.Fn X509_NAME_ENTRY_dup +copies +.Fa val_in +by calling +.Fn i2d_X509_NAME_ENTRY +and +.Fn d2i_X509_NAME_ENTRY . +.Sh RETURN VALUES +.Fn d2i_X509_NAME +and +.Fn X509_NAME_dup +return the new +.Vt X509_NAME +object or +.Dv NULL +if an error occurs. +.Pp +.Fn X509_NAME_set +and +.Fn X509_NAME_get0_der +return 1 on success or 0 if an error occurs. +.Pp +.Fn d2i_X509_NAME_ENTRY +and +.Fn X509_NAME_ENTRY_dup +return the new +.Vt X509_NAME_ENTRY +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_X509_NAME +and +.Fn i2d_X509_NAME_ENTRY +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr X509_NAME_ENTRY_new 3 , +.Xr X509_NAME_new 3 , +.Xr X509_NAME_print_ex 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Pp +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules: +Specification of Basic Encoding Rules (BER), Canonical Encoding +Rules (CER) and Distinguished Encoding Rules (DER). +.Sh HISTORY +.Fn X509_NAME_dup +first appeared in SSLeay 0.4.4. +.Fn d2i_X509_NAME , +.Fn i2d_X509_NAME , +.Fn d2i_X509_NAME_ENTRY , +.Fn i2d_X509_NAME_ENTRY , +and +.Fn X509_NAME_ENTRY_dup +first appeared in SSLeay 0.5.1. +.Fn X509_NAME_set +first appeared in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_NAME_get0_der +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/static/openbsd/man3/d2i_X509_REQ.3 b/static/openbsd/man3/d2i_X509_REQ.3 new file mode 100644 index 00000000..0f113757 --- /dev/null +++ b/static/openbsd/man3/d2i_X509_REQ.3 @@ -0,0 +1,152 @@ +.\" $OpenBSD: d2i_X509_REQ.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_X509_REQ 3 +.Os +.Sh NAME +.Nm d2i_X509_REQ , +.Nm i2d_X509_REQ , +.Nm d2i_X509_REQ_bio , +.Nm d2i_X509_REQ_fp , +.Nm i2d_X509_REQ_bio , +.Nm i2d_X509_REQ_fp , +.Nm d2i_X509_REQ_INFO , +.Nm i2d_X509_REQ_INFO +.Nd decode and encode PKCS#10 certification requests +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_REQ * +.Fo d2i_X509_REQ +.Fa "X509_REQ **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_REQ +.Fa "X509_REQ *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_REQ * +.Fo d2i_X509_REQ_bio +.Fa "BIO *in_bio" +.Fa "X509_REQ **val_out" +.Fc +.Ft X509_REQ * +.Fo d2i_X509_REQ_fp +.Fa "FILE *in_fp" +.Fa "X509_REQ **val_out" +.Fc +.Ft int +.Fo i2d_X509_REQ_bio +.Fa "BIO *out_bio" +.Fa "X509_REQ *val_in" +.Fc +.Ft int +.Fo i2d_X509_REQ_fp +.Fa "FILE *out_fp" +.Fa "X509_REQ *val_in" +.Fc +.Ft X509_REQ_INFO * +.Fo d2i_X509_REQ_INFO +.Fa "X509_REQ_INFO **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_REQ_INFO +.Fa "X509_REQ_INFO *val_in" +.Fa "unsigned char **der_out" +.Fc +.Sh DESCRIPTION +These functions decode and encode PKCS#10 certification requests. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_X509_REQ +and +.Fn i2d_X509_REQ +decode and encode an ASN.1 +.Vt CertificationRequest +structure defined in RFC 2986 section 4.2. +.Fn d2i_X509_REQ_bio , +.Fn d2i_X509_REQ_fp , +.Fn i2d_X509_REQ_bio , +and +.Fn i2d_X509_REQ_fp +are similar except that they decode or encode using a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn d2i_X509_REQ_INFO +and +.Fn i2d_X509_REQ_INFO +decode and encode an ASN.1 +.Vt CertificationRequestInfo +structure defined in RFC 2986 section 4.1. +.Sh RETURN VALUES +.Fn d2i_X509_REQ , +.Fn d2i_X509_REQ_bio , +and +.Fn d2i_X509_REQ_fp +return an +.Vt X509_REQ +object or +.Dv NULL +if an error occurs. +.Pp +.Fn d2i_X509_REQ_INFO +returns an +.Vt X509_REQ_INFO +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_X509_REQ +and +.Fn i2d_X509_REQ_INFO +return the number of bytes successfully encoded or a negative value +if an error occurs. +.Pp +.Fn i2d_X509_REQ_bio +and +.Fn i2d_X509_REQ_fp +return 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr PEM_read_X509_REQ 3 , +.Xr X509_REQ_new 3 +.Sh STANDARDS +RFC 2986: PKCS #10: Certification Request Syntax Specification +.Sh HISTORY +.Fn d2i_X509_REQ , +.Fn i2d_X509_REQ , +.Fn d2i_X509_REQ_fp , +.Fn i2d_X509_REQ_fp , +.Fn d2i_X509_REQ_INFO , +and +.Fn i2d_X509_REQ_INFO +first appeared in SSLeay 0.5.1. +.Fn d2i_X509_REQ_bio +and +.Fn i2d_X509_REQ_bio +first appeared in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . diff --git a/static/openbsd/man3/d2i_X509_SIG.3 b/static/openbsd/man3/d2i_X509_SIG.3 new file mode 100644 index 00000000..1700b2d7 --- /dev/null +++ b/static/openbsd/man3/d2i_X509_SIG.3 @@ -0,0 +1,160 @@ +.\" $OpenBSD: d2i_X509_SIG.3,v 1.11 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 8 2025 $ +.Dt D2I_X509_SIG 3 +.Os +.Sh NAME +.Nm d2i_X509_SIG , +.Nm i2d_X509_SIG , +.Nm d2i_PKCS8_bio , +.Nm i2d_PKCS8_bio , +.Nm d2i_PKCS8_fp , +.Nm i2d_PKCS8_fp +.\" In the next line, the number "7" is not a typo. +.\" These functions are misnamed. +.Nd decode and encode PKCS#7 digest information +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509.h +.Ft X509_SIG * +.Fo d2i_X509_SIG +.Fa "X509_SIG **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_SIG +.Fa "X509_SIG *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft X509_SIG * +.Fo d2i_PKCS8_bio +.Fa "BIO *in_bio" +.Fa "X509_SIG **val_out" +.Fc +.Ft int +.Fo i2d_PKCS8_bio +.Fa "BIO *out_bio" +.Fa "X509_SIG *val_in" +.Fc +.Ft X509_SIG * +.Fo d2i_PKCS8_fp +.Fa "FILE *in_fp" +.Fa "X509_SIG **val_out" +.Fc +.Ft int +.Fo i2d_PKCS8_fp +.Fa "FILE *out_fp" +.Fa "X509_SIG *val_in" +.Fc +.Sh DESCRIPTION +.Fn d2i_X509_SIG +and +.Fn i2d_X509_SIG +decode and encode an ASN.1 +.Vt DigestInfo +structure defined in RFC 2315 section 9.4 +and equivalently in RFC 8017 section 9.2. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp +.Fn d2i_PKCS8_bio +and +.Fn d2i_PKCS8_fp +are similar to +.Fn d2i_X509_SIG +except that they read from a +.Vt BIO +or +.Vt FILE +pointer. +.Pp +.Fn i2d_PKCS8_bio +and +.Fn i2d_PKCS8_fp +are similar to +.Fn i2d_X509_SIG +except that they write to a +.Vt BIO +or +.Vt FILE +pointer. +.Sh RETURN VALUES +.Fn d2i_X509_SIG , +.Fn d2i_PKCS8_bio , +and +.Fn d2i_PKCS8_fp +return a +.Vt X509_SIG +object or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_X509_SIG +returns the number of bytes successfully encoded or a negative value +if an error occurs. +.Pp +.Fn i2d_PKCS8_bio +and +.Fn i2d_PKCS8_fp +return 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr ASN1_item_d2i 3 , +.Xr PKCS7_new 3 , +.Xr RSA_sign 3 , +.Xr X509_SIG_new 3 +.Sh STANDARDS +RFC 2315: PKCS #7: Cryptographic Message Syntax, +section 9: Signed-data content type +.Pp +RFC 8017: PKCS #1: RSA Cryptography Specifications, +section 9: Encoding Methods for Signatures +.Sh HISTORY +.Fn d2i_X509_SIG +and +.Fn i2d_X509_SIG +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn d2i_PKCS8_bio , +.Fn i2d_PKCS8_bio , +.Fn d2i_PKCS8_fp , +and +.Fn i2d_PKCS8_fp +first appeared in OpenSSL 0.9.4 and have been available since +.Ox 2.6 . +.Sh BUGS +.Fn d2i_PKCS8_bio , +.Fn i2d_PKCS8_bio , +.Fn d2i_PKCS8_fp , +and +.Fn i2d_PKCS8_fp +are severely misnamed and should have been called +.Dq d2i_X509_SIG_bio +and so on. +.Pp +Or arguably, the +.Vt X509_SIG +object is misnamed itself, considering that it represents +.Vt DigestInfo +from PKCS#7 and PKCS#1. +Then again, calling it +.Dq PKCS8 +instead clearly isn't an improvement. +.Pp +Either way, these names just don't fit. diff --git a/static/openbsd/man3/daemon.3 b/static/openbsd/man3/daemon.3 new file mode 100644 index 00000000..6254171f --- /dev/null +++ b/static/openbsd/man3/daemon.3 @@ -0,0 +1,100 @@ +.\" $OpenBSD: daemon.3,v 1.14 2022/07/30 07:19:30 jsg 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. +.\" +.Dd $Mdocdate: July 30 2022 $ +.Dt DAEMON 3 +.Os +.Sh NAME +.Nm daemon +.Nd run in the background +.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 +If the argument +.Fa nochdir +is zero, +.Fn daemon +changes the current working directory to the root +.Pq Pa / . +.Pp +If the argument +.Fa noclose +is zero, +.Fn daemon +redirects standard input, standard output and standard error to +.Pa /dev/null . +.Sh RETURN VALUES +Upon success, +.Fn daemon +returns 0; otherwise \-1 is returned. +.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.3 Reno +libutil and moved to libc in +.Bx 4.4 . +.Sh CAVEATS +If the +.Ar noclose +argument is zero, +.Fn daemon +closes the first three file descriptors and redirects 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. diff --git a/static/openbsd/man3/dbopen.3 b/static/openbsd/man3/dbopen.3 new file mode 100644 index 00000000..87ed04cc --- /dev/null +++ b/static/openbsd/man3/dbopen.3 @@ -0,0 +1,538 @@ +.\" $OpenBSD: dbopen.3,v 1.28 2015/09/10 10:20:55 jmc Exp $ +.\" $NetBSD: dbopen.3,v 1.6 1995/02/27 13:23:25 cgd Exp $ +.\" +.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. +.\" +.\" 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 $Mdocdate: September 10 2015 $ +.Dt DBOPEN 3 +.Os +.Sh NAME +.Nm dbopen +.Nd database access methods +.Sh SYNOPSIS +.In sys/types.h +.In fcntl.h +.In limits.h +.In db.h +.Ft DB * +.Fn dbopen "const char *file" "int flags" "int mode" "DBTYPE type" "const void *openinfo" +.Sh DESCRIPTION +The +.Fn dbopen +function 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 +.Fn dbopen +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_NOFOLLOW , +.Dv O_NONBLOCK , +.Dv O_RDONLY , +.Dv O_RDWR , +.Dv O_SHLOCK , +.Dv O_SYNC , +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 +.\".IR or 'ing +.\"them into the +.\".I flags +.\"argument. +.\".Bl -tag -width XXXXX +.\".It 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. +.\".It DB_SHMEM +.\"Place the underlying memory pool used by the database in shared +.\"memory. +.\"Necessary for concurrent access. +.\".It DB_TXN +.\"Support transactions in the database. +.\"The DB_LOCK and DB_SHMEM flags must be set as well. +.\".El +.Pp +The +.Fa type +argument is of type +.Fa 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. +.Pp +.Fn dbopen +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, + unsigned int flags); + int (*fd)(const DB *db); + int (*get)(const DB *db, DBT *key, DBT *data, + unsigned int flags); + int (*put)(const DB *db, DBT *key, const DBT *data, + unsigned int flags); + int (*sync)(const DB *db, u_int flags); + int (*seq)(const DB *db, DBT *key, DBT *data, + unsigned 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 +.Fn dbopen , +and sometimes one or more pointers to key/data structures and a flag value. +.Bl -tag -width XXXXX -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 flags +may be set to the following value: +.Bl -tag -width R_NOOVERWRITE +.It Dv R_CURSOR +Delete the record referenced by the cursor. +The cursor must have previously been initialized. +.El +.Pp +.Fa del +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 +.Fn dbopen +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. +.Pp +.Fa flags +is currently unused. +Specifying anything but 0 will result in an error. +.It Fa put +A pointer to a routine to store key/data pairs in the database. +.Pp +The parameter +.Fa flags +may be set to one of the following values: +.Bl -tag -width R_NOOVERWRITE +.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 +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 +.Fa flags +value +.Sy must +be set to one of the following values: +.Bl -tag -width R_NOOVERWRITE +.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 +.Fa flags +value may be set to the following value: +.Bl -tag -width R_NOOVERWRITE +.It Dv R_RECNOSYNC +If the +.Dv DB_RECNO +access method is being used, this flag causes the +.Fa 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 +.Sh 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 Ds -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 +.Fn dbopen +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 XEINVALX +.It Bq Er EFTYPE +A file is incorrectly formatted. +.It Bq 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 the file and the software. +.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 recno 3 +.Rs +.%T "LIBTP: Portable, Modular Transactions for UNIX" +.%A Margo Seltzer +.%A Michael Olson +.%J USENIX proceedings +.%D Winter 1992 +.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/openbsd/man3/default_colors.3 b/static/openbsd/man3/default_colors.3 new file mode 100644 index 00000000..c657ac29 --- /dev/null +++ b/static/openbsd/man3/default_colors.3 @@ -0,0 +1,147 @@ +.\" $OpenBSD: default_colors.3,v 1.3 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 2000-2011,2016 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1997,1999,2000,2005 +.\" +.\" $Id: default_colors.3,v 1.3 2023/10/17 09:52:08 nicm Exp $ +.TH default_colors 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBuse_default_colors\fP, +\fBassume_default_colors\fP \- use terminal's default colors +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint use_default_colors(void);\fP +.br +\fBint assume_default_colors(int \fIfg\fB, int \fIbg\fB);\fR +.SH DESCRIPTION +The \fBuse_default_colors\fP and \fBassume_default_colors\fP +functions are extensions to the curses library. +They are used with terminals that support ISO 6429 color, or equivalent. +These terminals allow the application to reset color to an unspecified +default value (e.g., with SGR 39 or SGR 49). +.PP +Applications that paint a colored background over the whole screen +do not take advantage of SGR 39 and SGR 49. +Some applications are designed to work with the default background, +using colors only for text. +For example, there are several implementations of the \fBls\fP program +which use colors to denote different file types or permissions. +These \*(``color ls\*('' programs do not necessarily +modify the background color, +typically using only the \fBsetaf\fP terminfo capability to set the +foreground color. +Full-screen applications that use default colors can achieve similar +visual effects. +.PP +The first function, \fBuse_default_colors\fP +tells the curses library to assign terminal default +foreground/background colors to color number \-1. +So init_pair(x,COLOR_RED,\-1) +will initialize pair x as red on default background +and init_pair(x,\-1,COLOR_BLUE) will +initialize pair x as default foreground on blue. +.PP +The other, \fBassume_default_colors\fP +is a refinement which tells which colors to paint for color pair 0. +This function recognizes a special color number \-1, +which denotes the default terminal color. +.PP +The following are equivalent: +.RS +.br +.I use_default_colors(); +.br +.I assume_default_colors(\-1,\-1); +.RE +.PP +These are ncurses extensions. +For other curses implementations, color +number \-1 does not mean anything, just as for ncurses before a +successful call of \fBuse_default_colors\fP or \fBassume_default_colors\fP. +.PP +Other curses implementations do not allow an application to modify color pair 0. +They assume that the background is COLOR_BLACK, +but do not ensure that the color pair 0 is painted to match the +assumption. +If your application does not use either +.B use_default_colors +or +.B assume_default_colors +ncurses will paint a white foreground (text) with black background +for color pair 0. +.SH RETURN VALUE +These functions return the integer \fBERR\fP upon failure +and \fBOK\fP on success. +They will fail if either the terminal does not support +the \fBorig_pair\fP or \fBorig_colors\fP capability. +If the \fBinitialize_pair\fP capability is not found, this causes an +error as well. +.SH NOTES +Associated with this extension, the \fBinit_pair\fP function accepts +negative arguments to specify default foreground or background colors. +.PP +The \fBuse_default_colors\fP function was added to support \fBded\fP. +This is a full-screen application which uses curses to manage only part +of the screen. +The bottom portion of the screen, which is of adjustable +size, is left uncolored to display the results from shell commands. +The top portion of the screen colors filenames using a scheme like the +\*(``color ls\*('' programs. +Attempting to manage the background color of the screen for this application +would give unsatisfactory results for a variety of reasons. +This extension was devised after +noting that color xterm (and similar programs) provides a background color +which does not necessarily correspond to any of the ANSI colors. +While a special terminfo entry could be constructed using nine colors, +there was no mechanism provided within curses to account for the related +\fBorig_pair\fP and \fBback_color_erase\fP capabilities. +.PP +The \fBassume_default_colors\fP function was added to solve +a different problem: support for applications which would use +environment variables and other configuration to bypass curses' +notion of the terminal's default colors, setting specific values. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on +Version 7, BSD or System V implementations. +It is recommended that +any code depending on them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBded\fP(1), +\fBcurs_color\fP(3). +.SH AUTHOR +Thomas Dickey (from an analysis of the requirements for color xterm +for XFree86 3.1.2C, February 1996). diff --git a/static/openbsd/man3/define_key.3 b/static/openbsd/man3/define_key.3 new file mode 100644 index 00000000..00f5ae04 --- /dev/null +++ b/static/openbsd/man3/define_key.3 @@ -0,0 +1,68 @@ +.\" $OpenBSD: define_key.3,v 1.6 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1997 +.\" +.\" $Id: define_key.3,v 1.6 2023/10/17 09:52:08 nicm Exp $ +.TH define_key 3 2022-02-12 "ncurses 6.4" "Library calls" +.SH NAME +\fBdefine_key\fP \- define a keycode +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint define_key(const char *\fIdefinition\fB, int \fIkeycode\fB);\fR +.SH DESCRIPTION +This is an extension to the curses library. +It permits an application to define keycodes with their corresponding control +strings, so that the ncurses library will interpret them just as it would +the predefined codes in the terminfo database. +.PP +If the given string is null, any existing definition for the keycode is +removed. +Similarly, if the given keycode is negative or zero, any existing string +for the given definition is removed. +.SH RETURN VALUE +The keycode must be greater than zero, and the string non-null, +otherwise \fBERR\fP is returned. +\fBERR\fP may also be returned if there is insufficient memory to allocate the +data to store the definition. +If no error is detected, \fBOK\fP is returned. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on +Version 7, BSD or System V implementations. +It is recommended that +any code depending on them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBkeyok\fP(3), +\fBkey_defined\fP(3). +.SH AUTHOR +Thomas Dickey. diff --git a/static/openbsd/man3/des_read_pw.3 b/static/openbsd/man3/des_read_pw.3 new file mode 100644 index 00000000..2ffe13bb --- /dev/null +++ b/static/openbsd/man3/des_read_pw.3 @@ -0,0 +1,198 @@ +.\" $OpenBSD: des_read_pw.3,v 1.13 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL doc/crypto/des.pod +.\" 53934822 Jun 9 16:39:19 2016 -0400 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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. +.\" +.\" The original file was written by Ulf Moeller . +.\" Copyright (c) 2000 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt DES_READ_PW 3 +.Os +.Sh NAME +.Nm EVP_read_pw_string , +.Nm EVP_read_pw_string_min , +.Nm EVP_set_pw_prompt , +.Nm EVP_get_pw_prompt +.Nd compatibility user interface functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Ft int +.Fo EVP_read_pw_string +.Fa "char *buf" +.Fa "int length" +.Fa "const char *prompt" +.Fa "int verify" +.Fc +.Ft int +.Fo EVP_read_pw_string_min +.Fa "char *buf" +.Fa "int min_length" +.Fa "int length" +.Fa "const char *prompt" +.Fa "int verify" +.Fc +.Ft void +.Fo EVP_set_pw_prompt +.Fa "const char *default_prompt" +.Fc +.Ft char * +.Fn EVP_get_pw_prompt void +.Sh DESCRIPTION +.Fn EVP_read_pw_string +writes the +.Fa prompt +to +.Pa /dev/tty , +or, if that could not be opened, to standard output, turns echo off, +and reads an input string from +.Pa /dev/tty , +or, if that could not be opened, from standard input. +The string is returned in +.Fa buf , +which must have space for at least +.Fa length +bytes. +If the +.Fa length +argument exceeds +.Dv BUFSIZ , +.Dv BUFSIZ +is used instead. +If +.Fa verify +is set, the user is asked for the password twice and unless the two +copies match, an error is returned. +.Pp +.Fn EVP_read_pw_string_min +additionally checks that the password is at least +.Fa min_length +bytes long. +.Pp +.Fn EVP_set_pw_prompt +sets a default prompt to a copy of +.Fa default_prompt , +or clears the default prompt if the +.Fa default_prompt +argument is +.Dv NULL +or an empty string. +If the +.Fa default_prompt +argument is longer than 79 bytes, +the copy is silently truncated to a string length of 79 bytes. +.Pp +As long as a default prompt is set, +.Fn EVP_read_pw_string +and +.Fn EVP_read_pw_string_min +can be called with a +.Fa prompt +argument of +.Dv NULL , +in which case the default prompt is used instead. +.Sh RETURN VALUES +.Fn EVP_read_pw_string +and +.Fn EVP_read_pw_string_min +return 0 on success or a negative value on failure. +.Pp +They return \-1 if +.Fa length +is less than or equal to zero or on memory allocation failure. +They return \-1 or \-2 if the internal call to +.Xr UI_process 3 +fails. +.Pp +In addition, +.Fa EVP_read_pw_string_min +returns \-1 if +.Fa min_length +is negative, if +.Fa length +is less than or equal to +.Fa min_length , +or if the user entered a password shorter than +.Fa min_length . +.Pp +.Fn EVP_get_pw_prompt +returns an internal pointer to static memory containing the default prompt, or +.Dv NULL +if no default prompt is set. +.Sh SEE ALSO +.Xr UI_new 3 +.Sh HISTORY +.Fn EVP_read_pw_string +first appeared in SSLeay 0.5.1 and +.Fn EVP_set_pw_prompt +and +.Fn EVP_get_pw_prompt +in SSLeay 0.6.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_read_pw_string_min +first appeared in OpenSSL 1.0.0 +and has been available since +.Ox 4.9 . diff --git a/static/openbsd/man3/devname.3 b/static/openbsd/man3/devname.3 new file mode 100644 index 00000000..4d626a4e --- /dev/null +++ b/static/openbsd/man3/devname.3 @@ -0,0 +1,66 @@ +.\" $OpenBSD: devname.3,v 1.8 2013/06/05 03:39:22 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt DEVNAME 3 +.Os +.Sh NAME +.Nm devname +.Nd get device name +.Sh SYNOPSIS +.In sys/stat.h +.In stdlib.h +.Ft char * +.Fn devname "dev_t dev" "mode_t type" +.Sh DESCRIPTION +The +.Fn devname +function returns a pointer to the name of the block or character +device in +.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 +.Dv S_IFBLK +or +.Dv S_IFCHR . +If no device matches the specified values, or no information is +available, a pointer to the string +.Qq ?? +is returned. +.Sh SEE ALSO +.Xr stat 2 , +.Xr dev_mkdb 8 +.Sh HISTORY +The +.Nm devname +function call appeared in +.Bx 4.4 . diff --git a/static/openbsd/man3/dirname.3 b/static/openbsd/man3/dirname.3 new file mode 100644 index 00000000..76c19130 --- /dev/null +++ b/static/openbsd/man3/dirname.3 @@ -0,0 +1,93 @@ +.\" $OpenBSD: dirname.3,v 1.24 2020/10/20 19:30:14 naddy Exp $ +.\" +.\" Copyright (c) 1997 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. +.\" +.Dd $Mdocdate: October 20 2020 $ +.Dt DIRNAME 3 +.Os +.Sh NAME +.Nm dirname +.Nd extract the directory portion of a pathname +.Sh SYNOPSIS +.In libgen.h +.Ft char * +.Fn dirname "char *path" +.Sh DESCRIPTION +The +.Fn dirname +function is the converse of +.Xr basename 3 ; +it returns a pointer to the parent directory of the pathname pointed to by +.Ar path . +Any trailing +.Sq \&/ +characters are not counted as part of the directory +name. +If +.Ar path +is a null pointer, the empty string, or contains no +.Sq \&/ +characters, +.Fn dirname +returns a pointer to the string +.Qq \&. , +signifying the current directory. +.Sh RETURN VALUES +On successful completion, +.Fn dirname +returns a pointer to the parent directory of +.Ar path . +.Pp +If +.Fn dirname +fails, a null pointer is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er ENAMETOOLONG +The path component to be returned was larger than +.Dv PATH_MAX . +.El +.Sh SEE ALSO +.Xr basename 1 , +.Xr dirname 1 , +.Xr basename 3 +.Sh STANDARDS +The +.Fn dirname +function conforms to the X/Open System Interfaces option of the +.St -p1003.1-2008 +specification. +.Sh HISTORY +The +.Fn dirname +function first appeared in +.Ox 2.2 . +.Sh AUTHORS +.An Todd C. Miller +.Sh CAVEATS +.Fn dirname +returns a pointer to internal static storage space that will be overwritten +by subsequent calls. +.Pp +Other vendor implementations of +.Fn dirname +may modify the contents of the string passed to +.Fn dirname ; +this should be taken into account when writing code which calls this function +if portability is desired. diff --git a/static/openbsd/man3/div.3 b/static/openbsd/man3/div.3 new file mode 100644 index 00000000..b4b42ba8 --- /dev/null +++ b/static/openbsd/man3/div.3 @@ -0,0 +1,63 @@ +.\" 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. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (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: div.3,v 1.13 2022/09/11 06:38:11 jmc Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt DIV 3 +.Os +.Sh NAME +.Nm div +.Nd return quotient and remainder from division +.Sh SYNOPSIS +.In stdlib.h +.Ft div_t +.Fn div "int num" "int denom" +.Sh DESCRIPTION +The +.Fn div +function computes the value +.Fa num Ns / Ns Fa denom +and returns the quotient and remainder in a structure named +.Fa div_t +that contains two +.Vt int +members named +.Fa quot +and +.Fa rem . +.Sh SEE ALSO +.Xr imaxdiv 3 , +.Xr ldiv 3 , +.Xr lldiv 3 +.Sh STANDARDS +The +.Fn div +function conforms to +.St -ansiC . diff --git a/static/openbsd/man3/ecvt.3 b/static/openbsd/man3/ecvt.3 new file mode 100644 index 00000000..f478f8e4 --- /dev/null +++ b/static/openbsd/man3/ecvt.3 @@ -0,0 +1,166 @@ +.\" $OpenBSD: ecvt.3,v 1.13 2019/01/25 00:19:25 millert Exp $ +.\" +.\" Copyright (c) 2002 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 $Mdocdate: January 25 2019 $ +.Dt ECVT 3 +.Os +.Sh NAME +.Nm ecvt , +.Nm fcvt , +.Nm gcvt +.Nd convert double to ASCII string +.Sh SYNOPSIS +.In stdlib.h +.Ft char * +.Fn ecvt "double value" "int ndigit" "int *decpt" "int *sign" +.Ft char * +.Fn fcvt "double value" "int ndigit" "int *decpt" "int *sign" +.Ft char * +.Fn gcvt "double value" "int ndigit" "char *buf" +.Sh DESCRIPTION +.Bf -symbolic +These functions are provided for compatibility with legacy code. +New code should use the +.Xr snprintf 3 +function for improved safety and portability. +.Ef +.Pp +The +.Fn ecvt , +.Fn fcvt +and +.Fn gcvt +functions convert the double precision floating-point number +.Fa value +to a NUL-terminated +.Tn ASCII +string. +.Pp +The +.Fn ecvt +function converts +.Fa value +to a NUL-terminated string of exactly +.Fa ndigit +digits and returns a pointer to that string. +The result is padded with zeroes from left to right as needed. +There are no leading zeroes unless +.Fa value +itself is 0. +The least significant digit is rounded in an implementation-dependent manner. +The position of the decimal point relative to the beginning of the string +is stored in +.Fa decpt . +A negative value indicates that the decimal point is located +to the left of the returned digits (this occurs when there is no +whole number component to +.Fa value ) . +If +.Fa value +is zero, it is unspecified whether the integer pointed to by +.Fa decpt +will be 0 or 1. +The decimal point itself is not included in the returned string. +If the sign of the result is negative, the integer pointed to by +.Fa sign +is non-zero; otherwise, it is 0. +.Pp +If the converted value is out of range or is not representable, +the contents of the returned string are unspecified. +.Pp +The +.Fn fcvt +function is identical to +.Fn ecvt +with the exception that +.Fa ndigit +specifies the number of digits after the decimal point (zero-padded as +needed). +.Pp +The +.Fn gcvt +function converts +.Fa value +to a NUL-terminated string similar to the %g +.Xr printf 3 +format specifier and stores the result in +.Fa buf . +It produces +.Fa ndigit +significant digits similar to the %f +.Xr printf 3 +format specifier where possible. +If +.Fa ndigit +does allow sufficient precision, the result is stored in +exponential notation similar to the %e +.Xr printf 3 +format specifier. +If +.Fa value +is less than zero, +.Fa buf +will be prefixed with a minus sign. +A decimal point is included in the returned string if +.Fa value +is not a whole number. +Unlike the +.Fn ecvt +and +.Fn fcvt +functions, +.Fa buf +is not zero-padded. +.Sh RETURN VALUES +The +.Fn ecvt , +.Fn fcvt +and +.Fn gcvt +functions return a NUL-terminated string representation of +.Fa value . +.Sh SEE ALSO +.Xr printf 3 , +.Xr strtod 3 +.Sh STANDARDS +The +.Fn ecvt , +.Fn fcvt +and +.Fn gcvt +functions conform to +.St -p1003.1-2001 ; +as of +.St -p1003.1-2008 +they are no longer a part of the standard. +.Sh CAVEATS +The +.Fn ecvt +and +.Fn fcvt +functions return a pointer to internal storage space that will be +overwritten by subsequent calls to either function. +.Pp +The maximum possible precision of the return value is limited by the +precision of a double and may not be the same on all architectures. +.Pp +The +.Xr snprintf 3 +function is preferred over these functions for new code. diff --git a/static/openbsd/man3/eddsa_pk_new.3 b/static/openbsd/man3/eddsa_pk_new.3 new file mode 100644 index 00000000..2f7b3118 --- /dev/null +++ b/static/openbsd/man3/eddsa_pk_new.3 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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 fido_assert_verify 3 , +.Xr fido_cred_pubkey_ptr 3 , +.Xr rs256_pk_new 3 diff --git a/static/openbsd/man3/editline.3 b/static/openbsd/man3/editline.3 new file mode 100644 index 00000000..ebcf4cb4 --- /dev/null +++ b/static/openbsd/man3/editline.3 @@ -0,0 +1,986 @@ +.\" $OpenBSD: editline.3,v 1.50 2025/06/05 18:57:01 schwarze Exp $ +.\" $NetBSD: editline.3,v 1.88 2016/02/25 14:59:22 wiz Exp $ +.\" +.\" Copyright (c) 1997-2003 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 $Mdocdate: June 5 2025 $ +.Dt EDITLINE 3 +.Os +.Sh NAME +.Nm editline , +.Nm el_init , +.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_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 SYNOPSIS +.Lb libedit libcurses +.In histedit.h +.Ft EditLine * +.Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr" +.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 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 +The +.Nm +library is designed to work with blocking I/O only. +If the +.Dv FIONBIO +.Xr ioctl 2 +or the +.Dv O_NONBLOCK +.Xr fcntl 2 +is set on +.Ar fin , +.Fn el_gets +and +.Fn el_wgets +will almost certainly fail with +.Ar EAGAIN . +.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. +The only locales supported are UTF-8 and the default C or POSIX locale. +If any other locale is set, behaviour is undefined. +.Sh LINE EDITING FUNCTIONS +The line editing functions use a common data structure, +.Fa EditLine , +which is created by +.Fn el_init +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_end +Clean up and finish with +.Fa e , +assumed to have been created with +.Fn el_init . +.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. +.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_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 . +.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_PREP_TERM , Fa "int" +Sets or clears terminal editing mode. +.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 . +.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 $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_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 +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_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 +.Xr readline 3 +compatibility. +The caller is responsible for free'ing the string in the returned +.Fa HistEvent . +.El +.Pp +.Fn history +returns \*[Gt]= 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 curses 3 , +.Xr signal 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/openbsd/man3/elf.3 b/static/openbsd/man3/elf.3 new file mode 100644 index 00000000..09fe9fec --- /dev/null +++ b/static/openbsd/man3/elf.3 @@ -0,0 +1,625 @@ +.\" 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,v 1.9 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd June 12, 2019 +.Dt ELF 3 +.Os +.Sh NAME +.Nm elf +.Nd API for manipulating ELF objects +.Sh SYNOPSIS +.Lb libelf +.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 +.Fn *elf* +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 +.Nm +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 +.Nm +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 "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 "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 "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 "SHT_PREINIT_ARRAY" "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 "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 "elf_getshstrndx" -compact +.It Fn elf32_checksum , Fn elf64_checksum +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 . +.Sh AUTHORS +The ELF library was written by +.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . diff --git a/static/openbsd/man3/elf_aux_info.3 b/static/openbsd/man3/elf_aux_info.3 new file mode 100644 index 00000000..1bd1a092 --- /dev/null +++ b/static/openbsd/man3/elf_aux_info.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: elf_aux_info.3,v 1.1 2024/07/14 09:48:48 jca Exp $ +.\" +.\" Origin: FreeBSD auxv.3 +.\" +.\" Copyright (c) 2019 Ian Lepore +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list 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 $Mdocdate: July 14 2024 $ +.Dt ELF_AUX_INFO 3 +.Os +.Sh NAME +.Nm elf_aux_info +.Nd extract data from the elf auxiliary vector of the current process +.Sh SYNOPSIS +.In sys/auxv.h +.Ft int +.Fn elf_aux_info "int aux" "void *buf" "int buflen" +.Sh DESCRIPTION +The +.Fn elf_aux_info +function retrieves the auxiliary info vector requested in +.Va aux . +The information is stored into the provided buffer if it will fit. +The following values can be requested (corresponding buffer sizes are +specified in parenthesis): +.Bl -tag -width AT_HWCAP2 +.It AT_HWCAP +CPU / hardware feature flags +.Dv (sizeof(unsigned long)) . +.It AT_HWCAP2 +CPU / hardware feature flags +.Dv (sizeof(unsigned long)) . +.It AT_PAGESZ +Page size in bytes +.Dv (sizeof(int)) . +.El +.Sh RETURN VALUES +Returns zero on success, or an error number on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +An unknown item was requested. +.It Bq Er EINVAL +The provided buffer was not the right size for the requested item. +.It Bq Er ENOENT +The requested item is not available. +.El +.Sh HISTORY +The +.Fn elf_aux_info +function appeared in +.Fx 12.0 +and was first available in +.Ox 7.6 . diff --git a/static/openbsd/man3/elf_begin.3 b/static/openbsd/man3/elf_begin.3 new file mode 100644 index 00000000..cc6ed4a0 --- /dev/null +++ b/static/openbsd/man3/elf_begin.3 @@ -0,0 +1,314 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd December 11, 2011 +.Dt ELF_BEGIN 3 +.Os +.Sh NAME +.Nm elf_begin +.Nd open an ELF file or ar(1) archive +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar fd +is an open file descriptor returned from an +.Xr open 2 +system call. +Function +.Fn elf_begin +uses argument +.Ar fd +for reading or writing depending on the value of argument +.Ar cmd . +Argument +.Ar elf +is primarily used for iterating through archives. +.Pp +The argument +.Ar cmd +can have the following values: +.Bl -tag -width "ELF_C_WRITE" +.It ELF_C_NULL +Causes +.Fn elf_begin +to return NULL. +Arguments +.Ar fd +and +.Ar 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 +.Ar fd +and +.Ar elf . +It can be used for both +.Xr ar 1 +archives and for ELF objects. +.Pp +If argument +.Ar elf +is NULL, the library will allocate a new ELF descriptor for the file +being processed. +The argument +.Ar fd +should have been opened for reading. +.Pp +If argument +.Ar elf +is not NULL, and references a regular ELF file previously opened with +.Fn elf_begin , +then the activation count for the descriptor referenced by argument +.Ar elf +is incremented. +The value in argument +.Ar fd +should match that used to open the descriptor argument +.Ar elf . +.Pp +If argument +.Ar elf +is not 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 +.Ar fd +should match that used to open the archive earlier. +.Pp +If argument +.Ar elf +is not NULL, and references an +.Xr ar 1 +archive opened earlier with +.Fn elf_memory , +then the value of the argument +.Ar 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 +.Ar fd +should have been opened for reading and writing. +If argument +.Ar elf +is NULL, the library will allocate a new ELF descriptor for +the file being processed. +If the argument +.Ar elf +is non-null, it should point to a descriptor previously +allocated with +.Fn elf_begin +with the same values for arguments +.Ar fd +and +.Ar cmd ; +in this case the library will increment the activation count for descriptor +.Ar 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 +.Ar fd +should have been opened for writing. +Argument +.Ar elf +is ignored, and the previous contents of file referenced by argument +.Ar fd +are overwritten. +.El +.Ss Processing ar(1) archives +An +.Xr ar 1 +archive may be opened in read mode (with argument +.Ar 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 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)) == -1) { + \&... 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 +.Ar elf +could not be parsed. +.It Bq Er ELF_E_ARGUMENT +The value in argument +.Ar cmd +was unrecognized. +.It Bq Er ELF_E_ARGUMENT +A non-null value for argument +.Ar elf +was specified when +.Ar cmd +was set to +.Dv ELF_C_RDWR . +.It Bq Er ELF_E_ARGUMENT +The value of argument +.Ar fd +differs from the one the ELF descriptor +.Ar elf +was created with. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar cmd +differs from the value specified when ELF descriptor +.Ar elf +was created. +.It Bq Er ELF_E_ARGUMENT +An +.Xr ar 1 +archive was opened with +.Ar cmd +set to +.Dv ELF_C_RDWR . +.It Bq Er ELF_E_ARGUMENT +The file referenced by argument +.Ar fd +was empty. +.It Bq Er ELF_E_ARGUMENT +The underlying file for argument +.Ar fd +was of an unsupported type. +.It Bq Er ELF_E_IO +The file descriptor in argument +.Ar fd +was invalid. +.It Bq Er ELF_E_IO +The file descriptor in argument +.Ar fd +could not be read or written to. +.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 +.Ar 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_rand 3 , +.Xr elf_update 3 , +.Xr gelf 3 diff --git a/static/openbsd/man3/elf_cntl.3 b/static/openbsd/man3/elf_cntl.3 new file mode 100644 index 00000000..aa713ced --- /dev/null +++ b/static/openbsd/man3/elf_cntl.3 @@ -0,0 +1,110 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd August 9, 2006 +.Dt ELF_CNTL 3 +.Os +.Sh NAME +.Nm elf_cntl +.Nd control an elf file descriptor +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar elf . +.Pp +Argument +.Ar 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 +.Ar elf . +For ELF descriptors opened with mode +.Ar ELF_C_WRITE +or +.Ar 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 +.Ar elf +into memory so that the underlying file descriptor can be +safely closed with command +.Dv ELF_C_FDDONE . +.El +.Pp +Argument +.Ar 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 +.Ar elf +is a descriptor for an archive member. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar 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/openbsd/man3/elf_end.3 b/static/openbsd/man3/elf_end.3 new file mode 100644 index 00000000..34572959 --- /dev/null +++ b/static/openbsd/man3/elf_end.3 @@ -0,0 +1,75 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd June 29, 2006 +.Dt ELF_END 3 +.Os +.Sh NAME +.Nm elf_end +.Nd release an ELF descriptor +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar 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 NULL value is permitted for argument +.Ar elf . +.Pp +A call to +.Fn elf_end +decrements the activation count for descriptor +.Ar 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 +.Ar 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 +.Ar elf Ap s +activation count, or zero if argument +.Ar elf +was NULL. +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_memory 3 , +.Xr gelf 3 diff --git a/static/openbsd/man3/elf_errmsg.3 b/static/openbsd/man3/elf_errmsg.3 new file mode 100644 index 00000000..de6da66e --- /dev/null +++ b/static/openbsd/man3/elf_errmsg.3 @@ -0,0 +1,106 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd June 11, 2006 +.Dt ELF_ERRMSG 3 +.Os +.Sh NAME +.Nm elf_errmsg , +.Nm elf_errno +.Nd ELF library error message handling +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar error . +A zero value for argument +.Ar error +retrieves the most recent error encountered by the ELF +library. +An argument value of -1 behaves identically, except that +it guarantees a non-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 +.Ar error . +With a zero argument, the function will return a 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/openbsd/man3/elf_fill.3 b/static/openbsd/man3/elf_fill.3 new file mode 100644 index 00000000..ec7a67a3 --- /dev/null +++ b/static/openbsd/man3/elf_fill.3 @@ -0,0 +1,51 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd June 11, 2006 +.Dt ELF_FILL 3 +.Os +.Sh NAME +.Nm elf_fill +.Nd set fill byte for inter-section padding +.Sh SYNOPSIS +.Lb libelf +.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/openbsd/man3/elf_flagdata.3 b/static/openbsd/man3/elf_flagdata.3 new file mode 100644 index 00000000..857a8573 --- /dev/null +++ b/static/openbsd/man3/elf_flagdata.3 @@ -0,0 +1,226 @@ +.\" 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,v 1.4 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar arhdr , +.Ar data , +.Ar elf +and +.Ar 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 +.Ar arhdr +should have been returned by a prior call to +.Xr elf_getarhdr 3 . +.It +Argument +.Ar 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 +.Ar elf +should have been allocated by a prior call to one of +.Xr elf_begin 3 +or +.Xr elf_memory 3 . +.It +Argument +.Ar 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 NULL to simplify error handling in +application code. +.Pp +Argument +.Ar cmd +may have the following values: +.Bl -tag -width ELF_C_SET +.It Dv ELF_C_CLR +The argument +.Ar flags +specifies the flags to be cleared. +.It Dv ELF_C_SET +The argument +.Ar flags +specifies the flags to be set. +.El +.Pp +The argument +.Ar 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 +.Ar 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 +.Ar 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 +.Ar 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 +.Ar cmd +argument. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar flags +had unsupported flags set. +.It Bq Er ELF_E_ARGUMENT +The argument +.Ar 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/openbsd/man3/elf_getarhdr.3 b/static/openbsd/man3/elf_getarhdr.3 new file mode 100644 index 00000000..87a46dba --- /dev/null +++ b/static/openbsd/man3/elf_getarhdr.3 @@ -0,0 +1,96 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd August 15, 2006 +.Dt ELF_GETARHDR 3 +.Os +.Sh NAME +.Nm elf_getarhdr +.Nd retrieve ar(1) header for an archive member +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar 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 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_ARGUMENT +Argument +.Ar elf +was NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar 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/openbsd/man3/elf_getarsym.3 b/static/openbsd/man3/elf_getarsym.3 new file mode 100644 index 00000000..228d5b02 --- /dev/null +++ b/static/openbsd/man3/elf_getarsym.3 @@ -0,0 +1,129 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd August 15, 2006 +.Dt ELF_GETARSYM 3 +.Os +.Sh NAME +.Nm elf_getarsym +.Nd retrieve the symbol table of an archive +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar elf +should be a descriptor for an +.Xr ar 1 +archive opened using +.Fn elf_begin +or +.Fn elf_memory . +.Pp +If the archive +.Ar 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 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 +.Ar 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 NULL +pointer if an error was encountered. +.Pp +If argument +.Ar 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 +.Ar 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 +.Ar elf +was NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar 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/openbsd/man3/elf_getbase.3 b/static/openbsd/man3/elf_getbase.3 new file mode 100644 index 00000000..3c7984ee --- /dev/null +++ b/static/openbsd/man3/elf_getbase.3 @@ -0,0 +1,70 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd June 6, 2010 +.Dt ELF_GETBASE 3 +.Os +.Sh NAME +.Nm elf_getbase +.Nd get the base offset for an object file +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar 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 +.Ar elf +was 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/openbsd/man3/elf_getdata.3 b/static/openbsd/man3/elf_getdata.3 new file mode 100644 index 00000000..8f179ab6 --- /dev/null +++ b/static/openbsd/man3/elf_getdata.3 @@ -0,0 +1,233 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar scn . +The returned data descriptor will be setup to contain translated data. +Argument +.Ar data +may be NULL, in which case the function returns the first data descriptor +associated with section +.Ar scn . +If argument +.Ar data +is not NULL, it must be a pointer to a data descriptor associated with +section descriptor +.Ar scn , +and function +.Fn elf_getdata +will return a pointer to the next data descriptor for the section, +or 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 +.Ar 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 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 +.Ar 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 +.Ar 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 +.Ar scn +as +.Dq dirty . +.Pp +Function +.Fn elf_rawdata +is used to step through the data descriptors associated with +section +.Ar scn . +In contrast to function +.Fn elf_getdata , +this function returns untranslated data. +If argument +.Ar data +is NULL, the first data descriptor associated with section +.Ar scn +is returned. +If argument +.Ar data +is not NULL, is must be a data descriptor associated with +section +.Ar scn , +and function +.Fn elf_rawdata +will return the next data descriptor in the list, or 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 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 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 +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 +.Ar scn +or +.Ar data +was NULL. +.It Bq Er ELF_E_ARGUMENT +The data descriptor referenced by argument +.Ar data +is not associated with section descriptor +.Ar scn . +.It Bq Er ELF_E_ARGUMENT +The section denoted by argument +.Ar 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 +.Ar scn +had type +.Dv SHT_NULL . +.It Bq Er ELF_E_SECTION +The type of the section +.Ar scn +was not recognized by the library. +.It Bq Er ELF_E_SECTION +The size of the section +.Ar scn +is not a multiple of the file size for its section type. +.It Bq Er ELF_E_SECTION +The file offset for section +.Ar scn +is incorrect. +.It Bq Er ELF_E_UNIMPL +The section type associated with section +.Ar scn +is not supported. +.It Bq Er ELF_E_VERSION +Section +.Ar 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/openbsd/man3/elf_getident.3 b/static/openbsd/man3/elf_getident.3 new file mode 100644 index 00000000..52c2e33c --- /dev/null +++ b/static/openbsd/man3/elf_getident.3 @@ -0,0 +1,82 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd July 3, 2006 +.Dt ELF_GETIDENT 3 +.Os +.Sh NAME +.Nm elf_getident +.Nd return the initial bytes of a file +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar elf . +.Pp +If argument +.Ar sz +is non-null, the size of the identification area returned is written +to the location pointed to by +.Ar sz . +This location is set to zero on errors. +.Sh RETURN VALUES +Function +.Fn elf_getident +will return a non-NULL pointer to the initial bytes of the file if +successful, or 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 NULL value was passed in for argument +.Ar elf . +.It Bq Er ELF_E_SEQUENCE +ELF descriptor +.Ar 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/openbsd/man3/elf_getphdrnum.3 b/static/openbsd/man3/elf_getphdrnum.3 new file mode 100644 index 00000000..9139335f --- /dev/null +++ b/static/openbsd/man3/elf_getphdrnum.3 @@ -0,0 +1,84 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar elf +and stores it into the location pointed to by argument +.Ar 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 NULL value was passed in for argument +.Ar elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +lacks an ELF Executable Header. +.It Bq Er ELF_E_HEADER +The ELF Executable Header associated with argument +.Ar 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/openbsd/man3/elf_getphnum.3 b/static/openbsd/man3/elf_getphnum.3 new file mode 100644 index 00000000..aae838f9 --- /dev/null +++ b/static/openbsd/man3/elf_getphnum.3 @@ -0,0 +1,91 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar elf +and stores it into the location pointed to by argument +.Ar 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 NULL value was passed in for argument +.Ar elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +lacks an ELF Executable Header. +.It Bq Er ELF_E_HEADER +The ELF Executable Header associated with argument +.Ar 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/openbsd/man3/elf_getscn.3 b/static/openbsd/man3/elf_getscn.3 new file mode 100644 index 00000000..d375557e --- /dev/null +++ b/static/openbsd/man3/elf_getscn.3 @@ -0,0 +1,154 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar index +in the object denoted by ELF descriptor +.Ar 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 +.Ar scn . +.Pp +Function +.Fn elf_newscn +creates a new section and appends it to the list of sections +associated with descriptor +.Ar elf . +The library will automatically increment the +.Va e_shnum +field of the ELF header associated with descriptor +.Ar 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 +.Ar 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 +.Ar scn +is allowed to be 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 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 +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 +.Ar elf +or +.Ar scn +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar index +exceeded the current number of sections in the ELF object. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not a descriptor for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Section descriptor +.Ar scn +was not associated with ELF descriptor +.Ar elf . +.It Bq Er ELF_E_CLASS +Descriptor +.Ar elf +was of an unknown ELF class. +.It Bq Er ELF_E_SECTION +Argument +.Ar 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/openbsd/man3/elf_getshdrnum.3 b/static/openbsd/man3/elf_getshdrnum.3 new file mode 100644 index 00000000..a19f552f --- /dev/null +++ b/static/openbsd/man3/elf_getshdrnum.3 @@ -0,0 +1,76 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar elf +and stores it into the location pointed to by argument +.Ar 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 NULL value was passed in for argument +.Ar elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar 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/openbsd/man3/elf_getshdrstrndx.3 b/static/openbsd/man3/elf_getshdrstrndx.3 new file mode 100644 index 00000000..5b86e680 --- /dev/null +++ b/static/openbsd/man3/elf_getshdrstrndx.3 @@ -0,0 +1,77 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar elf +and stores it into the location pointed to by argument +.Ar 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 NULL value was passed in for argument +.Ar elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +lacks an ELF Executable header. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar 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/openbsd/man3/elf_getshnum.3 b/static/openbsd/man3/elf_getshnum.3 new file mode 100644 index 00000000..0b0eec0a --- /dev/null +++ b/static/openbsd/man3/elf_getshnum.3 @@ -0,0 +1,82 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar elf +and stores it into the location pointed to by argument +.Ar 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 NULL value was passed in for argument +.Ar elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar 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/openbsd/man3/elf_getshstrndx.3 b/static/openbsd/man3/elf_getshstrndx.3 new file mode 100644 index 00000000..a7e4d975 --- /dev/null +++ b/static/openbsd/man3/elf_getshstrndx.3 @@ -0,0 +1,93 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar elf +and stores it into the location pointed to by argument +.Ar ndxptr . +.Pp +Function +.Fn elf_setshstrndx +sets the index of the section name string table to argument +.Ar 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 NULL value was passed in for argument +.Ar elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +lacks an ELF Executable header. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar 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/openbsd/man3/elf_hash.3 b/static/openbsd/man3/elf_hash.3 new file mode 100644 index 00000000..b3649a4b --- /dev/null +++ b/static/openbsd/man3/elf_hash.3 @@ -0,0 +1,56 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd August 15, 2006 +.Dt ELF_HASH 3 +.Os +.Sh NAME +.Nm elf_hash +.Nd compute a hash value for a string +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar 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/openbsd/man3/elf_kind.3 b/static/openbsd/man3/elf_kind.3 new file mode 100644 index 00000000..c23a54a8 --- /dev/null +++ b/static/openbsd/man3/elf_kind.3 @@ -0,0 +1,70 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd June 1, 2006 +.Dt ELF_KIND 3 +.Os +.Sh NAME +.Nm elf_kind +.Nd determine ELF file type +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar elf . +The argument +.Ar elf +is allowed to be 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 +.Ar elf +is an archive. +.It Dv ELF_K_ELF +The file associated with argument +.Ar elf +is an ELF file. +.It Dv ELF_K_NONE +The argument +.Ar elf +was NULL, or the ELF library could not determine the type of the file +associated with argument +.Ar 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/openbsd/man3/elf_memory.3 b/static/openbsd/man3/elf_memory.3 new file mode 100644 index 00000000..a8af157e --- /dev/null +++ b/static/openbsd/man3/elf_memory.3 @@ -0,0 +1,121 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar image +points to the start of the memory image of the file or archive. +Argument +.Ar 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 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)) == -1 || + fstat(fd, &sb) == -1 || + (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 NULL value was used for argument +.Ar image +or the value of argument +.Ar 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 +.Ar 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 gelf 3 diff --git a/static/openbsd/man3/elf_next.3 b/static/openbsd/man3/elf_next.3 new file mode 100644 index 00000000..28fec12d --- /dev/null +++ b/static/openbsd/man3/elf_next.3 @@ -0,0 +1,98 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd February 27, 2019 +.Dt ELF_NEXT 3 +.Os +.Sh NAME +.Nm elf_next +.Nd provide sequential access to the next archive member +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar 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 +.Ar 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 +.Ar 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 +.Ar elf . +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_end 3 , +.Xr elf_rand 3 diff --git a/static/openbsd/man3/elf_open.3 b/static/openbsd/man3/elf_open.3 new file mode 100644 index 00000000..b0ebca56 --- /dev/null +++ b/static/openbsd/man3/elf_open.3 @@ -0,0 +1,125 @@ +.\" 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,v 1.5 2025/06/12 01:16:50 schwarze Exp $ +.\" +.Dd June 12, 2019 +.Dt ELF_OPEN 3 +.Os +.Sh NAME +.Nm elf_open , +.Nm elf_openmemory +.Nd open ELF objects and ar(1) archives +.Sh SYNOPSIS +.Lb libelf +.In libelf.h +.Ft "Elf *" +.Fn elf_open "int fd" +.Ft "Elf *" +.Fn elf_openmemory "char *image" "size_t sz" +.Sh DESCRIPTION +.Em Important : +The functions +.Fn elf_open +and +.Fn elf_openmemory +are extensions to the +.Xr elf 3 +API, for the internal use of the +Elftoolchain project. +Portable applications should not use these functions. +.Pp +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 +.Ar 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 +.Ar image . +The argument +.Ar sz +specifies the size of the memory area in bytes. +.Sh RETURN VALUES +The function returns a pointer to a ELF descriptor if successful, or +NULL if an error occurred. +.Sh COMPATIBILITY +These functions are non-standard extensions to the +.Xr elf 3 +API set. +.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 ERRORS +These functions can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +The argument +.Ar fd +was of an unsupported file type. +.It Bq Er ELF_E_ARGUMENT +The argument +.Ar sz +was zero, or the argument +.Ar image +was NULL. +.It Bq Er ELF_E_IO +The file descriptor in argument +.Ar fd +was invalid. +.It Bq Er ELF_E_IO +The file descriptor in argument +.Ar 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/openbsd/man3/elf_rand.3 b/static/openbsd/man3/elf_rand.3 new file mode 100644 index 00000000..d5d763b3 --- /dev/null +++ b/static/openbsd/man3/elf_rand.3 @@ -0,0 +1,117 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd June 17, 2006 +.Dt ELF_RAND 3 +.Os +.Sh NAME +.Nm elf_rand +.Nd provide sequential access to the next archive member +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar archive +to be adjusted so that the next call to +.Xr elf_begin 3 +will provide access to the archive member at byte offset +.Ar offset +in the archive. +Argument +.Ar 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 +.Ar 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 +.Ar archive +was null. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar archive +was not a descriptor for an +.Xr ar 1 +archive. +.It Bq Er ELF_E_ARCHIVE +Argument +.Ar 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/openbsd/man3/elf_rawfile.3 b/static/openbsd/man3/elf_rawfile.3 new file mode 100644 index 00000000..20261003 --- /dev/null +++ b/static/openbsd/man3/elf_rawfile.3 @@ -0,0 +1,75 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd July 3, 2006 +.Dt ELF_RAWFILE 3 +.Os +.Sh NAME +.Nm elf_rawfile +.Nd return uninterpreted contents of an ELF file +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar elf . +.Pp +If argument +.Ar 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 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 +.Ar elf +was NULL. +.It Bq Er ELF_E_SEQUENCE +Argument +.Ar 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/openbsd/man3/elf_strptr.3 b/static/openbsd/man3/elf_strptr.3 new file mode 100644 index 00000000..7f307b6c --- /dev/null +++ b/static/openbsd/man3/elf_strptr.3 @@ -0,0 +1,115 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd December 16, 2006 +.Dt ELF_STRPTR 3 +.Os +.Sh NAME +.Nm elf_strptr +.Nd retrieve a string pointer in a string table +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar elf +is a descriptor for an ELF object. +Argument +.Ar scndx +is the section index for an ELF string table. +Argument +.Ar 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 NULL in case an error was +encountered. +.Sh ERRORS +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was NULL +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar scndx +was not the section index for a string table. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar stroffset +exceeded the size of the string table. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar stroffset +index an unallocated region of the string table. +.It Bq Er ELF_E_DATA +Offset +.Ar 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 +.Ar scndx . +.It Bq Er ELF_E_HEADER +ELF descriptor +.Ar 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 +.Ar scndx +contained a malformed section header. +.It Bq Er ELF_E_SECTION +The ELF descriptor in argument +.Ar 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/openbsd/man3/elf_update.3 b/static/openbsd/man3/elf_update.3 new file mode 100644 index 00000000..acabb20f --- /dev/null +++ b/static/openbsd/man3/elf_update.3 @@ -0,0 +1,381 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd April 22, 2019 +.Dt ELF_UPDATE 3 +.Os +.Sh NAME +.Nm elf_update +.Nd update an ELF descriptor +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar elf +should reference a valid ELF descriptor. +.Pp +Argument +.Ar 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 +.Ar 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 +.Ar 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 exec_elf.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 exec_elf.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 +.Ar elf +was null. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar cmd +was not recognized. +.It Bq Er ELF_E_ARGUMENT +The argument +.Ar 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 +.Ar elf +did not match the class of the file. +.It Bq Er ELF_E_DATA +An +.Vt Elf_Data +descriptor contained in argument +.Ar 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 +.Ar 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 +.Ar elf +specified an alignment incompatible with its containing section. +.It Bq Er ELF_E_LAYOUT +Argument +.Ar elf +contained section descriptors that overlapped in extent. +.It Bq Er ELF_E_LAYOUT +Argument +.Ar 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 +.Ar 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 +.Ar elf +from its underlying file. +.It Bq Er ELF_E_UNIMPL +Argument +.Ar elf +contained a section with an unsupported ELF type. +.It Bq Er ELF_E_VERSION +Argument +.Ar 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/openbsd/man3/elf_version.3 b/static/openbsd/man3/elf_version.3 new file mode 100644 index 00000000..b7016b06 --- /dev/null +++ b/static/openbsd/man3/elf_version.3 @@ -0,0 +1,94 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd November 9, 2011 +.Dt ELF_VERSION 3 +.Os +.Sh NAME +.Nm elf_version +.Nd retrieve or set ELF library operating version +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar version +is +.Dv EV_NONE , +the +.Fn elf_version +function returns the currently configured operating version for the +ELF library. +.Pp +If the argument +.Ar version +is not +.Dv EV_NONE , +and if argument +.Ar version +is supported by the ELF library, function +.Fn elf_version +sets the library's operating version to +.Ar version , +and returns the previous value of the operating version. +If argument +.Ar 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/openbsd/man3/erf.3 b/static/openbsd/man3/erf.3 new file mode 100644 index 00000000..0817a39f --- /dev/null +++ b/static/openbsd/man3/erf.3 @@ -0,0 +1,105 @@ +'\" e +.\" $OpenBSD: erf.3,v 1.18 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ERFC 3 +.Os +.Sh NAME +.Nm erf , +.Nm erff , +.Nm erfl , +.Nm erfc , +.Nm erfcf , +.Nm erfcl +.Nd error function operators +.Sh SYNOPSIS +.Lb libm +.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 +function calculates the error function of x, and +the +.Fn erff +and +.Fn erfl +functions are single and double precision versions of +.Fn erf . +The error function is defined as: +.Bd -unfilled -offset indent +.EQ +roman erf left ( x right ) = +2 over sqrt pi int from 0 to x e sup {- t sup 2} dt +.EN +.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. +The +.Fn erfcf +and +.Fn erfcl +functions are single and double precision version of +.Fn erfc . +.Sh SEE ALSO +.Xr exp 3 +.Sh HISTORY +The +.Fn erf +and +.Fn erfc +functions first appeared in +.At 32v . diff --git a/static/openbsd/man3/err.3 b/static/openbsd/man3/err.3 new file mode 100644 index 00000000..7d67c4f5 --- /dev/null +++ b/static/openbsd/man3/err.3 @@ -0,0 +1,153 @@ +.\" $OpenBSD: ERR.3,v 1.12 2025/06/08 22:40:29 schwarze Exp $ +.\" OpenSSL 186bb907 Apr 13 11:05:13 2015 -0700 +.\" +.\" This file was written by Ulf Moeller and +.\" Dr. Stephen Henson . +.\" Copyright (c) 2000, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt ERR 3 +.Os +.Sh NAME +.Nm ERR +.Nd OpenSSL error codes +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/err.h +.Sh DESCRIPTION +When a call to the OpenSSL library fails, this is usually signaled by +the return value, and an error code is stored in an error queue +associated with the current thread. +The +.Nm +library provides functions to obtain these error codes and textual error +messages. +The +.Xr ERR_get_error 3 +manpage describes how to access error codes. +.Pp +Error codes contain information about where the error occurred, and what +went wrong. +.Xr ERR_GET_LIB 3 +describes how to extract this information. +A method to obtain human-readable error messages is described in +.Xr ERR_error_string 3 . +.Pp +.Xr ERR_clear_error 3 +can be used to clear the error queue. +.Pp +Note that +.Xr ERR_remove_state 3 +should be used to avoid memory leaks when threads are terminated. +.Sh ADDING NEW ERROR CODES TO OPENSSL +See +.Xr ERR_put_error 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. +.Pp +When you are using new function or reason codes, run +.Sy make errors . +The necessary +.Sy #define Ns s +will then automatically be added to the sub-library's header file. +.Ss Adding new libraries +When adding a new sub-library to OpenSSL, assign it a library number +.Dv ERR_LIB_XXX , +define a macro +.Fn XXXerr +(both in +.In openssl/err.h ) , +add its name to +.Va ERR_str_libraries[] +(in +.Pa /usr/src/lib/libcrypto/err/err.c ) , +and add +.Fn ERR_load_XXX_strings +to the +.Fn ERR_load_crypto_strings +function (in +.Sy /usr/src/lib/libcrypto/err/err_all.c ) . +Finally, add +.Pa xxx_err.c +to the +.Pa Makefile . +.Sh USING ERROR CODES IN EXTERNAL LIBRARIES +It is also possible to use OpenSSL's error code scheme in external +libraries. +.Sh INTERNALS +The error queues are stored in a hash table with one +.Vt ERR_STATE +entry for each PID. +.Fn ERR_get_state +returns the current thread's +.Vt ERR_STATE . +An +.Vt ERR_STATE +can hold up to +.Dv ERR_NUM_ERRORS +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 a hash table. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr ERR_asprintf_error_data 3 , +.Xr ERR_clear_error 3 , +.Xr ERR_error_string 3 , +.Xr ERR_get_error 3 , +.Xr ERR_GET_LIB 3 , +.Xr ERR_load_crypto_strings 3 , +.Xr ERR_load_strings 3 , +.Xr ERR_print_errors 3 , +.Xr ERR_put_error 3 , +.Xr ERR_remove_state 3 , +.Xr ERR_set_mark 3 , +.Xr SSL_get_error 3 diff --git a/static/openbsd/man3/es256_pk_new.3 b/static/openbsd/man3/es256_pk_new.3 new file mode 100644 index 00000000..d1e57d09 --- /dev/null +++ b/static/openbsd/man3/es256_pk_new.3 @@ -0,0 +1,141 @@ +.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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 fido_assert_verify 3 , +.Xr fido_cred_pubkey_ptr 3 , +.Xr rs256_pk_new 3 diff --git a/static/openbsd/man3/ether_aton.3 b/static/openbsd/man3/ether_aton.3 new file mode 100644 index 00000000..83fe9888 --- /dev/null +++ b/static/openbsd/man3/ether_aton.3 @@ -0,0 +1,114 @@ +.\" $OpenBSD: ether_aton.3,v 1.4 2025/06/29 00:33:46 dlg Exp $ +.\" +.\" Written by roland@frob.com. Public domain. +.\" +.Dd $Mdocdate: June 29 2025 $ +.Dt ETHER_ATON 3 +.Os +.Sh NAME +.Nm ether_aton , +.Nm ether_ntoa , +.Nm ether_ntohost , +.Nm ether_hostton , +.Nm ether_line +.Nd get ethers entry +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/if.h +.In netinet/in.h +.In netinet/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" "struct ether_addr *e" +.Ft int +.Fn ether_hostton "const char *hostname" "struct ether_addr *e" +.Ft int +.Fn ether_line "const char *l" "struct ether_addr *e" "char *hostname" +.Sh DESCRIPTION +Ethernet addresses are represented by the +following structure: +.Bd -literal -offset indent +struct ether_addr { + u_int8_t ether_addr_octet[ETHER_ADDR_LEN]; +}; +.Ed +.Pp +The +.Fn ether_ntoa +function converts this structure into an +.Tn ASCII +string of the form +.Dq 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 +function converts an +.Tn 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. +.Fn ether_aton +will return NULL if the string does not represent a valid address. +.Pp +The +.Fn ether_ntohost +and +.Fn ether_hostton +functions interrogate the database 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. +This buffer should be +.Dv MAXHOSTNAMELEN +characters in size. +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. +.Pp +Each call reads +.Pa /etc/ethers +from the beginning. +.Pp +The +.Fn ether_line +function parses a line from the +.Pa /etc/ethers +file and fills in the passed +.Vt 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. +The character buffer should be +.Dv MAXHOSTNAMELEN +characters in size. +.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 0.9b . +.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/openbsd/man3/evbuffer_new.3 b/static/openbsd/man3/evbuffer_new.3 new file mode 100644 index 00000000..40f92e5f --- /dev/null +++ b/static/openbsd/man3/evbuffer_new.3 @@ -0,0 +1,280 @@ +.\" $OpenBSD: evbuffer_new.3,v 1.16 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" +.\" 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: June 13 2025 $ +.Dt EVBUFFER_NEW 3 +.Os +.Sh NAME +.Nm evbuffer_new , +.Nm evbuffer_free , +.Nm evbuffer_setcb , +.Nm evbuffer_expand , +.Nm evbuffer_add , +.Nm evbuffer_add_buffer , +.Nm evbuffer_add_printf , +.Nm evbuffer_add_vprintf , +.Nm evbuffer_drain , +.Nm evbuffer_remove , +.Nm evbuffer_write , +.Nm evbuffer_read , +.Nm evbuffer_find , +.Nm evbuffer_readline , +.Nm evbuffer_readln , +.Nm EVBUFFER_LENGTH , +.Nm EVBUFFER_DATA +.Nd libevent utility API for buffered input/output +.Sh SYNOPSIS +.Lb libevent +.In event.h +.Ft struct evbuffer * +.Fn "evbuffer_new" "void" +.Ft void +.Fn "evbuffer_free" "struct evbuffer *buf" +.Ft void +.Fo evbuffer_setcb +.Fa "struct evbuffer *buf" +.Fa "void (*cb)(struct evbuffer *, size_t, size_t, void *)" +.Fa "void *cbarg" +.Fc +.Ft int +.Fn "evbuffer_expand" "struct evbuffer *buf" "size_t datlen" +.Ft int +.Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size" +.Ft int +.Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src" +.Ft int +.Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..." +.Ft int +.Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap" +.Ft void +.Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size" +.Ft int +.Fn "evbuffer_remove" "struct evbuffer *buf" "void *data" "size_t datlen" +.Ft int +.Fn "evbuffer_write" "struct evbuffer *buf" "int fd" +.Ft int +.Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size" +.Ft u_char * +.Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size" +.Ft char * +.Fn "evbuffer_readline" "struct evbuffer *buf" +.Ft char * +.Fo evbuffer_readln +.Fa "struct evbuffer *buf" +.Fa "size_t *read_out" +.Fa "enum evbuffer_eol_style eol_style" +.Fc +.Ft size_t +.Fn "EVBUFFER_LENGTH" "const struct evbuffer *buf" +.Ft u_char * +.Fn "EVBUFFER_DATA" "const struct evbuffer *buf" +.Sh DESCRIPTION +The evbuffer API provides an implementation of buffering for use with +libevent. +.Pp +.Fn evbuffer_new +allocates and initialises a new evbuffer structure. +.Pp +.Fn evbuffer_free +deallocates the evbuffer structure +.Fa buf +and any referenced storage. +.Pp +.Fn evbuffer_setcb +sets the callback +.Fa cb +to be invoked with argument +.Fa cbarg +when the data in evbuffer +.Fa buf +is modified. +.Pp +.Fn evbuffer_expand +expands the available space in +.Fa buf +to at least +.Fa datlen +bytes. +.Pp +.Fn evbuffer_add +appends a copy of +.Fa size +bytes from buffer +.Fa data +to the end of the evbuffer +.Fa buf . +.Pp +.Fn evbuffer_add_buffer +moves the data off the +.Fa src +evbuffer and appends it to +.Fa dst . +.Pp +.Fn evbuffer_add_printf +appends a +.Xr printf 3 +style formatted string specified by +.Fa fmt +to the end of +.Fa buf . +.Pp +.Fn evbuffer_add_vprintf +appends a +.Xr vprintf 3 +style formatted string specified by +.Fa fmt +with a va_list +.Fa ap +to the end of +.Fa buf . +.Pp +.Fn evbuffer_drain +deletes +.Fa size +bytes from the beginning of the evbuffer +.Fa buf . +.Pp +.Fn evbuffer_remove +reads and drains up to +.Fa datlen +bytes from the beginning of the evbuffer +.Fa buf +into +.Fa data . +.Pp +.Fn evbuffer_write +writes and drains the contents of evbuffer +.Fa buf +to the file descriptor +.Fa fd . +.Pp +.Fn evbuffer_read +appends up to +.Fa size +bytes on to the end of the evbuffer +.Fa buf +by reading from the file descriptor +.Fa fd . +.Pp +.Fn evbuffer_find +finds the +.Fa size +length string +.Fa data +in the evbuffer +.Fa buf . +.Pp +.Fn evbuffer_readline +reads and drains a single line from the evbuffer +.Fa buf . +A line is delimited by "\en", "\er", "\er\en", or "\en\er". +It is the responsibility of the caller to free the returned line with +.Xr free 3 . +.Pp +.Fn evbuffer_readln +reads and drains a single line from the evbuffer +.Fa buf . +The length of the line will be stored in +.Fa read_out +on success. +It is the responsibility of the caller to free the returned line with +.Xr free 3 . +The line delimiter is specified as one of the following: +.Bl -tag -width xxx -offset indent +.It Dv EVBUFFER_EOL_ANY +Any sequence of newline or carriage return characters. +.It Dv EVBUFFER_EOL_CRLF +A new line optionally preceded by a carriage return. +.It Dv EVBUFFER_EOL_CRLF_STRICT +A carriage return followed by a new line character. +.It Dv EVBUFFER_EOL_LF +A new line character. +.El +.Pp +.Fn EVBUFFER_LENGTH +reports how many bytes are stored in the evbuffer +.Fa buf . +.Sh RETURN VALUES +.Fn evbuffer_new +returns a pointer to a newly allocated buffer on success, +or +.Dv NULL +on failure and sets +.Va errno +to indicate the failure. +.Pp +.Fn evbuffer_expand , +.Fn evbuffer_add , +and +.Fn evbuffer_add_buffer +return 0 on success, +or -1 on failure and set +.Va errno +to indicate the failure. +.Pp +.Fn evbuffer_add_printf +and +.Fn evbuffer_add_vprintf +return the number of bytes added on success, +or -1 on failure. +.Pp +.Fn evbuffer_remove +returns the number of bytes read. +.Pp +.Fn evbuffer_write +returns the number of bytes written and drained on success, +or -1 on failure and sets +.Va errno +to indicate the failure. +.Pp +.Fn evbuffer_read +returns the number of bytes appended to the evbuffer on success, +0 on an end of file condition, +or -1 on failure and sets +.Va errno +to indicate the failure. +.Pp +.Fn evbuffer_find +returns a pointer to the start of the string within the evbuffer on success, +or +.Dv NULL +on failure. +.Pp +.Fn evbuffer_readline +and +.Fn evbuffer_readln +return a pointer to the line on success, +or +.Dv NULL +on failure. +.Pp +.Fn EVBUFFER_LENGTH +returns the number of bytes available in the evbuffer. +.Pp +.Fn EVBUFFER_DATA +returns a pointer to the evbuffer +.Fa buf +on success. +.Sh SEE ALSO +.Xr errno 2 , +.Xr event 3 , +.Xr free 3 , +.Xr printf 3 +.Sh AUTHORS +The +.Nm event +library was written by +.An Niels Provos . diff --git a/static/openbsd/man3/event.3 b/static/openbsd/man3/event.3 new file mode 100644 index 00000000..d670c12b --- /dev/null +++ b/static/openbsd/man3/event.3 @@ -0,0 +1,596 @@ +.\" $OpenBSD: event.3,v 1.58 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2000 Artur Grabowski +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. 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 $Mdocdate: June 13 2025 $ +.Dt EVENT_INIT 3 +.Os +.Sh NAME +.Nm event_init , +.Nm event_dispatch , +.Nm event_set , +.Nm event_add , +.Nm event_del , +.Nm event_pending , +.Nm event_initialized , +.Nm evtimer_set , +.Nm evtimer_add , +.Nm evtimer_del , +.Nm evtimer_pending , +.Nm evtimer_initialized , +.Nm signal_set , +.Nm signal_add , +.Nm signal_del , +.Nm signal_pending , +.Nm signal_initialized , +.Nm event_once , +.Nm event_loop , +.Nm event_loopexit , +.Nm event_loopbreak , +.Nm event_asr_run , +.Nm event_asr_abort , +.Nm event_priority_init , +.Nm event_priority_set , +.Nm event_base_dispatch , +.Nm event_base_loop , +.Nm event_base_loopexit , +.Nm event_base_loopbreak , +.Nm event_base_set , +.Nm event_base_once , +.Nm event_base_free , +.Nm bufferevent_base_set , +.Nm bufferevent_new , +.Nm bufferevent_free , +.Nm bufferevent_write , +.Nm bufferevent_write_buffer , +.Nm bufferevent_read , +.Nm bufferevent_enable , +.Nm bufferevent_disable , +.Nm bufferevent_settimeout , +.Nm bufferevent_setwatermark , +.Nm EVBUFFER_INPUT , +.Nm EVBUFFER_OUTPUT +.Nd execute a function when a specific event occurs +.Sh SYNOPSIS +.Lb libevent +.In sys/time.h +.In event.h +.Ft struct event_base * +.Fn "event_init" "void" +.Ft int +.Fn "event_dispatch" "void" +.Ft void +.Fn "event_set" "struct event *ev" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" +.Ft int +.Fn "event_add" "struct event *ev" "const struct timeval *tv" +.Ft int +.Fn "event_del" "struct event *ev" +.Ft int +.Fn "event_pending" "struct event *ev" "short event" "struct timeval *tv" +.Ft int +.Fn "event_initialized" "struct event *ev" +.Ft void +.Fn "evtimer_set" "struct event *ev" "void (*fn)(int, short, void *)" "void *arg" +.Ft void +.Fn "evtimer_add" "struct event *ev" "const struct timeval *tv" +.Ft void +.Fn "evtimer_del" "struct event *ev" +.Ft int +.Fn "evtimer_pending" "struct event *ev" "struct timeval *tv" +.Ft int +.Fn "evtimer_initialized" "struct event *ev" +.Ft void +.Fn "signal_set" "struct event *ev" "int signal" "void (*fn)(int, short, void *)" "void *arg" +.Ft void +.Fn "signal_add" "struct event *ev" "const struct timeval *tv" +.Ft void +.Fn "signal_del" "struct event *ev" +.Ft int +.Fn "signal_pending" "struct event *ev" "struct timeval *tv" +.Ft int +.Fn "signal_initialized" "struct event *ev" +.Ft int +.Fn "event_once" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "const struct timeval *tv" +.Ft int +.Fn "event_loop" "int flags" +.Ft int +.Fn "event_loopexit" "const struct timeval *tv" +.Ft int +.Fn "event_loopbreak" "void" +.Ft struct event_asr * +.Fn event_asr_run "struct asr_query *aq" "void (*fn)(struct asr_result *, void *)" "void *arg" +.Ft void +.Fn event_asr_abort "struct event_asr *eva" +.Ft int +.Fn "event_priority_init" "int npriorities" +.Ft int +.Fn "event_priority_set" "struct event *ev" "int priority" +.Ft int +.Fn "event_base_dispatch" "struct event_base *base" +.Ft int +.Fn "event_base_loop" "struct event_base *base" "int flags" +.Ft int +.Fn "event_base_loopexit" "struct event_base *base" "const struct timeval *tv" +.Ft int +.Fn "event_base_loopbreak" "struct event_base *base" +.Ft int +.Fn "event_base_set" "struct event_base *base" "struct event *ev" +.Ft int +.Fn "event_base_once" "struct event_base *base" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "const struct timeval *tv" +.Ft void +.Fn "event_base_free" "struct event_base *base" +.Ft int +.Fn "bufferevent_base_set" "struct event_base *base" "struct bufferevent *bufev" +.Ft struct bufferevent * +.Fn "bufferevent_new" "int fd" "evbuffercb readcb" "evbuffercb writecb" "everrorcb errorcb" "void *cbarg" +.Ft void +.Fn "bufferevent_free" "struct bufferevent *bufev" +.Ft int +.Fn "bufferevent_write" "struct bufferevent *bufev" "const void *data" "size_t size" +.Ft int +.Fn "bufferevent_write_buffer" "struct bufferevent *bufev" "struct evbuffer *buf" +.Ft size_t +.Fn "bufferevent_read" "struct bufferevent *bufev" "void *data" "size_t size" +.Ft int +.Fn "bufferevent_enable" "struct bufferevent *bufev" "short event" +.Ft int +.Fn "bufferevent_disable" "struct bufferevent *bufev" "short event" +.Ft void +.Fn "bufferevent_settimeout" "struct bufferevent *bufev" "int timeout_read" "int timeout_write" +.Ft void +.Fn "bufferevent_setwatermark" "struct bufferevent *bufev" "short events" "size_t lowmark" "size_t highmark" +.Ft struct evbuffer * +.Fn "EVBUFFER_INPUT" "struct bufferevent *bufev" +.Ft struct evbuffer * +.Fn "EVBUFFER_OUTPUT" "struct bufferevent *bufev" +.Sh DESCRIPTION +The +.Nm event +API provides a mechanism to execute a function when a specific event +on a file descriptor occurs or after a given time has passed. +.Pp +The +.Nm event +API needs to be initialized with +.Fn event_init +before it can be used. +.Pp +In order to process events, an application needs to call +.Fn event_dispatch . +This function only returns on error, and should replace the event core +of the application program. +.Pp +The function +.Fn event_set +prepares the event structure +.Fa ev +to be used in future calls to +.Fn event_add +and +.Fn event_del . +The event will be prepared to call the function specified by the +.Fa fn +argument with an +.Fa int +argument indicating the file descriptor, a +.Fa short +argument indicating the type of event, and a +.Fa void * +argument given in the +.Fa arg +argument. +The +.Fa fd +indicates the file descriptor that should be monitored for events. +The events can be either +.Va EV_READ , +.Va EV_WRITE , +or both, +indicating that an application can read or write from the file descriptor +respectively without blocking. +.Pp +The function +.Fa fn +will be called with the file descriptor that triggered the event and +the type of event which will be either +.Va EV_TIMEOUT , +.Va EV_SIGNAL , +.Va EV_READ , +or +.Va EV_WRITE . +Additionally, an event which has registered interest in more than one of the +preceding events, via bitwise-OR to +.Fn event_set , +can provide its callback function with a bitwise-OR of more than one triggered +event. +The additional flag +.Va EV_PERSIST +makes an +.Fn event_add +persistent until +.Fn event_del +has been called. +.Pp +Once initialized, the +.Fa ev +structure can be used repeatedly with +.Fn event_add +and +.Fn event_del +and does not need to be reinitialized unless the function called and/or +the argument to it are to be changed. +However, when an +.Fa ev +structure has been added to libevent using +.Fn event_add +the structure must persist until the event occurs (assuming +.Fa EV_PERSIST +is not set) or is removed +using +.Fn event_del . +You may not reuse the same +.Fa ev +structure for multiple monitored descriptors; each descriptor +needs its own +.Fa ev . +.Pp +The function +.Fn event_add +schedules the execution of the +.Fa ev +event when the event specified in +.Fn event_set +occurs or in at least the time specified in the +.Fa tv . +If +.Fa tv +is +.Dv NULL , +no timeout occurs and the function will only be called +if a matching event occurs on the file descriptor. +The event in the +.Fa ev +argument must be already initialized by +.Fn event_set +and may not be used in calls to +.Fn event_set +until it has timed out or been removed with +.Fn event_del . +If the event in the +.Fa ev +argument already has a scheduled timeout, the old timeout will be +replaced by the new one. +.Pp +The function +.Fn event_del +will cancel the event in the argument +.Fa ev . +If the event has already executed or has never been added, +the call will have no effect. +.Pp +The functions +.Fn evtimer_set , +.Fn evtimer_add , +.Fn evtimer_del , +.Fn evtimer_initialized , +and +.Fn evtimer_pending +are abbreviations for common situations where only a timeout is required. +The file descriptor passed will be \-1, and the event type will be +.Va EV_TIMEOUT . +.Pp +The functions +.Fn signal_set , +.Fn signal_add , +.Fn signal_del , +.Fn signal_initialized , +and +.Fn signal_pending +are abbreviations. +The event type will be a persistent +.Va EV_SIGNAL . +That means +.Fn signal_set +adds +.Va EV_PERSIST . +.Pp +The function +.Fn event_once +is similar to +.Fn event_set . +However, it schedules a callback to be called exactly once and does not +require the caller to prepare an +.Fa event +structure. +This function supports +.Fa EV_TIMEOUT , +.Fa EV_READ , +and +.Fa EV_WRITE . +.Pp +The +.Fn event_pending +function can be used to check if the event specified by +.Fa event +is pending to run. +If +.Va EV_TIMEOUT +was specified and +.Fa tv +is not +.Dv NULL , +the expiration time of the event will be returned in +.Fa tv . +.Pp +The +.Fn event_initialized +macro can be used to check if an event has been initialized. +.Pp +The +.Nm event_loop +function provides an interface for single pass execution of pending +events. +The flags +.Va EVLOOP_ONCE +and +.Va EVLOOP_NONBLOCK +are recognized. +The +.Nm event_loopexit +function exits from the event loop. +The next +.Fn event_loop +iteration after the +given timer expires will complete normally (handling all queued events) then +exit without blocking for events again. +Subsequent invocations of +.Fn event_loop +will proceed normally. +The +.Nm event_loopbreak +function exits from the event loop immediately. +.Fn event_loop +will abort after the next event is completed; +.Fn event_loopbreak +is typically invoked from this event's callback. +This behavior is analogous to the "break;" statement. +Subsequent invocations of +.Fn event_loop +will proceed normally. +.Pp +It is the responsibility of the caller to provide these functions with +pre-allocated event structures. +.Pp +The +.Fn event_asr_run +function is used to schedule the asynchronous resolver query +.Ar aq +to run within a libevent event loop, and call the +.Ar fn +callback when the result is available. +The extra +.Ar arg +parameter is passed to the callback. +The user does not need to set up an event structure for using this function. +It returns an opaque handle representing the running query. +This handle becomes invalid before the callback is run. +It can be cancelled by calling the +.Fn event_asr_abort +function. +See +.Xr asr_run 3 +for details on constructing asynchronous resolver queries. +.Sh EVENT PRIORITIES +By default +.Nm libevent +schedules all active events with the same priority. +However, sometimes it is desirable to process some events with a higher +priority than others. +For that reason, +.Nm 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 +.Fn event_priority_init +function. +This function should be called before the first call to +.Fn event_dispatch . +The +.Fn event_priority_set +function can be used to assign a priority to an event. +By default, +.Nm libevent +assigns the middle priority to all events unless their priority +is explicitly set. +.Sh THREAD SAFE EVENTS +The +.Nm event +API has experimental support for thread-safe events. +When initializing the library via +.Fn event_init , +an event base is returned. +This event base can be used in conjunction with calls to +.Fn event_base_set , +.Fn event_base_dispatch , +.Fn event_base_loop , +.Fn event_base_loopexit , +.Fn bufferevent_base_set +and +.Fn event_base_free . +.Fn event_base_set +should be called after preparing an event with +.Fn event_set , +as +.Fn event_set +assigns the provided event to the most recently created event base. +.Fn bufferevent_base_set +should be called after preparing a bufferevent with +.Fn bufferevent_new . +.Fn event_base_free +should be used to free memory associated with the event base +when it is no longer needed. +.Sh BUFFERED EVENTS +The +.Nm event +API provides an abstraction on top of the regular event callbacks. +This abstraction is called a +.Va "buffered event" . +A buffered event provides input and output buffers that get filled +and drained automatically. +The user of a buffered event no longer deals directly with the IO, +but instead is reading from input and writing to output buffers. +.Pp +A new bufferevent is created by +.Fn bufferevent_new . +The parameter +.Fa fd +specifies the file descriptor from which data is read and written to. +This file descriptor is not allowed to be a +.Xr pipe 2 . +The next three parameters are callbacks. +The read and write callback have the following form: +.Ft void +.Fn "(*cb)" "struct bufferevent *bufev" "void *arg" . +The error callback has the following form: +.Ft void +.Fn "(*cb)" "struct bufferevent *bufev" "short what" "void *arg" . +The argument is specified by the fourth parameter +.Fa "cbarg" . +A +.Fa bufferevent struct +pointer is returned on success, NULL on error. +Both the read and the write callback may be NULL. +The error callback has to be always provided. +.Pp +Once initialized, the bufferevent structure can be used repeatedly with +.Fn bufferevent_enable +and +.Fn bufferevent_disable . +The flags parameter can be a combination of +.Va EV_READ +and +.Va EV_WRITE . +When read enabled, the bufferevent will try to read from the file +descriptor and call the read callback. +The write callback is executed +whenever the output buffer is drained below the write low watermark, +which is +.Va 0 +by default. +.Pp +The +.Fn bufferevent_setwatermark +function can set the low and high watermarks +for read and write events. +The +.Fa events +can be either +.Va EV_READ , +.Va EV_WRITE +or both. +When used with +.Va EV_READ , +a bufferevent does not invoke the user read callback +unless there is at least +.Fa lowmark +data in the buffer. +If the read buffer is beyond +.Fa highmark , +the bufferevent stops reading from the file descriptor. +When used with +.Va EV_WRITE , +the user write callback is invoked whenever the buffered data +falls below +.Fa lowmark . +.Pp +The +.Fn bufferevent_write +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. +.Fn bufferevent_write +returns 0 on success or \-1 on failure. +The +.Fn bufferevent_read +function is used to read data from the input buffer, +returning the amount of data read. +.Pp +If multiple bases are in use, +.Fn bufferevent_base_set +must be called before +enabling the bufferevent for the first time. +.Pp +The +.Fn EVBUFFER_INPUT +and +.Fn EVBUFFER_OUTPUT +macros return a pointer to evbuffer +.Fa input +and +.Fa output +respectively for the specified bufferevent +.Fa bufev . +.Sh ADDITIONAL NOTES +It is possible to disable support for +.Va kqueue , poll +or +.Va select +by setting the environment variable +.Va EVENT_NOKQUEUE , EVENT_NOPOLL +or +.Va EVENT_NOSELECT , +respectively. +By setting the environment variable +.Va EVENT_SHOW_METHOD , +.Nm libevent +displays the kernel notification method that it uses. +.Sh RETURN VALUES +Upon successful completion +.Fn event_add +and +.Fn event_del +return 0. +Otherwise, \-1 is returned and the global variable errno is +set to indicate the error. +.Sh SEE ALSO +.Xr kqueue 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr asr_run 3 , +.Xr evbuffer_new 3 , +.Xr timeout 9 +.Sh HISTORY +The +.Nm event +API manpage is based on the +.Xr timeout 9 +manpage by Artur Grabowski. +Support for real-time signals was added by Taral. +.Sh AUTHORS +The +.Nm event +library was written by +.An Niels Provos . diff --git a/static/openbsd/man3/event_base_loop.3 b/static/openbsd/man3/event_base_loop.3 new file mode 100644 index 00000000..26c35604 --- /dev/null +++ b/static/openbsd/man3/event_base_loop.3 @@ -0,0 +1,192 @@ +.\" $OpenBSD: event_base_loop.3,v 1.6 2025/06/07 20:50:40 schwarze Exp $ +.\" Copyright (c) 2023 Ted Bullock +.\" +.\" 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: June 7 2025 $ +.Dt EVENT_BASE_LOOP 3 +.Os +.Sh NAME +.Nm event_base_loop , +.Nm event_loop , +.Nm event_base_dispatch , +.Nm event_dispatch +.Nd run an event loop +.Sh SYNOPSIS +.Lb libevent +.In event.h +.Ft int +.Fn event_base_loop "struct event_base *base" "int flags" +.Ft int +.Fn event_loop "int flags" +.Ft int +.Fn event_base_dispatch "struct event_base *base" +.Ft int +.Fn event_dispatch void +.Sh DESCRIPTION +An event loop waits for events +and invokes an associated callback function whenever one occurs. +This enables asynchronous programming, allowing a program to perform other +tasks while waiting for an event to occur. +Asynchronous programming is a useful idiom for handling multiple I/O +operations, such as network connections, user interfaces, or disk operations +without blocking the main loop of a program. +.Pp +The +.Fn event_base_loop +family of functions run an event loop. +By default, they return when there are no more scheduled events. +.Pp +There are three types of events these functions monitor: +signal, kernel, and timer events. +Events involving POSIX signals are configured with +.Xr signal_set 3 . +Kernel events such as network activity and changes to file descriptors are +configured with +.Xr event_set 3 . +Timer events are configured with +.Xr evtimer_set 3 . +.Pp +The event library categorizes event states as: +.Bl -tag -width initialized +.It Em initialized +These have been configured with +.Xr event_set 3 +and not yet registered with an event loop. +.It Em scheduled +These are registered to a loop using +.Xr event_add 3 +and are idle, waiting to trigger and be processed by the loop. +They can be queried with +.Fn event_pending 3 . +.It Em activated +These are triggered events. +The loop processes events until all activated events are resolved. +Some of these, such as signals, may persist and become scheduled again. +.El +.Pp +The arguments are as follows: +.Bl -tag -width flags +.It Fa base +A pointer to an +.Vt event_base +structure returned from +.Xr event_base_new 3 +or +.Xr event_init 3 . +.It Fa flags +Zero or more of the following flags OR'ed together: +.Bl -tag -width EVLOOP_NONBLOCK +.It Dv EVLOOP_ONCE +Run the event loop for one iteration and then return. +This is useful for a main program that needs to perform actions outside +the event loop. +.It Dv EVLOOP_NONBLOCK +Run the event loop in non-blocking mode. +The loop returns after processing activated signal and kernel events and does +not wait for timer events to expire. +.El +.El +.Pp +The function +.Fn event_loop +is a version of +.Fn event_base_loop +that requires the library to be initialized by +.Xr event_init 3 . +.Pp +.Fn event_base_dispatch +is equivalent to calling +.Fn event_base_loop +with +.Fa flags +set to zero. +Likewise, +.Fn event_dispatch +is the same as invoking +.Fn event_loop +with +.Fa flags +set to zero. +.Sh RETURN VALUES +The event loop functions return: +.Pp +.Bl -tag -compact -offset 3n -width 3n +.It \-1 +on error, +.Va errno +is set. +.It 0 +on success, asked to terminate loop. +.It 1 +on success, no scheduled events remain. +.El +.Sh ERRORS +These functions have complex interactions with +.Va errno . +Error conditions that set +.Va errno +change corresponding to the kernel notification method the +.Fa base +structure is using. +These values directly correspond to +.Xr kevent 2 , +.Xr poll 2 +or +.Xr select 2 +system calls and default to +.Xr kevent 2 +on +.Ox . +Refer to +.Xr event_base_new 3 +for details on kernel notification methods. +.Bl -tag -width Er +.It Bq Er EINTR +Although the kernel notification methods can set +.Va errno +to +.Er EINTR , +.Fn event_base_loop +and related functions never fail with +.Va errno +set to +.Er EINTR . +.El +.Sh SEE ALSO +.Xr kevent 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr event_base_new 3 , +.Xr event_set 3 +.Sh HISTORY +.Fn event_dispatch +first appeared in libevent-0.1 and has been available since +.Ox 3.2 . +.Pp +.Fn event_loop +first appeared in libevent-0.4 and has been available since +.Ox 3.2 . +.Pp +.Fn event_base_dispatch +and +.Fn event_base_loop +first appeared in libevent-1.0 and have been available since +.Ox 3.8 . +.Sh AUTHORS +The event library and these functions were written by +.An -nosplit +.An Niels Provos . +.Pp +This manual page was written by +.An Ted Bullock Aq Mt tbullock@comlore.com . diff --git a/static/openbsd/man3/event_base_new.3 b/static/openbsd/man3/event_base_new.3 new file mode 100644 index 00000000..52ea70d9 --- /dev/null +++ b/static/openbsd/man3/event_base_new.3 @@ -0,0 +1,322 @@ +.\" $OpenBSD: event_base_new.3,v 1.7 2025/06/07 20:50:40 schwarze Exp $ +.\" Copyright (c) 2023 Ted Bullock +.\" +.\" 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: June 7 2025 $ +.Dt EVENT_BASE_NEW 3 +.Os +.Sh NAME +.Nm event_base_new , +.Nm event_init , +.Nm event_reinit , +.Nm event_base_free +.Nd event_base structure initialization +.Sh SYNOPSIS +.Lb libevent +.In event.h +.Ft "struct event_base *" +.Fn event_base_new void +.Ft "struct event_base *" +.Fn event_init void +.Ft int +.Fn event_reinit "struct event_base *base" +.Ft void +.Fn event_base_free "struct event_base *base" +.Sh DESCRIPTION +The functions +.Fn event_base_new +and +.Fn event_init +allocate and initialize an opaque +.Vt event_base +structure. +This structure is used to schedule and monitor events using the operating +system's most efficient or stable kernel notification method. +.Pp +Kernel notification methods are ways for a program to be notified of +events that occur in the operating system's kernel. +Examples of such events include changes to file descriptors, file I/O +operations or network activity. +The library chooses from several methods to notify programs about events. +Each method is implemented using a system call, including +.Xr kqueue 2 , +.Xr poll 2 , +or +.Xr select 2 . +By default, +.Ox +uses the +.Xr kqueue 2 +method. +.Pp +The function +.Fn event_init +behaves like +.Fn event_base_new , +except it additionally saves a pointer to the returned structure +in an internal global variable. +It is designed for programs that need only one single event loop. +.Pp +If +.Fn event_init +was not invoked before using an event API function that requires it, +or if such a function is called after +.Fn event_base_free +has destroyed the structure that was returned from +.Fn event_init , +a +.Dv NULL +pointer access occurs unless otherwise documented. +.Pp +After calling +.Xr fork 2 , +invoke +.Fn event_reinit +in the child process for each initialized +.Vt event_base +structure to reset the event queues and any registered events. +.Pp +The +.Fn event_base_free +function releases all resources associated with the +.Fa base +structure returned by an earlier call to +.Fn event_base_new +or +.Fn event_init . +It is intended to be called after the event loop has been stopped. +.Pp +If +.Fn event_init +has been used and +.Fn event_base_free +is called with the +.Fa base +structure returned from +.Fn event_init +or with a +.Dv NULL +pointer argument, the structure that was returned from +.Fn event_init +is freed as usual, and the pointer to it is also deleted +from the internal global variable. +If +.Fn event_init +was not used, calling +.Fn event_base_free +with a +.Dv NULL +pointer argument triggers an +.Xr assert 3 +call. +.Sh RETURN VALUES +.Fn event_base_new +and +.Fn event_init +return the newly allocated +.Vt event_base +structure. +If no kernel notification method can be initialized, both functions call +.Xr exit 3 +with a status of 1 and do not return. +.Pp +On success, +.Fn event_reinit +returns 0. +If one or more events fail to reinitialize, the function returns -1. +.Pp +If the +.Xr poll 2 +or +.Xr select 2 +kernel notification method is used but +.Xr socketpair 2 +fails, all three functions do not return but +.Xr exit 3 +the program with a status of 1. +This may also happen in some cases of +.Xr malloc 3 +failure. +.Sh ENVIRONMENT +Environment variables can modify the behavior of +.Fn event_base_new +and +.Fn event_init +to disable individual kernel notification methods for the returned +.Vt event_base +structure and to enable additional diagnostic reporting: +.Bl -tag -width Ds +.It Ev EVENT_NOKQUEUE +Disable support for +.Xr kqueue 2 . +.It Ev EVENT_NOPOLL +Disable support for +.Xr poll 2 . +.It Ev EVENT_NOSELECT +Disable support for +.Xr select 2 . +.It Ev EVENT_SHOW_METHOD +If the log callback is configured, +report which kernel notification method the returned +.Vt event_base +structure is using. +.El +.Pp +These environment variables are ignored if +.Xr issetugid 2 +reports that the program was executed as setuid or setgid. +The values of the environment variables are always ignored, even if they are +empty or zero. +.Sh DIAGNOSTICS +Many event library functions report error and diagnostic messages via +the log callback system that can optionally be enabled with +.Xr event_set_log_callback 3 . +.Pp +The following error messages can occur: +.Bl -tag -width Ds +.It Dq evsignal_init: socketpair: Em reason +While trying to initialize the +.Xr poll 2 +or +.Xr select 2 +kernel notification method in +.Fn event_base_new +or +.Fn event_init , +.Xr socketpair 2 +failed for the given +.Em reason . +.It Dq event_base_new: no event mechanism available +Each kernel notification method is either disabled via the +.Sx ENVIRONMENT , +or trying to initialize it failed. +Some memory allocation failures may also cause this error. +.It Dq event_base_reinit: could not reinitialize event mechanism +Failed to reinitialize the kernel notification method. +.El +.Pp +In addition, all three functions may issue various error messages +indicating memory allocation failure, but not all such failures are +reported in this manner. +.Pp +The following diagnostic messages can occur: +.Bl -tag -width Ds +.It Dq libevent using: Em method +The environment variable +.Ev EVENT_SHOW_METHOD +is defined and the event library is using the given kernel notification +.Em method , +which is either +.Qq kqueue , +.Qq poll , +or +.Qq select . +.It Dq kqueue: Em reason +Calling +.Xr kqueue 2 +failed in +.Fn event_base_new +or +.Fn event_init +for the given +.Em reason . +Other kernel notification methods are automatically tried. +.El +.Sh ERRORS +Even when they fail, most event library functions do not explicitly set +.Xr errno 2 . +Exceptions are mentioned in individual manual pages. +.Pp +However, many event library functions call C library functions +or system calls internally that do set +.Xr errno 2 +when they fail. +Consequently, many event library functions set +.Xr errno 2 +in some cases of failure but not in others. +.Pp +The functions +.Fn event_base_new , +.Fn event_init , +and +.Fn event_reinit +may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr kqueue 2 +and +.Xr malloc 3 . +.Pp +The same three functions may overwrite +.Xr errno 2 +even if successful, for example when one kernel notification method +fails to initialize and another succeeds, or when a disregarded +memory allocation failure occurs. +.Sh SEE ALSO +.Xr fork 2 , +.Xr kqueue 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr event_base_loop 3 , +.Xr event_set_log_callback 3 +.Sh HISTORY +The +.Ox +event library is a modified version of libevent-1.4. +.Pp +The function +.Fn event_init +first appeared in libevent-0.1 and has been available since +.Ox 3.2 . +.Pp +.Fn event_base_free +first appeared in libevent-1.2 and has been available since +.Ox 4.0 . +.Pp +.Fn event_base_new +and +.Fn event_reinit +first appeared in libevent-1.4.1 and have been available since +.Ox 4.8 . +.Pp +Support for +.Dv EVENT_NOKQUEUE +first appeared in libevent-0.4 and has been available since +.Ox 3.2 . +Support for the other environment variables first appeared in libevent-0.7a. +.Dv EVENT_NOSELECT +and +.Dv EVENT_SHOW_METHOD +have been available since +.Ox 3.4 +and +.Dv EVENT_NOPOLL +since +.Ox 3.5 . +.Sh AUTHORS +The event library and these functions were written by +.An -nosplit +.An Niels Provos . +.Pp +This manual page was written by +.An Ted Bullock Aq Mt tbullock@comlore.com . +.Sh CAVEATS +The event API is not thread safe if any +.Vt "event_base" +structure, no matter whether created using +.Fn event_base_new +or +.Fn event_init , +is accessed by more than one thread, +unless the application program implements its own locking mechanism. diff --git a/static/openbsd/man3/event_set.3 b/static/openbsd/man3/event_set.3 new file mode 100644 index 00000000..f16c9bd5 --- /dev/null +++ b/static/openbsd/man3/event_set.3 @@ -0,0 +1,419 @@ +.\" $OpenBSD: event_set.3,v 1.5 2025/06/07 20:50:40 schwarze Exp $ +.\" Copyright (c) 2023 Ted Bullock +.\" +.\" 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: June 7 2025 $ +.Dt EVENT_SET 3 +.Os +.Sh NAME +.Nm event_set , +.Nm evtimer_set , +.Nm signal_set , +.Nm event_base_set , +.Nm event_add , +.Nm evtimer_add , +.Nm signal_add , +.Nm event_del , +.Nm evtimer_del , +.Nm signal_del , +.Nm event_base_once , +.Nm event_once +.Nd configure an event +.Sh SYNOPSIS +.Lb libevent +.In event.h +.Ft void +.Fo event_set +.Fa "struct event *event" +.Fa "int fd" +.Fa "short flags" +.Fa "void (*callback)(int, short, void *)" +.Fa "void *arg" +.Fc +.Ft void +.Fo evtimer_set +.Fa "struct event *event" +.Fa "void (*callback)(int, short, void *)" +.Fa "void *arg" +.Fc +.Ft void +.Fo signal_set +.Fa "struct event *event" +.Fa "int signal" +.Fa "void (*callback)(int, short, void *)" +.Fa "void *arg" +.Fc +.Ft int +.Fn event_base_set "struct event_base *base" "struct event *event" +.Ft int +.Fn event_add "struct event *event" "const struct timeval *tv" +.Ft int +.Fn evtimer_add "struct event *event" "const struct timeval *tv" +.Ft int +.Fn signal_add "struct event *event" "const struct timeval *tv" +.Ft int +.Fn event_del "struct event *event" +.Ft int +.Fn evtimer_del "struct event *event" +.Ft int +.Fn signal_del "struct event *event" +.Ft int +.Fo event_base_once +.Fa "struct event_base *base" +.Fa "int fd" +.Fa "short flags" +.Fa "void (*callback)(int, short, void *)" +.Fa "void *arg" +.Fa "const struct timeval *tv" +.Fc +.Ft int +.Fo event_once +.Fa "int fd" +.Fa "short flags" +.Fa "void (*callback)(int, short, void *)" +.Fa "void *arg" +.Fa "const struct timeval *tv" +.Fc +.Sh DESCRIPTION +The +.Fn event_set +function initializes an uninitialized, unused, +.Fa event +structure to monitor a file descriptor, signal, or timeout. +Once initialized, the event can be scheduled using +.Fn event_add . +The event becomes activated and the +.Fa callback +is triggered when the file descriptor state changes, the signal arrives, +or the timeout expires. +Refer to +.Xr event_base_loop 3 +for documentation on running an event loop. +.Pp +Arguments for +.Fn event_set +are as follows: +.Bl -tag -width Ds +.It Fa event +The event structure to initialize. +If +.Fa event +is +.Dv NULL +the behavior is undefined. +.It Fa fd +The file descriptor or signal to monitor. +Unassociated timeout events require this set to \-1. +.It Fa flags +Flags indicating how to monitor events. +Unassociated timeout events require this set to 0. +.Bl -tag -width EV_PERSIST +.It Dv EV_READ +Triggered when data is available for reading from the file descriptor. +.It Dv EV_WRITE +Triggered when the file descriptor is ready for writing. +Can be combined with +.Dv EV_READ +to indicate that the program can read from or write to the file descriptor +without blocking. +.It Dv EV_SIGNAL +Refers to a signal event that is triggered when a specified signal is +received. +Cannot be used together with either +.Dv EV_READ +or +.Dv EV_WRITE . +.It Dv EV_PERSIST +Indicates that the event should persist after it triggers. +That is, it should remain active until it is removed by calling +.Fn event_del . +Signal events typically require this flag. +.El +.It Fa callback +A user-defined function that is executed when the event triggers. +.Pp +.Bl -enum -width Ds -compact +.It +The first parameter is the file descriptor or signal to monitor. +.It +The second parameter is an event flag composed of at least one of +.Dv EV_TIMEOUT , +.Dv EV_READ , +.Dv EV_WRITE , +.Dv EV_SIGNAL +and +.Dv EV_PERSIST +combined with a binary OR operation. +.It +The third parameter corresponds to a user-specified pointer passed as a +.Vt void * . +.El +.It Fa arg +User-specified pointer to pass to the +.Fa callback +function. +.El +.Pp +There are several helper macros that make it easier to set up timeout and +signal events in the library. +The helper macros share a distinct naming convention. +For example, the macros +.Fn evtimer_set +and +.Fn signal_set +are named consistently with the library function +.Fn event_set . +The following macro and function calls are equivalent: +.Bd -literal -offset indent +evtimer_set(event, callback, arg); +event_set(event, \-1, 0, callback, arg); +.Ed +.Pp +Likewise, configuring a signal event with +.Fn signal_set +has an equivalent call to +.Fn event_set : +.Bd -literal -offset indent +signal_set(event, signal, callback, arg); +event_set(event, signal, EV_SIGNAL|EV_PERSIST, callback, arg); +.Ed +.Pp +If +.Xr event_init 3 +was called earlier, +.Fn event_set +associates the +.Fa event +with the +.Vt event_base +structure it created; otherwise, the +.Fa event +is not associated with any +.Vt event_base +structure. +If a program needs to assign an event to a specific +.Vt event_base +structure, it should call +.Fn event_base_set +after calling +.Fn event_set . +The first argument of +.Fn event_base_set +is the target +.Vt event_base +structure, and the second argument is the +.Fa event +to be reassigned. +The behavior is undefined if either argument is +.Dv NULL . +Only events that have not been scheduled with +.Fn event_add +or corresponding helper macros or functions can be assigned to a new +.Vt event_base +structure. +.Pp +.Fn event_add +schedules the +.Fa event +using the kernel notification method of its associated +.Vt event_base +structure; see +.Xr event_base_new 3 +for information about kernel notification methods. +If a timeout is specified, it is added to the event timeout list. +Events can register as timeout events without attaching to file +descriptors or signals. +Programs can set the +.Fa tv +argument to +.Dv NULL +to specify that an event has no timeout. +The behavior is undefined if the +.Fa event +is +.Dv NULL +or uninitialized. +The effect of the macros +.Fn evtimer_add +and +.Fn signal_add +is identical to +.Fn event_add . +.Pp +If +.Fn event_add +is called again with a new or updated timeout value before the event trigger +is processed, the function: +.Bl -enum +.It +Unschedules the existing timeout if it exists. +.It +Sets a new timeout starting from when the function was most recently invoked. +.It +Reschedules the event with the event loop. +.El +.Pp +.Fn event_del +removes the +.Fa event +from the event loop of its associated +.Vt event_base +structure. +The behavior of the function is undefined if the +.Fa event +is +.Dv NULL . +On success, it removes the event from internal event queues and unregisters it +with the kernel notification method. +The function fails if the library was neither initialized with +.Xr event_init 3 +nor was the event previously assigned to an +.Vt event_base +with +.Fn event_base_set . +The function does not free memory assigned to user-defined data structures, +nor does it close open file descriptors. +The effect of the macros +.Fn evtimer_del +and +.Fn signal_del +is identical to +.Fn event_del . +.Pp +.Fn event_base_once +is used to schedule a +.Fa callback +function to be executed exactly once without +requiring the caller to create and manage an +.Vt event +structure. +The arguments are as follows: +.Bl -tag -width Ds +.It Fa base +A pointer to an +.Vt event_base +structure initialized by +.Xr event_base_new 3 . +The behavior is undefined if +.Fa base +is +.Dv NULL . +.It Fa fd +A file descriptor to monitor. +.It Fa flags +.Dv EV_TIMEOUT , +.Dv EV_READ , +.Dv EV_WRITE , +or +.Dv EV_READ | EV_WRITE . +.It Fa callback +A user-defined function that is executed when the event triggers. +This callback matches the same prototype and design used in +.Fn event_set . +.It Fa arg +A user-specified pointer to pass to the +.Fa callback +function. +.It Fa tv +A pointer to an optional timeout +.Vt timeval +structure, ignored if +.Dv NULL . +.El +.Pp +.Fn event_once +behaves similar to +.Fn event_base_once +and requires that the library is initialized with +.Xr event_init 3 . +.Pp +To check the status of a scheduled event, refer to the +.Xr event_pending 3 +manual page. +If a program needs to manually trigger an event, refer to +.Xr event_active 3 . +.Sh RETURN VALUES +These functions return 0 on success or \-1 on failure. +.Pp +.Fn event_base_set +returns \-1 if the +.Fa event +has already been processed by +.Fn event_add . +.Pp +.Fn event_add +returns \-1 if a memory allocation fault occurs, +.Va errno +is set. +Other internal library errors terminate the program with +.Xr exit 3 +after reporting to the log callback (see +.Xr event_set_log_callback 3 ) . +.Sh ERRORS +On failure +.Fn event_add +can set errno +as follows: +.Bl -tag -width Er +.It Bq Er ENOMEM +The system has insufficient memory to add the +.Fa event +to the event loop. +.El +.Sh SEE ALSO +.Xr event_active 3 , +.Xr event_base_loop 3 , +.Xr event_base_new 3 , +.Xr event_pending 3 +.Sh HISTORY +.Fn event_set , +.Fn event_add +and +.Fn event_del +first appeared in libevent-0.1, +.Fn signal_set , +.Fn signal_add , +and +.Fn signal_del +in libevent-0.5 , +and +.Fn evtimer_set , +.Fn evtimer_add +and +.Fn evtimer_del +in libevent-0.6. +These functions have been available since +.Ox 3.2 . +.Pp +.Fn event_once +first appeared in libevent-0.8 and has been available since +.Ox 3.6 . +.Pp +.Fn event_base_set +first appeared in libevent-1.0 and has been available since +.Ox 3.8 . +.Pp +.Fn event_base_once +first appeared in libevent-1.3c and has been available since +.Ox 4.4 . +.Sh AUTHORS +.An -nosplit +.An Niels Provos +wrote the event library and these functions except for +.Fn event_base_once +which was also created by +.An Wouter Wijngaards . +.Pp +This manual page was written by +.An Ted Bullock Aq Mt tbullock@comlore.com . diff --git a/static/openbsd/man3/event_set_log_callback.3 b/static/openbsd/man3/event_set_log_callback.3 new file mode 100644 index 00000000..e83ee3fb --- /dev/null +++ b/static/openbsd/man3/event_set_log_callback.3 @@ -0,0 +1,138 @@ +.\" $OpenBSD: event_set_log_callback.3,v 1.3 2025/06/07 20:50:40 schwarze Exp $ +.\" Copyright (c) 2023 Ted Bullock +.\" +.\" 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: June 7 2025 $ +.Dt EVENT_SET_LOG_CALLBACK 3 +.Os +.Sh NAME +.Nm event_set_log_callback +.Nd set callback for diagnostics +.Sh SYNOPSIS +.Lb libevent +.In event.h +.Ft typedef void +.Fo (*event_log_cb) +.Fa "int sev" +.Fa "const char *msg" +.Fc +.Ft void +.Fo event_set_log_callback +.Fa "event_log_cb cb" +.Fc +.Sh DESCRIPTION +The event library uses an optional callback function configured using +.Fn event_set_log_callback +to report error and diagnostic messages from many functions. +By default the library does not report diagnostics. +After executing the callback to report an error the event library invokes +.Xr exit 3 ; +this happens even if no callback is configured. +.Pp +.Fa cb +is a function pointer to a callback with the following parameters: +.Bl -tag -width 4n +.It Fa sev : +represents the severity of the message and may be one of: +.Bl -tag -width "_EVENT_LOG_DEBUG" +.It Dv _EVENT_LOG_DEBUG +Messages for debugging purposes. +These message are suppressed by the library unless it is compiled with +.Dv USE_DEBUG . +.It Dv _EVENT_LOG_MSG +Messages providing information. +.It Dv _EVENT_LOG_WARN +Messages indicating non-fatal issues. +.It Dv _EVENT_LOG_ERR +Messages indicating fatal issues. +The library terminates the program by calling +.Xr exit 3 +after reporting the message. +.El +.It Fa msg : +an ASCII string containing the message. +.El +.Pp +Default behavior is restored and callbacks are prevented if +.Fa cb +is +.Dv NULL . +.Sh EXAMPLES +The following C program illustrates use of +.Fn event_set_log_callback . +The callback function +.Fn cb +includes logic to identify the severity levels of diagnostic messages. +.Bd -literal -offset indent +#include +#include +#include + +void +cb(int sev, const char *msg) +{ + switch (sev) { + case _EVENT_LOG_DEBUG: + printf("DEBUG: %s\en", msg); + break; + case _EVENT_LOG_MSG: + printf("INFO: %s\en", msg); + break; + case _EVENT_LOG_WARN: + printf("WARNING: %s\en", msg); + break; + case _EVENT_LOG_ERR: + printf("ERROR: %s\en", msg); + break; + } +} + +int +main(int argc, char *argv[]) +{ + struct event_base *eb; + /* Redirect diagnostic messages to `cb` callback */ + event_set_log_callback(cb); + /* Report the kernel notification method */ + setenv("EVENT_SHOW_METHOD", "", 1); + /* Initialize library; failures won't return */ + eb = event_base_new(); + /* Disable diagnostic messages */ + event_set_log_callback(NULL); + + /* Do something with the event library here */ + + /* Deallocate memory */ + event_base_free(eb); + return 0; +} +.Ed +.Sh SEE ALSO +.Xr event_base_new 3 , +.Xr exit 3 +.Sh HISTORY +.Fn event_set_log_callback +first appeared in libevent-1.0c and has been available since +.Ox 3.8 . +.Sh AUTHORS +The event library was written by +.An -nosplit +.An Niels Provos . +.Pp +.Fn event_set_log_callback +and the diagnostic reporting system was written by +.An Nick Mathewson . +.Pp +This manual page was written by +.An Ted Bullock Aq Mt tbullock@comlore.com . diff --git a/static/openbsd/man3/evp.3 b/static/openbsd/man3/evp.3 new file mode 100644 index 00000000..3a7acf1f --- /dev/null +++ b/static/openbsd/man3/evp.3 @@ -0,0 +1,250 @@ +.\" $OpenBSD: evp.3,v 1.38 2025/06/11 13:48:54 schwarze Exp $ +.\" full merge up to: OpenSSL man7/evp 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" This file was written by Ulf Moeller , +.\" Matt Caswell , Geoff Thorpe , +.\" and Dr. Stephen Henson . +.\" Copyright (c) 2000, 2002, 2006, 2013, 2016 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 11 2025 $ +.Dt EVP 3 +.Os +.Sh NAME +.Nm evp +.Nd high-level cryptographic functions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/evp.h +.Sh DESCRIPTION +The EVP library provides a high-level interface to cryptographic +functions. +The abbreviation +.Dq EVP +is intended to mean +.Dq EnVeloPe +in the sense of +.Dq wrapper library . +It is not related to the technical meaning of the term +.Dq envelope +in contexts like +.Xr CMS_encrypt 3 , +.Xr EVP_SealInit 3 , +.Xr PKCS7_encrypt 3 , +or +.Xr SMIME_write_PKCS7 3 . +.Pp +.Xr EVP_SealInit 3 +and +.Xr EVP_OpenInit 3 +provide public key encryption and decryption to implement digital +"envelopes". +.Pp +The +.Xr EVP_DigestSignInit 3 +and +.Xr EVP_DigestVerifyInit 3 +functions implement digital signatures and Message Authentication Codes +(MACs). +Also see the older +.Xr EVP_SignInit 3 +and +.Xr EVP_VerifyInit 3 +functions. +.Pp +Symmetric encryption is available with the +.Xr EVP_EncryptInit 3 +functions. +The +.Xr EVP_DigestInit 3 +functions provide message digests. +.Pp +Authenticated encryption with additional data (AEAD) is available with +the +.Xr EVP_AEAD_CTX_init 3 +functions. +.Pp +The +.Fn EVP_PKEY_* +functions provide a high-level interface to asymmetric algorithms. +To create a new +.Vt EVP_PKEY , +see +.Xr EVP_PKEY_new 3 . +.Vt EVP_PKEY Ns s +can be associated with a private key of a particular algorithm +by using the functions described in the +.Xr EVP_PKEY_set1_RSA 3 +page, or new keys can be generated using +.Xr EVP_PKEY_keygen 3 . +.Vt EVP_PKEY Ns s +can be compared using +.Xr EVP_PKEY_cmp 3 +or printed using +.Xr EVP_PKEY_print_private 3 . +.Pp +The +.Fn EVP_PKEY_* +functions support the full range of asymmetric algorithm operations: +.Bl -bullet +.It +For key agreement, see +.Xr EVP_PKEY_derive 3 . +.It +For signing and verifying, see +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +and +.Xr EVP_PKEY_verify_recover 3 . +However, note that these functions do not perform a digest of the +data to be signed. +Therefore, normally you would use the +.Xr EVP_DigestSignInit 3 +functions for this purpose. +.It +For encryption and decryption see +.Xr EVP_PKEY_encrypt 3 +and +.Xr EVP_PKEY_decrypt 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 +.Xr EVP_SealInit 3 +and +.Xr EVP_OpenInit 3 +functions. +.El +.Pp +The +.Xr EVP_BytesToKey 3 +function provides some limited support for password based encryption. +Careful selection of the parameters will provide a PKCS#5 PBKDF1 +compatible implementation. +However, new applications should typically not use this (preferring, for +example, PBKDF2 from PCKS#5). +.Pp +The +.Xr EVP_EncodeInit 3 +family of functions provides base64 encoding and decoding. +.Sh SEE ALSO +.Xr ASN1_item_digest 3 , +.Xr ASN1_item_sign 3 , +.Xr BIO_f_cipher 3 , +.Xr BIO_f_md 3 , +.Xr CMAC_Init 3 , +.Xr CMS_encrypt 3 , +.Xr CMS_sign 3 , +.Xr crypto 3 , +.Xr d2i_PKCS8PrivateKey_bio 3 , +.Xr d2i_PrivateKey 3 , +.Xr EVP_AEAD_CTX_init 3 , +.Xr EVP_aes_128_cbc 3 , +.Xr EVP_BytesToKey 3 , +.Xr EVP_camellia_128_cbc 3 , +.Xr EVP_chacha20 3 , +.Xr EVP_CIPHER_CTX_ctrl 3 , +.Xr EVP_CIPHER_CTX_get_cipher_data 3 , +.Xr EVP_CIPHER_CTX_init 3 , +.Xr EVP_CIPHER_CTX_set_flags 3 , +.Xr EVP_CIPHER_do_all 3 , +.Xr EVP_CIPHER_meth_new 3 , +.Xr EVP_CIPHER_nid 3 , +.Xr EVP_des_cbc 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_DigestSignInit 3 , +.Xr EVP_DigestVerifyInit 3 , +.Xr EVP_EncodeInit 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_MD_CTX_ctrl 3 , +.Xr EVP_MD_nid 3 , +.Xr EVP_OpenInit 3 , +.Xr EVP_PKCS82PKEY 3 , +.Xr EVP_PKEY_asn1_get_count 3 , +.Xr EVP_PKEY_cmp 3 , +.Xr EVP_PKEY_CTX_ctrl 3 , +.Xr EVP_PKEY_CTX_get_operation 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_CTX_set_hkdf_md 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_get_default_digest_nid 3 , +.Xr EVP_PKEY_keygen 3 , +.Xr EVP_PKEY_new 3 , +.Xr EVP_PKEY_print_private 3 , +.Xr EVP_PKEY_set1_RSA 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_size 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 , +.Xr EVP_rc4 3 , +.Xr EVP_SealInit 3 , +.Xr EVP_sha1 3 , +.Xr EVP_sha3_224 3 , +.Xr EVP_SignInit 3 , +.Xr EVP_sm3 3 , +.Xr EVP_sm4_cbc 3 , +.Xr EVP_VerifyInit 3 , +.Xr HMAC 3 , +.Xr OCSP_basic_sign 3 , +.Xr OCSP_request_sign 3 , +.Xr PEM_get_EVP_CIPHER_INFO 3 , +.Xr PEM_read_bio_PrivateKey 3 , +.Xr PKCS12_create 3 , +.Xr PKCS5_PBKDF2_HMAC 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_sign 3 , +.Xr RSA_pkey_ctx_ctrl 3 , +.Xr SSL_CTX_set_tlsext_ticket_key_cb 3 , +.Xr X509_ALGOR_set0 3 , +.Xr X509_check_private_key 3 , +.Xr X509_digest 3 , +.Xr X509_get_pubkey 3 , +.Xr X509_PUBKEY_set 3 , +.Xr X509_sign 3 , +.Xr X509_to_X509_REQ 3 diff --git a/static/openbsd/man3/execv.3 b/static/openbsd/man3/execv.3 new file mode 100644 index 00000000..6e4f1485 --- /dev/null +++ b/static/openbsd/man3/execv.3 @@ -0,0 +1,264 @@ +.\" $OpenBSD: execv.3,v 1.2 2023/05/13 16:36:40 kn 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. +.\" +.Dd $Mdocdate: May 13 2023 $ +.Dt EXECV 3 +.Os +.Sh NAME +.Nm execl , +.Nm execlp , +.Nm execle , +.Nm execv , +.Nm execvp , +.Nm execvpe +.Nd execute a file +.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 execle "const char *path" "const char *arg" ... "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 +This family of functions replace the current process image with a +new process image. +The functions described in this manual page are front-ends for the +.Xr execve 2 +system call; see that manual page for detailed information +about the replacement of the current process. +.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 , +and +.Fn execle +functions can be thought of as +.Fa arg0 , +.Fa arg1 , +\&..., +.Fa 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 null pointer. +.Pp +The +.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 +.Em must +be terminated by a null pointer itself. +.Pp +The +.Fn execle +and +.Fn execvpe +functions also specify the environment of the executed process by following +the null +pointer that terminates the list of arguments in the parameter list +or the pointer to the +.Va 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 null pointer itself. +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 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 +.Pq Sq \&/ +character. +The search path is the path specified in the environment by +.Ev PATH +variable. +If this variable isn't specified, +.Dv _PATH_DEFPATH +from +.In paths.h +is used instead, consisting of +.Pa /usr/bin , +.Pa /bin , +.Pa /usr/sbin , +.Pa /sbin , +.Pa /usr/X11R6/bin , +.Pa /usr/local/bin , +.Pa /usr/local/sbin . +.Pp +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.) +.Sh RETURN VALUES +If any of these functions return, an error has 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 +default shell program +.El +.Sh ERRORS +.Fn execl , +.Fn execle , +.Fn execlp , +.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 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 ktrace 2 , +.Xr ptrace 2 , +.Xr environ 7 +.Sh STANDARDS +Historically, the default path for the +.Fn execlp +and +.Fn execvp +functions was +.Pa \&. , +.Pa /bin , +.Pa /usr/bin . +This was changed to improve security and behaviour. +.Pp +The behavior of +.Fn execlp +and +.Fn execvp +when errors occur while attempting to execute the file is historic +practice, but has not traditionally been documented and is not specified +by the +.Tn POSIX +standard. +.Pp +Traditionally, the functions +.Fn execlp +and +.Fn execvp +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. +.Pp +.Fn execl , +.Fn execv , +.Fn execle , +.Fn execlp +and +.Fn execvp +conform to +.St -p1003.1-88 . +.Fn execvpe +is a GNU extension. +.Sh HISTORY +The functions +.Fn execl +and +.Fn execv +first appeared in +.At v2 . +A predecessor to +.Fn execvp , +.Fn pexec , +first appeared in the Programmer's Workbench (PWB/UNIX). +The functions +.Fn execle , +.Fn execlp , +.Fn execve , +and +.Fn execvp +first appeared in +.At v7 . diff --git a/static/openbsd/man3/exit.3 b/static/openbsd/man3/exit.3 new file mode 100644 index 00000000..ccb416ee --- /dev/null +++ b/static/openbsd/man3/exit.3 @@ -0,0 +1,101 @@ +.\" 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. +.\" +.\" $OpenBSD: exit.3,v 1.19 2025/06/03 14:15:53 yasuoka Exp $ +.\" +.Dd $Mdocdate: June 3 2025 $ +.Dt EXIT 3 +.Os +.Sh NAME +.Nm exit +.Nd perform normal program termination +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn exit "int status" +.Sh DESCRIPTION +The +.Fn exit +function terminates a process. +.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 and 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 . +Note that typically +.Xr _exit 2 +only passes the lower 8 bits of +.Fa status +on to the parent, thus negative values have less meaning. +.Sh RETURN VALUES +The +.Fn exit +function never returns. +.Sh SEE ALSO +.Xr _exit 2 , +.Xr atexit 3 , +.Xr fflush 3 , +.Xr intro 3 , +.Xr sysexits 3 , +.Xr tmpfile 3 +.Sh STANDARDS +The +.Fn exit +function conforms to +.St -p1003.1-2024 . +.Sh HISTORY +An +.Fn exit +function first appeared as a system call in +.At v1 . +It has accepted the +.Fa status +argument since +.At v2 . +In +.At v7 , +the bare system call was renamed to +.Xr _exit 2 . diff --git a/static/openbsd/man3/exp.3 b/static/openbsd/man3/exp.3 new file mode 100644 index 00000000..67a513d9 --- /dev/null +++ b/static/openbsd/man3/exp.3 @@ -0,0 +1,351 @@ +.\" $OpenBSD: exp.3,v 1.36 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt EXP 3 +.Os +.Sh NAME +.Nm exp , +.Nm expf , +.Nm expl , +.Nm exp2 , +.Nm exp2f , +.Nm exp2l , +.Nm expm1 , +.Nm expm1f , +.Nm expm1l , +.Nm log , +.Nm logf , +.Nm logl , +.Nm log2 , +.Nm log2f , +.Nm log2l , +.Nm log10 , +.Nm log10f , +.Nm log10l , +.Nm log1p , +.Nm log1pf , +.Nm log1pl , +.Nm pow , +.Nm powf , +.Nm powl +.Nd exponential, logarithm, power functions +.Sh SYNOPSIS +.Lb libm +.In math.h +.Ft double +.Fn exp "double x" +.Ft float +.Fn expf "float x" +.Ft long double +.Fn expl "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" +.Ft double +.Fn log "double x" +.Ft float +.Fn logf "float x" +.Ft long double +.Fn logl "long double x" +.Ft double +.Fn log2 "double x" +.Ft float +.Fn log2f "float x" +.Ft long double +.Fn log2l "long double x" +.Ft double +.Fn log10 "double x" +.Ft float +.Fn log10f "float x" +.Ft long 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 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 exp +function computes the base +.Ms e +exponential value of the given argument +.Fa x . +The +.Fn expf +function is a single precision version of +.Fn exp . +The +.Fn expl +function is an extended precision version of +.Fn exp . +.Pp +The +.Fn exp2 +function computes the base 2 exponential of the given argument +.Fa x . +The +.Fn exp2f +function is a single precision version of +.Fn exp2 . +The +.Fn exp2l +function is an extended precision version of +.Fn exp2 . +.Pp +The +.Fn expm1 +function computes the value exp(x) \(mi 1 accurately even for tiny argument +.Fa x . +The +.Fn expm1f +function is a single precision version of +.Fn expm1 . +The +.Fn expm1l +function is an extended precision version of +.Fn expm1 . +.Pp +The +.Fn log +function computes the value of the natural logarithm of argument +.Fa x . +The +.Fn logf +function is a single precision version of +.Fn log . +The +.Fn logl +function is an extended precision version of +.Fn log . +.Pp +The +.Fn log2 +function computes the value of the logarithm of argument +.Fa x +to base 2. +The +.Fn log2f +function is a single precision version of +.Fn log2 . +The +.Fn log2l +function is an extended precision version of +.Fn log2 . +.Pp +The +.Fn log10 +function computes the value of the logarithm of argument +.Fa x +to base 10. +The +.Fn log10f +function is a single precision version of +.Fn log10 . +The +.Fn log10l +function is an extended precision version of +.Fn log10 . +.Pp +The +.Fn log1p +function computes +the value of log(1 + x) accurately even for tiny argument +.Fa x . +The +.Fn log1pf +function is a single precision version of +.Fn log1p . +The +.Fn log1pl +function is an extended precision version of +.Fn log1p . +.Pp +The +.Fn pow +function computes the value of +.Fa x +to the exponent +.Fa y . +The +.Fn powf +function is a single precision version of +.Fn pow . +The +.Fn powl +function is an extended precision version of +.Fn pow . +.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 , +.Fn expm1 +and +.Fn pow +detect if the computed value will overflow +and set the global variable +.Va errno +to +.Er ERANGE . +The function +.Fn pow x y +checks to see if +.Fa x +< 0 and +.Fa y +is not an integer, in the event this is true, +the global variable +.Va errno +is set to +.Er EDOM . +.Sh ERRORS (due to Roundoff etc.) +exp(x), log(x), expm1(x) and log1p(x) are accurate to within +an +.Em ulp , +and log10(x) to within about 2 +.Em ulps ; +an +.Em ulp +is one +.Em Unit +in the +.Em Last +.Em Place . +The error in +.Fn pow x y +is below about 2 +.Em ulps +when its +magnitude is moderate, but increases as +.Fn pow x y +approaches +the over/underflow thresholds until almost as many bits could be +lost as are occupied by the floating\-point format's exponent +field; that is 11 bits for IEEE 754 Double. +No such drastic loss has been exposed by testing; the worst +errors observed have been below 300 +.Em ulps +for IEEE 754 Double. +Moderate values of +.Fn pow +are accurate enough that +.Fn pow integer integer +is exact until it is bigger than 2**53 for IEEE 754. +.Sh NOTES +The functions exp(x) \(mi 1 and log(1 + x) are called +expm1 and logp1 in BASIC on the Hewlett\-Packard HP-71B +and APPLE Macintosh, EXP1 and LN1 in Pascal, exp1 and log1 in C +on APPLE Macintoshes, where they have been provided to make +sure financial calculations of ((1 + x)**n \(mi 1) / x, namely +expm1(n * log1p(x)) / x, will be accurate when x is tiny. +They also provide accurate inverse hyperbolic functions. +.Pp +The function +.Fn pow x 0 +returns x**0 = 1 for all x including x = 0 and infinity. +Previous implementations of +.Fn pow +may have defined x**0 to be undefined in some or all of these cases. +Here are reasons for returning x**0 = 1 always: +.Bl -enum -width indent +.It +Any program that already tests whether x is zero (or +infinite or NaN) before computing x**0 cannot care +whether 0**0 = 1 or not. +Any program that depends upon 0**0 to be invalid is dubious anyway since that +expression's meaning and, if invalid, its consequences +vary from one computer system to another. +.It +Some Algebra texts (e.g., Sigler's) define x**0 = 1 for +all x, including x = 0. +This is compatible with the convention that accepts a[0] +as the value of polynomial +.Bd -literal -offset indent +p(x) = a[0]*x**0 + a[1]*x**1 + a[2]*x**2 +...+ a[n]*x**n +.Ed +.Pp +at x = 0 rather than reject a[0]*0**0 as invalid. +.It +Analysts will accept 0**0 = 1 despite that x**y can +approach anything or nothing as x and y approach 0 +independently. +The reason for setting 0**0 = 1 anyway is this: +.Bd -filled -offset indent +If x(z) and y(z) are +.Em any +functions analytic (expandable +in power series) in z around z = 0, and if there +x(0) = y(0) = 0, then x(z)**y(z) \(-> 1 as z \(-> 0. +.Ed +.It +If 0**0 = 1, then infinity**0 = 1/0**0 = 1 too; and +then NaN**0 = 1 too because x**0 = 1 for all finite +and infinite x, i.e., independently of x. +.El +.Sh SEE ALSO +.Xr fpclassify 3 , +.Xr ilogb 3 +.Sh HISTORY +The +.Fn exp +and +.Fn log +functions first appeared in +.At v1 ; +.Fn pow +in +.At v3 ; +.Fn log10 +in +.At v7 ; +.Fn log1p +and +.Fn expm1 +in +.Bx 4.3 . diff --git a/static/openbsd/man3/fabs.3 b/static/openbsd/man3/fabs.3 new file mode 100644 index 00000000..e13cecb0 --- /dev/null +++ b/static/openbsd/man3/fabs.3 @@ -0,0 +1,84 @@ +.\" $OpenBSD: fabs.3,v 1.4 2025/06/06 21:50:10 schwarze Exp $ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" @(#)fabs.3 5.1 (Berkeley) 5/2/91 +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (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 +.\" +.Dd $Mdocdate: June 6 2025 $ +.Dt FABS 3 +.Os +.Sh NAME +.Nm fabs , +.Nm fabsf , +.Nm fabsl +.Nd floating-point absolute value functions +.Sh SYNOPSIS +.Lb libm +.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 +function computes the absolute value of a floating-point number +.Fa x . +The +.Fn fabsf +function is a single precision version of +.Fn fabs . +The +.Fn fabsl +function is an extended precision version of +.Fn fabs . +.Sh RETURN VALUES +The +.Fn fabs , +.Fn fabsf +and +.Fn fabsl +functions return the absolute value of +.Fa x . +.Sh SEE ALSO +.Xr abs 3 , +.Xr ceil 3 , +.Xr floor 3 , +.Xr rint 3 +.Sh STANDARDS +The +.Fn fabs +function conforms to +.St -ansiC . +.Sh HISTORY +An +.Fn fabs +function first appeared in +.At v6 . diff --git a/static/openbsd/man3/fclose.3 b/static/openbsd/man3/fclose.3 new file mode 100644 index 00000000..df308480 --- /dev/null +++ b/static/openbsd/man3/fclose.3 @@ -0,0 +1,141 @@ +.\" $OpenBSD: fclose.3,v 1.13 2025/07/16 15:33:05 yasuoka 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. +.\" +.Dd $Mdocdate: July 16 2025 $ +.Dt FCLOSE 3 +.Os +.Sh NAME +.Nm fclose , +.Nm fdclose +.Nd close a stream +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn fclose "FILE *stream" +.Ft int +.Fn fdclose "FILE *stream" "int *fdp" +.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 then any buffered data is written +first, +while if the stream was being used for input then the underlying +file position may be updated, +as if via +.Xr fflush 3 . +.Pp +The +.Fn fdclose +function is equivalent to +.Fn fclose +except that it does not close the associated file descriptor. +If +.Fa fdp +is not +.Dv NULL , +the file descriptor will be stored through it. +If the stream was created with a function other than +.Xr fopen 3 , +.Xr fdopen 3 , +or +.Xr freopen 3 +and as a result does not have an associated file descriptor then +-1 will stored through +.Fa fdp . +.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 +The +.Fn fclose +and +.Fn fdclose +functions will fail if +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa stream +is not an open stream. +.El +.Pp +The +.Fn fdclose +function will fail if +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP +The argument +.Fa stream +does not have an associated file descriptor. +.El +.Pp +They may also fail and set +.Va errno +for any of the errors specified for the +.Xr fflush 3 +routine. +.Pp +The +.Fn fclose +function may also fail and set +.Va errno +for any of the errors specified for the +.Xr close 2 +routine. +.Sh SEE ALSO +.Xr close 2 , +.Xr fflush 3 , +.Xr fopen 3 , +.Xr setvbuf 3 +.Sh STANDARDS +The +.Fn fclose +function conforms to +.St -p1003.1-2024 . +.Sh HISTORY +The +.Fn fclose +function first appeared in +.At v7 . +.Pp +The +.Fn fdclose +function first appeared in +.Fx 11.0 . diff --git a/static/openbsd/man3/fdim.3 b/static/openbsd/man3/fdim.3 new file mode 100644 index 00000000..5c7470ad --- /dev/null +++ b/static/openbsd/man3/fdim.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: fdim.3,v 1.5 2025/10/14 06:30:16 jsg 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. +.\" +.\" $FreeBSD: src/lib/msun/man/fdim.3,v 1.1 2004/06/30 07:04:01 das Exp $ +.\" +.Dd $Mdocdate: October 14 2025 $ +.Dt FDIM 3 +.Os +.Sh NAME +.Nm fdim , +.Nm fdimf , +.Nm fdiml +.Nd positive difference functions +.Sh SYNOPSIS +.Lb libm +.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 a NaN, then a NaN is returned. +Otherwise, the result is +.Li +0.0 . +.Pp +Overflow or underflow may occur if 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 +.Sh STANDARDS +The +.Fn fdim , +.Fn fdimf , +and +.Fn fdiml +functions conform to +.St -isoC-99 . +.Sh HISTORY +These routines first appeared in +.Ox 4.5 . diff --git a/static/openbsd/man3/feclearexcept.3 b/static/openbsd/man3/feclearexcept.3 new file mode 100644 index 00000000..1f6824d8 --- /dev/null +++ b/static/openbsd/man3/feclearexcept.3 @@ -0,0 +1,171 @@ +.\" $OpenBSD: feclearexcept.3,v 1.8 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt FECLEAREXCEPT 3 +.Os +.Sh NAME +.Nm feclearexcept , +.Nm fegetexceptflag , +.Nm feraiseexcept , +.Nm fesetexceptflag , +.Nm fetestexcept +.Nd access floating-point status flags +.Sh SYNOPSIS +.Lb libm +.In fenv.h +.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 +These functions provide access to the floating-point status flags. +The +.Fa excepts +input argument is a bitmask specifying an exception type and +containing any of the values listed below. +.Bl -tag -width "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. +.Pp +For instance, subtraction of infinities, division of zero by zero, +ordered comparison involving NaNs, 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. +.It Dv FE_DENORMAL +Denormalization exception occurs when the result of a floating-point +expression is a denormalized number. +.Pp +This is available only on the floating-point implementations of +amd64 and i386 processors. +.El +.Pp +Additionally, the macro +.Dv FE_ALL_EXCEPT +is simply the bitwise OR of all floating-point exception macros +listed above. +.Pp +The +.Fn feclearexcept +function clears the floating-point exceptions represented by +.Fa excepts . +.Pp +The +.Fn fegetexceptflag +function stores a representation of the states of the floating-point +flags indicated by +.Pa excepts +in the object pointed to by +.Pa flagp . +.Pp +The +.Fn feraiseexcept +function raises floating-point exceptions represented by +.Pa excepts . +.Pp +The +.Fn fesetexceptflag +function sets the floating-point status flags indicated by +.Pa excepts +to the states stored in the object pointed to by +.Pa flagp . +The value of +.Pa flagp +shall have been set by a previous call to +.Fn fegetexceptflag +whose second argument represented at least those floating-point +exceptions represented by +.Pa excepts . +This function does not raise floating-point exceptions, but only +sets the state of the flags. +.Pp +The +.Fn fetestexcept +function determines which of a specified subset of the floating-point +exception flags are currently set. +The +.Pa excepts +specifies the floating-point status flags to be queried. +.Sh RETURN VALUES +The +.Fn feclearexcept , +.Fn fegetexceptflag , +.Fn feraiseexcept , +and +.Fn fesetexceptflag +functions return zero on success, and non-zero if an error occurred. +The +.Fn fetestexcept +function returns a bitmask of a specified subset of the floating-point +exception flags which are currently set. +.Sh SEE ALSO +.Xr feenableexcept 3 , +.Xr fegetenv 3 , +.Xr fegetround 3 +.Sh STANDARDS +The +.Fn feclearexcept , +.Fn fegetexceptflag , +.Fn feraiseexcept , +.Fn fesetexceptflag , +and +.Fn fetestexcept +functions conform to +.St -isoC-99 . +.Pp +The return types for +.Fn feclearexcept , +.Fn fegetexceptflag , +.Fn feraiseexcept , +and +.Fn fesetexceptflag +are +.Vt int +for alignment with +.St -isoC-99 +Defect Report #202. +.Sh HISTORY +These functions first appeared in +.Ox 5.0 . +.Sh CAVEATS +On some architectures, +.Fn feraiseexcept +additionally raises the +.Dq inexact +floating-point exception whenever it raises the +.Dq overflow +or +.Dq underflow +floating-point exception. diff --git a/static/openbsd/man3/feenableexcept.3 b/static/openbsd/man3/feenableexcept.3 new file mode 100644 index 00000000..d06f0b20 --- /dev/null +++ b/static/openbsd/man3/feenableexcept.3 @@ -0,0 +1,87 @@ +.\" $OpenBSD: feenableexcept.3,v 1.4 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt FEENABLEEXCEPT 3 +.Os +.Sh NAME +.Nm feenableexcept , +.Nm fedisableexcept , +.Nm fegetexcept +.Nd control floating-point exception masks +.Sh SYNOPSIS +.Lb libm +.In fenv.h +.Ft int +.Fn feenableexcept "int excepts" +.Ft int +.Fn fedisableexcept "int excepts" +.Ft int +.Fn fegetexcept void +.Sh DESCRIPTION +These functions provide control of the floating-point exception +masks. +The +.Fa excepts +input argument is a bitmask specifying an exception type and +containing any of the values listed in +.Xr feclearexcept 3 . +.Pp +The +.Fn feenableexcept +function unmasks the floating-point exceptions represented by +.Fa excepts . +The future floating-point operations that produce +.Fa excepts +will trap, and a +.Dv SIGFPE +will be delivered to the process. +.Pp +The +.Fn fedisableexcept +function masks the floating-point exceptions represented by +.Fa excepts . +All exceptions are masked by default. +.Pp +The +.Fn fegetexcept +function returns the current exception mask. +.Sh RETURN VALUES +The +.Fn feenableexcept , +and +.Fn fedisableexcept +functions return the previous exception mask. +The +.Fn fegetexcept +function returns the current exception mask. +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr feclearexcept 3 , +.Xr fegetenv 3 , +.Xr fegetround 3 +.Sh STANDARDS +The +.Fn feenableexcept , +.Fn fedisableexcept , +and +.Fn fegetexcept +functions are +.Ox +extensions. +.Sh HISTORY +These functions first appeared in +.Ox 5.0 . diff --git a/static/openbsd/man3/fegetenv.3 b/static/openbsd/man3/fegetenv.3 new file mode 100644 index 00000000..816f270b --- /dev/null +++ b/static/openbsd/man3/fegetenv.3 @@ -0,0 +1,128 @@ +.\" $OpenBSD: fegetenv.3,v 1.5 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt FEGETENV 3 +.Os +.Sh NAME +.Nm fegetenv , +.Nm feholdexcept , +.Nm fesetenv , +.Nm feupdateenv +.Nd manage floating-point environment +.Sh SYNOPSIS +.Lb libm +.In fenv.h +.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 +These functions manage the floating-point environment \(em status +flags, rounding direction modes and exception masks \(em as one entity. +The +.Fa envp +input argument is an object representing the floating-point environment. +The macro +.Dv FE_DFL_ENV +represents the default floating-point environment \(em the one installed +at program startup. +.Pp +The +.Fn fegetenv +function stores the current floating-point environment in the object +pointed to by +.Pa envp . +.Pp +The +.Fn feholdexcept +function saves the current floating-point environment in the object +pointed to by +.Pa envp , +clears the floating-point status flags, and then installs a non-stop +(continue on floating-point exceptions) mode for all floating-point +exceptions. +.Pp +The +.Fn fesetenv +function establishes the floating-point environment represented by +the object pointed to by +.Pa envp . +The argument +.Pa envp +shall point to an object set by a call to +.Fn fegetenv +or +.Fn feholdexcept , +or equal the macro +.Dv FE_DFL_ENV . +Note that +.Fn fesetenv +merely installs the state of the floating-point status flags +represented through its argument, and does not raise these +floating-point exceptions. +.Pp +The +.Fn feupdateenv +function saves the currently raised floating-point exceptions in +its automatic storage, installs the floating-point environment +represented by the object pointed to by +.Pa envp , +and then raises the saved floating-point exceptions. +The argument +.Pa envp +shall point to an object set by a call to +.Fn feholdexcept +or +.Fn fegetenv , +or equal the macro +.Dv FE_DFL_ENV . +.Sh RETURN VALUES +The +.Fn fegetenv , +.Fn feholdexcept , +.Fn fesetenv , +and +.Fn feupdateenv +functions return zero on success, and non-zero if an error occurred. +.Sh SEE ALSO +.Xr feclearexcept 3 , +.Xr feenableexcept 3 , +.Xr fegetround 3 +.Sh STANDARDS +The +.Fn fegetenv , +.Fn feholdexcept , +.Fn fesetenv , +and +.Fn feupdateenv +functions conform to +.St -isoC-99 . +.Pp +The return types for +.Fn fegetenv , +.Fn fesetenv , +and +.Fn feupdateenv +are +.Vt int +for alignment with +.St -isoC-99 +Defect Report #202. diff --git a/static/openbsd/man3/fegetround.3 b/static/openbsd/man3/fegetround.3 new file mode 100644 index 00000000..4f7e891d --- /dev/null +++ b/static/openbsd/man3/fegetround.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: fegetround.3,v 1.5 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt FEGETROUND 3 +.Os +.Sh NAME +.Nm fegetround , +.Nm fesetround +.Nd control floating-point rounding direction modes +.Sh SYNOPSIS +.Lb libm +.In fenv.h +.Ft int +.Fn fegetround void +.Ft int +.Fn fesetround "int round" +.Sh DESCRIPTION +These functions provide control of floating-point rounding direction +modes. +The +.Fa round +input argument is a value specifying a rounding direction mode and +containing any of the values listed below. +.Bl -tag -width "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 +function gets the current rounding direction. +.Pp +The +.Fn fesetround +function establishes the rounding direction represented by +.Pa round . +If the argument is not equal to the value of a rounding direction +macro, the rounding direction is not changed. +.Sh RETURN VALUES +The +.Fn fegetround +function returns the current rounding direction. +The +.Fn fesetround +function return zero on success, and non-zero if an error occurred. +.Sh SEE ALSO +.Xr feclearexcept 3 , +.Xr feenableexcept 3 , +.Xr fegetenv 3 +.Sh STANDARDS +The +.Fn fegetround +and +.Fn fesetround +functions conform to +.St -isoC-99 . +.Sh HISTORY +These functions first appeared in +.Ox 5.0 . diff --git a/static/openbsd/man3/ferror.3 b/static/openbsd/man3/ferror.3 new file mode 100644 index 00000000..0f0bdf21 --- /dev/null +++ b/static/openbsd/man3/ferror.3 @@ -0,0 +1,111 @@ +.\" $OpenBSD: ferror.3,v 1.11 2021/10/31 16:56:47 schwarze 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. +.\" +.Dd $Mdocdate: October 31 2021 $ +.Dt FERROR 3 +.Os +.Sh NAME +.Nm clearerr , +.Nm feof , +.Nm ferror , +.Nm fileno +.Nd check and reset stream status +.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. +.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 +returns the file descriptor associated with the given +.Fa stream +or \-1 if it is not associated with any file descriptor, +for example if it was created with +.Xr fmemopen 3 , +.Xr open_memstream 3 , +or +.Xr funopen 3 . +.Sh ERRORS +These functions should not fail and do not set the external +variable +.Va errno . +.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 . +.Sh HISTORY +The functions +.Fn clearerr , +.Fn feof , +.Fn ferror , +and +.Fn fileno +first appeared in +.At v7 . diff --git a/static/openbsd/man3/fflush.3 b/static/openbsd/man3/fflush.3 new file mode 100644 index 00000000..5facdcd2 --- /dev/null +++ b/static/openbsd/man3/fflush.3 @@ -0,0 +1,132 @@ +.\" $OpenBSD: fflush.3,v 1.20 2025/06/12 00:21:39 jsg 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. +.\" +.Dd $Mdocdate: June 12 2025 $ +.Dt FFLUSH 3 +.Os +.Sh NAME +.Nm fflush , +.Nm fpurge +.Nd flush a stream +.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. +If +.Fa stream +is a stream opened for reading with +.Xr fdopen 3 , +.Xr fopen 3 , +or +.Xr freopen 3 +of a seekable file and it is not already at EOF then +.Fn fflush +sets the seek position of the file to the file position of the +stream and discards any text pushed back via +.Xr ungetc 3 +or +.Xr ungetwc 3 . +The open status of the stream is unaffected. +.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 +or +.Xr ungetwc 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 setvbuf 3 +.Sh STANDARDS +The +.Fn fflush +function conforms to +.St -p1003.1-2024 . +.Sh HISTORY +A predecessor +.Fn flush +first appeared in +.At v1 . +The +.Fn fflush +function first appeared in +.At v4 . +The +.Fn fpurge +function first appeared in +.Bx 4.3 Reno . diff --git a/static/openbsd/man3/ffs.3 b/static/openbsd/man3/ffs.3 new file mode 100644 index 00000000..0b78fbfd --- /dev/null +++ b/static/openbsd/man3/ffs.3 @@ -0,0 +1,82 @@ +.\" 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. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (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: ffs.3,v 1.13 2025/11/06 17:19:11 schwarze Exp $ +.\" +.Dd $Mdocdate: November 6 2025 $ +.Dt FFS 3 +.Os +.Sh NAME +.Nm ffs , +.Nm ffsl , +.Nm ffsll +.Nd find first bit set in a bit string +.Sh SYNOPSIS +.In strings.h +.Ft int +.Fn ffs "int value" +.Ft int +.Fn ffsl "long value" +.Ft int +.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 rightmost bit. +A return value of 0 means that the argument was zero. +.Sh SEE ALSO +.Xr bit_ffs 3 +.Sh STANDARDS +The +.Fn ffs +function conforms to +.St -p1003.1-2008 . +The +.Fn ffsl +and +.Fn ffsll +functions conform to +.St -p1003.1-2024 . +.Sh HISTORY +The +.Fn ffs +function first appeared in +.Bx 4.2 . +The +.Fn ffsl +and +.Fn ffsll +functions first appeared in +.Ox 7.9 . diff --git a/static/openbsd/man3/fgetln.3 b/static/openbsd/man3/fgetln.3 new file mode 100644 index 00000000..3319e1fd --- /dev/null +++ b/static/openbsd/man3/fgetln.3 @@ -0,0 +1,151 @@ +.\" $OpenBSD: fgetln.3,v 1.19 2017/12/01 11:18:40 schwarze 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. +.\" +.Dd $Mdocdate: December 1 2017 $ +.Dt FGETLN 3 +.Os +.Sh NAME +.Nm fgetln +.Nd get a line from a stream +.Sh SYNOPSIS +.In stdio.h +.Ft char * +.Fn fgetln "FILE *stream" "size_t *len" +.Sh DESCRIPTION +Using this function is error-prone in multiple ways; +consider using the safer and more portable function +.Xr getline 3 +instead. +.Pp +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 NUL character. +The length of the line, including the final newline, +is stored in the memory location to which +.Fa len +points and is guaranteed to be greater than 0 upon successful completion. +(Note, however, that if the last line in the stream 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 I/O operation on +.Fa stream +(whether successful or not) +or as soon as the stream is closed. +Otherwise, +.Dv NULL +is returned. +.Pp +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 ferror 3 , +.Xr fgetc 3 , +.Xr fgets 3 , +.Xr fgetwln 3 , +.Xr fopen 3 , +.Xr fparseln 3 , +.Xr getline 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 NUL 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; + + lbuf = NULL; + while ((buf = fgetln(fp, &len))) { + if (buf[len - 1] == '\en') + buf[len - 1] = '\e0'; + else { + /* EOF without EOL, copy and add the NUL */ + if ((lbuf = malloc(len + 1)) == NULL) + err(1, NULL); + memcpy(lbuf, buf, len); + lbuf[len] = '\e0'; + buf = lbuf; + } + printf("%s\en", buf); + } + free(lbuf); + if (ferror(fp)) + err(1, "fgetln"); +.Ed diff --git a/static/openbsd/man3/fgets.3 b/static/openbsd/man3/fgets.3 new file mode 100644 index 00000000..0acd5b0f --- /dev/null +++ b/static/openbsd/man3/fgets.3 @@ -0,0 +1,201 @@ +.\" $OpenBSD: fgets.3,v 1.35 2017/12/01 11:18:40 schwarze 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. +.\" +.Dd $Mdocdate: December 1 2017 $ +.Dt FGETS 3 +.Os +.Sh NAME +.Nm fgets +.Nd get a line from a stream +.Sh SYNOPSIS +.In stdio.h +.Ft char * +.Fn fgets "char *str" "int size" "FILE *stream" +.Sh DESCRIPTION +The +.Fn fgets +function reads at most +.Ar size Ns \-1 +characters 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, on error, or after +.Ar size Ns \-1 +bytes are read. +The newline, if any, is retained. +The string will be NUL-terminated if +.Fn fgets +succeeds; otherwise the contents of +.Fa str +are undefined. +.Sh RETURN VALUES +Upon successful completion, +.Fn fgets +returns a pointer to the string. +If end-of-file or an error occurs before any characters are read, +it returns +.Dv NULL . +The +.Fn fgets +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. +Whether +.Fn fgets +can possibly fail with a +.Ar size +argument of 1 is implementation-dependent. +On +.Ox , +.Fn fgets +will never return +.Dv NULL +when +.Ar size +is 1. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The given +.Fa stream +is not a readable stream. +.It Bq Er EINVAL +The given +.Fa size +is less than or equal to 0. +.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 . +.Sh SEE ALSO +.Xr feof 3 , +.Xr ferror 3 , +.Xr fgetws 3 , +.Xr getline 3 +.Sh STANDARDS +The function +.Fn fgets +conforms to +.St -ansiC . +.Sh HISTORY +The function +.Fn fgets +first appeared in +.At v7 . +.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 -offset indent +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 \*(Gt 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 NUL +.Pq Sq \e0 +character. +If the first character of a line returned by +.Fn fgets +were NUL, +.Fn strchr +would immediately return without considering the rest of the returned text +which may indeed include a newline. +.El +.Pp +Consider using +.Xr getline 3 +instead when dealing with untrusted input. +.Pp +It is erroneous to assume that +.Fn fgets +never returns an empty string when successful. +If a line starts with the NUL character, fgets will store the NUL and +continue reading until it encounters a newline or end-of-file. +This will result in an empty string being returned. +The following bit of code illustrates a case where the programmer assumes +the string cannot be zero length. +.Bd -literal -offset indent +char buf[1024]; + +if (fgets(buf, sizeof(buf), fp) != NULL) { + /* WRONG */ + if (buf[strlen(buf) - 1] == '\en') + buf[strlen(buf) - 1] = '\e0'; +} +.Ed +.Pp +If +.Fn strlen +returns 0, the index into the buffer becomes \-1. +One way to concisely and correctly trim a newline is shown below. +.Bd -literal -offset indent +char buf[1024]; + +if (fgets(buf, sizeof(buf), fp) != NULL) + buf[strcspn(buf, "\en")] = '\e0'; +.Ed diff --git a/static/openbsd/man3/fgetwln.3 b/static/openbsd/man3/fgetwln.3 new file mode 100644 index 00000000..a8a1d362 --- /dev/null +++ b/static/openbsd/man3/fgetwln.3 @@ -0,0 +1,115 @@ +.\" $OpenBSD: fgetwln.3,v 1.2 2015/01/13 14:02:30 schwarze 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. +.\" +.Dd $Mdocdate: January 13 2015 $ +.Dt FGETWLN 3 +.Os +.Sh NAME +.Nm fgetwln +.Nd get a line of wide characters from a stream +.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 and is guaranteed to be greater than 0 upon successful completion. +(Note, however, that if the last line in the stream 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 I/O operation on +.Fa stream +(whether successful or not) +or as soon as the stream is closed. +Otherwise, +.Dv NULL +is returned. +.Pp +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 [EBADF] +.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 malloc 3 , +.Xr mbrtowc 3 , +.Xr read 2 , +.Xr stat 2 , +or +.Xr realloc 3 . +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fgetln 3 , +.Xr fgetws 3 , +.Xr fopen 3 +.Sh HISTORY +The +.Fn fgetwln +function first appeared in +.Ox 5.7 . diff --git a/static/openbsd/man3/fgetws.3 b/static/openbsd/man3/fgetws.3 new file mode 100644 index 00000000..137e5467 --- /dev/null +++ b/static/openbsd/man3/fgetws.3 @@ -0,0 +1,122 @@ +.\" $OpenBSD: fgetws.3,v 1.5 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" $NetBSD: fgetws.3,v 1.2 2003/08/07 16:43:23 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. +.\" +.\" @(#)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 $Mdocdate: June 13 2025 $ +.Dt FGETWS 3 +.Os +.Sh NAME +.Nm fgetws +.Nd get a line of wide characters from a stream +.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/openbsd/man3/fido_assert_allow_cred.3 b/static/openbsd/man3/fido_assert_allow_cred.3 new file mode 100644 index 00000000..44784358 --- /dev/null +++ b/static/openbsd/man3/fido_assert_allow_cred.3 @@ -0,0 +1,48 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.Dt FIDO_ASSERT_ALLOW_CRED 3 +.Os +.Sh NAME +.Nm fido_assert_allow_cred +.Nd allow a credential in a FIDO2 assertion +.Sh SYNOPSIS +.Lb libfido2 libcbor libcrypto libz +.In fido.h +.Ft int +.Fn fido_assert_allow_cred "fido_assert_t *assert" "const unsigned char *ptr" "size_t len" +.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. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_assert_allow_cred +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/openbsd/man3/fido_assert_new.3 b/static/openbsd/man3/fido_assert_new.3 new file mode 100644 index 00000000..c47fa623 --- /dev/null +++ b/static/openbsd/man3/fido_assert_new.3 @@ -0,0 +1,259 @@ +.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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_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_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 +.Lb libfido2 libcbor libcrypto libz +.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_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_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. +.Pp +The +.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_sigcount , +and +.Fn fido_assert_flags +functions return pointers to the CBOR-encoded 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_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/openbsd/man3/fido_assert_set_authdata.3 b/static/openbsd/man3/fido_assert_set_authdata.3 new file mode 100644 index 00000000..20763599 --- /dev/null +++ b/static/openbsd/man3/fido_assert_set_authdata.3 @@ -0,0 +1,239 @@ +.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Nd set parameters of a FIDO2 assertion +.Sh SYNOPSIS +.Lb libfido2 libcbor libcrypto libz +.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" +.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 +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 diff --git a/static/openbsd/man3/fido_assert_verify.3 b/static/openbsd/man3/fido_assert_verify.3 new file mode 100644 index 00000000..60b71de4 --- /dev/null +++ b/static/openbsd/man3/fido_assert_verify.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.Dt FIDO_ASSERT_VERIFY 3 +.Os +.Sh NAME +.Nm fido_assert_verify +.Nd verifies the signature of a FIDO2 assertion statement +.Sh SYNOPSIS +.Lb libfido2 libcbor libcrypto libz +.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_RS256 , +or +.Dv COSE_EDDSA , +and +.Fa pk +points to a +.Vt es256_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/openbsd/man3/fido_bio_dev_get_info.3 b/static/openbsd/man3/fido_bio_dev_get_info.3 new file mode 100644 index 00000000..e51d7bd1 --- /dev/null +++ b/static/openbsd/man3/fido_bio_dev_get_info.3 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_bio_enroll_new.3 b/static/openbsd/man3/fido_bio_enroll_new.3 new file mode 100644 index 00000000..4fb6e355 --- /dev/null +++ b/static/openbsd/man3/fido_bio_enroll_new.3 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_bio_info_new.3 b/static/openbsd/man3/fido_bio_info_new.3 new file mode 100644 index 00000000..a941ee26 --- /dev/null +++ b/static/openbsd/man3/fido_bio_info_new.3 @@ -0,0 +1,82 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_bio_template.3 b/static/openbsd/man3/fido_bio_template.3 new file mode 100644 index 00000000..a6a8f3e3 --- /dev/null +++ b/static/openbsd/man3/fido_bio_template.3 @@ -0,0 +1,180 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_cbor_info_new.3 b/static/openbsd/man3/fido_cbor_info_new.3 new file mode 100644 index 00000000..52f15a88 --- /dev/null +++ b/static/openbsd/man3/fido_cbor_info_new.3 @@ -0,0 +1,242 @@ +.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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_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_fwversion +.Nd FIDO2 CBOR Info API +.Sh SYNOPSIS +.Lb libfido2 libcbor libcrypto libz +.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 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_fwversion "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_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_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_fwversion +function returns the firmware version attribute of +.Fa ci . +.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_open 3 diff --git a/static/openbsd/man3/fido_cred_exclude.3 b/static/openbsd/man3/fido_cred_exclude.3 new file mode 100644 index 00000000..cb0bfa28 --- /dev/null +++ b/static/openbsd/man3/fido_cred_exclude.3 @@ -0,0 +1,61 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.Dt FIDO_CRED_EXCLUDE 3 +.Os +.Sh NAME +.Nm fido_cred_exclude +.Nd appends a credential ID to a credential's list of excluded credentials +.Sh SYNOPSIS +.Lb libfido2 libcbor libcrypto libz +.In fido.h +.Ft int +.Fn fido_cred_exclude "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.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. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_cred_exclude +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/openbsd/man3/fido_cred_new.3 b/static/openbsd/man3/fido_cred_new.3 new file mode 100644 index 00000000..10a5cac4 --- /dev/null +++ b/static/openbsd/man3/fido_cred_new.3 @@ -0,0 +1,294 @@ +.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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_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_len , +.Nm fido_cred_attstmt_len , +.Nm fido_cred_type , +.Nm fido_cred_flags , +.Nm fido_cred_sigcount +.Nd FIDO2 credential API +.Sh SYNOPSIS +.Lb libfido2 libcbor libcrypto libz +.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 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_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_attstmt_len "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 format 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 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 authenticator data, x509 certificate, and signature parts of a +credential are typically passed to a FIDO2 server for verification. +.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/openbsd/man3/fido_cred_set_authdata.3 b/static/openbsd/man3/fido_cred_set_authdata.3 new file mode 100644 index 00000000..e4841429 --- /dev/null +++ b/static/openbsd/man3/fido_cred_set_authdata.3 @@ -0,0 +1,355 @@ +.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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_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_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 +.Lb libfido2 libcbor libcrypto libz +.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_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_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_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 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 +.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_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 format 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 by U2F , +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 not +be able to generate +.Vt "packed" . +.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_RS256 , +or +.Dv COSE_EDDSA . +The type of a credential may only be set once. +Note that not all authenticators support COSE_RS256 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/openbsd/man3/fido_cred_verify.3 b/static/openbsd/man3/fido_cred_verify.3 new file mode 100644 index 00000000..524a0283 --- /dev/null +++ b/static/openbsd/man3/fido_cred_verify.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_credman_metadata_new.3 b/static/openbsd/man3/fido_credman_metadata_new.3 new file mode 100644 index 00000000..b0e2464b --- /dev/null +++ b/static/openbsd/man3/fido_credman_metadata_new.3 @@ -0,0 +1,327 @@ +.\" Copyright (c) 2019-2021 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_dev_enable_entattest.3 b/static/openbsd/man3/fido_dev_enable_entattest.3 new file mode 100644 index 00000000..5f2c39b3 --- /dev/null +++ b/static/openbsd/man3/fido_dev_enable_entattest.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2020 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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. +.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_cred_pin_minlen 3 , +.Xr fido_dev_get_cbor_info 3 , +.Xr fido_dev_reset 3 diff --git a/static/openbsd/man3/fido_dev_get_assert.3 b/static/openbsd/man3/fido_dev_get_assert.3 new file mode 100644 index 00000000..ab81ccb3 --- /dev/null +++ b/static/openbsd/man3/fido_dev_get_assert.3 @@ -0,0 +1,77 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.Dt FIDO_DEV_GET_ASSERT 3 +.Os +.Sh NAME +.Nm fido_dev_get_assert +.Nd obtains an assertion from a FIDO2 device +.Sh SYNOPSIS +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_dev_get_touch_begin.3 b/static/openbsd/man3/fido_dev_get_touch_begin.3 new file mode 100644 index 00000000..a6a30a54 --- /dev/null +++ b/static/openbsd/man3/fido_dev_get_touch_begin.3 @@ -0,0 +1,74 @@ +.\" Copyright (c) 2020 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_dev_info_manifest.3 b/static/openbsd/man3/fido_dev_info_manifest.3 new file mode 100644 index 00000000..5deb6bc4 --- /dev/null +++ b/static/openbsd/man3/fido_dev_info_manifest.3 @@ -0,0 +1,189 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_dev_largeblob_get.3 b/static/openbsd/man3/fido_dev_largeblob_get.3 new file mode 100644 index 00000000..f4a986bf --- /dev/null +++ b/static/openbsd/man3/fido_dev_largeblob_get.3 @@ -0,0 +1,195 @@ +.\" Copyright (c) 2020 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_dev_make_cred.3 b/static/openbsd/man3/fido_dev_make_cred.3 new file mode 100644 index 00000000..0a18f062 --- /dev/null +++ b/static/openbsd/man3/fido_dev_make_cred.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_dev_open.3 b/static/openbsd/man3/fido_dev_open.3 new file mode 100644 index 00000000..4532c36d --- /dev/null +++ b/static/openbsd/man3/fido_dev_open.3 @@ -0,0 +1,294 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_dev_set_io_functions.3 b/static/openbsd/man3/fido_dev_set_io_functions.3 new file mode 100644 index 00000000..5775b105 --- /dev/null +++ b/static/openbsd/man3/fido_dev_set_io_functions.3 @@ -0,0 +1,239 @@ +.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_dev_set_pin.3 b/static/openbsd/man3/fido_dev_set_pin.3 new file mode 100644 index 00000000..b9c94f71 --- /dev/null +++ b/static/openbsd/man3/fido_dev_set_pin.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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 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/openbsd/man3/fido_init.3 b/static/openbsd/man3/fido_init.3 new file mode 100644 index 00000000..2ba0ebc1 --- /dev/null +++ b/static/openbsd/man3/fido_init.3 @@ -0,0 +1,73 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.Dt FIDO_INIT 3 +.Os +.Sh NAME +.Nm fido_init , +.Nm fido_set_log_handler +.Nd initialise the FIDO2 library +.Sh SYNOPSIS +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/fido_strerr.3 b/static/openbsd/man3/fido_strerr.3 new file mode 100644 index 00000000..c4737cf0 --- /dev/null +++ b/static/openbsd/man3/fido_strerr.3 @@ -0,0 +1,28 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.Dt FIDO_STRERR 3 +.Os +.Sh NAME +.Nm fido_strerr +.Nd FIDO2 error codes +.Sh SYNOPSIS +.Lb libfido2 libcbor libcrypto libz +.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/openbsd/man3/flockfile.3 b/static/openbsd/man3/flockfile.3 new file mode 100644 index 00000000..eb4eb1d9 --- /dev/null +++ b/static/openbsd/man3/flockfile.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: flockfile.3,v 1.1 2025/07/25 18:27:57 tedu Exp $ +.\" +.\" Copyright (c) 2025 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 $Mdocdate: July 25 2025 $ +.Dt FLOCKFILE 3 +.Os +.Sh NAME +.Nm flockfile , +.Nm ftrylockfile , +.Nm funlockfile +.Nd locking for stdio streams +.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 +These functions provide application control over the locking of stdio streams. +.Fn flockfile +and +.Fn ftrylockfile +increment the lock count associated with +.Fa file +on behalf of the calling thread. +If another thread owns the lock, +.Fn flockfile +blocks until the lock becomes available, whereas +.Fn ftrylockfile +returns immediately and indicates failure. +.Pp +When called by a thread holding the lock, +.Fn funlockfile +decrements the lock count by one. +When the lock count reaches zero, the calling thread relinquishes +ownership of the lock. +.Pp +Functions such as +.Xr fread 3 +and +.Xr fprintf 3 +are internally thread safe by default, but additional locking may be used +to coordinate sequences of multiple calls. +.Sh RETURN VALUES +.Fn ftrylockfile +returns zero for success and non-zero for failure. +.Sh SEE ALSO +.Xr getc_unlocked 3 , +.Xr pthreads 3 , +.Xr putc_unlocked 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2024 . +.Sh HISTORY +These functions have been available since +.Ox 2.5 . +.Sh CAVEATS +Reading from one stream can flush a different buffered output stream, +leading to deadlocks. diff --git a/static/openbsd/man3/floor.3 b/static/openbsd/man3/floor.3 new file mode 100644 index 00000000..e6e50fa7 --- /dev/null +++ b/static/openbsd/man3/floor.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: floor.3,v 1.15 2025/06/07 10:33:06 schwarze Exp $ +.\" Copyright (c) 1985, 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: @(#)floor.3 6.5 (Berkeley) 4/19/91 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt FLOOR 3 +.Os +.Sh NAME +.Nm floor , +.Nm floorf , +.Nm floorl +.Nd round to largest integral value not greater than x +.Sh SYNOPSIS +.Lb libm +.In math.h +.Ft double +.Fn floor "double x" +.Ft float +.Fn floorf "float x" +.Ft long double +.Fn floorl "long double x" +.Sh DESCRIPTION +The +.Fn floor +function returns the largest integral value +less than or equal to +.Fa x . +The +.Fn floorf +function is a single precision version of +.Fn floor . +The +.Fn floorl +function is an extended precision version of +.Fn floor . +.Sh SEE ALSO +.Xr abs 3 , +.Xr ceil 3 , +.Xr fabs 3 , +.Xr nextafter 3 , +.Xr rint 3 +.Sh STANDARDS +The +.Fn floor +function conforms to +.St -ansiC . +.Sh HISTORY +A +.Fn floor +function first appeared in +.At v5 . diff --git a/static/openbsd/man3/fma.3 b/static/openbsd/man3/fma.3 new file mode 100644 index 00000000..a4d6a5f1 --- /dev/null +++ b/static/openbsd/man3/fma.3 @@ -0,0 +1,59 @@ +.\" $OpenBSD: fma.3,v 1.4 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Martynas Venckus +.\" +.\" 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: June 7 2025 $ +.Dt FMA 3 +.Os +.Sh NAME +.Nm fma , +.Nm fmaf , +.Nm fmal +.Nd floating multiply-add +.Sh SYNOPSIS +.Lb libm +.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 compute (x * y) + z, rounded as one ternary operation. +The result is rounded according to the current rounding mode. +.Sh RETURN VALUES +The +.Fn fma , +.Fn fmaf +and +.Fn fmal +functions return (x * y) + z, rounded as one ternary operation. +.Sh SEE ALSO +.Xr fegetround 3 , +.Xr remainder 3 +.Sh STANDARDS +The +.Fn fma , +.Fn fmaf +and +.Fn fmal +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/fmax.3 b/static/openbsd/man3/fmax.3 new file mode 100644 index 00000000..6a222f48 --- /dev/null +++ b/static/openbsd/man3/fmax.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: fmax.3,v 1.6 2025/10/14 06:30:16 jsg 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. +.\" +.\" $FreeBSD: src/lib/msun/man/fmax.3,v 1.2 2005/01/14 09:12:05 ru Exp $ +.\" +.Dd $Mdocdate: October 14 2025 $ +.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 SYNOPSIS +.Lb libm +.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 a NaN, then the other argument is returned. +If both arguments are NaNs, then the result is a NaN. +These routines do not raise any floating-point exceptions. +.Sh SEE ALSO +.Xr fabs 3 , +.Xr fdim 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 +.Ox 4.5 . diff --git a/static/openbsd/man3/fmemopen.3 b/static/openbsd/man3/fmemopen.3 new file mode 100644 index 00000000..782dfa34 --- /dev/null +++ b/static/openbsd/man3/fmemopen.3 @@ -0,0 +1,198 @@ +.\" $OpenBSD: fmemopen.3,v 1.5 2025/06/01 08:40:54 op Exp $ +.\" $NetBSD: fmemopen.3,v 1.5 2010/10/07 00:14:14 enami 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. 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 $Mdocdate: June 1 2025 $ +.Dt FMEMOPEN 3 +.Os +.Sh NAME +.Nm fmemopen +.Nd open a stream that points to the given buffer +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn fmemopen "void *buffer" "size_t size" "const char *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 released 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 +.Sq 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+XXX" -offset indent +.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. +.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 +.Sq + . +.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 funopen 3 , +.Xr malloc 3 , +.Xr open_memstream 3 +.Sh STANDARDS +The function +.Fn fmemopen +conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn fmemopen +function first appeared in +.Ox 5.4 . diff --git a/static/openbsd/man3/fmod.3 b/static/openbsd/man3/fmod.3 new file mode 100644 index 00000000..78390d08 --- /dev/null +++ b/static/openbsd/man3/fmod.3 @@ -0,0 +1,95 @@ +.\" $OpenBSD: fmod.3,v 1.14 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt FMOD 3 +.Os +.Sh NAME +.Nm fmod , +.Nm fmodf , +.Nm fmodl +.Nd floating-point remainder functions +.Sh SYNOPSIS +.Lb libm +.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 / Ns Fa y . +The +.Fn fmodf +function is a single precision version of +.Fn fmod . +The +.Fn fmodl +function is an extended precision version of +.Fn fmod . +.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 remainder 3 +.Sh STANDARDS +The +.Fn fmod +function conforms to +.St -ansiC . +.Sh HISTORY +An +.Fn fmod +function first appeared in +.At v5 . diff --git a/static/openbsd/man3/fmt_scaled.3 b/static/openbsd/man3/fmt_scaled.3 new file mode 100644 index 00000000..b2193f36 --- /dev/null +++ b/static/openbsd/man3/fmt_scaled.3 @@ -0,0 +1,135 @@ +.\" $OpenBSD: fmt_scaled.3,v 1.9 2025/06/06 22:01:40 schwarze Exp $ +.\" Copyright (c) 2001, 2003 Ian Darwin. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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 $Mdocdate: June 6 2025 $ +.Dt FMT_SCALED 3 +.Os +.Sh NAME +.Nm fmt_scaled , +.Nm scan_scaled +.Nd handle numbers with a human-readable scale +.Sh SYNOPSIS +.Lb libutil +.In util.h +.Ft int +.Fn scan_scaled "char *number_w_scale" "long long *result" +.Ft int +.Fn fmt_scaled "long long number" "char *result" +.Sh DESCRIPTION +The +.Fn scan_scaled +function scans the given number and looks for a terminal scale multiplier +of B, K, M, G, T, P or E +.Pq in either upper or lower case +for Byte, Kilobyte, Megabyte, Gigabyte, Terabyte, Petabyte, Exabyte +.Po computed using powers of two, i.e., Megabyte = 1024*1024 +.Pc . +The number can have a decimal point, as in 1.5K, which returns 1536 +.Pq 1024+512 . +If no scale factor is found, B is assumed. +.Pp +The +.Fn fmt_scaled +function formats a number for display using the same +"human-readable" format, that is, a number with one of the above scale factors. +Numbers will be printed with a maximum of four digits (preceded by +a minus sign if the value is negative); values such +as 0B, 100B, 1023B, 1K, 1.5K, 5.5M, and so on, will be generated. +The +.Qq result +buffer must be allocated with at least +.Dv FMT_SCALED_STRSIZE +bytes. +The result will be left-justified in the given space, and NUL-terminated. +.Sh RETURN VALUES +The +.Fn scan_scaled +and +.Fn fmt_scaled +functions +return 0 on success. +In case of error, they return \-1, leave +.Va *result +as is, and set +.Va errno +to one of the following values: +.Dv ERANGE +if the input string represents a number that is too large to represent. +.Dv EINVAL +if an unknown character was used as scale factor, or +if the input to +.Fn scan_scaled +was malformed, e.g., too many '.' characters. +.Sh EXAMPLES +.Bd -literal -offset indent +char *cinput = "1.5K"; +long long result; +if (scan_scaled(cinput, &result) == 0) + printf("%s -> %lld\en", cinput, result); +else + fprintf(stderr, "%s - invalid\en", cinput); + +char buf[FMT_SCALED_STRSIZE]; +long long ninput = 10483892; +if (fmt_scaled(ninput, buf) == 0) + printf("%lld -> %s\en", ninput, buf); +else + fprintf(stderr, "fmt scaled failed (errno %d)", errno); +.Ed +.Sh SEE ALSO +.Xr printf 3 , +.Xr scanf 3 +.Sh HISTORY +The functions +.Fn fmt_scaled +and +.Fn scan_scaled +first appeared in +.Ox 3.4 . +.Sh AUTHORS +.An -nosplit +.An Ken Stailey +wrote the first version of the code that became +.Fn fmt_scaled , +originally inside +.Ox +.Xr df 1 . +.An Ian Darwin +excerpted this and made it into a library routine +(with significant help from +.An Paul Janzen ) , +and wrote +.Fn scan_scaled . +.Sh BUGS +Some of the scale factors have misleading meanings in lower case +(p for P is incorrect; p should be pico- and P for Peta-). +However, we bend the SI rules in favor of common sense here. +A person creating a disk partition of "100m" is unlikely to require +100 millibytes (i.e., 0.1 byte) of storage in the partition; +100 megabytes is the only reasonable interpretation. +.Pp +Cannot represent the larger scale factors on all architectures. +.Pp +Ignores the current locale. diff --git a/static/openbsd/man3/fn.3 b/static/openbsd/man3/fn.3 new file mode 100644 index 00000000..9310c039 --- /dev/null +++ b/static/openbsd/man3/fn.3 @@ -0,0 +1,13 @@ +.Dd July 24, 2016 +.Dt FN 3 +.Os +.Sh NAME +.Nm \&Fn +.Nd indexing of function prototype macros +.Sh SYNOPSIS +.Ft fn_type +.Fn fn_func fn_arg +.Ft fo_type +.Fo fo_name +.Fa fo_arg +.Fc diff --git a/static/openbsd/man3/fnmatch.3 b/static/openbsd/man3/fnmatch.3 new file mode 100644 index 00000000..f04b88fc --- /dev/null +++ b/static/openbsd/man3/fnmatch.3 @@ -0,0 +1,157 @@ +.\" $OpenBSD: fnmatch.3,v 1.17 2022/07/30 07:19:30 jsg 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 $Mdocdate: July 30 2022 $ +.Dt FNMATCH 3 +.Os +.Sh NAME +.Nm fnmatch +.Nd match filename or pathname using shell globbing rules +.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 +.In fnmatch.h . +.Bl -tag -width FNM_PATHNAME +.It Dv FNM_NOESCAPE +Normally, every occurrence of a backslash +.Pq Sq \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 +.Fa string +must be explicitly matched by periods in +.Fa pattern . +If this flag is not set, then leading periods are treated as regular +characters. +The definition of +.Dq leading +is related to the specification of +.Dv FNM_PATHNAME . +A period is always leading +if it is the first character in +.Fa string . +Additionally, if +.Dv FNM_PATHNAME +is set, +a period is leading +if it immediately follows a slash. +.It Dv FNM_LEADING_DIR +Ignore +.Sq /* +rest after successful +.Fa pattern +matching. +.It Dv FNM_CASEFOLD +Ignore case distinctions in both the +.Fa pattern +and the +.Fa string . +.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 +and +.St -xpg4.2 . +.Pp +Note, however, that the flags +.Dv FNM_LEADING_DIR +and +.Dv FNM_CASEFOLD +are extensions and should not be used by applications striving for +strict standards conformance. +.Sh HISTORY +A predecessor to +.Fn fnmatch , +.Fn gmatch , +first appeared in the Programmer's Workbench (PWB/UNIX). +The +.Fn fnmatch +function first appeared in +.Bx 4.3 Reno . +.Sh BUGS +The pattern +.Ql * +matches the empty string, even if +.Dv FNM_PATHNAME +is specified. diff --git a/static/openbsd/man3/fopen.3 b/static/openbsd/man3/fopen.3 new file mode 100644 index 00000000..5a56e54f --- /dev/null +++ b/static/openbsd/man3/fopen.3 @@ -0,0 +1,300 @@ +.\" $OpenBSD: fopen.3,v 1.33 2023/09/28 01:51:00 jsg 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. +.\" +.Dd $Mdocdate: September 28 2023 $ +.Dt FOPEN 3 +.Os +.Sh NAME +.Nm fopen , +.Nm fdopen , +.Nm freopen +.Nd stream open functions +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn fopen "const char *path" "const char *mode" +.Ft FILE * +.Fn fdopen "int fildes" "const char *mode" +.Ft FILE * +.Fn freopen "const char *path" "const char *mode" "FILE *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 (additional characters may follow these sequences): +.Bl -tag -width indent +.It Do Li r Dc or Do Li rb Dc +Open file for reading. +.It Do Li r+ Dc or Do Li rb+ Dc or Do Li r+b Dc +Open for reading and writing. +.It Do Li w Dc or Do Li wb Dc +Open for writing. +The file is created if it does not exist, otherwise it is truncated. +.It Do Li w+ Dc or Do Li wb+ Dc or Do Li w+b Dc +Open for reading and writing. +The file is created if it does not exist, otherwise it is truncated. +.It Do Li a Dc or Do Li ab Dc +Open for writing. +The file is created if it does not exist. +.It Do Li a+ Dc or Do Li ab+ Dc or Do Li a+b Dc +Open for reading and writing. +The file is created if it does not exist. +.El +.Pp +The letter +.Dq b +in the +.Fa mode +strings above is strictly for compatibility with +.St -ansiC +and has no effect; the +.Dq b +is ignored. +.Pp +After any of the above prefixes, the +.Fa mode +string can also include zero or more of the following: +.Bl -tag -width indent +.It Dq Li e +The close-on-exec flag is set on the underlying file descriptor of the new +.Vt FILE . +.It Dq Li x +If the +.Fa mode +string starts with +.Dq w +or +.Dq a +then the function shall fail if the file specified by +.Fa path +already exists, as if the +.Dv O_EXCL +flag was passed to the +.Xr open 2 +function. +It has no effect if used with +.Fn fdopen +or the +.Fa mode +string begins with +.Dq r . +.El +.Pp +The +.Fn fopen +and +.Fn freopen +functions initially position the stream at the start of the file +unless the file is opened in append mode +.Po +.Sq a +or +.Sq a+ +.Pc , +in which case the stream is initially positioned at the end of the file. +.Pp +Opening a file in append mode causes all subsequent writes to it +to be forced to the current end-of-file, regardless of intervening +repositioning of the stream. +.Pp +Any created files will have mode +.Qq Dv S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH +.Pq Li 0666 , +as modified by the process' +umask value (see +.Xr umask 2 ) . +.Pp +Reads and writes cannot be arbitrarily intermixed on read/write streams. +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. +If +.Fn fdopen +fails, the file descriptor +.Fa fildes +is not affected in any way. +.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 always closed, even if +.Fn freopen +fails. +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 ) . +.Sh RETURN VALUES +Upon successful completion, +.Fn fopen , +.Fn fdopen , +and +.Fn freopen +return a +.Vt 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 mode +provided to +.Fn fopen , +.Fn fdopen , +or +.Fn freopen +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 fseek 3 , +.Xr funopen 3 +.Sh STANDARDS +The +.Fn fopen +and +.Fn freopen +functions conform to +.St -ansiC . +The +.Fn fdopen +function conforms to +.St -p1003.1-88 . +.Sh HISTORY +The +.Fn fopen +function first appeared in +.At v1 . +The +.Fn fdopen +and +.Fn freopen +functions first appeared in +.At v7 . +.Pp +Support for the +.Dq e +and +.Dq x +mode letters appeared in +.Ox 5.7 . +.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 +.Vt 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/openbsd/man3/form.3 b/static/openbsd/man3/form.3 new file mode 100644 index 00000000..da81ab19 --- /dev/null +++ b/static/openbsd/man3/form.3 @@ -0,0 +1,245 @@ +'\" t +.\" $OpenBSD: form.3,v 1.7 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form.3,v 1.7 2023/10/17 09:52:10 nicm Exp $ +.TH form 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBform\fP \- curses extension for programming forms +.SH SYNOPSIS +\fB#include \fP +.SH DESCRIPTION +The \fBform\fP library provides terminal-independent facilities for composing +form screens on character-cell terminals. +The library includes: field +routines, which create and modify form fields; and form routines, which group +fields into forms, display forms on the screen, and handle interaction with the +user. +.PP +The \fBform\fP library uses the \fBcurses\fP libraries. +To use the \fBform\fP library, link with the options +\fB\-lform \-lcurses\fP. +.PP +Your program should set up the locale, e.g., +.sp + \fBsetlocale(LC_ALL, "");\fP +.sp +so that input/output processing will work. +.PP +A curses initialization routine such as \fBinitscr\fP must be called +before using any of these functions. +. +.SS Current Default Values for Field Attributes +. +The \fBform\fP library maintains a default value for field attributes. +You +can get or set this default by calling the appropriate \fBset_\fP +or retrieval +routine with a \fBNULL\fP field pointer. +Changing this default with a +\fBset_\fP function affects future field creations, but does not change the +rendering of fields already created. +. +.SS Routine Name Index +. +The following table lists each \fBform\fP routine and the name of +the manual page on which it is described. +Routines flagged with \*(``*\*('' +are ncurses-specific, not present in SVr4. +.PP +.TS +l l +l l . +\fBcurses\fP Routine Name Manual Page Name += +current_field \fBform_page\fP(3) +data_ahead \fBform_data\fP(3) +data_behind \fBform_data\fP(3) +dup_field \fBform_field_new\fP(3) +dynamic_field_info \fBform_field_info\fP(3) +field_arg \fBform_field_validation\fP(3) +field_back \fBform_field_attributes\fP(3) +field_buffer \fBform_field_buffer\fP(3) +field_count \fBform_field\fP(3) +field_fore \fBform_field_attributes\fP(3) +field_index \fBform_page\fP(3) +field_info \fBform_field_info\fP(3) +field_init \fBform_hook\fP(3) +field_just \fBform_field_just\fP(3) +field_opts \fBform_field_opts\fP(3) +field_opts_off \fBform_field_opts\fP(3) +field_opts_on \fBform_field_opts\fP(3) +field_pad \fBform_field_attributes\fP(3) +field_status \fBform_field_buffer\fP(3) +field_term \fBform_hook\fP(3) +field_type \fBform_field_validation\fP(3) +field_userptr \fBform_field_userptr\fP(3) +form_driver \fBform_driver\fP(3) +form_driver_w \fBform_driver\fP(3)* +form_fields \fBform_field\fP(3) +form_init \fBform_hook\fP(3) +form_opts \fBform_opts\fP(3) +form_opts_off \fBform_opts\fP(3) +form_opts_on \fBform_opts\fP(3) +form_page \fBform_page\fP(3) +form_request_by_name \fBform_requestname\fP(3)* +form_request_name \fBform_requestname\fP(3)* +form_sub \fBform_win\fP(3) +form_term \fBform_hook\fP(3) +form_userptr \fBform_userptr\fP(3) +form_win \fBform_win\fP(3) +free_field \fBform_field_new\fP(3) +free_fieldtype \fBform_fieldtype\fP(3) +free_form \fBform_new\fP(3) +link_field \fBform_field_new\fP(3) +link_fieldtype \fBform_fieldtype\fP(3) +move_field \fBform_field\fP(3) +new_field \fBform_field_new\fP(3) +new_fieldtype \fBform_fieldtype\fP(3) +new_form \fBform_new\fP(3) +new_page \fBform_new_page\fP(3) +pos_form_cursor \fBform_cursor\fP(3) +post_form \fBform_post\fP(3) +scale_form \fBform_win\fP(3) +set_current_field \fBform_page\fP(3) +set_field_back \fBform_field_attributes\fP(3) +set_field_buffer \fBform_field_buffer\fP(3) +set_field_fore \fBform_field_attributes\fP(3) +set_field_init \fBform_hook\fP(3) +set_field_just \fBform_field_just\fP(3) +set_field_opts \fBform_field_opts\fP(3) +set_field_pad \fBform_field_attributes\fP(3) +set_field_status \fBform_field_buffer\fP(3) +set_field_term \fBform_hook\fP(3) +set_field_type \fBform_field_validation\fP(3) +set_field_userptr \fBform_field_userptr\fP(3) +set_fieldtype_arg \fBform_fieldtype\fP(3) +set_fieldtype_choice \fBform_fieldtype\fP(3) +set_form_fields \fBform_field\fP(3) +set_form_init \fBform_hook\fP(3) +set_form_opts \fBform_field_opts\fP(3) +set_form_page \fBform_page\fP(3) +set_form_sub \fBform_win\fP(3) +set_form_term \fBform_hook\fP(3) +set_form_userptr \fBform_userptr\fP(3) +set_form_win \fBform_win\fP(3) +set_max_field \fBform_field_buffer\fP(3) +set_new_page \fBform_new_page\fP(3) +unfocus_current_field \fBform_page\fP(3)* +unpost_form \fBform_post\fP(3) +.TE +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fP on error, +and set \fBerrno\fP to the corresponding error-code returned by functions +returning an integer. +Routines that return +an integer return one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_CONNECTED +The field is already connected to a form. +.TP 5 +.B E_INVALID_FIELD +Contents of a field are not valid. +.TP 5 +.B E_NOT_CONNECTED +No fields are connected to the form. +.TP 5 +.B E_NOT_POSTED +The form has not been posted. +.TP 5 +.B E_NO_ROOM +Form is too large for its window. +.TP 5 +.B E_POSTED +The form is already posted. +.TP 5 +.B E_REQUEST_DENIED +The form driver could not process the request. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_UNKNOWN_COMMAND +The form driver code saw an unknown request code. +.SH NOTES +The header file \fB\fP automatically includes the header files +\fB\fP and \fB\fP. +.PP +In your library list, libform.a should be before libncurses.a; that is, +you want to say \*(``\-lform \-lncurses\*('', not the other way around +(which would give you a link error when using static libraries). +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.PP +The menu facility was documented in SVr4.2 in +\fICharacter User Interface Programming (UNIX SVR4.2)\fP. +.PP +It is not part of X/Open Curses. +.PP +Aside from ncurses, there are few implementations: +.bP +systems based on SVr4 source code, e.g., Solaris. +.bP +NetBSD curses. +.PP +A few functions in this implementation are extensions added for ncurses, +but not provided by other implementations, e.g., +\fBform_driver_w\fP, +\fBunfocus_current_field\fP. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for ncurses by Eric +S. Raymond. +.SH SEE ALSO +\fBcurses\fP(3) and related pages whose names begin \*(``form_\*('' for detailed +descriptions of the entry points. +.PP +This describes \fBncurses\fP +version 6.4 (patch 20230826). diff --git a/static/openbsd/man3/form_cursor.3 b/static/openbsd/man3/form_cursor.3 new file mode 100644 index 00000000..4aea1cfd --- /dev/null +++ b/static/openbsd/man3/form_cursor.3 @@ -0,0 +1,73 @@ +'\" t +.\" $OpenBSD: form_cursor.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_cursor.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH form_cursor 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBpos_form_cursor\fP \- position a form window cursor +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint pos_form_cursor(FORM *\fIform\fB);\fR +.SH DESCRIPTION +The function \fBpos_form_cursor\fP restores the cursor to the position required +for the forms driver to continue processing requests. +This is useful after +\fBcurses\fP routines have been called to do screen-painting in response to a +form operation. +.SH RETURN VALUE +This routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_NOT_POSTED +The form has not been posted. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +. +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_data.3 b/static/openbsd/man3/form_data.3 new file mode 100644 index 00000000..d9d69dea --- /dev/null +++ b/static/openbsd/man3/form_data.3 @@ -0,0 +1,63 @@ +'\" t +.\" $OpenBSD: form_data.3,v 1.13 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_data.3,v 1.13 2023/10/17 09:52:10 nicm Exp $ +.TH form_data 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBdata_ahead\fP, +\fBdata_behind\fP \- test for off-screen data in given forms +.SH SYNOPSIS +\fB#include \fP +.sp +\fBbool data_ahead(const FORM *\fIform\fB);\fR +.br +\fBbool data_behind(const FORM *\fIform\fB);\fR +.SH DESCRIPTION +The function \fBdata_ahead\fP tests whether there is off-screen data +ahead in the given form. +It returns TRUE (1) or FALSE (0). +.PP +The function \fBdata_behind\fP tests whether there is off-screen data +behind in the given form. +It returns TRUE (1) or FALSE (0). +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_driver.3 b/static/openbsd/man3/form_driver.3 new file mode 100644 index 00000000..22324800 --- /dev/null +++ b/static/openbsd/man3/form_driver.3 @@ -0,0 +1,269 @@ +'\" t +.\" $OpenBSD: form_driver.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_driver.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH form_driver 3 2023-08-19 "ncurses 6.4" "Library calls" +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBform_driver\fP, +\fBform_driver_w\fP \- command-processing loop of the form system +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint form_driver(FORM *\fIform\fB, int \fIc\fB);\fR +.br +\fBint form_driver_w(FORM *\fIform\fB, int \fIc\fB, wchar_t \fIwch\fB);\fR +.SH DESCRIPTION +.SS form_driver +Once a form has been posted (displayed), you should funnel input events to it +through \fBform_driver\fP. This routine has three major input cases: +.bP +The input is a form navigation request. +Navigation request codes are constants defined in \fB\fP, +which are distinct from the key- and character codes returned +by \fBwgetch\fP(3). +.bP +The input is a printable character. +Printable characters (which must be positive, less than 256) are +checked according to the program's locale settings. +.bP +The input is the KEY_MOUSE special key associated with an mouse event. +.SS form_driver_w +This extension simplifies the use of the forms library using wide characters. +The input is either a key code (a request) or a wide character +returned by \fBget_wch\fP(3). +The type must be passed as well, +to enable the library to determine whether the parameter +is a wide character or a request. +.SS Form-driver requests +The form driver requests are as follows: +.PP +.TS +l l +_ _ +l l. +\fBName\fP \fBDescription\fP +REQ_BEG_FIELD Move to the beginning of the field. +REQ_BEG_LINE Move to the beginning of the line. +REQ_CLR_EOF Clear to end of field from cursor. +REQ_CLR_EOL Clear to end of line from cursor. +REQ_CLR_FIELD Clear the entire field. +REQ_DEL_CHAR Delete character at the cursor. +REQ_DEL_LINE Delete line at the cursor. +REQ_DEL_PREV Delete character before the cursor. +REQ_DEL_WORD Delete blank-delimited word at the cursor. +REQ_DOWN_CHAR Move down in the field. +REQ_DOWN_FIELD Move down to a field. +REQ_END_FIELD Move to the end of the field. +REQ_END_LINE Move to the end of the line. +REQ_FIRST_FIELD Move to the first field. +REQ_FIRST_PAGE Move to the first page. +REQ_INS_CHAR Insert a blank at the cursor. +REQ_INS_LINE Insert a blank line at the cursor. +REQ_INS_MODE Enter insert mode. +REQ_LAST_FIELD Move to the last field. +REQ_LAST_PAGE Move to the last field. +REQ_LEFT_CHAR Move left in the field. +REQ_LEFT_FIELD Move left to a field. +REQ_NEW_LINE Insert or overlay a new line. +REQ_NEXT_CHAR Move to the next char. +REQ_NEXT_CHOICE Display next field choice. +REQ_NEXT_FIELD Move to the next field. +REQ_NEXT_LINE Move to the next line. +REQ_NEXT_PAGE Move to the next page. +REQ_NEXT_PAGE Move to the next page. +REQ_NEXT_WORD Move to the next word. +REQ_OVL_MODE Enter overlay mode. +REQ_PREV_CHAR Move to the previous char. +REQ_PREV_CHOICE Display previous field choice. +REQ_PREV_FIELD Move to the previous field. +REQ_PREV_LINE Move to the previous line. +REQ_PREV_PAGE Move to the previous page. +REQ_PREV_WORD Move to the previous word. +REQ_RIGHT_CHAR Move right in the field. +REQ_RIGHT_FIELD Move right to a field. +REQ_SCR_BCHAR Scroll the field backward a character. +REQ_SCR_BHPAGE Scroll the field backward half a page. +REQ_SCR_BLINE Scroll the field backward a line. +REQ_SCR_BPAGE Scroll the field backward a page. +REQ_SCR_FCHAR Scroll the field forward a character. +REQ_SCR_FHPAGE Scroll the field forward half a page. +REQ_SCR_FLINE Scroll the field forward a line. +REQ_SCR_FPAGE Scroll the field forward a page. +REQ_SCR_HBHALF Horizontal scroll the field backward half a line. +REQ_SCR_HBLINE Horizontal scroll the field backward a line. +REQ_SCR_HFHALF Horizontal scroll the field forward half a line. +REQ_SCR_HFLINE Horizontal scroll the field forward a line. +REQ_SFIRST_FIELD Move to the sorted first field. +REQ_SLAST_FIELD Move to the sorted last field. +REQ_SNEXT_FIELD Move to the sorted next field. +REQ_SPREV_FIELD Move to the sorted previous field. +REQ_UP_CHAR Move up in the field. +REQ_UP_FIELD Move up to a field. +REQ_VALIDATION Validate field. +.TE +.PP +If the second argument is a printable character, the driver places it +in the current position in the current field. +If it is one of the forms +requests listed above, that request is executed. +.SS Field validation +The form library makes updates to the window associated +with form fields rather than directly to the field buffers. +.PP +The form driver provides low-level control over updates to the form fields. +The form driver also provides for validating modified fields +to ensure that the contents +meet whatever constraints an application may attach using \fBset_field_type\fP. +.PP +You can validate a field without making any changes to it using +\fBREQ_VALIDATION\fP. +The form driver also validates a field in these cases: +.bP +a call to \fBset_current_field\fP attempts to move to a different field. +.bP +a call to \fBset_current_page\fP attempts to move +to a different page of the form. +.bP +a request attempts to move to a different field. +.bP +a request attempts to move to a different page of the form. +.PP +In each case, the move fails if the field is invalid. +.PP +If the modified field is valid, the form driver copies the modified +data from the window associated with the field +to the field buffer. +.SS Mouse handling +If the second argument is the KEY_MOUSE special key, the associated +mouse event is translated into one of the above pre-defined requests. +Currently only clicks in the user window (e.g., inside the form display +area or the decoration window) are handled. +.PP +If you click above the display region of the form: +.RS 3 +.TP +a REQ_PREV_FIELD is generated for a single click, +.TP +a REQ_PREV_PAGE is generated for a double-click and +.TP +a REQ_FIRST_FIELD is generated for a triple-click. +.RE +.PP +If you click below the display region of the form: +.RS 3 +.TP +a REQ_NEXT_FIELD is generated for a single click, +.TP +a REQ_NEXT_PAGE is generated for a double-click and +.TP +a REQ_LAST_FIELD is generated for a triple-click. +.RE +.PP +If you click at an field inside the display area of the form: +.RS 3 +.bP +the form cursor is positioned to that field. +.bP +If you double-click a field, +the form cursor is positioned to that field +and \fBE_UNKNOWN_COMMAND\fP is returned. +This return value makes sense, +because a double click usually means that an field-specific action should +be returned. +It is exactly the purpose of this return value to signal that an +application specific command should be executed. +.bP +If a translation +into a request was done, \fBform_driver\fP returns the result of this request. +.RE +.PP +If you clicked outside the user window +or the mouse event could not be translated +into a form request an \fBE_REQUEST_DENIED\fP is returned. +.SS Application-defined commands +If the second argument is neither printable nor one of the above +pre-defined form requests, the driver assumes it is an application-specific +command and returns \fBE_UNKNOWN_COMMAND\fP. Application-defined commands +should be defined relative to \fBMAX_COMMAND\fP, the maximum value of these +pre-defined requests. +.SH RETURN VALUE +\fBform_driver\fP returns one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NOT_POSTED +The form has not been posted. +.TP 5 +.B E_INVALID_FIELD +Contents of field is invalid. +.TP 5 +.B E_NOT_CONNECTED +No fields are connected to the form. +.TP 5 +.B E_REQUEST_DENIED +The form driver could not process the request. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_UNKNOWN_COMMAND +The form driver code saw an unknown request code. +. +.SH SEE ALSO +\fBcurses\fP(3), +\fBform\fP(3), +\fBform_fieldtype\fP(3), +\fBform_field_buffer\fP(3), +\fBform_field_validation\fP(3), +\fBform_variables\fP(3), +\fBgetch\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header files +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_field.3 b/static/openbsd/man3/form_field.3 new file mode 100644 index 00000000..0f384611 --- /dev/null +++ b/static/openbsd/man3/form_field.3 @@ -0,0 +1,95 @@ +'\" t +.\" $OpenBSD: form_field.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2012 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.TH form_field 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBform_field\fP \- make and break connections between fields and forms +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_form_fields(FORM *\fIform\fB, FIELD **\fIfields\fB);\fR +.br +\fBFIELD **form_fields(const FORM *\fIform\fB);\fR +.br +\fBint field_count(const FORM *\fIform\fB);\fR +.br +\fBint move_field(FIELD *\fIfield\fB, int \fIfrow\fB, int \fIfcol\fB);\fR +.SH DESCRIPTION +The function \fBset_form_fields\fP changes the field pointer array of +the given \fIform\fP. The array must be terminated by a \fBNULL\fP. +.PP +The function \fBform_fields\fP returns the field array of the given form. +.PP +The function \fBfield_count\fP returns the count of fields in \fIform\fP. +.PP +The function \fBmove_field\fP moves the given field (which must be disconnected) +to a specified location on the screen. +.SH RETURN VALUE +The function \fBform_fields\fP returns a pointer (which may be \fBNULL\fP). +It does not set \fBerrno\fP. +.PP +The function \fBfield_count\fP returns \fBERR\fP if the \fIform\fP parameter +is \fBNULL\fP. +.PP +The functions \fBset_form_fields\fP and \fBmove_field\fP return one of +the following codes on error: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CONNECTED +The field is already connected to a form. +.TP 5 +.B E_POSTED +The form is already posted. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.PP +The SVr4 forms library documentation specifies the \fBfield_count\fP error value +as \-1 (which is the value of \fBERR\fP). +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_field_attributes.3 b/static/openbsd/man3/form_field_attributes.3 new file mode 100644 index 00000000..062f64ff --- /dev/null +++ b/static/openbsd/man3/form_field_attributes.3 @@ -0,0 +1,97 @@ +'\" t +.\" $OpenBSD: form_field_attributes.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2006,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_attributes.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.TH form_field_attributes 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBform_field_attributes\fP \- color and attribute control for form fields +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_field_fore(FIELD *\fIfield\fB, chtype \fIattr\fB);\fR +.br +\fBchtype field_fore(const FIELD *\fIfield\fB);\fR +.sp +\fBint set_field_back(FIELD *\fIfield\fB, chtype \fIattr\fB);\fR +.br +\fBchtype field_back(const FIELD *\fIfield\fB);\fR +.sp +\fBint set_field_pad(FIELD *\fIfield\fB, int \fIpad\fB);\fR +.br +\fBint field_pad(const FIELD *\fIfield\fB);\fR +.SH DESCRIPTION +The function \fBset_field_fore\fP sets the foreground attribute of +\fIfield\fP. This is the highlight used to display the field contents. The +function \fBfield_fore\fP returns the foreground attribute. +The default is +\fBA_STANDOUT\fP. +.PP +The function \fBset_field_back\fP sets the background attribute of +\fIform\fP. This is the highlight used to display the extent fields in the +form. +The function \fBfield_back\fP returns the background attribute. +The +default is \fBA_NORMAL\fP. +.PP +The function \fBset_field_pad\fP sets the character used to fill the field. +The function \fBfield_pad\fP returns the given form's pad character. +The +default is a blank. +.SH RETURN VALUE +These routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +. +.SH SEE ALSO +\fBcurses\fP(3) and related pages whose names begin \*(``form_\*('' for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_field_buffer.3 b/static/openbsd/man3/form_field_buffer.3 new file mode 100644 index 00000000..23f2df90 --- /dev/null +++ b/static/openbsd/man3/form_field_buffer.3 @@ -0,0 +1,145 @@ +'\" t +.\" $OpenBSD: form_field_buffer.3,v 1.14 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_buffer.3,v 1.14 2023/10/17 09:52:10 nicm Exp $ +.TH form_field_buffer 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBform_field_buffer\fP \- field buffer control +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_field_buffer(FIELD *\fIfield\fB, int \fIbuf\fB, const char *\fIvalue\fB);\fR +.br +\fBchar *field_buffer(const FIELD *\fIfield\fB, int \fIbuffer\fB);\fR +.sp +\fBint set_field_status(FIELD *\fIfield\fB, bool \fIstatus\fB);\fR +.br +\fBbool field_status(const FIELD *\fIfield\fB);\fR +.sp +\fBint set_max_field(FIELD *\fIfield\fB, int \fImax\fB);\fR +.SH DESCRIPTION +The function \fBset_field_buffer\fP sets the numbered buffer of the given field +to contain a given string: +.RS 3 +.bP +Buffer 0 is the displayed value of the field. +.bP +Other numbered buffers may be allocated by applications through the \fBnbuf\fP +argument of (see \fBform_field_new\fP(3)) +but are not manipulated by the forms library. +.RE +.PP +The function \fBfield_buffer\fP returns a pointer to +the contents of the given numbered buffer: +.RS 3 +.bP +The buffer contents always have the same length, +and are padded with trailing spaces +as needed to ensure this length is the same. +.bP +The buffer may contain leading spaces, depending on how it was set. +.bP +The buffer contents are set with \fBset_field_buffer\fP, +or as a side effect of any editing operations on the corresponding field. +.bP +Editing operations are based on the \fIwindow\fP which displays the field, +rather than a \fIstring\fP. +The window contains only printable characters, and is filled with blanks. +If you want the raw data, you must write your +own routine that copies the value out of the buffer and removes the leading +and trailing spaces. +.bP +Because editing operations change the content of the buffer to +correspond to the window, you should not rely on using buffers +for long-term storage of form data. +.RE +.PP +The function \fBset_field_status\fP sets the associated status flag of +\fIfield\fP; \fBfield_status\fP gets the current value. +The status flag +is set to a nonzero value whenever the field changes. +.PP +The function \fBset_max_field\fP sets the maximum size for a dynamic field. +An argument of 0 turns off any maximum size threshold for that field. +.SH RETURN VALUE +The \fBfield_buffer\fP function returns NULL on error. +It sets \fBerrno\fP according to their success: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.PP +The \fBfield_status\fP function returns \fBTRUE\fP or \fBFALSE\fP. +.PP +The remaining routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.SH SEE ALSO +\fBcurses\fP(3) and related pages whose names begin \*(``form_\*('' for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB\fP automatically includes the header file +.PP +When configured for wide characters, \fBfield_buffer\fP returns a pointer +to temporary storage (allocated and freed by the library). +The application should not attempt to modify the data. +It will be freed on the next call to \fBfield_buffer\fP to return the +same buffer. +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.PP +The \fBset_max_field\fP function checks for an ncurses extension +\fBO_INPUT_FIELD\fP which allows a dynamic field to shrink if the new +limit is smaller than the current field size. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_field_info.3 b/static/openbsd/man3/form_field_info.3 new file mode 100644 index 00000000..529c4d12 --- /dev/null +++ b/static/openbsd/man3/form_field_info.3 @@ -0,0 +1,94 @@ +'\" t +.\" $OpenBSD: form_field_info.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_info.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.TH form_field_info 3 2022-02-12 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBdynamic_field_info\fP, +\fBfield_info\fP \- retrieve field characteristics +.SH SYNOPSIS +.nf +\fB#include \fP +.sp +\fBint field_info(const FIELD *\fIfield\fB,\fR + \fBint *\fIrows\fB, int *\fIcols\fB,\fR + \fBint *\fIfrow\fB, int *\fIfcol\fB,\fR + \fBint *\fInrow\fB, int *\fInbuf\fB);\fR +.sp +\fBint dynamic_field_info(const FIELD *\fIfield\fB,\fR + \fBint *\fIrows\fB, int *\fIcols\fB, int *\fImax\fB);\fR +.fi +.SH DESCRIPTION +The function \fBfield_info\fP returns the sizes and other attributes passed in +to the field at its creation time. +The attributes are: height, width, row of +upper-left corner, column of upper-left corner, number off-screen rows, and +number of working buffers. +.PP +The function \fBdynamic_field_info\fP returns the actual size of the field, and +its maximum possible size. +If the field has no size limit, the location +addressed by the third argument will be set to 0. +A field can be made dynamic +by turning off the \fBO_STATIC\fP option with \fBfield_opts_off\fP. +.SH RETURN VALUE +These routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.SH SEE ALSO +\fBcurses\fP(3) and related pages whose names begin \*(``form_\*('' for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.PP +A null (zero pointer) is accepted for any of the return values, +to ignore that value. +Not all implementations allow this, e.g., Solaris 2.7 does not. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_field_just.3 b/static/openbsd/man3/form_field_just.3 new file mode 100644 index 00000000..9415e175 --- /dev/null +++ b/static/openbsd/man3/form_field_just.3 @@ -0,0 +1,80 @@ +'\" t +.\" $OpenBSD: form_field_just.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_just.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.TH form_field_just 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBset_field_just\fP, +\fBfield_just\fP \- retrieve field characteristics +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_field_just(FIELD *\fIfield\fB, int \fIjustification\fB);\fR +.br +\fBint field_just(const FIELD *\fIfield\fB);\fR +.SH DESCRIPTION +The function \fBset_field_just\fP sets the justification attribute of +a field; \fBfield_just\fP returns a field's justification attribute. +The attribute may be one of NO_JUSTIFICATION, JUSTIFY_RIGHT, +JUSTIFY_LEFT, or JUSTIFY_CENTER. +. +.SH RETURN VALUE +The function \fBfield_just\fP returns one of: NO_JUSTIFICATION, +JUSTIFY_RIGHT, JUSTIFY_LEFT, or JUSTIFY_CENTER. +.PP +The function \fBset_field_just\fP returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.SH SEE ALSO +\fBcurses\fP(3) and related pages whose names begin \*(``form_\*('' for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_field_new.3 b/static/openbsd/man3/form_field_new.3 new file mode 100644 index 00000000..f349be63 --- /dev/null +++ b/static/openbsd/man3/form_field_new.3 @@ -0,0 +1,109 @@ +'\" t +.\" $OpenBSD: form_field_new.3,v 1.12 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_new.3,v 1.12 2023/10/17 09:52:10 nicm Exp $ +.TH form_field_new 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBnew_field\fP, +\fBdup_field\fP, +\fBlink_field\fP, +\fBfree_field\fP \- create and destroy form fields +.SH SYNOPSIS +\fB#include \fP +.sp +\fBFIELD *new_field(int \fIheight\fB, int \fIwidth\fB,\fR + \fBint \fItoprow\fB, int \fIleftcol\fB,\fR + \fBint \fIoffscreen\fB, int \fInbuffers\fB);\fR +.br +\fBFIELD *dup_field(FIELD *\fIfield\fB, int \fItoprow\fB, int \fIleftcol\fB);\fR +.br +\fBFIELD *link_field(FIELD *\fIfield\fB, int \fItoprow\fB, int \fIleftcol\fB);\fR +.br +\fBint free_field(FIELD *\fIfield\fB);\fR +.SH DESCRIPTION +The function \fBnew_field\fP allocates a new field and initializes it from the +parameters given: height, width, row of upper-left corner, column of upper-left +corner, number off-screen rows, and number of additional working buffers. +.PP +The function \fBdup_field\fP duplicates a field at a new location. +Most +attributes (including current contents, size, validation type, buffer count, +growth threshold, justification, foreground, background, pad character, +options, and user pointer) are copied. +Field status and the field page bit are +not copied. +.PP +The function \fBlink_field\fP acts like \fBdup_field\fP, but the new field +shares buffers with its parent. +Attribute data is separate. +.PP +The function \fBfree_field\fP de-allocates storage associated with a field. +.SH RETURN VALUE +The functions \fBnew_field\fP, \fBdup_field\fP, \fBlink_field\fP return +\fBNULL\fP on error. +They set \fBerrno\fP according to their success: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred, e.g., malloc failure. +.PP +The function \fBfree_field\fP returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CONNECTED +field is connected. +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.PP +It may be unwise to count on the set of attributes copied by +\fBdup_field\fP being portable; the System V forms library documents are +not very explicit about what gets copied and what does not. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_field_opts.3 b/static/openbsd/man3/form_field_opts.3 new file mode 100644 index 00000000..1f156eb5 --- /dev/null +++ b/static/openbsd/man3/form_field_opts.3 @@ -0,0 +1,151 @@ +'\" t +.\" $OpenBSD: form_field_opts.3,v 1.13 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2014,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_opts.3,v 1.13 2023/10/17 09:52:10 nicm Exp $ +.TH form_field_opts 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_field_opts\fP, +\fBfield_opts_on\fP, +\fBfield_opts_off\fP, +\fBfield_opts\fP \- set and get field options +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_field_opts(FIELD *\fIfield\fB, Field_Options \fIopts\fB);\fR +.br +\fBField_Options field_opts(const FIELD *\fIfield\fB);\fR +.sp +\fBint field_opts_on(FIELD *\fIfield\fB, Field_Options \fIopts\fB);\fR +.br +\fBint field_opts_off(FIELD *\fIfield\fB, Field_Options \fIopts\fB);\fR +.SH DESCRIPTION +The function \fBset_field_opts\fP sets all the given field's option bits (field +option bits may be logically-OR'ed together). +.PP +The function \fBfield_opts_on\fP turns on the given option bits, and leaves +others alone. +.PP +The function \fBfield_opts_off\fP turns off the given option bits, and leaves +others alone. +.PP +The function \fBfield_opts\fP returns the field's current option bits. +.PP +The following standard options are defined (all are on by default): +.TP 5 +O_ACTIVE +The field is visited during processing. +If this option is off, the field will +not be reachable by navigation keys. +Please notice that an invisible field +appears to be inactive also. +.TP 5 +O_AUTOSKIP +Skip to the next field when this one fills. +.TP 5 +O_BLANK +The field is cleared whenever a character is entered at the first position. +.TP 5 +O_EDIT +The field can be edited. +.TP 5 +O_NULLOK +Allow a blank field. +.TP 5 +O_PASSOK +Validate field only if modified by user. +.TP 5 +O_PUBLIC +The field contents are displayed as data is entered. +.TP 5 +O_STATIC +Field buffers are fixed to field's original size. +Turn this option off to create a dynamic field. +.TP 5 +O_VISIBLE +The field is displayed. +If this option is off, display of the field is +suppressed. +.TP 5 +O_WRAP +Words that do not fit on a line are wrapped to the next line. +Words are +blank-separated. +.PP +These extension options are defined (extensions are off by default): +.TP 5 +O_DYNAMIC_JUSTIFY +Permit dynamic fields to be justified, like static fields. +.TP 5 +O_NO_LEFT_STRIP +Preserve leading whitespace in the field buffer, which is normally discarded. +.TP 5 +O_EDGE_INSERT_STAY +When inserting into a field up to the boundary position, +optionally delay the scrolling, +so that the last inserted character remains visible, +but advance the cursor to reflect the insertion. +This allows the form library to display the +inserted character in one-character fields +as well as allowing the library to maintain consistent state. +.TP 5 +O_INPUT_FIELD +The \fBset_max_field\fP function checks for this extension, +which allows a dynamic field to shrink if the new +limit is smaller than the current field size. +.SH RETURN VALUE +Except for \fBfield_opts\fP, each routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CURRENT +The field is the current field. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), +\fBform\fP(3). +\fBform_field_just\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_field_userptr.3 b/static/openbsd/man3/form_field_userptr.3 new file mode 100644 index 00000000..83e54b58 --- /dev/null +++ b/static/openbsd/man3/form_field_userptr.3 @@ -0,0 +1,68 @@ +'\" t +.\" $OpenBSD: form_field_userptr.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_userptr.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.TH form_field_userptr 3 2022-02-12 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_field_userptr\fP, +\fBfield_userptr\fP \- associate application data with a form field +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_field_userptr(FIELD *\fIfield\fB, void *\fIuserptr\fB);\fR +.br +\fBvoid *field_userptr(const FIELD *\fIfield\fB);\fR +.SH DESCRIPTION +Every form field has a field that can be used to hold application-specific data +(that is, the form-driver code leaves it alone). +These functions get and set +that field. +.SH RETURN VALUE +The function \fBfield_userptr\fP returns a pointer (which may be \fBNULL\fP). +It does not set \fBerrno\fP. +.PP +The function \fBset_field_userptr\fP returns \fBE_OK\fP (success). +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.PP +The user pointer is a void pointer. +We chose not to leave it as a char pointer for SVr4 compatibility. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_field_validation.3 b/static/openbsd/man3/form_field_validation.3 new file mode 100644 index 00000000..7b43ea69 --- /dev/null +++ b/static/openbsd/man3/form_field_validation.3 @@ -0,0 +1,234 @@ +.\" $OpenBSD: form_field_validation.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_validation.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.TH form_field_validation 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBform_field_validation\fP \- data type validation for fields +.SH SYNOPSIS +\fB#include \fP +.sp +\fBvoid *field_arg(const FIELD *\fIfield\fB);\fR +.br +\fBFIELDTYPE *field_type(const FIELD *\fIfield\fB);\fR +.br +\fBint set_field_type(FIELD *\fIfield\fB, FIELDTYPE *\fItype\fB, ...);\fR +.sp +/* predefined field types */ +.br +\fBFIELDTYPE *TYPE_ALNUM;\fP +.br +\fBFIELDTYPE *TYPE_ALPHA;\fP +.br +\fBFIELDTYPE *TYPE_ENUM;\fP +.br +\fBFIELDTYPE *TYPE_INTEGER;\fP +.br +\fBFIELDTYPE *TYPE_NUMERIC;\fP +.br +\fBFIELDTYPE *TYPE_REGEXP;\fP +.br +\fBFIELDTYPE *TYPE_IPV4;\fP +.SH DESCRIPTION +By default, no validation is done on form fields. +You can associate a form with with a \fIfield type\fP, +making the form library validate input. +.SS field_arg +Returns a pointer to the field's argument block. +The \fIargument block\fP is an opaque structure containing +a copy of the arguments provided in a \fBset_field_type\fP call. +.SS field_type +Returns a pointer to the \fIfield type\fP associated with the form field, +i.e., by calling \fBset_field_type\fP. +.SS set_field_type +The function \fBset_field_type\fP associates +a field type with a given form field. +This is the type checked by validation functions. +Most field types are configurable, +via arguments which the caller provides when calling \fBset_field_type\fP. +.PP +Several field types are predefined by the form library. +.SS Predefined types +It is possible to set up new programmer-defined field types. +Field types are implemented via the \fBFIELDTYPE\fP data +structure, which contains several pointers to functions. +.PP +See the \fBform_fieldtype\fP(3) manual page, +which describes functions which can be used to construct +a field-type dynamically. +.PP +The predefined types are as follows: +.TP 5 +TYPE_ALNUM +Alphanumeric data. +Required parameter: +.RS +.bP +a third \fBint\fP argument, a minimum field width. +.RE +.TP 5 +TYPE_ALPHA +Character data. +Required parameter: +.RS +.bP +a third \fBint\fP argument, a minimum field width. +.RE +.TP 5 +TYPE_ENUM +Accept one of a specified set of strings. +Required parameters: +.RS +.bP +a third \fB(char **)\fP argument pointing to a string list; +.bP +a fourth \fBint\fP flag argument to enable case-sensitivity; +.bP +a fifth \fBint\fP flag argument specifying whether a partial +match must be a unique one. +If this flag is off, a prefix matches the first +of any set of more than one list elements with that prefix. +.RE +.IP +The library copies the string list, +so you may use a list that lives in automatic variables on the stack. +.TP 5 +TYPE_INTEGER +Integer data, parsable to an integer by \fBatoi\fP(3). +Required parameters: +.RS +.bP +a third \fBint\fP argument controlling the precision, +.bP +a fourth \fBlong\fP argument constraining minimum value, +.bP +a fifth \fBlong\fP constraining maximum value. +If the maximum value is less than or equal to the minimum value, the range is +simply ignored. +.RE +.IP +On return, the field buffer is formatted according to the +\fBprintf\fP format specification \*(``.*ld\*('', +where the \*(``*\*('' is replaced by the precision argument. +.IP +For details of the precision handling see \fBprintf\fP(3). +.TP 5 +TYPE_NUMERIC +Numeric data (may have a decimal-point part). +Required parameters: +.RS +.bP +a third \fBint\fP argument controlling the precision, +.bP +a fourth \fBdouble\fP argument constraining minimum value, +.bP +and a fifth \fBdouble\fP constraining maximum value. +If your system supports locales, +the decimal point character must be the one specified by your locale. +If the maximum value is less than or equal to the minimum value, +the range is simply ignored. +.RE +.IP +On return, the field buffer is formatted according to the +\fBprintf\fP format specification \*(``.*f\*('', +where the \*(``*\*('' is replaced by the precision argument. +.IP +For details of the precision handling see \fBprintf\fP(3). +.TP 5 +TYPE_REGEXP +Regular expression data. +Required parameter: +.RS +.bP +a third argument, a regular expression \fB(char *)\fP string. +The data is valid if the regular expression matches it. +.RE +.IP +Regular expressions +are in the format of \fBregcomp\fP and \fBregexec\fP. +.IP +The regular expression must match the whole field. +If you have for example, an eight character wide field, +a regular expression "^[0\-9]*$" always +means that you have to fill all eight positions with digits. +If you want to allow fewer digits, +you may use for example "^[0\-9]* *$" which is good for +trailing spaces (up to an empty field), +or "^ *[0\-9]* *$" which is good for +leading and trailing spaces around the digits. +.TP 5 +TYPE_IPV4 +An Internet Protocol Version 4 address. +Required parameter: +.RS +.bP +none +.RE +.IP +The form library checks whether or not the buffer has the form \fIa.b.c.d\fP, +where \fIa\fP, \fIb\fP, \fIc\fP, and \fId\fP are numbers in the range 0 to 255. +Trailing blanks in the buffer are ignored. +The address itself is not validated. +.IP +This is an ncurses extension; +this field type may not be available in other curses implementations. +.SH RETURN VALUE +The functions \fBfield_type\fP and \fBfield_arg\fP return \fBNULL\fP on error. +The function \fBset_field_type\fP returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), +\fBform\fP(3), +\fBform_fieldtype\fP(3), +\fBform_variables\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_fieldtype.3 b/static/openbsd/man3/form_fieldtype.3 new file mode 100644 index 00000000..fa33369b --- /dev/null +++ b/static/openbsd/man3/form_fieldtype.3 @@ -0,0 +1,168 @@ +'\" t +.\" $OpenBSD: form_fieldtype.3,v 1.13 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2006,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_fieldtype.3,v 1.13 2023/10/17 09:52:10 nicm Exp $ +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.TH form_fieldtype 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBform_fieldtype\fP \- define validation-field types +.SH SYNOPSIS +\fB#include \fP +.sp +\fBFIELDTYPE *new_fieldtype(\fP + \fBbool (* const \fIfield_check\fB)(FIELD *, const void *),\fR + \fBbool (* const \fIchar_check\fB)(int, const void *));\fR +.br +\fBint free_fieldtype(FIELDTYPE *\fIfieldtype\fB);\fR +.sp +\fBint set_fieldtype_arg(\fP + \fBFIELDTYPE *\fIfieldtype\fB,\fR + \fBvoid *(* const \fImake_arg\fB)(va_list *),\fR + \fBvoid *(* const \fIcopy_arg\fB)(const void *),\fR + \fBvoid (* const \fIfree_arg\fB)(void *));\fR +.br +\fBint set_fieldtype_choice(\fP + \fBFIELDTYPE *\fIfieldtype\fB,\fR + \fBbool (* const \fInext_choice\fB)(FIELD *, const void *),\fR + \fBbool (* const \fIprev_choice\fB)(FIELD *, const void *));\fR +.sp +\fBFIELDTYPE *link_fieldtype(FIELDTYPE *\fItype1\fB,\fR + \fBFIELDTYPE *\fItype2\fB);\fR +.SH DESCRIPTION +.SS new_fieldtype +The function \fBnew_fieldtype\fP creates a new field type usable for data +validation. +Its parameters are function pointers: +.TP 5 +\fIfield_check\fP +This function checks the +validity of an entered data string whenever the user attempts to leave a field. +It has two arguments: +.RS +.bP +The (FIELD *) argument is passed in so the validation predicate can see the +field's buffer, sizes and other attributes. +.bP +The second argument is an +argument-block structure, about which more below. +.RE +.TP 5 +\fIchar_check\fP +This function validates input characters as they are entered. +The form library passes it the character to be checked +and a pointer to an argument-block structure. +.SS free_fieldtype +The \fBfree_fieldtype\fP function +frees the space allocated for a given validation type by \fBnew_fieldtype\fP. +.SS set_fieldtype_arg +The function \fBset_fieldtype_arg\fP associates +three storage-management functions with a field type: +.TP 5 +\fImake_arg\fP +This function is automatically applied to the +list of arguments you give \fBset_field_type\fP when attaching validation +to a field. +It stores the arguments in an allocated argument-block +object which is used when validating input. +.TP 5 +\fIcopy_arg\fP +This function may be used by applications to copy argument-blocks. +.TP 5 +\fIfree_arg\fP +Frees an argument-block structure. +.PP +You must supply the \fImake_arg\fP function. +The other two are optional: you may supply NULL for them. +In this case, the form library assumes +that \fImake_arg\fP does not allocate memory but simply loads the +argument into a single scalar value. +.SS set_fieldtype_choice +The form driver requests \fBREQ_NEXT_CHOICE\fP and \fBREQ_PREV_CHOICE\fP assume +that the possible values of a field form an ordered set, and provide the forms +user with a way to move through the set. +.PP +The \fBset_fieldtype_choice\fP +function allows forms programmers to define successor and predecessor functions +for the field type. +These functions take the field pointer and an +argument-block structure as arguments. +.SS link_fieldtype +The function \fBlink_fieldtype\fP creates +a new field type from the two given types. +They are connected by an logical 'OR'. +.SH RETURN VALUE +The pointer-valued routines return NULL on error. +They set \fBerrno\fP according to their success: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred, e.g., malloc failure. +.PP +The integer-valued routines return one of the following codes on +error: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CONNECTED +The field is already connected to a form. +.TP 5 +.B E_CURRENT +The field is the current field. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), +\fBform\fP(3), +\fBform_field_validation\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_hook.3 b/static/openbsd/man3/form_hook.3 new file mode 100644 index 00000000..d4e35752 --- /dev/null +++ b/static/openbsd/man3/form_hook.3 @@ -0,0 +1,102 @@ +'\" t +.\" $OpenBSD: form_hook.3,v 1.12 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2007,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_hook.3,v 1.12 2023/10/17 09:52:10 nicm Exp $ +.TH form_hook 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBform_hook\fP \- set hooks for automatic invocation by applications +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_field_init(FORM *\fIform\fB, Form_Hook \fIfunc\fB);\fR +.br +\fBForm_Hook field_init(const FORM *\fIform\fB);\fR +.sp +\fBint set_field_term(FORM *\fIform\fB, Form_Hook \fIfunc\fB);\fR +.br +\fBForm_Hook field_term(const FORM *\fIform\fB);\fR +.sp +\fBint set_form_init(FORM *\fIform\fB, Form_Hook \fIfunc\fB);\fR +.br +\fBForm_Hook form_init(const FORM *\fIform\fB);\fR +.sp +\fBint set_form_term(FORM *\fIform\fB, Form_Hook \fIfunc\fB);\fR +.br +\fBForm_Hook form_term(const FORM *\fIform\fB);\fR +.SH DESCRIPTION +These functions make it possible to set hook functions to be called at various +points in the automatic processing of input event codes by \fBform_driver\fP. +.PP +The function \fBset_field_init\fP sets a hook to be called at form-post time +and each time the selected field changes (after the change). +\fBfield_init\fP +returns the current field init hook, if any (\fBNULL\fP if there is no such +hook). +.PP +The function \fBset_field_term\fP sets a hook to be called at form-unpost time +and each time the selected field changes (before the change). +\fBfield_term\fP +returns the current field term hook, if any (\fBNULL\fP if there is no such +hook). +.PP +The function \fBset_form_init\fP sets a hook to be called at form-post time and +just after a page change once it is posted. +\fBform_init\fP returns the +current form init hook, if any (\fBNULL\fP if there is no such hook). +.PP +The function \fBset_form_term\fP sets a hook to be called at form-unpost time +and just before a page change once it is posted. +\fBform_init\fP +returns the current form term hook, if any (\fBNULL\fP if there is no such +hook). +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fP on error. +Other routines +return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_new.3 b/static/openbsd/man3/form_new.3 new file mode 100644 index 00000000..1f7630f5 --- /dev/null +++ b/static/openbsd/man3/form_new.3 @@ -0,0 +1,87 @@ +'\" t +.\" $OpenBSD: form_new.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_new.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.TH form_new 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBnew_form\fP, +\fBfree_form\fP \- create and destroy forms +.SH SYNOPSIS +\fB#include \fP +.sp +\fBFORM *new_form(FIELD **\fIfields\fB);\fR +.br +\fBint free_form(FORM *\fIform\fB);\fR +.SH DESCRIPTION +The function \fBnew_form\fP creates a new form connected to a specified field +pointer array (which must be \fBNULL\fP-terminated). +.PP +The function \fBfree_form\fP disconnects \fIform\fP from its field array +and frees the storage allocated for the form. +.SH RETURN VALUE +The function \fBnew_form\fP returns \fBNULL\fP on error. +It sets \fBerrno\fP according to the function's success: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CONNECTED +The field is already connected to a form. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred, e.g., malloc failure. +.PP +The function \fBfree_form\fP returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The form has already been posted. +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_new_page.3 b/static/openbsd/man3/form_new_page.3 new file mode 100644 index 00000000..e5f39760 --- /dev/null +++ b/static/openbsd/man3/form_new_page.3 @@ -0,0 +1,76 @@ +'\" t +.\" $OpenBSD: form_new_page.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_new_page.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.TH form_new_page 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBset_new_page\fP, +\fBnew_page\fP \- form pagination functions +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_new_page(FIELD *\fIfield\fB, bool \fInew_page_flag\fB);\fR +.br +\fBbool new_page(const FIELD *\fIfield\fB);\fR +.SH DESCRIPTION +The function \fBset_new_page\fP sets or resets a flag marking the given field +as the beginning of a new page on its form. +.PP +The function \fBnew_page\fP is a predicate which tests if a given field marks +a page beginning on its form. +.SH RETURN VALUE +The function \fBnew_page\fP returns \fBTRUE\fP or \fBFALSE\fP. +.PP +The function \fBset_new_page\fP returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_CONNECTED +The given field is already connected to a form. +.SH SEE ALSO +\fBcurses\fP(3) and related pages whose names begin \*(``form_\*('' for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_opts.3 b/static/openbsd/man3/form_opts.3 new file mode 100644 index 00000000..5e6cc706 --- /dev/null +++ b/static/openbsd/man3/form_opts.3 @@ -0,0 +1,90 @@ +'\" t +.\" $OpenBSD: form_opts.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_opts.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.TH form_opts 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_form_opts\fP, +\fBform_opts_on\fP, +\fBform_opts_off\fP, +\fBform_opts\fP \- set and get form options +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_form_opts(FORM *\fIform\fB, Field_Options \fIopts\fB);\fR +.br +\fBField_Options form_opts(const FORM *\fIform\fB);\fR +.sp +\fBint form_opts_on(FORM *\fIform\fB, Field_Options \fIopts\fB);\fR +.br +\fBint form_opts_off(FORM *\fIform\fB, Field_Options \fIopts\fB);\fR +.SH DESCRIPTION +The function \fBset_form_opts\fP sets all the given form's option bits (form +option bits may be logically-OR'ed together). +.PP +The function \fBform_opts_on\fP turns on the given option bits, and leaves +others alone. +.PP +The function \fBform_opts_off\fP turns off the given option bits, and leaves +others alone. +.PP +The function \fBform_opts\fP returns the form's current option bits. +.PP +The following options are defined (all are on by default): +.TP 5 +O_NL_OVERLOAD +Overload the \fBREQ_NEW_LINE\fP forms driver request so that calling it at the +end of a field goes to the next field. +.TP 5 +O_BS_OVERLOAD +Overload the \fBREQ_DEL_PREV\fP forms driver request so that calling it at the +beginning of a field goes to the previous field. +.SH RETURN VALUE +Except for \fBform_opts\fP, each routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_page.3 b/static/openbsd/man3/form_page.3 new file mode 100644 index 00000000..efb07b8e --- /dev/null +++ b/static/openbsd/man3/form_page.3 @@ -0,0 +1,102 @@ +'\" t +.\" $OpenBSD: form_page.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2016 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_page.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.TH form_page 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBform_page\fP \- set and get form page number +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_current_field(FORM *\fIform\fB, FIELD *\fIfield\fB);\fR +.br +\fBFIELD *current_field(const FORM *\fIform\fB);\fR +.sp +\fBint unfocus_current_field(FORM *\fIform\fB);\fR +.sp +\fBint set_form_page(FORM *\fIform\fB, int \fIn\fB);\fR +.br +\fBint form_page(const FORM *\fIform\fB);\fR +.sp +\fBint field_index(const FIELD *\fIfield\fB);\fR +.SH DESCRIPTION +The function \fBset_current_field\fP sets the current field of the given +form; \fBcurrent_field\fP returns the current field of the given form. +.PP +The function \fBunfocus_current_field\fP removes the focus from the current +field of the form. +In such state, inquiries via \fBcurrent_field\fP shall return a NULL pointer. +.PP +The function \fBset_form_page\fP sets the form's page number (goes to page +\fIn\fP of the form). +.PP +The function \fBform_page\fP returns the form's current page number. +.PP +The function \fBfield_index\fP returns the index of the field in the +field array of the form it is connected to. +It returns \fBERR\fP if +the argument is the null pointer or the field is not connected. +.SH RETURN VALUE +Except for \fBform_page\fP, each routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_INVALID_FIELD +Contents of a field are not valid. +.TP 5 +.B E_REQUEST_DENIED +The form driver could not process the request. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +. +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.PP +The \fBunfocus_current_field\fP function is an ncurses extension. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_post.3 b/static/openbsd/man3/form_post.3 new file mode 100644 index 00000000..f7d8a63f --- /dev/null +++ b/static/openbsd/man3/form_post.3 @@ -0,0 +1,90 @@ +'\" t +.\" $OpenBSD: form_post.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_post.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH form_post 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBpost_form\fP, +\fBunpost_form\fP \- write or erase forms from associated subwindows +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint post_form(FORM *\fIform\fB);\fR +.br +\fBint unpost_form(FORM *\fIform\fB);\fR +.SH DESCRIPTION +The function \fBpost_form\fP displays a form to its associated subwindow. +To trigger physical display of the subwindow, +use \fBrefresh\fP(3) or some equivalent +\fBcurses\fP routine (the implicit \fBdoupdate\fP triggered by an \fBcurses\fP +input request will do). +.PP +The function \fBunpost_form\fP erases form from its associated subwindow. +.SH RETURN VALUE +These routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NOT_POSTED +The form has not been posted. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the form. +.TP 5 +.B E_NO_ROOM +Form is too large for its window. +.TP 5 +.B E_POSTED +The form has already been posted. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +. +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_requestname.3 b/static/openbsd/man3/form_requestname.3 new file mode 100644 index 00000000..ac887ce6 --- /dev/null +++ b/static/openbsd/man3/form_requestname.3 @@ -0,0 +1,71 @@ +'\" t +.\" $OpenBSD: form_requestname.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_requestname.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH form_requestname 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBform_request_by_name\fP, +\fBform_request_name\fP \- handle printable form request names +.SH SYNOPSIS +\fB#include \fP +.sp +\fBconst char *form_request_name(int \fIrequest\fB);\fR +.br +\fBint form_request_by_name(const char *\fIname\fB);\fR +.SH DESCRIPTION +.SS form_request_name +The function \fBform_request_name\fP returns the printable name of a form +request code. +.SS form_request_name_by_name +The function \fBform_request_by_name\fP searches in the name-table for a request +with the given name and returns its request code. +Otherwise E_NO_MATCH is returned. +.SH RETURN VALUE +\fBform_request_name\fP returns \fBNULL\fP on error and sets \fBerrno\fP +to \fBE_BAD_ARGUMENT\fP. +.PP +\fBform_request_by_name\fP returns \fBE_NO_MATCH\fP on error. +It does not set \fBerrno\fP. +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on +Version 7, BSD or System V implementations. +It is recommended that +any code depending on them be conditioned using NCURSES_VERSION. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_userptr.3 b/static/openbsd/man3/form_userptr.3 new file mode 100644 index 00000000..bfd6fb28 --- /dev/null +++ b/static/openbsd/man3/form_userptr.3 @@ -0,0 +1,67 @@ +'\" t +.\" $OpenBSD: form_userptr.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_userptr.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.TH form_userptr 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_form_userptr\fP, +\fBform_userptr\fP \- associate application data with a form item +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_form_userptr(FORM *\fIform\fB, void *\fIuserptr\fB);\fR +.br +\fBvoid* form_userptr(const FORM *\fIform\fB);\fR +.SH DESCRIPTION +Every form and every form item has a field that can be used to hold +application-specific data (that is, the form-driver code leaves it alone). +These functions get and set the form user pointer field. +.SH RETURN VALUE +The function \fBform_userptr\fP returns a pointer (which may be \fBNULL\fP). +It does not set \fBerrno\fP. +.PP +The function \fBset_form_userptr\fP returns \fBE_OK\fP (success). +.SH SEE ALSO +\fBcurses\fP(3), \fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.PP +The user pointer is a void pointer. +We chose not to leave it as a char pointer for SVr4 compatibility. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/form_variables.3 b/static/openbsd/man3/form_variables.3 new file mode 100644 index 00000000..4ff571a2 --- /dev/null +++ b/static/openbsd/man3/form_variables.3 @@ -0,0 +1,81 @@ +.\"*************************************************************************** +.\" Copyright 2020,2021 Thomas E. Dickey * +.\" Copyright 2010-2013,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_variables.3,v 1.1 2023/10/17 09:52:10 nicm Exp $ +.TH form_variables 3 2021-12-25 "ncurses 6.4" "Library calls" +.na +.hy 0 +.SH NAME +\fBTYPE_ALNUM\fP, +\fBTYPE_ALPHA\fP, +\fBTYPE_ENUM\fP, +\fBTYPE_INTEGER\fP, +\fBTYPE_IPV4\fP, +\fBTYPE_NUMERIC\fP, +\fBTYPE_REGEXP\fP +\- form system global variables +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +.PP +\fBFIELDTYPE * TYPE_ALNUM;\fP +\fBFIELDTYPE * TYPE_ALPHA;\fP +\fBFIELDTYPE * TYPE_ENUM;\fP +\fBFIELDTYPE * TYPE_INTEGER;\fP +\fBFIELDTYPE * TYPE_IPV4;\fP +\fBFIELDTYPE * TYPE_NUMERIC;\fP +\fBFIELDTYPE * TYPE_REGEXP;\fP +.fi +.SH DESCRIPTION +These are building blocks for the form library, +defining fields that can be created using +the \fBform_fieldtype\fP(3) functions. +Each provides functions for field- and character-validation, +according to the given datatype. +.SS TYPE_ALNUM +This holds alphanumeric data. +.SS TYPE_ALPHA +This holds alphabetic data. +.SS TYPE_ENUM +This holds an enumerated type. +.SS TYPE_INTEGER +This holds a decimal integer. +.SS TYPE_IPV4 +This holds an IPv4 internet address, e.g., "127.0.0.1". +.SS TYPE_NUMERIC +This holds a decimal number, with optional sign and decimal point. +.SS TYPE_REGEXP +This holds a regular expression. +.SH PORTABILITY +The \fBTYPE_IPV4\fP variable is an extension not provided by older +implementations of the form library. +.SH SEE ALSO +\fBform\fP(3). diff --git a/static/openbsd/man3/form_win.3 b/static/openbsd/man3/form_win.3 new file mode 100644 index 00000000..d0fc36a3 --- /dev/null +++ b/static/openbsd/man3/form_win.3 @@ -0,0 +1,97 @@ +'\" t +.\" $OpenBSD: form_win.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2006,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_win.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.TH form_win 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBform_win\fP \- make and break form window and subwindow associations +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_form_win(FORM *\fIform\fB, WINDOW *\fIwin\fB);\fR +.br +\fBWINDOW *form_win(const FORM *\fIform\fB);\fR +.sp +\fBint set_form_sub(FORM *\fIform\fB, WINDOW *\fIsub\fB);\fR +.br +\fBWINDOW *form_sub(const FORM *\fIform\fB);\fR +.sp +\fBint scale_form(const FORM *\fIform\fB, int *\fIrows\fB, int *\fIcolumns\fB);\fR +.SH DESCRIPTION +Every form has an associated pair of \fBcurses\fP windows. +The form window +displays any title and border associated with the window; the form subwindow +displays the items of the form that are currently available for selection. +.PP +The first four functions get and set those windows. +It is not necessary to set +either window; by default, the driver code uses \fBstdscr\fP for both. +.PP +In the \fBset_\fP functions, window argument of \fBNULL\fP is treated as though +it were \fBstsdcr\fP. A form argument of \fBNULL\fP is treated as a request +to change the system default form window or subwindow. +.PP +The function \fBscale_form\fP returns the minimum size required for the +subwindow of \fIform\fP. +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fP on error. +Routines that return +an integer return one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The form has already been posted. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the form. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_variables\fP(3), +\fBform\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V forms library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/fparseln.3 b/static/openbsd/man3/fparseln.3 new file mode 100644 index 00000000..a5ed5605 --- /dev/null +++ b/static/openbsd/man3/fparseln.3 @@ -0,0 +1,140 @@ +.\" $OpenBSD: fparseln.3,v 1.13 2025/06/13 18:34:00 schwarze Exp $ +.\" $NetBSD: fparseln.3,v 1.7 1999/07/02 15:49:12 simonb 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 $Mdocdate: June 13 2025 $ +.Dt FPARSELN 3 +.Os +.Sh NAME +.Nm fparseln +.Nd return the next logical line from a stream +.Sh SYNOPSIS +.Lb libutil +.In stdio.h +.In util.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 null terminated, contains no trailing newline, +and 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 referenced by +.Fa len . +.It Fa lineno +If not +.Dv NULL , +the value of the memory location to which +.Fa lineno +references 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 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 +.Ql \e , +is used to remove any special meaning from the next character. +.It Fa delim[1] +The continuation character, which defaults to +.Ql \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 +.Ql # , +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 OR'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 +Internally, the +.Fn fparseln +function uses +.Xr fgetln 3 , +so all error conditions that apply to +.Xr fgetln 3 +apply to +.Fn fparseln +as well. +In addition +.Fn fparseln +may set +.Va errno +to +.Er ENOMEM +and return +.Dv NULL +if it runs out of memory. +.Sh SEE ALSO +.Xr fgetln 3 diff --git a/static/openbsd/man3/fpclassify.3 b/static/openbsd/man3/fpclassify.3 new file mode 100644 index 00000000..b63c5117 --- /dev/null +++ b/static/openbsd/man3/fpclassify.3 @@ -0,0 +1,157 @@ +.\" $OpenBSD: fpclassify.3,v 1.6 2025/06/07 23:56:57 schwarze Exp $ +.\" +.\" Copyright (c) 2003 Mike Barcroft +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (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/fpclassify.3,v 1.6 2005/01/27 05:46:16 das Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt FPCLASSIFY 3 +.Os +.Sh NAME +.Nm fpclassify , +.Nm isfinite , +.Nm isinf , +.Nm isnan , +.Nm isnormal , +.Nm signbit , +.Nm finite , +.Nm finitef , +.Nm isinff , +.Nm isnanf +.Nd classify a floating-point number +.Sh SYNOPSIS +.Lb libm +.In math.h +.Ft int +.Fn fpclassify "real-floating x" +.Ft int +.Fn isfinite "real-floating x" +.Ft int +.Fn isinf "real-floating x" +.Ft int +.Fn isnan "real-floating x" +.Ft int +.Fn isnormal "real-floating x" +.Ft int +.Fn signbit "real-floating x" +.Sh DESCRIPTION +The +.Fn fpclassify +macro takes an argument of +.Fa x +and returns one of the following manifest constants: +.Pp +.Bl -tag -width "FP_SUBNORMALXXX" -offset indent -compact +.It Dv FP_INFINITE +Indicates that +.Fa x +is an infinite number. +.It Dv FP_NAN +Indicates that +.Fa x +is not a number (NaN). +.It Dv FP_NORMAL +Indicates that +.Fa x +is a normalized number. +.It Dv FP_SUBNORMAL +Indicates that +.Fa x +is a denormalized number. +.It Dv FP_ZERO +Indicates that +.Fa x +is zero (0 or \-0). +.El +.Pp +The +.Fn isfinite +macro returns a non-zero value if and only if its argument has +a finite (zero, subnormal, or normal) value. +.Pp +The +.Fn isinf , +.Fn isnan , +and +.Fn isnormal +macros return non-zero if and only if +.Fa x +is an infinity, NaN, +or a non-zero normalized number, respectively. +.Pp +The +.Fn signbit +macro takes an argument of +.Fa x +and returns non-zero if the value of its sign is negative, otherwise 0. +.Sh SEE ALSO +.Xr isgreater 3 +.Sh STANDARDS +The +.Fn fpclassify , +.Fn isfinite , +.Fn isinf , +.Fn isnan , +.Fn isnormal , +and +.Fn signbit +macros conform to +.St -isoC-99 . +.Pp +The symbols +.Fn isinff , +and +.Fn isnanf +are provided as compatibility aliases to +.Fn isinf , +and +.Fn isnan , +respectively, and their uses are deprecated. +Similarly, +.Fn finite +and +.Fn finitef +are deprecated versions of +.Fn isfinite . +.Sh HISTORY +The +.Fn fpclassify , +.Fn isfinite , +.Fn isinf , +.Fn isnan , +.Fn isnormal , +and +.Fn signbit +macros were added in +.Ox 4.4 . +.Bx 3 +introduced +.Fn isinf +and +.Fn isnan +functions, which accepted +.Vt double +arguments; these have been superseded by the macros +described above. diff --git a/static/openbsd/man3/fpgetmask.3 b/static/openbsd/man3/fpgetmask.3 new file mode 100644 index 00000000..a0499311 --- /dev/null +++ b/static/openbsd/man3/fpgetmask.3 @@ -0,0 +1,122 @@ +.\" $OpenBSD: fpgetmask.3,v 1.10 2015/09/14 15:14:55 schwarze Exp $ +.\" $NetBSD: fpgetmask.3,v 1.3 2001/09/16 02:57:03 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 $Mdocdate: September 14 2015 $ +.Dt FPGETMASK 3 +.Os +.Sh NAME +.Nm fpgetmask , +.Nm fpgetround , +.Nm fpgetsticky , +.Nm fpsetmask , +.Nm fpsetround , +.Nm fpsetsticky +.Nd IEEE FP mode control +.Sh SYNOPSIS +.In ieeefp.h +.Ft fp_except +.Fn fpgetmask void +.Ft fp_rnd +.Fn fpgetround void +.Ft fp_except +.Fn fpgetsticky void +.Ft fp_except +.Fn fpsetmask "fp_except mask" +.Ft fp_rnd +.Fn fpsetround "fp_rnd rnd_dir" +.Ft fp_except +.Fn fpsetsticky "fp_except sticky" +.Sh DESCRIPTION +A rounding mode is one of +.Dv FP_RZ , FP_RM , FP_RN , +or +.Dv FP_RP , +for rounding towards zero, rounding +.Pq Em Minus infinity +down, rounding to +.Em nearest , +and rounding +.Pq Em Plus infinity +up. +The default mode is +.Dv FP_RN . +.Pp +An +.Ft fp_except +value is a bitmask specifying an exception type and containing any of +the values listed below. +.Bl -column FP_X_UFLxx -offset indent +.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_DNML Ta Denormalization Pq amd64 and i386 only +.El +.Pp +The +.Fn fpsetmask +function will cause future operations with the specified result status to +raise the +.Dv SIGFPE +exception. +The +.Fn fpsetround +function will cause future operations to use the specified dynamic 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 +The +.Fn fpsetsticky +function will set or clear the specified 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 diff --git a/static/openbsd/man3/fputs.3 b/static/openbsd/man3/fputs.3 new file mode 100644 index 00000000..790de254 --- /dev/null +++ b/static/openbsd/man3/fputs.3 @@ -0,0 +1,107 @@ +.\" $OpenBSD: fputs.3,v 1.13 2017/12/01 11:18:40 schwarze 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. +.\" +.Dd $Mdocdate: December 1 2017 $ +.Dt FPUTS 3 +.Os +.Sh NAME +.Nm fputs , +.Nm puts +.Nd output a line to a stream +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn fputs "const char *str" "FILE *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 . +.Pp +The function +.Fn puts +writes the string +.Fa str , +and a terminating newline character, +to the stream +.Em stdout . +.Sh RETURN VALUES +Upon successful completion a non-negative integer is returned. +Otherwise, +.Dv EOF +is returned, the global variable +.Va errno +is set to indicate the error, +and the error indicator is set for the stream. +.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 routines +.Xr write 2 . +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fputws 3 , +.Xr putc 3 , +.Xr stdio 3 +.Sh STANDARDS +The functions +.Fn fputs +and +.Fn puts +conform to +.St -ansiC . +.Sh HISTORY +The function +.Fn puts +first appeared in +.At v6 +and +.Fn fputs +in +.At v7 . diff --git a/static/openbsd/man3/fputws.3 b/static/openbsd/man3/fputws.3 new file mode 100644 index 00000000..75d5cea2 --- /dev/null +++ b/static/openbsd/man3/fputws.3 @@ -0,0 +1,89 @@ +.\" $OpenBSD: fputws.3,v 1.4 2010/09/10 18:38:19 jmc Exp $ +.\" +.\" $NetBSD: fputws.3,v 1.2 2003/08/07 16:43:24 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. +.\" +.\" @(#)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 $Mdocdate: September 10 2010 $ +.Dt FPUTWS 3 +.Os +.Sh NAME +.Nm fputws +.Nd output a line of wide characters to a stream +.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/openbsd/man3/fread.3 b/static/openbsd/man3/fread.3 new file mode 100644 index 00000000..255419ac --- /dev/null +++ b/static/openbsd/man3/fread.3 @@ -0,0 +1,126 @@ +.\" $OpenBSD: fread.3,v 1.11 2015/03/12 02:16:29 lteo 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. +.\" +.Dd $Mdocdate: March 12 2015 $ +.Dt FREAD 3 +.Os +.Sh NAME +.Nm fread , +.Nm fwrite +.Nd binary stream input/output +.Sh SYNOPSIS +.In stdio.h +.Ft size_t +.Fn fread "void *ptr" "size_t size" "size_t nmemb" "FILE *stream" +.Ft size_t +.Fn fwrite "const void *ptr" "size_t size" "size_t nmemb" "FILE *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 . +.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, +.Fn fread +and +.Fn fwrite +return 0 with no change made to the +.Fa stream . +If the product of +.Fa size +and +.Fa nmemb +results in integer 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 . +.Sh HISTORY +The functions +.Fn fread +and +.Fn fwrite +first appeared in +.At v7 . diff --git a/static/openbsd/man3/frexp.3 b/static/openbsd/man3/frexp.3 new file mode 100644 index 00000000..eac84846 --- /dev/null +++ b/static/openbsd/man3/frexp.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: frexp.3,v 1.15 2025/06/06 21:50:10 schwarze 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. +.\" +.Dd $Mdocdate: June 6 2025 $ +.Dt FREXP 3 +.Os +.Sh NAME +.Nm frexp , +.Nm frexpf , +.Nm frexpl +.Nd convert floating-point number to fractional and integral components +.Sh SYNOPSIS +.Lb libm +.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 +.Vt int +object pointed to by +.Fa exp . +The +.Fn frexpf +function is a single precision version of +.Fn frexp . +The +.Fn frexpl +function is an extended precision version of +.Fn frexp . +.Sh RETURN VALUES +The +.Fn frexp , +.Fn frexpf +and +.Fn frexpl +functions return the value +.Li x , +such that +.Li x +is a +.Vt double +with magnitude in the interval [1/2,\ 1) or zero, and +.Fa value +equals +.Li 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 modf 3 +.Sh STANDARDS +The +.Fn frexp +function conforms to +.St -ansiC . diff --git a/static/openbsd/man3/fseek.3 b/static/openbsd/man3/fseek.3 new file mode 100644 index 00000000..602b6369 --- /dev/null +++ b/static/openbsd/man3/fseek.3 @@ -0,0 +1,259 @@ +.\" $OpenBSD: fseek.3,v 1.19 2022/09/11 06:38:11 jmc 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.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 SYNOPSIS +.In stdio.h +.Ft int +.Fn fgetpos "FILE *stream" "fpos_t *pos" +.Ft int +.Fn fseek "FILE *stream" "long offset" "int whence" +.Ft int +.Fn fseeko "FILE *stream" "off_t offset" "int whence" +.Ft int +.Fn fsetpos "FILE *stream" "const fpos_t *pos" +.Ft long +.Fn ftell "FILE *stream" +.Ft off_t +.Fn ftello "FILE *stream" +.Ft void +.Fn rewind "FILE *stream" +.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 +.Fn fseek +except that it takes an +.Vt off_t +as its +.Fa offset . +.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 +.Fn ftell +except that its return value is of type +.Vt 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 +The +.Fn fgetpos +and +.Fn fsetpos +functions are alternate interfaces equivalent to +.Fn ftell +and +.Fn fseek +(with whence set to +.Dv SEEK_SET ) , +setting and storing the current value of +the file offset into or from the object referenced by +.Fa pos . +On some systems an +.Dq Fa fpos_t +object may be a complex object +and these routines may be the only way to portably reposition a text stream. +.Sh RETURN VALUES +The +.Fn rewind +function returns no value. +Prefer +.Fn fseek , +which is just as portable, and does not hide errors. +Upon successful completion, +.Fn fgetpos , +.Fn fseek , +.Fn fseeko , +and +.Fn fsetpos +return 0 and +.Fn ftell +and +.Fn ftello +return the current offset. +Otherwise, +.Fn fseek , +.Fn fseeko , +.Fn ftell , +and +.Fn ftello +return \-1 and +.Fn fgetpos +and +.Fn fsetpos +return a non-zero value and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn fgetpos , +.Fn fseek , +.Fn fseeko , +.Fn fsetpos , +.Fn ftell , +.Fn ftello , +and +.Fn rewind +functions will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa stream +specified is not a seekable stream. +.El +.Pp +Additionally, the +.Fn fseek +and +.Fn fseeko +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa whence +argument was not +.Dv SEEK_SET , +.Dv SEEK_END , +or +.Dv SEEK_CUR . +.El +.Pp +Additionally, the +.Fn ftell +function will fail if: +.Bl -tag -width Er +.It Bq Er EOVERFLOW +The value of the file position indicator is too large to be represented by a +.Vt long . +.El +.Pp +Finally, the functions +.Fn fgetpos , +.Fn fseek , +.Fn fseeko , +.Fn fsetpos , +.Fn ftell , +and +.Fn ftello +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 +.Sh STANDARDS +The +.Fn fgetpos , +.Fn fsetpos , +.Fn fseek , +.Fn ftell , +and +.Fn rewind +functions conform to +.St -ansiC +and +.St -xpg4 . +.Pp +The +.Fn fseeko +and +.Fn ftello +functions conform to +.St -xpg4 . +.Sh HISTORY +The functions +.Fn fseek , +.Fn ftell , +and +.Fn rewind +first appeared in +.At v7 . diff --git a/static/openbsd/man3/ftok.3 b/static/openbsd/man3/ftok.3 new file mode 100644 index 00000000..f4b6f1c7 --- /dev/null +++ b/static/openbsd/man3/ftok.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: ftok.3,v 1.17 2014/11/15 22:22:09 guenther 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. +.\" 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 $Mdocdate: November 15 2014 $ +.Dt FTOK 3 +.Os +.Sh NAME +.Nm ftok +.Nd create IPC identifier from a pathname +.Sh SYNOPSIS +.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 refer to 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 . +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 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 ancestors +were originally created. diff --git a/static/openbsd/man3/fts_open.3 b/static/openbsd/man3/fts_open.3 new file mode 100644 index 00000000..4b03a613 --- /dev/null +++ b/static/openbsd/man3/fts_open.3 @@ -0,0 +1,757 @@ +.\" $OpenBSD: fts_open.3,v 1.1 2019/09/02 21:18:41 deraadt 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 $Mdocdate: September 2 2019 $ +.Dt FTS_OPEN 3 +.Os +.Sh NAME +.Nm fts_open , +.Nm fts_read , +.Nm fts_children , +.Nm fts_set , +.Nm fts_close +.Nd traverse a file hierarchy +.Sh SYNOPSIS +.In sys/types.h +.In sys/stat.h +.In fts.h +.Ft FTS * +.Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT **, const FTSENT **)" +.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 option" +.Ft int +.Fn fts_close "FTS *ftsp" +.Sh DESCRIPTION +These +functions are provided for traversing +.Ux +file hierarchies. +The +.Fn fts_open +function returns a +.Dq handle +on a file hierarchy, which is then supplied to +the other 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 within the hierarchy. +.Pp +In general, directories are visited two distinguishable times; in pre-order +(before any of their descendants are visited) and in post-order (after all +of their descendants have been visited). +Files are visited once. +It is possible to walk the hierarchy +.Dq logically +(following symbolic links) +or +.Dq physically +(not following symbolic links), +order the walk of the hierarchy, or +prune and/or re-visit portions of the hierarchy. +.Pp +Two structures are defined (and typedef'd) in the include file +.In fts.h . +The first is +.Dv FTS , +the structure that represents the file hierarchy itself. +The second is +.Li FTSENT , +the structure that represents a file in the file +hierarchy. +Normally, an +.Li FTSENT +structure is returned for every file in the file +hierarchy. +In this manual page, +.Dq file +and +.Dq Li FTSENT No structure +are generally +interchangeable. +.Pp +The +.Li FTSENT +structure contains at least the following fields, which are +described in greater detail below: +.Bd -literal +typedef struct _ftsent { + unsigned short fts_info; /* flags for FTSENT structure */ + char *fts_accpath; /* access path */ + char *fts_path; /* root path */ + size_t fts_pathlen; /* strlen(fts_path) */ + char *fts_name; /* file name */ + size_t fts_namelen; /* strlen(fts_name) */ + int 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 "fts_namelen" +.It Fa fts_info +One of the following flags describing the returned +.Li 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 FTS_DEFAULT +.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 +.Li FTSENT +structure will be filled in as well.) +.It Dv FTS_DEFAULT +Any +.Li 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 +.Dq \&. +or +.Dq .. +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 +.Li 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. +.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 +.Li FTSENT +structure representing the parent of the starting point (or root) +of the traversal is numbered +.Dv FTS_ROOTPARENTLEVEL +(\-1), and the +.Li FTSENT +structure for the root +itself is numbered +.Dv FTS_ROOTLEVEL +(0). +Note that while +.Fa fts_level +cannot hold a number of levels greater than +.Dv FTS_MAXLEVEL , +the functions themselves are not limited to a fixed number +of levels. +Application code that inspects +.Fa fts_level +should be written with this in mind. +.It Fa fts_errno +Upon return of an +.Li 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 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 functions. +It is initialized to +.Dv NULL . +.It Fa fts_parent +A pointer to the +.Li 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 null-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 +.Li FTSENT +structure in the hierarchy that references the same file as the current +.Li 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 NUL terminated +.Em only +for the file most recently returned by +.Fn fts_read . +To use these fields to reference any files represented by other +.Li FTSENT +structures will require that the path buffer be modified using the +information contained in that +.Li 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 NUL 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 null pointer. +.Pp +There are +a number of options, at least one of which (either +.Dv FTS_LOGICAL +or +.Dv FTS_PHYSICAL ) +must be specified. +The +.Fa options +are selected by +.Tn OR Ns 'ing +the following values: +.Bl -tag -width "FTS_PHYSICAL" +.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 routines to return +.Li 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 +.Li 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 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 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 +.Li FTSENT +structures reference file characteristic information (the +.Fa statp +field) for each file visited. +This option relaxes that requirement as a performance optimization, +allowing the functions to set the +.Fa fts_info +field to +.Dv FTS_NSOK +and leave the contents of the +.Fa statp +field undefined. +.It Dv FTS_PHYSICAL +This option causes the routines to return +.Li FTSENT +structures for symbolic links themselves instead +of the target files they point to. +If this option is set, +.Li 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 +.Dq \&. +or +.Dq .. +encountered in the file hierarchy are ignored. +This option causes the routines to return +.Li FTSENT +structures for them. +.It Dv FTS_XDEV +This option prevents from descending into directories that have +a different device number than the file from which the descent began. +.El +.Pp +The +.Fa compar +argument +specifies a user-defined function which may be used to order the traversal +of the hierarchy. +It +takes two pointers to pointers to +.Li 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 +.Li 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 +.Fa 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 +.Li FTSENT +structure describing a file in +the hierarchy. +Directories (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. +(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.) +.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 +.Li FTSENT +structure is returned, and +.Va errno +may or may not have been set (see +.Fa fts_info ) . +.Pp +The +.Li 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 +.Li 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 +.Li FTSENT +structure describing the first entry in a null-terminated +linked list of +the files in the directory represented by the +.Li FTSENT +structure most recently returned by +.Fn fts_read . +The list is linked through the +.Fa fts_link +field of the +.Li 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 +.Li 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 0. +If an error occurs, +.Fn fts_children +returns +.Dv NULL +and sets +.Va errno +appropriately. +.Pp +The +.Li 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 +.Fa options +may be set to the following value: +.Bl -tag -width FTS_NAMEONLY +.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 or \-1 if an error occurred. +.Fa option +must be set to one of the following values: +.Bl -tag -width FTS_PHYSICAL +.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 (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 . +.Rv -std fts_close +.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 function +.Xr fchdir 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 +A specified option is invalid or +.Fa path_argv +is empty. +.El +.Sh SEE ALSO +.Xr find 1 , +.Xr chdir 2 , +.Xr stat 2 , +.Xr qsort 3 +.Sh HISTORY +These functions first appeared in +.Bx 4.3 Reno . +The interface was revised in +.Bx 4.4 . diff --git a/static/openbsd/man3/ftw.3 b/static/openbsd/man3/ftw.3 new file mode 100644 index 00000000..6c344a31 --- /dev/null +++ b/static/openbsd/man3/ftw.3 @@ -0,0 +1,212 @@ +.\" $OpenBSD: ftw.3,v 1.14 2019/09/02 21:18:41 deraadt 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 $Mdocdate: September 2 2019 $ +.Dt FTW 3 +.Os +.Sh NAME +.Nm ftw , +.Nm 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_open 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 -offset indent +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 +.Pf ( Fn nftw +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 +.Pf ( Fn nftw +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 FTW_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, in the case of +.Nm ftw +only, greater than +.Dv OPEN_MAX . +.El +.Sh SEE ALSO +.Xr chdir 2 , +.Xr close 2 , +.Xr open 2 , +.Xr stat 2 , +.Xr fts_open 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 . +.Sh BUGS +The +.Fa maxfds +argument is currently ignored. diff --git a/static/openbsd/man3/funopen.3 b/static/openbsd/man3/funopen.3 new file mode 100644 index 00000000..704508d5 --- /dev/null +++ b/static/openbsd/man3/funopen.3 @@ -0,0 +1,156 @@ +.\" $OpenBSD: funopen.3,v 1.20 2022/08/05 00:53:57 jsg 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. +.\" +.Dd $Mdocdate: August 5 2022 $ +.Dt FUNOPEN 3 +.Os +.Sh NAME +.Nm funopen , +.Nm fropen , +.Nm fwopen +.Nd open a stream +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn funopen "const void *cookie" "int (*readfn)(void *, char *, int)" \ + "int (*writefn)(void *, const char *, int)" \ + "off_t (*seekfn)(void *, off_t, int)" \ + "int (*closefn)(void *)" +.Ft FILE * +.Fn fropen "const void *cookie" "int (*readfn)(void *, char *, int)" +.Ft FILE * +.Fn fwopen "const void *cookie" "int (*writefn)(void *, const char *, int)" +.Sh DESCRIPTION +The +.Fn funopen +function associates a stream with up to four I/O functions. +Either +.Fa readfn +or +.Fa writefn +must be specified; +the others may be given as +.Dv NULL +pointers. +These I/O functions will be used to read, write, seek, and close +the new 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 +with the exceptions that they are passed the +.Fa cookie +argument specified to +.Fn funopen +in place of the traditional file descriptor argument. +.Pp +Read and write 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 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 +.Fn 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 fopen 3 , +.Xr fseek 3 , +.Xr setvbuf 3 +.Sh HISTORY +The +.Fn funopen +functions first appeared in +.Bx 4.3 Net/2 . +.Sh BUGS +The +.Fn funopen +function may not be portable to systems other than +.Bx . diff --git a/static/openbsd/man3/fuse_chan_fd.3 b/static/openbsd/man3/fuse_chan_fd.3 new file mode 100644 index 00000000..66039d89 --- /dev/null +++ b/static/openbsd/man3/fuse_chan_fd.3 @@ -0,0 +1,56 @@ +.\" $OpenBSD: fuse_chan_fd.3,v 1.5 2025/09/23 09:28:28 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: September 23 2025 $ +.Dt FUSE_CHAN_FD 3 +.Os +.Sh NAME +.Nm fuse_chan_fd +.Nd get the file descriptor for an open FUSE device +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft int +.Fn fuse_chan_fd "struct fuse_chan *ch" +.Sh DESCRIPTION +.Fn fuse_chan_fd +returns the file descriptor to the FUSE device opened for reading +and writing by +.Xr fuse_mount 3 . +.Sh RETURN VALUES +If successful, +.Fn fuse_chan_fd +returns a non-negative integer, termed a file descriptor. +If +.Fa ch +is +.Dv NULL , +a value of -1 is returned. +.Sh SEE ALSO +.Xr fuse_mount 3 , +.Xr open 3 , +.Xr fuse 4 +.Sh STANDARDS +The +.Fn fuse_chan_fd +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_chan_fd +function first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com diff --git a/static/openbsd/man3/fuse_daemonize.3 b/static/openbsd/man3/fuse_daemonize.3 new file mode 100644 index 00000000..c223d29b --- /dev/null +++ b/static/openbsd/man3/fuse_daemonize.3 @@ -0,0 +1,62 @@ +.\" $OpenBSD: fuse_daemonize.3,v 1.6 2025/09/23 09:28:28 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: September 23 2025 $ +.Dt FUSE_DAEMONIZE 3 +.Os +.Sh NAME +.Nm fuse_daemonize +.Nd run in the background +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft int +.Fn fuse_daemonize "int foreground" +.Sh DESCRIPTION +If +.Fa foreground +is 0, +.Fn fuse_daemonize +detaches from the controlling terminal and runs in the background as a +system daemon. +Otherwise, the process continues to run in the foreground. +.Pp +The current working directory is changed to the root directory +.Pq Pa / . +Standard input, standard output, and standard error are redirected to +.Pa /dev/null . +.Sh RETURN VALUES +Upon success, +.Fn fuse_daemonize +returns 0; otherwise -1 is returned. +.Sh ERRORS +.Fn fuse_daemonize +can fail for the same reasons as +.Xr daemon 3 . +.Sh SEE ALSO +.Xr daemon 3 , +.Xr fuse_parse_cmdline 3 +.Sh STANDARDS +The +.Fn fuse_daemonize +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_daemonize +function first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com diff --git a/static/openbsd/man3/fuse_destroy.3 b/static/openbsd/man3/fuse_destroy.3 new file mode 100644 index 00000000..a8c347a6 --- /dev/null +++ b/static/openbsd/man3/fuse_destroy.3 @@ -0,0 +1,57 @@ +.\" $OpenBSD: fuse_destroy.3,v 1.5 2025/09/23 09:28:28 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: September 23 2025 $ +.Dt FUSE_DESTROY 3 +.Os +.Sh NAME +.Nm fuse_destroy +.Nd free memory associated with a FUSE handle +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft void +.Fn fuse_destroy "struct fuse *f" +.Sh DESCRIPTION +.Fn fuse_destroy +frees memory associated with the FUSE channel and FUSE handle specified by +.Fa f . +The file system's destroy operation is called if +.Xr fuse_loop 3 +did not receive the +.Dv FBT_DESTROY +message, usually due to terminating from a signal. +.Pp +This function does not unmount the file system, which should be done +with +.Xr fuse_unmount 3 +before calling this function. +.Sh SEE ALSO +.Xr fuse_new 3 , +.Xr fuse_teardown 3 , +.Xr fuse_unmount 3 +.Sh STANDARDS +The +.Fn fuse_destroy +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_destroy +function first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_get_context.3 b/static/openbsd/man3/fuse_get_context.3 new file mode 100644 index 00000000..a23d9500 --- /dev/null +++ b/static/openbsd/man3/fuse_get_context.3 @@ -0,0 +1,59 @@ +.\" $OpenBSD: fuse_get_context.3,v 1.3 2025/06/10 12:55:33 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: June 10 2025 $ +.Dt FUSE_GET_CONTEXT 3 +.Os +.Sh NAME +.Nm fuse_get_context +.Nd FUSE utility routine +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft struct fuse_context * +.Fn fuse_get_context "void" +.Sh DESCRIPTION +.Fn fuse_get_context +returns a pointer to the structure +.Fa fuse_context . +This can be used by file systems to obtain information about the +thread that is accessing the file system. +The returned fuse_context is only valid during the lifetime of a FUSE +operation. +.Bd -literal +struct fuse_context { + struct fuse * fuse; + uid_t uid; /* effective user id */ + gid_t gid; /* effective group id */ + pid_t pid; /* thread id */ + void *private_data; /* set by file system on mount */ + mode_t umask; /* umask of the thread */ +}; +.Ed +.Sh SEE ALSO +.Xr fuse_new 3 +.Sh STANDARDS +The +.Fn fuse_get_context +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_get_context +function +first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com diff --git a/static/openbsd/man3/fuse_get_session.3 b/static/openbsd/man3/fuse_get_session.3 new file mode 100644 index 00000000..ba7c1df7 --- /dev/null +++ b/static/openbsd/man3/fuse_get_session.3 @@ -0,0 +1,45 @@ +.\" $OpenBSD: fuse_get_session.3,v 1.3 2025/06/10 12:55:33 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: June 10 2025 $ +.Dt FUSE_GET_SESSION 3 +.Os +.Sh NAME +.Nm fuse_get_session +.Nd get the FUSE session associated with a FUSE handle +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft struct fuse_session * +.Fn fuse_get_session "struct fuse *f" +.Sh DESCRIPTION +.Fn fuse_get_session +returns the FUSE session associated with the FUSE file handle +.Fa f . +.Sh SEE ALSO +.Xr fuse_remove_signal_handlers 3 , +.Xr fuse_set_signal_handlers 3 +.Sh STANDARDS +The +.Fn fuse_get_session +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_get_session +function first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com diff --git a/static/openbsd/man3/fuse_loop.3 b/static/openbsd/man3/fuse_loop.3 new file mode 100644 index 00000000..fcec2ebf --- /dev/null +++ b/static/openbsd/man3/fuse_loop.3 @@ -0,0 +1,91 @@ +.\" $OpenBSD: fuse_loop.3,v 1.5 2025/09/23 09:28:28 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: September 23 2025 $ +.Dt FUSE_LOOP 3 +.Os +.Sh NAME +.Nm fuse_loop , +.Nm fuse_loop_mt +.Nd wait for and process FUSE messages +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft int +.Fn fuse_loop "struct fuse *fuse" +.Ft int +.Fn fuse_loop_mt "struct fuse *fuse" +.Sh DESCRIPTION +.Fn fuse_loop +reads from the FUSE device and blocks, waiting for the +kernel to send it fbuf messages. +Each of these specifies a FUSE file system operation to execute. +The callbacks to invoke are specified by calling +.Xr fuse_new 3 +or +.Xr fuse_setup 3 +prior to calling +.Fn fuse_loop . +.Pp +.Fn fuse_loop +returns when it reads the +.Dv FBT_DESTROY +message, which indicates that +the file system is being unmounted. +.Pp +If FUSE signal handlers have been installed and +.Dv SIGHUP , +.Dv SIGINT , +or +.Dv SIGTERM +is received, +.Fn fuse_loop +terminates successfully. +See +.Xr fuse_set_signal_handlers 3 +for more details. +.Pp +.Fn fuse_loop_mt +is a multi-threaded variant that allows the file system to process +multiple file system operations in parallel. +This is not implemented on +.Ox . +.Sh RETURN VALUES +.Fn fuse_loop +returns 0 on success or -1 on failure. +.Pp +.Fn fuse_loop_mt +always returns -1. +.Sh SEE ALSO +.Xr fuse_main 3 , +.Xr fuse_set_signal_handlers 3 , +.Xr fb_queue 9 +.Sh STANDARDS +The +.Fn fuse_loop +and +.Fn fuse_loop_mt +functions conform to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_loop +and +.Fn fuse_loop_mt +functions first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_lowlevel_new.3 b/static/openbsd/man3/fuse_lowlevel_new.3 new file mode 100644 index 00000000..2e52030e --- /dev/null +++ b/static/openbsd/man3/fuse_lowlevel_new.3 @@ -0,0 +1,610 @@ +.\" $OpenBSD: fuse_lowlevel_new.3,v 1.4 2026/02/06 15:24:36 schwarze Exp $ +.\" +.\" Copyright (c) 2026 Helg Bredow +.\" +.\" 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: February 6 2026 $ +.Dt FUSE_LOWLEVEL_NEW 3 +.Os +.Sh NAME +.Nm fuse_lowlevel_new , +.Nm fuse_session_destroy , +.Nm fuse_add_direntry +.Nd initialise and destroy a FUSE session +.Sh SYNOPSIS +.Lb libfuse +.In fuse_lowlevel.h +.Ft struct fuse_session * +.Fo fuse_lowlevel_new +.Fa "struct fuse_args *args" +.Fa "const struct fuse_lowlevel_ops *ops" +.Fa "size_t ops_size" +.Fa "void *userdata" +.Fc +.Ft void +.Fn fuse_session_destroy "struct fuse_session *se" +.Ft size_t +.Fo fuse_add_direntry +.Fa "fuse_req_t req" +.Fa "char *buf" +.Fa "const size_t bufsize" +.Fa "const char *name" +.Fa "struct stat *stbuf" +.Fa "off_t off" +.Fc +.Sh DESCRIPTION +The +.Fn fuse_lowlevel_new +function creates a new FUSE session using the low-level API. +The low-level API gives the file system full control over request handling. +This session handles communication between the kernel and the user-space +filesystem implementation. +The returned session must later be destroyed with +.Fn fuse_session_destroy . +To begin processing requests, the caller must mount the file system with +.Xr fuse_mount 3 +and then enter a loop to process kernel requests, such as with +.Xr fuse_session_loop 3 . +.Pp +The +.Fa args +parameter points to arguments that are used to configure the session. +These arguments can be initialised from command-line arguments using +.Xr FUSE_ARGS_INIT 3 , or +.Fa args +may be +.Dv NULL +if no arguments need to be parsed. +The following arguments are supported: +.Bl -tag -width Ds +.It Fl d , odebug +Enable debug output that prints details of each request received to standard +error output. +.It Fl h , \-help +Print a usage message to standard error output. +.It Fl -V , \-version +Print FUSE library version to standard error output. +.It Fl omax_write +The maximum number of bytes that the filesystem can handle in one write +request. +.El +.Pp +The +.Fa ops +parameter points to the file system operations supported by the user-space +file system daemon. +See below. +.Pp +The +.Fa op_size +parameter specifies the size of the +.Vt struct fuse_lowlevel_ops +structure in bytes. +This allows forward compatibility when new operations are added. +.Pp +The +.Fa userdata +parameter is a pointer to user-defined data that will be passed to the +.Fn init +and +.Fn destroy +handlers. +.Pp +This function does not mount the filesystem or start the event loop. +After creating the session, +.Xr fuse_session_loop 3 +can be called to begin handling requests. +.Pp +FUSE operations work in the same way as their UNIX file system +counterparts. +A functional file system must implement at least +.Fn lookup , +.Fn getattr , +.Fn readdir , +.Fn open , +.Fn read +and +.Fn statfs . +The other functions are optional, and the struct members pointing to them +can be set to +.Dv NULL . +.Pp +The +.Ft fuse_lowlevel_ops +structure contains one function pointer to each of the functions listed +below. +The return type of each function pointer is +.Ft void . +.Pp +The first parameter to each of these operations (except for +.Fn init +and +.Fn destroy ) +is a reference to the kernel request. +The relevant parameters from the requested file system operations are +passed as arguments to each function. +.Pp +All operations can report failure with +.Xr fuse_reply_err 3 . +If no other response is indicated below, then operations must report +success by passing 0 to the +.Fa errno +argument +of +.Xr fuse_reply_err 3 . +.Pp +The operations defined in the +.Vt struct fuse_lowlevel_ops +structure are: +.Bl -tag -width Ds +.It Xo Fo access +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "int mask" +.Fc Xc +Not implemented. +.Ox +always behaves as if the default_permissions mount option was specified. +See +.Xr fuse_mount 3 . +.It Xo Fo create +.Fa "fuse_req_t req" +.Fa "fuse_ino_t parent" +.Fa "const char *name" +.Fa "most_t mode" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Not implemented. +File systems must implement +.Fn mknod +instead. +.It Fn destroy "void *userdata" +This is the last handler called when the file system is unmounted. +.It Xo Fo flush +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Called when a regular file is closed by the +.Xr close 2 +system call. +This is the only way for a file system to report an error on close. +.Pp +The +.Fa ino +argument identifies the file to be closed. +.Pp +The +.Fa ffi +argument is a +.Vt struct fuse_file_info +that contains the following fields: +.Pp +.Bl -tag -compact -width indent +.It Fa fh +The file handle returned by the file system when the file was opened. +.It Fa flush +1 if the file should be flushed before being closed, or +0 otherwise. +.El +.It Xo Fo fsync +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "int datasync" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Optional function that implements +.Xr fsync 2 +and +.Xr fdatasync 2 . +The +.Fa datasync +parameter specifies whether the operation is as a result +of a call to +.Xr fdatasync 2 +and is currently always 0 (false). +.Fa ffi.fh +is the file handle returned by the file system when +the file was opened. +.It Xo Fo fsyncdir +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "int datasync" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Not implemented. +.It Xo Fo getattr +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Corresponds to the +.Xr stat 2 +system call. +.Pp +On success, respond with +.Xr fuse_reply_attr 3 . +.It Xo Fo init +.Fa "void *userdata" +.Fa "struct fuse_conn_info *fci" +.Fc Xc +This is the first handler called by the kernel when the file system is +mounted. +.Fa userdata +is a pointer to the data passed to +.Fn fuse_lowlevel_new . +.Fa fci +contains connection information in the following structure: +.Bd -literal +struct fuse_conn_info { + uint32_t proto_major; + uint32_t proto_minor; + uint32_t async_read; + uint32_t max_write; + uint32_t max_readahead; + uint32_t capable; + uint32_t want; + uint32_t max_background; + uint32_t congestion_threshold; + uint32_t reserved[23]; +}; +.Ed +.It Xo Fo link +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "fuse_ino_t newparent" +.Fa "const char *name" +.Fc Xc +Create a hard link to +.Fa ino +in directory +.Fa parent +with +.Fa name . +.Pp +On success, respond with +.Xr fuse_reply_entry 3 . +.It Xo Fo lookup +.Fa "fuse_req_t req" +.Fa "fuse_ino_t newparent" +.Fa "const char *name" +.Fc Xc +Looks up an entry +.Fa name +in the directory specified by +.Fa parent . +.Pp +If the entry cannot be found then this operation should reply with +.Er ENOENT . +Alternatively, an entry with ino = 0 can be returned. +This is intended to indicate that the negative result can be cached for +.Fa entry_timeout +seconds. +However, +.Ox +does not cache lookups so this is equivalent to returning +.Er ENOENT . +.Pp +Valid responses are +.Xr fuse_reply_err 3 +and +.Xr fuse_reply_entry 3 . +.It Xo Fo mkdir +.Fa "fuse_req_t req" +.Fa "fuse_ino_t parent" +.Fa "const char *name" +.Fa "mode_t mode" +.Fc Xc +Called on +.Xr mkdir 2 +to create a new directory +.Fa name +in directory +.Fa parent +with mode +.Fa mode . +.Pp +On success, respond with +.Xr fuse_reply_entry 3 . +.It Xo Fo mknod +.Fa "fuse_req_t req" +.Fa "fuse_ino_t parent" +.Fa "const char *name" +.Fa "mode_t mode" +.Fa "dev_t rdev" +.Fc Xc +Called on +.Xr open 2 +and +.Xr mknod 2 +to create regular files, pipes and device special files with +.Fa name +in the directory +specified by +.Fa parent . +.Fa mode +specifies the file type and mode with which to create the file. +.Fa rdev +specifies the device number if creating a device. +.Pp +On success, respond with +.Xr fuse_reply_entry 3 . +.It Xo Fo open +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Called on +.Xr open 2 +to open the file specified by +.Fa ino . +If the same file is opened more than once with the same access mode +.Po +.Dv O_RDONLY , O_WRONLY , +or +.Dv O_RDWR +.Pc , +no matter whether by the same process or by different processes, the +.Ox +kernel only calls the +.Fn open +operation once, namely when the respective (file, mode) pair first occurs. +The flags are available in the +.Fa flags +member of +.Fa ffi . +The +.Dv O_CREAT +and +.Dv O_TRUNC +flags are never passed from the kernel to +.Fn open ; +instead, the kernel invokes the +.Fn mknod +and +.Fn truncate +operations before +.Fn open . +.Pp +On success, respond with +.Xr fuse_reply_open 3 . +.It Xo Fo opendir +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Called when a directory is opened for reading. +.Pp +On success, respond with +.Xr fuse_reply_open 3 . +.It Xo Fo read +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "size_t size" +.Fa "off_t off" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Read the contents of file +.Fa ino +at offset +.Fa off . +.Pp +On success, respond with +.Xr fuse_reply_buf 3 . +.It Xo Fo readdir +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "size_t size" +.Fa "off_t off" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Called to read the entries in a directory specified by +.Fa ino . +The file system implementation must use the +.Fn fuse_add_direntry +function to add each entry to a buffer. +The buffer must be large enough to hold the entry but no larger than +.Fa size . +If the remaining space in the buffer is too small, the entry won't be +written, but the required size will still be returned. +To check for success, compare the buffer size (bufsize) with the returned +entry size. +If the entry size is greater than the buffer size, the operation failed. +The size required can be determined by calling +.Fn fuse_add_direntry +with +.Fa buf +set to +.Dv NULL . +.Pp +On success, respond with +.Xr fuse_reply_buf 3 . +.It Xo Fo readlink +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fc Xc +Called to read the target of a symbolic link. +The target must be NUL-terminated. +.Pp +On success, respond with +.Xr fuse_reply_readlink 3 . +.It Xo Fo release +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Called when there are no more references to the file specified by +.Fa ino . +.It Xo Fo releasedir +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Called when there are no more references to the directory specified by +.Fa ino . +.It Xo Fo rename +.Fa "fuse_req_t req" +.Fa "fuse_ino_t parent" +.Fa "const char *name" +.Fa "fuse_ino_t newparent" +.Fa "const char *newname" +.Fc Xc +Rename the directory entry +.Fa name +to +.Fa newname . +.Fa newparent +specifies the inode of the new parent directory. +.It Xo Fo rmdir +.Fa "fuse_req_t req" +.Fa "fuse_ino_t parent" +.Fa "const char *name" +.Fc Xc +Delete directory +.Fa name +from directory +.Fa parent . +.It Xo Fo symlink +.Fa "fuse_req_t req" +.Fa "const char *target" +.Fa "fuse_ino_t parent" +.Fa "const char *name" +.Fc Xc +Create a symbolic link in +.Fa parent +pointing from +.Fa name +to the absolute or relative path +.Fa target . +.Pp +On success, respond with +.Xr fuse_reply_entry 3 . +.It Xo Fo setattr +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "struct stat *attr" +.Fa "int flags" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Called when file attributes are changed such as access permissions or +the file owner or group via +.Xr chown 2 +and +.Xr chmod 2 +system calls. +.Pp +The +.Fa flags +argument is the bitwise OR of one or more of the bitmasks from the +following list, requesting that the corresponding fields in +.Fa attr +be set on +.Fa ino : +.Bd -literal +.Dv FUSE_SET_ATTR_MODE +.Dv FUSE_SET_ATTR_UID +.Dv FUSE_SET_ATTR_GID +.Dv FUSE_SET_ATTR_SIZE +.Dv FUSE_SET_ATTR_ATIME +.Dv FUSE_SET_ATTR_MTIME +.Dv FUSE_SET_ATTR_ATIME_NOW +.Dv FUSE_SET_ATTR_MTIME_NOW +.Ed +.Pp +On success, return the updated attributes with +.Xr fuse_reply_attr 3 . +.It Xo Fo statfs +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fc Xc +Provide file system information. +.Pp +On success, respond with +.Xr fuse_reply_statfs 3 . +.It Xo Fo unlink +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "const char *name" +.Fc Xc +Delete file +.Fa name +from directory +.Fa parent . +.It Xo Fo write +.Fa "fuse_req_t req" +.Fa "fuse_ino_t ino" +.Fa "char char *buf" +.Fa "size_t size" +.Fa "off_t off" +.Fa "struct fuse_file_info *ffi" +.Fc Xc +Write +.Fa size +bytes from +.Fa buf +to file +.Fa ino +at offset +.Fa off . +.Pp +On success, respond with +.Xr fuse_reply_write 3 . +.El +.Pp +.Fn fuse_session_destroy +destroys the FUSE session +.Fa se , +freeing all associated resources. +This should be called after the session +loop completes and the file system has been unmounted. +.Pp +.Fn fuse_add_direntry +formats a single directory entry and appends it to a buffer suitable +for returning to the kernel. +.Fa buf +points to the location in the buffer where the new dirent should be added and +.Fa bufsize +specifies the remaining size of the buffer. +.Fa name +is a NUL-terminated string for the name of the new entry. +Only the st_ino field and bits 12-15 of the st_mode field from the +.Fa stbuf +argument are used. +All other fields are ignored. +.Fa off +is a file system specific offset of the next entry. +.Sh RETURN VALUES +.Fn fuse_lowlevel_new +returns a pointer to a newly created +.Vt struct fuse_session +on success or +.Dv NULL +on failure. +.Pp +.Fn fuse_add_direntry +returns the number of bytes required to store the directory entry, regardless +of whether it was written to +.Fa buf . +.Sh SEE ALSO +.Xr FUSE_ARGS_INIT 3 , +.Xr fuse_mount 3 , +.Xr fuse_reply_err 3 , +.Xr fuse_session_loop 3 +.Sh STANDARDS +These library functions conform to FUSE 2.6. +.Sh HISTORY +These library functions have been available since +.Ox 7.9 . +.Sh AUTHORS +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_main.3 b/static/openbsd/man3/fuse_main.3 new file mode 100644 index 00000000..4fd5fed3 --- /dev/null +++ b/static/openbsd/man3/fuse_main.3 @@ -0,0 +1,153 @@ +.\" $OpenBSD: fuse_main.3,v 1.10 2026/01/29 06:04:27 helg Exp $ +.\" +.\" Copyright (c) 2013 Sylvestre Gallon +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: January 29 2026 $ +.Dt FUSE_MAIN 3 +.Os +.Sh NAME +.Nm fuse_main +.Nd FUSE helper function +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft int +.Fn fuse_main "int argc" "char **argv" "const struct fuse_operations *ops" \ + "void *data" +.Sh DESCRIPTION +There are two ways of implementing a FUSE filesystem: +by calling only +.Fn fuse_main +and passing this function the +.Em ops +argument containing all the callbacks of the filesystem, +or by using the other functions, +as detailed in +.Xr fuse_loop 3 +.Pp +.Fa argv +is the list of arguments supplied to the program's main method and +must at a minimum specify the directory on which the file system is to +be mounted. +The other arguments can be custom arguments specific to the +file system or those supported by +.Xr fuse_parse_cmdline 3 , +.Xr fuse_new 3 +and +.Xr fuse_mount 3 . +.Sh EXAMPLES +Here is a simple example of a FUSE implementation: +.Bd -literal +#include +#include +#include + +static int +fs_readdir(const char *path, void *data, fuse_fill_dir_t filler, + off_t off, struct fuse_file_info *ffi) +{ + if (strcmp(path, "/") != 0) + return -ENOENT; + + filler(data, ".", NULL, 0); + filler(data, "..", NULL, 0); + filler(data, "file", NULL, 0); + return 0; +} + +static int +fs_read(const char *path, char *buf, size_t size, off_t off, + struct fuse_file_info *ffi) +{ + size_t len; + const char *file_contents = "fuse filesystem example\\n"; + + len = strlen(file_contents); + + if (off < len) { + if (off + size > len) + size = len - off; + memcpy(buf, file_contents + off, size); + } else + size = 0; + + return size; +} + +static int +fs_open(const char *path, struct fuse_file_info *ffi) +{ + if (strncmp(path, "/file", 10) != 0) + return -ENOENT; + + if ((ffi->flags & 3) != O_RDONLY) + return -EACCES; + + return 0; +} + +static int +fs_getattr(const char *path, struct stat *st) +{ + if (strcmp(path, "/") == 0) { + st->st_blksize = 512; + st->st_mode = S_IFDIR | 0755; + st->st_nlink = 2; + } else if (strcmp(path, "/file") == 0) { + st->st_mode = S_IFREG | 0644; + st->st_blksize = 512; + st->st_nlink = 1; + st->st_size = 5; + } else { + return -ENOENT; + } + + return 0; +} + +struct fuse_operations fsops = { + .readdir = fs_readdir, + .read = fs_read, + .open = fs_open, + .getattr = fs_getattr, +}; + +int +main(int argc, char **argv) +{ + return (fuse_main(argc, argv, &fsops, NULL)); +} +.Ed +.Sh SEE ALSO +.Xr fuse_loop 3 , +.Xr fuse_mount 3 , +.Xr fuse_new 3 , +.Xr fuse_parse_cmdline 3 , +.Xr fuse_setup 3 , +.Xr fuse_teardown 3 , +.Xr fuse 4 +.Sh STANDARDS +The +.Fn fuse_main +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_main +function first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_mount.3 b/static/openbsd/man3/fuse_mount.3 new file mode 100644 index 00000000..7020a48c --- /dev/null +++ b/static/openbsd/man3/fuse_mount.3 @@ -0,0 +1,125 @@ +.\" $OpenBSD: fuse_mount.3,v 1.5 2025/09/23 09:28:28 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: September 23 2025 $ +.Dt FUSE_MOUNT 3 +.Os +.Sh NAME +.Nm fuse_mount , +.Nm fuse_unmount +.Nd mount or dismount a FUSE file system +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft struct fuse_chan * +.Fn fuse_mount "const char *dir" "struct fuse_args *args" +.Ft void +.Fn fuse_unmount "const char *dir" "struct fuse_chan *ch" +.Sh DESCRIPTION +The +.Fn fuse_mount +function calls the +.Xr mount 2 +system call to graft the FUSE file system on to the file system tree +at the point +.Fa dir . +.Fa args +are FUSE specific mount options as documented by +.Xr mount 2 . +.Pp +The following mount options can be specified by preceding them with +.Fl o , +either individually or together separated by a comma. +.Bl -tag -width Ds +.It allow_other +Allow other users to access the file system. +By default, FUSE prevents other users from accessing the file system or to +.Xr statfs 2 +the file system. +This security measure is particularly important for +network file system that may expose private files. +It also guards against system processes being blocked indefinitely +if the file system stops responding. +.It default_permissions +Request that the kernel enforce file access permissions. +Alternatively, FUSE file systems can choose to implement access +checks internally. +On +.Ox , +this option is always set. +.It kernel_cache +Enables buffering of files in the kernel. +Not recommended for file systems that can be updated external to FUSE, +such as network file systems. +Not implemented. +.It max_read=%u +Specify the maximum size of read operations. +Note that the kernel limits this to FUSEBUFMAXSIZE. +This option should not be specified on the command line. +The correct (or optimum) value depends on the filesystem implementation +and should thus be specified by the filesystem internally. +.It ro +Mount the file system read-only. +Can also be specified by itself with +.Fl r . +.El +.Pp +.Fn fuse_unmount +closes the FUSE device and attempts to unmount the file system mounted at +.Fa dir +by calling the +.Xr unmount 2 +system call. +To avoid a deadlock, the kernel will not send the +.Dv FBT_DESTROY +message to the file system. +There is no way to determine whether this call was successful. +.Pp +Only the super user can mount and unmount FUSE file systems. +.Sh RETURN VALUES +.Fn fuse_main +returns +.Dv NULL +if the file system cannot be mounted. +.Sh ERRORS +.Fn fuse_mount +fails when one of the following occurs: +.Fa dir +does not exist or is not a directory. +The fuse device cannot be opened for reading and writing. +There was an error parsing the options specified by +.Fa args . +The file system could not be mounted. +.Sh SEE ALSO +.Xr mount 2 , +.Xr fuse_main 3 , +.Xr fuse_setup 3 , +.Xr fuse 4 +.Sh STANDARDS +The +.Fn fuse_mount +and +.Fn fuse_unmount +functions conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_mount +and +.Fn fuse_unmount +functions first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_new.3 b/static/openbsd/man3/fuse_new.3 new file mode 100644 index 00000000..946ca220 --- /dev/null +++ b/static/openbsd/man3/fuse_new.3 @@ -0,0 +1,249 @@ +.\" $OpenBSD: fuse_new.3,v 1.11 2025/09/23 09:28:28 schwarze Exp $ +.\" +.\" Copyright (c) 2013 Sylvestre Gallon +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: September 23 2025 $ +.Dt FUSE_NEW 3 +.Os +.Sh NAME +.Nm fuse_new +.Nd FUSE implementation routine to initialise the FUSE connection +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft struct fuse * +.Fn fuse_new "struct fuse_chan *fc" "struct fuse_args *args" \ + "const struct fuse_operations *ops" "unused size_t size" \ + "void *userdata" +.Sh DESCRIPTION +Initialises the FUSE library on the channel returned by +.Xr fuse_mount 3 . +.Pp +FUSE operations work in the same way as their UNIX file system +counterparts. +A major exception is that these routines return +a negated errno value (-errno) on failure. +.Pp +All operations are optional but a functional file system will want to +implement at least statfs, readdir, open, read and getattr. +FUSE returns +.Er ENOSYS +if any operation other than flush, fsync or +fsyncdir is not implemented. +.Pp +The first parameter to each of these operations (except for init and +destroy) is a NUL-terminated string representing the full path to +the file or directory, relative to the root of the file system, that +is being operated on. +.Bd -literal +struct fuse_operations { + int (*getattr)(const char *, struct stat *); + int (*readlink)(const char *, char *, size_t); + int (*getdir)(const char *, fuse_dirh_t, fuse_dirfil_t); + int (*mknod)(const char *, mode_t, dev_t); + int (*mkdir)(const char *, mode_t); + int (*unlink)(const char *); + int (*rmdir)(const char *); + int (*symlink)(const char *, const char *); + int (*rename)(const char *, const char *); + int (*link)(const char *, const char *); + int (*chmod)(const char *, mode_t); + int (*chown)(const char *, uid_t, gid_t); + int (*truncate)(const char *, off_t); + int (*utime)(const char *, struct utimbuf *); + int (*open)(const char *, struct fuse_file_info *); + int (*read)(const char *, char *, size_t, off_t, + struct fuse_file_info *); + int (*write)(const char *, const char *, size_t, off_t, + struct fuse_file_info *); + int (*statfs)(const char *, struct statvfs *); + int (*flush)(const char *, struct fuse_file_info *); + int (*release)(const char *, struct fuse_file_info *); + int (*fsync)(const char *, int, struct fuse_file_info *); + int (*setxattr)(const char *, const char *, const char *, + size_t int); + int (*getxattr)(const char *, const char *, char *, size_t); + int (*listxattr)(const char *, char *, size_t); + int (*removexattr)(const char *, const char *); + int (*opendir)(const char *, struct fuse_file_info *); + int (*readdir)(const char *, void *, fuse_fill_dir_t, off_t, + struct fuse_file_info *); + int (*releasedir)(const char *, struct fuse_file_info *); + int (*fsyncdir)(const char *, int, struct fuse_file_info *); + void *(*init)(struct fuse_conn_info *); + void (*destroy)(void *); + int (*access)(const char *, int); + int (*create)(const char *, mode_t, struct fuse_file_info *); + int (*ftruncate)(const char *, off_t, struct fuse_file_info *); + int (*fgetattr)(const char *, struct stat *, struct + fuse_file_info *); + int (*lock)(const char *, struct fuse_file_info *, int, + struct flock *); + int (*utimens)(const char *, const struct timespec *); + int (*bmap)(const char *, size_t , uint64_t *); +}; +.Ed +.Pp +The order of calls is: +.Bd -literal -offset indent +init +\&... +opendir +readdir +releasedir +open +read +write +\&... +flush +release +\&... +destroy +.Ed +.Bl -tag -width "releasedir" +.It access +Not implemented. +.Ox +always behaves as if the default_permissions mount option was specified. +See +.Xr fuse_mount 3 . +.It chmod +Called when file access permissions are changed. +.It chown +Called when either the file owner or group is changed. +.It create +Not implemented on +.Ox . +File systems must implement mknod instead. +In the reference implementation this is an atomic operation that both +creates and opens the file. +There is no equivalent in the +.Ox +VFS. +.It flush +Called when the file is closed by the +.Xr close 2 +system call. +This is the only way for a file system to return an error on close. +.It fsync +Optional function that implements +.Xr fsync 2 +and +.Xr fdatasync 2 . +The datasync parameter specifies whether the operation is as a result +of a call to +.Xr fdatasync 2 +and is currently always 0 (false). +ffi.fh_id will contain the file handle returned by the file system when +the file was opened. +.It fsyncdir +Not implemented. +.It getattr +Corresponds to the +.Xr stat 2 +system call. +Flags and extended attributes are ignored. +This operation is mandatory. +.It getxattr +Not implemented. +.It getdir +Deprecated. +File system should implement readdir instead. +.It mknod +Called on +.Xr open 2 +and +.Xr mknod 2 +to create regular files, pipes and device special files. +.It open +Called on +.Xr open 2 . +Due to the difference between FUSE and the +.Ox +VFS, +open will only be called once for each file +for every different combination of flags provided to +.Xr open 2 . +The O_CREAT and O_TRUNC flags are never passed from the kernel to open, +the mknod and truncate operations are invoked before open instead. +.It opendir +Called when a directory is opened for reading. +.It readlink +Called to read the target of a symbolic link. +The path must be NUL-terminated. +.It release +Called when there are no more references to the file. +.It releasedir +Called when there are no more references to the directory. +.It setattr +Equivalent to +.Xr chown 2 +and +.Xr chmod 2 +system calls. +Setting file flags is not supported. +.It setxattr +Not implemented. +.El +.Pp +Options supported by args are: +.Bl -tag -width "readdir_ino" +.It debug, -d +Print debug information to stdout. +.It gid=%u +The GID that will be reported as the group for all files by getattr. +.It hard_remove +Immediately delete a file even if it's currently open by a process. +Otherwise FUSE will temporarily rename the file and only delete it when +it is no longer referenced. +This is to avoid the file system having to deal with this situation. +This is always set on +.Ox . +.It readdir_ino +Similar to use_ino but the file system's inode number is only reported +for readdir. +This is always set on +.Ox +because it's required by +.Xr getcwd 3 . +.It uid=%u +The UID that will be reported as the owner for all files by getattr. +.It umask=%o +The file mode mask applied to the permission for all files by getattr. +.It use_ino +By default, FUSE will return an internal inode number for getattr and +readdir and this will be different every time the file system is +mounted. +If this is set, the file system's own inode number will be +reported instead. +Useful only for file system that have inode numbers. +.El +.Sh SEE ALSO +.Xr fuse_get_context 3 , +.Xr fuse_main 3 , +.Xr fuse_mount 3 +.Sh STANDARDS +The +.Fn fuse_new +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_new +function first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_opt.3 b/static/openbsd/man3/fuse_opt.3 new file mode 100644 index 00000000..3b8b46b3 --- /dev/null +++ b/static/openbsd/man3/fuse_opt.3 @@ -0,0 +1,430 @@ +.\" $OpenBSD: fuse_opt.3,v 1.9 2026/03/14 10:47:00 helg Exp $ +.\" +.\" Copyright (c) Ray Lai +.\" Copyright (c) Helg Bredow +.\" +.\" 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: March 14 2026 $ +.Dt FUSE_OPT 3 +.Os +.Sh NAME +.Nm FUSE_ARGS_INIT , +.Nm FUSE_OPT_IS_OPT_KEY , +.Nm FUSE_OPT_KEY , +.Nm FUSE_OPT_END , +.Nm fuse_opt_add_arg , +.Nm fuse_opt_insert_arg , +.Nm fuse_opt_add_opt , +.Nm fuse_opt_add_opt_escaped , +.Nm fuse_opt_free_args , +.Nm fuse_opt_match , +.Nm fuse_opt_parse +.Nd FUSE argument and option parser +.Sh SYNOPSIS +.Lb libfuse +.In fuse_opt.h +.Ft struct fuse_args +.Fo FUSE_ARGS_INIT +.Fa "int argc" +.Fa "char argv**" +.Fc +.Ft int +.Fo FUSE_OPT_IS_OPT_KEY +.Fa "fuse_opt *t" +.Fc +.Ft struct fuse_opt +.Fo FUSE_OPT_KEY +.Fa "const char *templ" +.Fa "int key" +.Fc +.Ft struct fuse_opt +.Fn FUSE_OPT_END +.Ft int +.Fo fuse_opt_add_arg +.Fa "struct fuse_args *args" +.Fa "const char *arg" +.Fc +.Ft int +.Fo fuse_opt_insert_arg +.Fa "struct fuse_args *args" +.Fa "int pos" +.Fa "const char *opt" +.Fc +.Ft int +.Fo fuse_opt_add_opt +.Fa "char **opts" +.Fa "const char *opt" +.Fc +.Ft int +.Fo fuse_opt_add_opt_escaped +.Fa "char **opts" +.Fa "const char *opt" +.Fc +.Ft void +.Fo fuse_opt_free_args +.Fa "struct fuse_args *args" +.Fc +.Ft int +.Fo fuse_opt_match +.Fa "const struct fuse_opt *opts" +.Fa "const char *opt" +.Fc +.Ft int +.Fo fuse_opt_parse +.Fa "struct fuse_args *args" +.Fa "void *data" +.Fa "const struct fuse_opt *opts" +.Fa "fuse_opt_proc_t proc" +.Fc +.Ft typedef int +.Fo (*fuse_opt_proc_t) +.Fa "void *data" +.Fa "const char *arg" +.Fa "int key" +.Fa "struct fuse_args *outargs" +.Fc +.Sh DESCRIPTION +These FUSE library functions and macros provide support for complex +argument and option parsing. +These are typically entered on the command line +but may also be passed by file systems to the +.Xr fuse_mount 3 +and +.Xr fuse_new 3 +functions. +.Ft struct fuse_args +holds string options in an array: +.Bd -literal -offset indent +struct fuse_args { + int argc; /* argument count */ + char **argv; /* NULL-terminated array of arguments */ + int allocated; /* argv was allocated and must be freed */ +}; +.Ed +.Pp +.Bl -tag -width Ds -compact +.It Fn FUSE_ARGS_INIT +initializes a +.Ft struct fuse_args +with +.Fa argc +and +.Fa argv , +which are usually obtained from +.Fn main . +.Fa argv +is +.Dv NULL Ns -terminated , +and is suitable for use with +.Xr execvp 3 . +.Fa argv +is used directly and +.Fa allocated +is set to 0. +.Pp +.It Fn fuse_opt_add_arg +adds a single option to the end of +.Fa args . +If +.Fa args->allocated +is 0, +.Fa args->argv +is copied to the heap and +.Fa args->allocated +is set to a non-zero value. +.Pp +.It Fn fuse_opt_insert_arg +inserts a single argument at position +.Fa pos +into +.Fa args , +shifting +.Fa args->argv +as needed. +.Pp +.It Fn fuse_opt_free_args +If +.Fa args +is allocated, free +.Fa args->argv +and zero all members of +.Fa args . +Otherwise, do nothing. +.Pp +.It Fn FUSE_OPT_KEY templ key +Return a +.Fa struct fuse_opt +template that matches an argument or option +.Vt templ +with option key +.Vt key . +This macro is used as an element in +.Fa struct fuse_opt +arrays to create a template that is processed by a +.Vt fuse_opt_proc_t . +The special constants +.Dv FUSE_OPT_KEY_KEEP +and +.Dv FUSE_OPT_KEY_DISCARD +can be specified for +.Fa val +if +.Fa proc +does not need to handle this option or argument; +.Fa proc +is not called in this case. +.Bd -literal -offset indent +struct fuse_opt { + const char *templ; /* template for option */ + unsigned long off; /* data offset */ + int val; /* key value */ +}; +.Ed +.Pp +The following special key values can be used for +.Fa val : +.Bd -literal -offset indent +FUSE_OPT_KEY_OPT /* no match */ +FUSE_OPT_KEY_NONOPT /* non-option */ +FUSE_OPT_KEY_KEEP /* don't process; return 1 */ +FUSE_OPT_KEY_DISCARD /* don't process; return 0 */ +.Ed +.It Fn FUSE_OPT_END +The last element of each +.Fa "struct fuse_opt *opts" +array passed to any function must be +.Dv FUSE_OPT_END . +.Pp +.It Fn FUSE_OPT_IS_OPT_KEY templ +Check whether +.Fa templ +is an option key. +.Pp +.It Fn fuse_opt_add_opt +adds an option +.Fa opt +to a comma-separated string of options +.Fa opts . +.Fa *opts +can be +.Dv NULL , +which is typically used when adding the first option. +.Pp +.It Fn fuse_opt_add_opt_escaped +escapes any +.Sq ,\& +and +.Sq \e +characters in +.Fa opt +before adding it to +.Fa opts . +.Pp +.It Fn fuse_opt_match +tests if the argument or option +.Fa opt +appears in the list of templates +.Fa opts . +If +.Fa opt +is an option then it must not include the -o prefix. +.Pp +.It Fn fuse_opt_parse +parses options, setting any members of +.Fa data +automatically depending on the format of the template. +If +.Fa proc +is not +.Dv NULL , +then this is called for any argument that matches a template +that has +.Fa offset No = Dv FUSE_OPT_KEY_OPT . +.Fa opts +is an array of +.Ft struct fuse_opt , +each of which describes actions for each option: +.Pp +The following templates are supported as options and must be preceded by +.Fl o +in the list of arguments, with or without a space between +.Fl o +and the option. +If multiple options are specified they can be comma separated or specified +individually with +.Fl o +each time. +For example, these are all valid: +.Bd -unfilled -offset indent +.Fl o Ar foo +.Sm off +.Fl o Ar bar +.Fl o Ar foo , bar +.Sm on +.Ed +.Pp +foo matches exactly +.Pp +foo= matches exactly +.Pp +foo=bar matches the option exactly (treated the same as if it didn't have an =). +.Pp +foo=%u %u can be any format that can be parsed by +.Fn sscanf 3 . +If this is %s then a copy of the string is allocated. +.Pp +Arguments +.Pp +-b or --bar matches the argument and sets the value of the struct at offset +to key. +.Pp +.Qq Fl b Ns \ \& +or +.Qq Fl \-bar Ns \ \& +(trailing space) argument expects a value, the whole argument, +including -b, is passed to +.Fa proc +.Pp +.Qq Fl b Ar %u +or +.Qq Fl \-bar Ar %u +is treated the same as foo=%u above +.Pp +Each argument or option is matched against every template. +This allows more than one member of +.Fa data +to be set by a single argument or option (see example for gid below). +.Pp +.It Fn fuse_opt_proc_t +The fuse_opt_proc_t function takes the following arguments. +.Bl -tag -width Ds +.It Fa data +data argument passed to +.Fn fuse_opt_parse +.It Fa arg +the whole argument or option +.It Fa key +is the key defined with the option or one of the special keys. +.It Fa outargs +The current list of arguments +.El +.El +.Sh RETURN VALUES +.Fn fuse_opt_add_arg , +.Fn fuse_opt_insert_arg , +.Fn fuse_opt_add_opt , +.Fn fuse_opt_add_opt_escaped , +and +.Fn fuse_opt_parse +return 0 on success or \-1 on error. +.Pp +.Fn fuse_opt_match +returns 1 on match or 0 if no match. +.Pp +The +.Fn fuse_opt_proc_t +callback shall return 1 to retain the option in the output argument vector, +or 0 to discard it. +This permits options to be preserved for subsequent processing. +A return value of \-1 indicates an error condition and causes +.Fn fuse_opt_parse +to terminate with failure. +.Sh EXAMPLES +.Bd -literal +#include +#include +#include +#include +#include + +enum { + KEY_FOO +}; + +struct foo_config { + char *foo; + int bar; + gid_t gid; + int set_gid; + int toggle; +}; + +#define FOO_OPT(t, m) {t, offsetof(struct foo_config, m), 1} + +struct fuse_opt opts[] = { + FUSE_OPT_KEY("--foo ", KEY_FOO),/* passed to foo_opt_proc() */ + FOO_OPT("-b", bar), /* set to 1 if present */ + FOO_OPT("toggle", toggle), /* set to 1 if present */ + FOO_OPT("gid=", set_gid), /* set to 1 if present */ + FOO_OPT("gid=%u", gid), /* set to parsed value of %u */ + FUSE_OPT_END +}; + +int +foo_opt_proc(void *data, const char *val, int key, struct fuse_args *args) +{ + struct foo_config *conf = data; + + switch(key) + { + case KEY_FOO: + conf->foo = strdup(val); + return (0); /* discard */ + } + + /* didn't process, so keep the option */ + return (1); +} + +int +main(int argc, char *argv[]) +{ + struct fuse_args args = FUSE_ARGS_INIT(argc, argv); + struct foo_config config; + + memset(&config, 0, sizeof(config)); + if (fuse_opt_parse(&args, &config, opts, foo_opt_proc) == -1) + err(1, "Usage: prog [foo=value] [-b] " + "[-o [gid=value],[toggle]]"); + + printf("foo=%s\en", config.foo); + printf("toggle=%d\en", config.toggle); + printf("bar=%d\en", config.bar); + printf("set_gid=%d\en", config.set_gid); + printf("gid=%u\en", config.gid); +} +.Ed +.Sh ERRORS +.Fn fuse_opt_add_arg , +.Fn fuse_opt_insert_arg , +.Fn fuse_opt_add_opt , +and +.Fn fuse_opt_add_opt_escaped +can run out of memory and set +.Va errno . +.Sh SEE ALSO +.Xr fuse_main 3 +.Sh STANDARDS +These library functions conform to FUSE 2.6. +.Sh HISTORY +These functions first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com +.An Helg Bredow Aq Mt helg@openbsd.org +.Pp +This manual was written by +.An Ray Lai Aq Mt ray@raylai.com +and updated by +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_parse_cmdline.3 b/static/openbsd/man3/fuse_parse_cmdline.3 new file mode 100644 index 00000000..60895134 --- /dev/null +++ b/static/openbsd/man3/fuse_parse_cmdline.3 @@ -0,0 +1,101 @@ +.\" $OpenBSD: fuse_parse_cmdline.3,v 1.3 2025/09/23 09:28:28 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: September 23 2025 $ +.Dt FUSE_PARSE_CMDLINE 3 +.Os +.Sh NAME +.Nm fuse_parse_cmdline +.Nd FUSE helper function to parse command line arguments +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft int +.Fn fuse_parse_cmdline "struct fuse_args *args" "char **mp" \ + "int *mt" "int *fg" +.Sh DESCRIPTION +.Fn fuse_parse_cmdline +is a helper function to parse standard FUSE arguments. +.Fa args +can be constructed using the +.Xr FUSE_ARGS_INIT 3 +macro. +.Pp +.Fn fuse_parse_cmdline +supports the following arguments. +.Bl -tag -width Ds +.It Fl d , Fl odebug +Causes debug information for subsequent FUSE library calls to be output to +stderr. +Implies +.Fl f . +.It Fl f +If this is specified then +.Fa fg +will be set to 1 on success. +This flag indicates that the file system +should not detach from the controlling terminal and run in the foreground. +.It Fl h , Fl -help , Fl ho +Print usage information for the options supported by +.Fn fuse_parse_cmdline . +.It Fl s +If this is specified then +.Fa mt +will be set to 0 on success. +This flag indicates that the file system +should be run in multi-threaded mode. +.Fl s +is currently ignored and +.Fa mt +will always be 0. +.It Fl V , Fl -version +Print the FUSE library version to stderr. +.El +.Pp +If the first argument not recognised by +.Fn fuse_parse_cmdline +is a valid directory then +.Fa mp +will be set to the canonicalized absolute pathname of this directory. +.Sh RETURN VALUES +The +.Fn fuse_parse_cmdline +function returns 0 on success or -1 if +.Fl h , Fl -help , Fl ho , Fl v +or +.Fl -version +are included in +.Fa argv +or +.Fa mp +does not exist or is not a directory. +.Sh SEE ALSO +.Xr FUSE_ARGS_INIT 3 , +.Xr fuse_daemonize 3 , +.Xr fuse_main 3 , +.Xr fuse_setup 3 +.Sh STANDARDS +The +.Fn fuse_parse_cmdline +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_parse_cmdline +function first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_reply_err.3 b/static/openbsd/man3/fuse_reply_err.3 new file mode 100644 index 00000000..4a0852e1 --- /dev/null +++ b/static/openbsd/man3/fuse_reply_err.3 @@ -0,0 +1,203 @@ +.\" $OpenBSD: fuse_reply_err.3,v 1.1 2026/02/01 20:02:58 helg Exp $ +.\" +.\" Copyright (c) 2026 Helg Bredow +.\" +.\" 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: February 1 2026 $ +.Dt FUSE_REPLY_ERR 3 +.Os +.Sh NAME +.Nm fuse_reply_err , +.Nm fuse_reply_buf , +.Nm fuse_reply_attr , +.Nm fuse_reply_open , +.Nm fuse_reply_write , +.Nm fuse_reply_entry , +.Nm fuse_reply_statfs , +.Nm fuse_reply_readlink +.Nd send replies to FUSE requests +.Sh SYNOPSIS +.Lb libfuse +.In fuse_lowlevel.h +.Ft int +.Fo fuse_reply_err +.Fa "fuse_req_t req" +.Fa "int errno" +.Fc +.Ft int +.Fo fuse_reply_buf +.Fa "fuse_req_t req" +.Fa "const char *buf" +.Fa "off_t size" +.Fc +.Ft int +.Fo fuse_reply_attr +.Fa "fuse_req_t req" +.Fa "const struct stat *attr" +.Fa "double attr_timeout" +.Fc +.Ft int +.Fo fuse_reply_open +.Fa "fuse_req_t req" +.Fa "const struct fuse_file_info *fi" +.Fc +.Ft int +.Fo fuse_reply_write +.Fa "fuse_req_t req" +.Fa "size_t count" +.Fc +.Ft int +.Fo fuse_reply_entry +.Fa "fuse_req_t req" +.Fa "const struct fuse_entry_param *e" +.Fc +.Ft int +.Fo fuse_reply_statfs +.Fa "fuse_req_t req" +.Fa "const struct statvfs *stbuf" +.Fc +.Ft int +.Fo fuse_reply_readlink +.Fa "fuse_req_t req" +.Fa "char *linkname" +.Fc +.Sh DESCRIPTION +These functions are used in the FUSE low-level API to send responses to +requests received from the kernel. +.Pp +Once called, the request is considered handled and must not be replied to +again. +.Bl -tag -width Ds +.It Fn fuse_reply_err "req" "errno" +Send an error response to the request +.Fa req . +The +.Fa errno +parameter must be a valid (non-negated) error number, for example +.Er ENOENT +or +.Er EACCES .. +.Pp +This is a valid response for all file system operations. +.It Fn fuse_reply_buf "req" "buf" "size" +Send a buffer +.Fa buf +of +.Fa size +bytes of data to the kernel. +.Pp +This is a valid response for +.Fn read +and +.Fn readdir +operations. +.It Fn fuse_reply_attr "req" "attr" "attr_timeout" +Replies with file attributes specified in +.Fa attr , +valid for +.Fa attr_timeout +seconds. +The +.Ox +kernel does not currently support attribute caching and +.Fa attr_timeout +will be ignored. +.Pp +This is a valid response for +.Fn getattr +and +.Fn setattr +operations. +.It Fn fuse_reply_open "req" "ffi" +Send a response to an open request with the file info structure +.Fa ffi . +Only the +.Fa fh +member of +.Fa ffi +is used. +.Pp +This is a valid response for +.Fn open +and +.Fn opendir +operations. +.It Fn fuse_reply_write "req" "count" +Reply to a write request with the +.Fa count +of bytes written. +.Pp +This is a valid response for the +.Fn write +operation. +.It Fn fuse_reply_entry "req" "e" +Reply to a lookup or other request that results in new file creation with +the details of the new directory entry +.Fa e , +which is defined as follows: +.Bd -literal +struct fuse_entry_param { + ino_t ino; /* inode number of the entry */ + unsigned long generation; /* must be non-zero */ + struct stat attr; /* attributes of the entry */ + double attr_timeout; /* ignored */ + double entry_timeout; /* ignored */ +}; +.Ed +.Pp +The +.Ox +kernel does not currently cache FUSE lookups or attributes and the +.Fa attr_timeout +and +.Fa entry_timeout +members are ignored. +.Pp +This is a valid response for the +.Fn lookup , +.Fn mknod , +.Fn mkdir , +.Fn symlink , and +.Fn link +operations. +.It Fn fuse_reply_statfs "req" "stbuf" +Reply with file system statistics provided in +.Fa stbuf . +.Pp +This is a valid response for the +.Fn statfs +operation. +.It Fn fuse_reply_readlink "req" "link" +Replies to a readlink request with the symbolic link path +.Fa link . +The target string cannot contain the NUL character. +.Pp +This is a valid response for the +.Fn readlink +operation. +.El +.Sh RETURN VALUES +All functions return 0 on success. +On failure, they return +.Pf \- Va errno +to indicate the error. +.Sh SEE ALSO +.Xr fuse_lowlevel_new 3 +.Sh STANDARDS +These library functions conform to FUSE 2.6. +.Sh HISTORY +These library functions have been available since +.Ox 7.9 . +.Sh AUTHORS +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_session_loop.3 b/static/openbsd/man3/fuse_session_loop.3 new file mode 100644 index 00000000..8f7ab476 --- /dev/null +++ b/static/openbsd/man3/fuse_session_loop.3 @@ -0,0 +1,120 @@ +.\" $OpenBSD: fuse_session_loop.3,v 1.1 2026/02/01 20:02:58 helg Exp $ +.\" +.\" Copyright (c) 2026 Helg Bredow +.\" +.\" 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: February 1 2026 $ +.Dt FUSE_SESSION_LOOP 3 +.Os +.Sh NAME +.Nm fuse_session_loop , +.Nm fuse_session_process , +.Nm fuse_session_add_chan , +.Nm fuse_session_remove_chan , +.Nm fuse_session_exit , +.Nm fuse_session_exited , +.Nm fuse_session_reset +.Nd manage lifecycle and event handling for a FUSE session +.Sh SYNOPSIS +.Lb fuse +.In fuse_lowlevel.h +.Ft int +.Fn fuse_session_loop "struct fuse_session *se" +.Ft void +.Fo fuse_session_process +.Fa "struct fuse_session *se" +.Fa "struct fuse_chan *ch" +.Fa "const struct fuse_buf *buf" +.Fa "struct fuse_buf *outbuf" +.Fc +.Ft void +.Fo fuse_session_add_chan +.Fa "struct fuse_session *se" +.Fa "struct fuse_chan *ch" +.Fc +.Ft void +.Fn fuse_session_remove_chan "struct fuse_chan *ch" +.Ft void +.Fn fuse_session_exit "struct fuse_session *se" +.Ft int +.Fn fuse_session_exited "struct fuse_session *se" +.Ft void +.Fn fuse_session_reset "struct fuse_session *se" +.Sh DESCRIPTION +These functions are part of the FUSE low-level API and are used to manage the +lifecycle, communication channel, and event processing of a FUSE session. +.Pp +A fuse_session is created with +.Xr fuse_lowlevel_new 3 . +.Bl -tag -width Ds +.It Fn fuse_session_loop "se" +Run the main event loop for the session +.Fa se . +This function blocks and processes incoming requests until +.Fn fuse_session_exit +is called. +.It Fn fuse_session_process "se" "buf" "bufsize" "ch" +Process a single buffer +.Fa buf +received from channel +.Fa ch +in the session +.Fa se . +If ch is +.Dv NULL +then the channel added to the session is used instead. +Used for manual request handling outside of the main loop. +.It Fn fuse_session_add_chan "se" "ch" +Add the communication channel +.Fa ch +to the session +.Fa se . +Channels are used to receive requests from the kernel. +A session may be associated with only one channel at a time, and a channel +may be associated with only one session at a time. +.It Fn fuse_session_remove_chan "ch" +Remove the channel +.Fa ch +from its associated session. +.It Fn fuse_session_exit "se" +Signal the session +.Fa se +to exit its event loop. +This does not destroy the session or unmount the filesystem. +.It Fn fuse_session_reset "se" +Reset the session +.Fa se +to a non-exited state, allowing the loop to be restarted. +.El +.Sh RETURN VALUES +.Fn fuse_session_loop +returns 0 on success or -1 on failure. +.Pp +.Fn fuse_session_exited +Returns non-zero if +.Fn fuse_session_exit +has been called and the session +.Fa se +is marked for termination. +.Sh SEE ALSO +.Xr fuse_chan_fd 3 , +.Xr fuse_lowlevel_new 3 , +.Xr fuse_mount 3 +.Sh STANDARDS +These library functions conform to FUSE 2.6. +.Sh HISTORY +These functions have been available since +.Ox 7.9 . +.Sh AUTHORS +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_set_signal_handlers.3 b/static/openbsd/man3/fuse_set_signal_handlers.3 new file mode 100644 index 00000000..576819a2 --- /dev/null +++ b/static/openbsd/man3/fuse_set_signal_handlers.3 @@ -0,0 +1,68 @@ +.\" $OpenBSD: fuse_set_signal_handlers.3,v 1.4 2025/09/23 09:28:28 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: September 23 2025 $ +.Dt FUSE_SET_SIGNAL_HANDLERS 3 +.Os +.Sh NAME +.Nm fuse_set_signal_handlers , +.Nm fuse_remove_signal_handlers +.Nd install and remove FUSE signal handlers +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft int +.Fn fuse_set_signal_handlers "struct fuse_session *se" +.Ft void +.Fn fuse_remove_signal_handlers "struct fuse_session *se" +.Sh DESCRIPTION +.Fn fuse_set_signal_handlers +installs signal handlers for the signals +.Dv SIGHUP , +.Dv SIGINT , +and +.Dv SIGTERM +that will attempt to unmount the file system. +.Dv SIGPIPE +will be ignored. +If there is already a signal handler installed for any of these signals +then it is not replaced. +.Pp +.Fn fuse_remove_signal_handlers +restores the default signal handlers for any signals that were +installed by +.Fn fuse_set_signal_handlers . +.Sh RETURN VALUES +.Fn fuse_set_signal_handlers +returns 0 on success or -1 on failure. +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr fuse_setup 3 +.Sh STANDARDS +The +.Fn fuse_set_signal_handlers +and +.Fn fuse_remove_signal_handlers +functions conform to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_set_signal_handlers +and +.Fn fuse_remove_signal_handlers +functions first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_setup.3 b/static/openbsd/man3/fuse_setup.3 new file mode 100644 index 00000000..6ba8b547 --- /dev/null +++ b/static/openbsd/man3/fuse_setup.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: fuse_setup.3,v 1.5 2025/09/23 09:28:28 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: September 23 2025 $ +.Dt FUSE_SETUP 3 +.Os +.Sh NAME +.Nm fuse_setup +.Nd FUSE helper function +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft struct fuse * +.Fn fuse_setup "int argc" "char **argv" \ + "const struct fuse_operations *ops" "size_t size" "char **mp" \ + "int *mt" "void *data" +.Sh DESCRIPTION +.Fn fuse_setup +is a helper function that mounts a FUSE file system, creates a new FUSE +session and installs signal handlers that will try to unmount the file +system on +.Dv SIGINT , +.Dv SIGTERM , +or +.Dv SIGHUP . +.Pp +.Fn fuse_setup +parses the arguments specified by +.Fa argv , +and if neither the +.Fl f , +.Fl d , +or +.Fl odebug +options were specified, detaches from the controlling terminal +and runs in the background. +On success, +.Fa mt +is set to 1 if the file system operations will be invoked in +parallel (multi-threaded) or to 0 if file system operations are serialized. +File systems that do not support multi-threaded operation must include the +.Fl s +argument in +.Fa argv . +.Ox +does not currently support multi-threaded operation. +.Pp +The file system will be mounted on +.Fa mp , +which is the directory specified by the first +argument that does not match one of the options recognised by +.Xr fuse_parse_cmdline 3 . +.Pp +.Fa fuse_operations +is a struct of size +.Fa size +that contains pointers to FUSE file system operations. +See +.Xr fuse_new 3 . +.Sh RETURN VALUES +.Fn fuse_setup +returns +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr fuse_main 3 , +.Xr fuse_mount 3 , +.Xr fuse_new 3 , +.Xr fuse_parse_cmdline 3 , +.Xr fuse_set_signal_handlers 3 , +.Xr fuse_teardown 3 , +.Xr fuse 4 +.Sh STANDARDS +The +.Fn fuse_setup +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_setup +function first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_teardown.3 b/static/openbsd/man3/fuse_teardown.3 new file mode 100644 index 00000000..4c7cdc0c --- /dev/null +++ b/static/openbsd/man3/fuse_teardown.3 @@ -0,0 +1,55 @@ +.\" $OpenBSD: fuse_teardown.3,v 1.3 2025/06/10 12:55:33 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: June 10 2025 $ +.Dt FUSE_TEARDOWN 3 +.Os +.Sh NAME +.Nm fuse_teardown +.Nd FUSE helper function +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft void +.Fn fuse_teardown "struct fuse *f" "char *mp" +.Sh DESCRIPTION +.Fn fuse_teardown +is a helper function that removes any signal handlers that were +installed by a previous call to +.Xr fuse_set_signal_handlers 3 +or +.Xr fuse_setup 3 +and unmounts the file system mounted at +.Fa mp . +The FUSE session +.Fa f +is then destroyed. +.Sh SEE ALSO +.Xr fuse_destroy 3 , +.Xr fuse_remove_signal_handlers 3 , +.Xr fuse_unmount 3 +.Sh STANDARDS +The +.Fn fuse_teardown +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_teardown +function first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com +.An Helg Bredow Aq Mt helg@openbsd.org diff --git a/static/openbsd/man3/fuse_version.3 b/static/openbsd/man3/fuse_version.3 new file mode 100644 index 00000000..9944dddc --- /dev/null +++ b/static/openbsd/man3/fuse_version.3 @@ -0,0 +1,43 @@ +.\" $OpenBSD: fuse_version.3,v 1.3 2025/06/10 12:55:33 schwarze Exp $ +.\" +.\" Copyright (c) 2018 Helg Bredow +.\" +.\" 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: June 10 2025 $ +.Dt FUSE_VERSION 3 +.Os +.Sh NAME +.Nm fuse_version +.Nd get the version of the FUSE library +.Sh SYNOPSIS +.Lb libfuse +.In fuse.h +.Ft int +.Fn fuse_version "void" +.Sh DESCRIPTION +Gets the version of the FUSE library as a whole number. +For example, Version 2.6 is returned as 26. +.Sh SEE ALSO +.Xr fuse_main 3 +.Sh STANDARDS +The +.Fn fuse_version +function conforms to FUSE 2.6. +.Sh HISTORY +The +.Fn fuse_version +function first appeared in +.Ox 5.4 . +.Sh AUTHORS +.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com diff --git a/static/openbsd/man3/fwide.3 b/static/openbsd/man3/fwide.3 new file mode 100644 index 00000000..b7fa3d74 --- /dev/null +++ b/static/openbsd/man3/fwide.3 @@ -0,0 +1,94 @@ +.\" $OpenBSD: fwide.3,v 1.3 2007/05/31 19:19:31 jmc Exp $ +.\" +.\" $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 $Mdocdate: May 31 2007 $ +.Dt FWIDE 3 +.Os +.Sh NAME +.Nm fwide +.Nd get/set orientation of a stream +.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/openbsd/man3/gai_strerror.3 b/static/openbsd/man3/gai_strerror.3 new file mode 100644 index 00000000..93d11aad --- /dev/null +++ b/static/openbsd/man3/gai_strerror.3 @@ -0,0 +1,95 @@ +.\" $OpenBSD: gai_strerror.3,v 1.11 2025/06/13 18:34:00 schwarze Exp $ +.\" $KAME: gai_strerror.3,v 1.1 2005/01/05 03:04:47 itojun 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 $Mdocdate: June 13 2025 $ +.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 name +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 name +.It Dv EAI_NONAME +.Fa name +or +.Fa service +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 service +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/openbsd/man3/gelf.3 b/static/openbsd/man3/gelf.3 new file mode 100644 index 00000000..2ba2ce70 --- /dev/null +++ b/static/openbsd/man3/gelf.3 @@ -0,0 +1,204 @@ +.\" 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,v 1.6 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd June 12, 2019 +.Dt GELF 3 +.Os +.Sh NAME +.Nm gelf +.Nd class-independent API for ELF manipulation +.Sh SYNOPSIS +.Lb libelf +.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 "gelf_update_shdr" +.It Fn gelf_update_dyn +Copy back an ELF +.Sy .dynamic +Table entry. +.It Fn gelf_update_ehdr +Copy back an ELF Executable Header 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/openbsd/man3/gelf_checksum.3 b/static/openbsd/man3/gelf_checksum.3 new file mode 100644 index 00000000..5dc89538 --- /dev/null +++ b/static/openbsd/man3/gelf_checksum.3 @@ -0,0 +1,114 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar 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 +.Ar elf +of class +.Dv ELFCLASS32 . +.Pp +Function +.Fn elf64_checksum +returns a checksum for an ELF descriptor +.Ar elf +of class +.Dv ELFCLASS64 . +.Pp +Function +.Fn gelf_checksum +provides a class-independent way retrieving the checksum +for ELF object +.Ar 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 +.Ar elf +was NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not a descriptor for an ELF file. +.It Bq Er ELF_E_ARGUMENT +The ELF descriptor +.Ar 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 +.Ar elf +did not match the class of the called function. +.It Bq Er ELF_E_HEADER +The ELF object specified by argument +.Ar 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 +.Ar 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/openbsd/man3/gelf_fsize.3 b/static/openbsd/man3/gelf_fsize.3 new file mode 100644 index 00000000..b6eddf6b --- /dev/null +++ b/static/openbsd/man3/gelf_fsize.3 @@ -0,0 +1,95 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar count +numbers of objects of ELF type +.Ar 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 +.Ar 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 +.Ar elf +was NULL in a call to +.Fn gelf_fsize . +.It Bq Er ELF_E_ARGUMENT +ELF descriptor +.Ar elf +had an unknown ELF class. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar type +contained an illegal value. +.It Bq Er ELF_E_UNIMPL +Support for ELF type +.Ar type +has not been implemented. +.It Bq Er ELF_E_VERSION +Argument +.Ar version +is not a supported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr gelf 3 diff --git a/static/openbsd/man3/gelf_getcap.3 b/static/openbsd/man3/gelf_getcap.3 new file mode 100644 index 00000000..b4d2d5f5 --- /dev/null +++ b/static/openbsd/man3/gelf_getcap.3 @@ -0,0 +1,126 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SUNW_cap . +Argument +.Ar 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 +.Ar ndx +in data buffer +.Ar data +and copies it to the destination pointed to by argument +.Ar cap +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_cap +converts the class-independent entry pointed to +by argument +.Ar cap +to class-dependent form, and writes it to the entry at index +.Ar ndx +in the data buffer described by argument +.Ar 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 +.Ar cap +if successful, or 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 +.Ar data +or +.Ar cap +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar ndx +was less than zero or larger than the number of entries in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Ar 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 +.Ar 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/openbsd/man3/gelf_getclass.3 b/static/openbsd/man3/gelf_getclass.3 new file mode 100644 index 00000000..071c6efc --- /dev/null +++ b/static/openbsd/man3/gelf_getclass.3 @@ -0,0 +1,60 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd July 3, 2006 +.Dt GELF_GETCLASS 3 +.Os +.Sh NAME +.Nm gelf_getclass +.Nd retrieve the class of an ELF descriptor +.Sh SYNOPSIS +.Lb libelf +.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 +.Ar elf . +.Sh RETURN VALUES +Function +.Fn gelf_getclass +will return one of +.Dv ELFCLASS32 +or +.Dv ELFCLASS64 +if the argument +.Ar elf +is a descriptor for an ELF file. +The value +.Dv ELFCLASSNONE +is returned if argument +.Ar 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/openbsd/man3/gelf_getdyn.3 b/static/openbsd/man3/gelf_getdyn.3 new file mode 100644 index 00000000..dcded7be --- /dev/null +++ b/static/openbsd/man3/gelf_getdyn.3 @@ -0,0 +1,129 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_DYNAMIC . +Argument +.Ar 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 +.Ar ndx +in data buffer +.Ar data +and copies it to the destination pointed to by argument +.Ar dyn +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_dyn +converts the class-independent entry pointed to +by argument +.Ar dyn +to class-dependent form, and writes it to the entry at index +.Ar ndx +in the data buffer described by argument +.Ar 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 +.Ar dyn +if successful, or 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 +.Ar data +or +.Ar dyn +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar ndx +was less than zero or larger than the number of entries in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Ar 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 +.Ar 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/openbsd/man3/gelf_getehdr.3 b/static/openbsd/man3/gelf_getehdr.3 new file mode 100644 index 00000000..738a2a5b --- /dev/null +++ b/static/openbsd/man3/gelf_getehdr.3 @@ -0,0 +1,122 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar 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 +.Ar elf . +These functions return +.Dv NULL +if an ELF header was not found in file +.Ar elf . +.Pp +Function +.Fn gelf_getehdr +stores a translated copy of the header for ELF file +.Ar elf +into the descriptor pointed to by argument +.Ar dst . +It returns argument +.Ar 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 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 +.Ar elf +was null. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not a descriptor for an ELF file. +.It Bq Er ELF_E_ARGUMENT +The elf class of descriptor +.Ar elf +was not recognized. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar dst +was null. +.It Bq Er ELF_E_CLASS +The ELF class of descriptor +.Ar elf +did not match that of the API function being called. +.It Bq Er ELF_E_HEADER +ELF descriptor +.Ar 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 +.Ar elf +did not adhere to the conventions used for extended numbering. +.It Bq Er ELF_E_VERSION +The ELF descriptor +.Ar 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/openbsd/man3/gelf_getmove.3 b/static/openbsd/man3/gelf_getmove.3 new file mode 100644 index 00000000..a9a1ae41 --- /dev/null +++ b/static/openbsd/man3/gelf_getmove.3 @@ -0,0 +1,125 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SUNW_move . +Argument +.Ar 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 +.Ar ndx +in data buffer +.Ar data +and copies it to the destination pointed to by argument +.Ar move +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_move +converts the class-independent move information pointed to +by argument +.Ar move +to class-dependent form, and writes it to the move record at index +.Ar ndx +in the data buffer described by argument +.Ar 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 +.Ar move +if successful, or 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 +.Ar data +or +.Ar move +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar ndx +was less than zero or larger than the number of records in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Ar 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 +.Ar 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/openbsd/man3/gelf_getphdr.3 b/static/openbsd/man3/gelf_getphdr.3 new file mode 100644 index 00000000..f4ad252c --- /dev/null +++ b/static/openbsd/man3/gelf_getphdr.3 @@ -0,0 +1,140 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar index +from ELF descriptor +.Ar elf . +The translated program header table entry will be written to the +address pointed to be argument +.Ar 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 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 +.Ar elf +was NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar dst +was NULL. +.It Bq Er ELF_E_ARGUMENT +Index +.Ar index +was out of range. +.It Bq Er ELF_E_CLASS +The class of ELF descriptor +.Ar elf +did not match the expected class of the function being called. +.It Bq Er ELF_E_HEADER +ELF descriptor +.Ar elf +did not possess an executable header. +.It Bq Er ELF_E_HEADER +ELF descriptor +.Ar 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 +.Ar elf +did not adhere to the conventions used for extended numbering. +.It Bq Er ELF_VERSION +ELF descriptor +.Ar 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/openbsd/man3/gelf_getrel.3 b/static/openbsd/man3/gelf_getrel.3 new file mode 100644 index 00000000..89292035 --- /dev/null +++ b/static/openbsd/man3/gelf_getrel.3 @@ -0,0 +1,126 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_REL . +Argument +.Ar 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 +.Ar ndx +in data buffer +.Ar data +and copies it to the destination pointed to by argument +.Ar rel +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_rel +converts the class-independent entry pointed to +by argument +.Ar rel +to class-dependent form, and writes it to the entry at index +.Ar ndx +in the data buffer described by argument +.Ar 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 +.Ar rel +if successful, or 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 +.Ar data +or +.Ar rel +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar ndx +was less than zero or larger than the number of entries in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Ar 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 +.Ar 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/openbsd/man3/gelf_getrela.3 b/static/openbsd/man3/gelf_getrela.3 new file mode 100644 index 00000000..a92909e3 --- /dev/null +++ b/static/openbsd/man3/gelf_getrela.3 @@ -0,0 +1,126 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_RELA . +Argument +.Ar 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 +.Ar ndx +in data buffer +.Ar data +and copies it to the destination pointed to by argument +.Ar rela +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_rela +converts the class-independent entry pointed to +by argument +.Ar rela +to class-dependent form, and writes it to the entry at index +.Ar ndx +in the data buffer described by argument +.Ar 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 +.Ar rela +if successful, or 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 +.Ar data +or +.Ar rela +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar ndx +was less than zero or larger than the number of entries in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Ar 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 +.Ar 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/openbsd/man3/gelf_getshdr.3 b/static/openbsd/man3/gelf_getshdr.3 new file mode 100644 index 00000000..83977d63 --- /dev/null +++ b/static/openbsd/man3/gelf_getshdr.3 @@ -0,0 +1,114 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar scn . +.Pp +Function +.Fn elf32_getshdr +retrieves a pointer to an +.Vt Elf32_Shdr +structure. +Section descriptor +.Ar 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 +.Ar 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 +.Ar scn +to the structure pointed to be argument +.Ar 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 NULL if an error was encountered. +.Pp +Function +.Fn gelf_getshdr +returns argument +.Ar dst +if successful, or 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 +.Ar scn +or +.Ar shdr +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar scn +was not associated a descriptor for an ELF object. +.It Bq Er ELF_E_CLASS +The ELF class associated with the section descriptor +.Ar 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/openbsd/man3/gelf_getsym.3 b/static/openbsd/man3/gelf_getsym.3 new file mode 100644 index 00000000..67b4b6b2 --- /dev/null +++ b/static/openbsd/man3/gelf_getsym.3 @@ -0,0 +1,130 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar 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 +.Ar 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 +.Ar ndx +in data buffer +.Ar data +and copies it to the destination pointed to by argument +.Ar sym +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_sym +converts the class-independent symbol information pointed to +by argument +.Ar sym +to class-dependent form, and writes it to the symbol entry at index +.Ar ndx +in the data buffer described by argument +.Ar 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 +.Ar sym +if successful, or 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 +.Ar data +or +.Ar sym +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar ndx +was less than zero or larger than the number of symbols in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Ar 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 +.Ar 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/openbsd/man3/gelf_getsyminfo.3 b/static/openbsd/man3/gelf_getsyminfo.3 new file mode 100644 index 00000000..92ab7e6b --- /dev/null +++ b/static/openbsd/man3/gelf_getsyminfo.3 @@ -0,0 +1,120 @@ +.\" 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,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SUNW_syminfo . +Argument +.Ar 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 +.Ar ndx +in data buffer +.Ar data +and copies it to the destination pointed to by argument +.Ar syminfo +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_syminfo +converts the class-independent record pointed to +by argument +.Ar syminfo +to class-dependent form, and writes it to the record at index +.Ar ndx +in the data buffer described by argument +.Ar data . +.Sh RETURN VALUES +Function +.Fn gelf_getsyminfo +returns the value of argument +.Ar syminfo +if successful, or 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 +.Ar data +or +.Ar syminfo +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar ndx +was less than zero or larger than the number of symbols in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Ar data +was not associated with a section containing symbol information. +.It Bq Er ELF_E_VERSION +The +.Vt Elf_Data +descriptor denoted by argument +.Ar 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/openbsd/man3/gelf_getsymshndx.3 b/static/openbsd/man3/gelf_getsymshndx.3 new file mode 100644 index 00000000..24e339d6 --- /dev/null +++ b/static/openbsd/man3/gelf_getsymshndx.3 @@ -0,0 +1,169 @@ +.\" 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_getsymshndx.3,v 1.3 2025/06/10 17:19:45 schwarze Exp $ +.\" +.Dd April 22, 2019 +.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 SYNOPSIS +.Lb libelf +.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 +.Ar symdata +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SYMTAB . +Argument +.Ar xndxdata +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SYMTAB_SHNDX . +Argument +.Ar ndx +is the index of the symbol table entry being retrieved or updated. +Argument +.Ar 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 +.Ar ndx +from the data descriptor specified by argument +.Ar symdata +and stores in class-independent form in argument +.Ar sym . +In addition it retrieves the extended section index for the +symbol from data buffer +.Ar xndxdata +and stores it into the location pointed to by argument +.Ar xndxptr . +.Pp +Function +.Fn gelf_update_symshndx +updates the underlying symbol table entry in data +descriptor +.Ar symdata +with the information in argument +.Ar sym . +In addition it sets the extended section index in +data buffer +.Ar xndxdata +to the value of argument +.Ar xndx . +.Sh RETURN VALUES +Function +.Fn gelf_getsymshndx +returns the value of argument +.Ar sym +if successful, or 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 +.Ar symdata , +.Ar xndxdata , +.Ar xndxptr +or +.Ar sym +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar ndx +was less than zero, or too large for either of descriptors +.Ar symdata +or +.Ar xndxdata . +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Ar symdata +was not associated with a section of type +.Dv SHT_SYMTAB . +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Ar xndxdata +was not associated with a section of type +.Dv SHT_SYMTAB_SHNDX . +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Ar symdata +and +.Ar xndxdata +were associated with different ELF objects. +.It Bq Er ELF_E_VERSION +The +.Vt Elf_Data +descriptors denoted by arguments +.Ar symdata +and +.Ar 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/openbsd/man3/gelf_newehdr.3 b/static/openbsd/man3/gelf_newehdr.3 new file mode 100644 index 00000000..a7b03ace --- /dev/null +++ b/static/openbsd/man3/gelf_newehdr.3 @@ -0,0 +1,196 @@ +.\" 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,v 1.5 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar 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 +.Ar elfclass +has value +.Dv ELFCLASS32 , +function +.Fn gelf_newehdr +returns the value returned by +.Fn elf32_newehdr "elf" . +When argument +.Ar 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 +.Ar 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 +.Ar elf . +.Sh RETURN VALUES +These functions return a pointer to a translated header descriptor +if successful, or 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 +.Ar elf +was null. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elfclass +had an unsupported value. +.It Bq Er ELF_E_ARGUMENT +The class of the ELF descriptor +.Ar elf +did not match that of the requested operation. +.It Bq Er ELF_E_ARGUMENT +For function +.Fn gelf_newehdr , +the class of argument +.Ar elf +was not +.Dv ELFCLASSNONE +and did not match the argument +.Ar elfclass . +.It Bq Er ELF_E_CLASS +The ELF class of descriptor +.Ar 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 +.Ar elf +did not adhere to the conventions used for extended numbering. +.It Bq Er ELF_E_VERSION +The ELF descriptor +.Ar 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/openbsd/man3/gelf_newphdr.3 b/static/openbsd/man3/gelf_newphdr.3 new file mode 100644 index 00000000..4bf95985 --- /dev/null +++ b/static/openbsd/man3/gelf_newphdr.3 @@ -0,0 +1,143 @@ +.\" 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,v 1.4 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar count +.Vt Elf32_Phdr +and +.Vt Elf64_Phdr +descriptors respectively, +discarding any existing program header table +already present in the ELF descriptor +.Ar elf . +A value of zero for argument +.Ar 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 +.Ar count +elements depending on the ELF class of ELF descriptor +.Ar 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 +.Ar elf +will no longer be valid. +.Sh RETURN VALUES +The functions a valid pointer if successful, or 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 +.Ar elf +was NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_CLASS +ELF descriptor +.Ar 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 +.Ar 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/openbsd/man3/gelf_update_ehdr.3 b/static/openbsd/man3/gelf_update_ehdr.3 new file mode 100644 index 00000000..a03016cd --- /dev/null +++ b/static/openbsd/man3/gelf_update_ehdr.3 @@ -0,0 +1,122 @@ +.\" 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,v 1.2 2025/06/10 17:19:45 schwarze Exp $ +.\" +.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 SYNOPSIS +.Lb libelf +.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 +.Ar ehdr . +.Pp +Function +.Fn gelf_update_phdr +updates the ELF Program Header structure at index +.Ar ndx +with the values in the class-independent program header +.Ar phdr . +.Pp +Function +.Fn gelf_update_shdr +updates the ELF Section Header structure associated with section +descriptor +.Ar scn +with the values in argument +.Ar 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 +.Ar elf , +.Ar ehdr , +.Ar phdr , +.Ar scn , +or +.Ar shdr +were NULL. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +had an unsupported ELF class. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar ndx +exceeded the number of entries in the program header table. +.It Bq Er ELF_E_ARGUMENT +Section descriptor +.Ar scn +was not associated with an ELF descriptor. +.It Bq Er ELF_E_MODE +ELF descriptor +.Ar 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/openbsd/man3/gelf_xlatetof.3 b/static/openbsd/man3/gelf_xlatetof.3 new file mode 100644 index 00000000..b8bf05d3 --- /dev/null +++ b/static/openbsd/man3/gelf_xlatetof.3 @@ -0,0 +1,279 @@ +.\" 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,v 1.3 2025/06/12 01:16:50 schwarze Exp $ +.\" +.Dd October 11, 2018 +.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 SYNOPSIS +.Lb libelf +.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 +.Ar 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 +.Ar 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 +.Ar 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 +.Ar 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 +.Ar elf . +.Sh RETURN VALUES +These functions return argument +.Ar dst +if successful, or 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 +.Ar src , +.Ar dst +or +.Ar elf +was NULL. +.It Bq Er ELF_E_ARGUMENT +Arguments +.Ar src +and +.Ar 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 +.Ar d_type +field of argument +.Ar src +specified an unsupported type. +.It Bq Er ELF_E_DATA +The +.Ar src +argument specified a buffer size that was not an integral multiple of +its underlying type. +.It Bq Er ELF_E_DATA +The +.Ar dst +argument specified a buffer size that was too small. +.It Bq Er ELF_E_DATA +Argument +.Ar 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 +.Ar dst +and +.Ar src +were not identical. +.It Bq Er ELF_E_UNIMPL +The argument +.Ar src +requested conversion for a type which is not currently +supported. +.It Bq Er ELF_E_VERSION +Argument +.Ar src +specified an unsupported version number. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr gelf 3 diff --git a/static/openbsd/man3/get_fpc_csr.3 b/static/openbsd/man3/get_fpc_csr.3 new file mode 100644 index 00000000..a4ff3db3 --- /dev/null +++ b/static/openbsd/man3/get_fpc_csr.3 @@ -0,0 +1,63 @@ +.\" $OpenBSD: get_fpc_csr.3,v 1.8 2025/06/06 21:09:33 schwarze Exp $ +.\" +.\" Copyright (c) 2010 Miodrag Vallat. +.\" +.\" 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: June 6 2025 $ +.Dt GET_FPC_CSR 3 mips64 +.Os +.Sh NAME +.Nm get_fpc_csr , +.Nm set_fpc_csr +.Nd floating-point control register access +.Sh SYNOPSIS +.\" These functions live in libc. +.In machine/fpu.h +.Ft int +.Fn get_fpc_csr void +.Ft int +.Fn set_fpc_csr "int csr" +.Sh DESCRIPTION +The +.Fn get_fpc_csr +function returns the current value of the floating-point control register. +The +.Fn set_fpc_csr +function replaces the value of the floating-point control register with +.Fa csr +and returns the previous value. +.Pp +These functions are provided for IRIX compatibility, +and should only be used to control the value of the +.Li FPCSR_FS +bit in the floating-point control register. +Portable code should use the +.Xr fpgetmask 3 , +.Xr fpgetround 3 , +.Xr fpgetsticky 3 , +.Xr fpsetmask 3 , +.Xr fpsetround 3 , +and +.Xr fpsetsticky 3 +functions to inquire or alter the floating-point control register. +.Sh RETURN VALUES +The +.Fn get_fpc_csr +and +.Fn set_fpc_csr +functions return the +.Pq previous +value of the floating-point control register. +.Sh SEE ALSO +.Xr fpgetmask 3 diff --git a/static/openbsd/man3/getaddrinfo.3 b/static/openbsd/man3/getaddrinfo.3 new file mode 100644 index 00000000..2df5fbe8 --- /dev/null +++ b/static/openbsd/man3/getaddrinfo.3 @@ -0,0 +1,481 @@ +.\" $OpenBSD: getaddrinfo.3,v 1.62 2025/12/08 13:30:08 jca Exp $ +.\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun 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 $Mdocdate: December 8 2025 $ +.Dt GETADDRINFO 3 +.Os +.Sh NAME +.Nm getaddrinfo , +.Nm freeaddrinfo +.Nd host and service name to socket address structure +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netdb.h +.Ft int +.Fn getaddrinfo "const char *hostname" "const char *servname" \ + "const struct addrinfo *hints" "struct addrinfo **res" +.Ft void +.Fn freeaddrinfo "struct addrinfo *ai" +.Sh DESCRIPTION +The +.Fn getaddrinfo +function is used to get a list of +.Tn IP +addresses and port numbers for host +.Fa hostname +and service +.Fa servname . +It is a replacement for and provides more flexibility than the +.Xr gethostbyname 3 +and +.Xr getservbyname 3 +functions. +.Pp +The +.Fa hostname +and +.Fa servname +arguments are either pointers to NUL-terminated strings or the null pointer. +An acceptable value for +.Fa hostname +is either a valid host name or a numeric host address string consisting +of a dotted decimal IPv4 address or an IPv6 address. +The +.Fa servname +is either a decimal port number or a service name listed in +.Xr services 5 . +At least one of +.Fa hostname +and +.Fa servname +must be non-null. +.Pp +.Fa hints +is an optional pointer to a +.Vt struct addrinfo , +as defined by +.In netdb.h : +.Bd -literal +struct addrinfo { + int ai_flags; /* input flags */ + int ai_family; /* address family for socket */ + int ai_socktype; /* socket type */ + int ai_protocol; /* protocol for socket */ + socklen_t ai_addrlen; /* length of socket-address */ + struct sockaddr *ai_addr; /* socket-address for socket */ + char *ai_canonname; /* canonical name for service location */ + struct addrinfo *ai_next; /* pointer to next in list */ +}; +.Ed +.Pp +This structure can be used to provide hints concerning the type of socket +that the caller supports or wishes to use. +The caller can supply the following structure elements in +.Fa hints : +.Bl -tag -width "ai_socktypeXX" +.It Fa ai_family +The address family that should be used. +When +.Fa ai_family +is set to +.Dv AF_UNSPEC , +it means the caller will accept any address family supported by the +operating system. +.It Fa ai_socktype +Denotes the type of socket that is wanted: +.Dv SOCK_STREAM , +.Dv SOCK_DGRAM , +or +.Dv SOCK_RAW . +When +.Fa ai_socktype +is zero, the caller will accept any socket type. +.It Fa ai_protocol +Indicates which transport protocol is desired, +.Dv IPPROTO_UDP +or +.Dv IPPROTO_TCP . +If +.Fa ai_protocol +is zero, the caller will accept any protocol. +.It Fa ai_flags +.Fa ai_flags +is formed by +.Tn OR Ns 'ing +the following values: +.Bl -tag -width "AI_CANONNAMEXX" +.It Dv AI_ADDRCONFIG +If the +.Dv AI_ADDRCONFIG +bit is set, IPv4 addresses will be returned only if an IPv4 address is +configured on an interface, and IPv6 addresses will be returned only if an IPv6 +address is configured on an interface. +Addresses on a loopback interface and link-local IPv6 addresses are not +considered valid as configured addresses. +This bit is only considered when determining whether a DNS query should +be performed or not. +.It Dv AI_CANONNAME +If the +.Dv AI_CANONNAME +bit is set, a successful call to +.Fn getaddrinfo +will return a NUL-terminated string containing the canonical name +of the specified host name in the +.Fa ai_canonname +element of the first +.Vt addrinfo +structure returned. +.It Dv AI_FQDN +If the +.Dv AI_FQDN +bit is set, a successful call to +.Fn getaddrinfo +will return a NUL-terminated string containing the fully qualified domain name +of the specified host name in the +.Fa ai_canonname +element of the first +.Vt addrinfo +structure returned. +.Pp +This is different from the +.Dv AI_CANONNAME +bit flag that returns the canonical name registered in DNS, +which may be different from the fully qualified domain name +that the host name resolved to. +Only one of the +.Dv AI_FQDN +and +.Dv AI_CANONNAME +bits can be set. +.It Dv AI_NUMERICHOST +If the +.Dv AI_NUMERICHOST +bit is set, it indicates that +.Fa hostname +should be treated as a numeric string defining an IPv4 or IPv6 address +and no name resolution should be attempted. +.It Dv AI_NUMERICSERV +If the +.Dv AI_NUMERICSERV +bit is set, it indicates that +.Fa servname +should be treated as a numeric port string +and no service name resolution should be attempted. +.It Dv AI_PASSIVE +If the +.Dv AI_PASSIVE +bit is set, it indicates that the returned socket address structure +is intended for use in a call to +.Xr bind 2 . +In this case, if the +.Fa hostname +argument is the 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, the returned socket address structure will be ready +for use in a call to +.Xr connect 2 +for a connection-oriented protocol or +.Xr connect 2 , +.Xr sendto 2 , +or +.Xr sendmsg 2 +if a connectionless protocol was chosen. +The +.Tn IP +address portion of the socket address structure will be set to the +loopback address if +.Fa hostname +is the null pointer and +.Dv AI_PASSIVE +is not set. +.El +.El +.Pp +All other elements of the +.Vt addrinfo +structure passed via +.Fa hints +must be zero or the null pointer. +.Pp +If +.Fa hints +is the null pointer, +.Fn getaddrinfo +behaves as if the caller provided a +.Vt struct addrinfo +with +.Fa ai_family +set to +.Dv AF_UNSPEC , +.Fa ai_flags +set to +.Dv AI_ADDRCONFIG , +and all other elements set to zero or +.Dv NULL . +.Pp +After a successful call to +.Fn getaddrinfo , +.Fa *res +is a pointer to a linked list of one or more +.Vt addrinfo +structures. +The list can be traversed by following the +.Fa ai_next +pointer in each +.Vt addrinfo +structure until a null pointer is encountered. +The three members +.Fa ai_family , +.Fa ai_socktype , +and +.Fa ai_protocol +in each returned +.Vt addrinfo +structure are suitable for a call to +.Xr socket 2 . +For each +.Vt addrinfo +structure in the list, the +.Fa ai_addr +member points to a filled-in socket address structure of length +.Fa ai_addrlen . +.Pp +This implementation of +.Fn getaddrinfo +allows numeric IPv6 address notation with scope identifier, +as documented in RFC 4007. +By appending the percent character and scope identifier to addresses, +one can fill the +.Li sin6_scope_id +field for addresses. +This would make management of scoped addresses easier +and allows cut-and-paste input of scoped addresses. +.Pp +At this moment the code supports only link-local addresses with the format. +The scope identifier is hardcoded to the name of the hardware interface +associated +with the link +.Po +such as +.Li ne0 +.Pc . +An example is +.Dq Li fe80::1%ne0 , +which means +.Do +.Li fe80::1 +on the link associated with the +.Li ne0 +interface +.Dc . +.Pp +The current implementation assumes a one-to-one relationship between +the interface and link, which is not necessarily true from the specification. +.Pp +All of the information returned by +.Fn getaddrinfo +is dynamically allocated: the +.Vt addrinfo +structures themselves as well as the socket address structures and +the canonical host name strings included in the +.Vt addrinfo +structures. +.Pp +Memory allocated for the dynamically allocated structures created by +a successful call to +.Fn getaddrinfo +is released by the +.Fn freeaddrinfo +function. +The +.Fa ai +pointer should be an +.Vt addrinfo +structure created by a call to +.Fn getaddrinfo . +.Sh RETURN VALUES +.Fn getaddrinfo +returns zero on success or one of the error codes listed in +.Xr gai_strerror 3 +if an error occurs. +If an error occurs, no memory is allocated by +.Fn getaddrinfo , +therefore it is not necessary to release the +.Vt addrinfo +structure(s). +.Sh EXAMPLES +The following code tries to connect to +.Dq Li www.kame.net +service +.Dq Li www +via a stream socket. +It loops through all the addresses available, regardless of address family. +If the destination resolves to an IPv4 address, it will use an +.Dv AF_INET +socket. +Similarly, if it resolves to IPv6, an +.Dv AF_INET6 +socket is used. +Observe that there is no hardcoded reference to a particular address family. +The code works even if +.Fn getaddrinfo +returns addresses that are not IPv4/v6. +.Bd -literal -offset indent +struct addrinfo hints, *res, *res0; +int error; +int save_errno; +int s; +const char *cause = NULL; + +memset(&hints, 0, sizeof(hints)); +hints.ai_family = AF_UNSPEC; +hints.ai_socktype = SOCK_STREAM; +error = getaddrinfo("www.kame.net", "www", &hints, &res0); +if (error) + errx(1, "%s", gai_strerror(error)); +s = -1; +for (res = res0; res; res = res->ai_next) { + s = socket(res->ai_family, res->ai_socktype, + res->ai_protocol); + if (s == -1) { + cause = "socket"; + continue; + } + + if (connect(s, res->ai_addr, res->ai_addrlen) == -1) { + cause = "connect"; + save_errno = errno; + close(s); + errno = save_errno; + s = -1; + continue; + } + + break; /* okay we got one */ +} +if (s == -1) + err(1, "%s", cause); +freeaddrinfo(res0); +.Ed +.Pp +The following example tries to open a wildcard listening socket onto service +.Dq Li www , +for all the address families available. +.Bd -literal -offset indent +struct addrinfo hints, *res, *res0; +int error; +int save_errno; +int s[MAXSOCK]; +int nsock; +const char *cause = NULL; + +memset(&hints, 0, sizeof(hints)); +hints.ai_family = AF_UNSPEC; +hints.ai_socktype = SOCK_STREAM; +hints.ai_flags = AI_PASSIVE; +error = getaddrinfo(NULL, "www", &hints, &res0); +if (error) + errx(1, "%s", gai_strerror(error)); +nsock = 0; +for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { + s[nsock] = socket(res->ai_family, res->ai_socktype, + res->ai_protocol); + if (s[nsock] == -1) { + cause = "socket"; + continue; + } + + if (bind(s[nsock], res->ai_addr, res->ai_addrlen) == -1) { + cause = "bind"; + save_errno = errno; + close(s[nsock]); + errno = save_errno; + continue; + } + (void) listen(s[nsock], 5); + + nsock++; +} +if (nsock == 0) + err(1, "%s", cause); +freeaddrinfo(res0); +.Ed +.Sh SEE ALSO +.Xr bind 2 , +.Xr connect 2 , +.Xr send 2 , +.Xr socket 2 , +.Xr gai_strerror 3 , +.Xr gethostbyname 3 , +.Xr getnameinfo 3 , +.Xr getservbyname 3 , +.Xr res_init 3 , +.Xr hosts 5 , +.Xr resolv.conf 5 , +.Xr services 5 , +.Xr hostname 7 +.Rs +.%A Craig Metz +.%B Proceedings of the Freenix Track: 2000 USENIX Annual Technical Conference +.%D June 2000 +.%T Protocol Independence Using the Sockets API +.Re +.Sh STANDARDS +The +.Fn getaddrinfo +function is defined by the +.St -p1003.1g-2000 +draft specification and documented in RFC 3493. +.Pp +The +.Dv AI_FQDN +flag bit first appeared in Windows 7. +.Pp +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A J. McCann +.%A W. Stevens +.%D February 2003 +.%R RFC 3493 +.%T Basic Socket Interface Extensions for IPv6 +.Re +.Pp +.Rs +.%A S. Deering +.%A B. Haberman +.%A T. Jinmei +.%A E. Nordmark +.%A B. Zill +.%D March 2005 +.%R RFC 4007 +.%T IPv6 Scoped Address Architecture +.Re +.Sh CAVEATS +The behavior of +.Fn freeaddrinfo "NULL" +is not specified and therefore not portable. diff --git a/static/openbsd/man3/getbsize.3 b/static/openbsd/man3/getbsize.3 new file mode 100644 index 00000000..a740ae4a --- /dev/null +++ b/static/openbsd/man3/getbsize.3 @@ -0,0 +1,76 @@ +.\" $OpenBSD: getbsize.3,v 1.10 2013/06/05 03:39:22 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt GETBSIZE 3 +.Os +.Sh NAME +.Nm getbsize +.Nd get user block size +.Sh SYNOPSIS +.In stdlib.h +.Ft char * +.Fn getbsize "int *headerlenp" "long *blocksizep" +.Sh DESCRIPTION +The +.Fn 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 +.Fn getbsize +function returns a pointer to a NUL-terminated +string describing +the block size, something like +.Qq 1K-blocks . +The memory referenced by +.Fa headerlenp +is filled in with the length of the string (not including the +terminating NUL byte). +The memory referenced by +.Fa blocksizep +is filled in with the 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/openbsd/man3/getc.3 b/static/openbsd/man3/getc.3 new file mode 100644 index 00000000..be721def --- /dev/null +++ b/static/openbsd/man3/getc.3 @@ -0,0 +1,171 @@ +.\" $OpenBSD: getc.3,v 1.18 2025/07/25 18:27:57 tedu 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. +.\" +.Dd $Mdocdate: July 25 2025 $ +.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 SYNOPSIS +.In stdio.h +.Ft int +.Fn fgetc "FILE *stream" +.Ft int +.Fn getc "FILE *stream" +.Ft int +.Fn getchar "void" +.Ft int +.Fn getc_unlocked "FILE *stream" +.Ft int +.Fn getchar_unlocked "void" +.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 +.Fn getc +with the argument +.Em stdin . +.Pp +The +.Fn getc_unlocked +and +.Fn getchar_unlocked +functions perform the same action, but do not obtain the stream lock. +They require that the stream first be locked with +.Xr flockfile 3 +for thread safe operation. +.Pp +The +.Fn getw +function obtains the next +.Vt 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 getwc 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-2024 . +.Sh HISTORY +The +.Fn getc +and +.Fn getw +functions first appeared in +.At v1 ; +.Fn getchar +in +.At v2 ; +and +.Fn fgetc +in +.At v7 . +The +.Fn getc_unlocked +and +.Fn getchar_unlocked +functions have been available since +.Ox 2.5 . +.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 . +.Pp +Since the size and byte order of an +.Vt int +may vary from one machine to another, +.Fn getw +is not recommended for portable applications. diff --git a/static/openbsd/man3/getcwd.3 b/static/openbsd/man3/getcwd.3 new file mode 100644 index 00000000..3ad154d6 --- /dev/null +++ b/static/openbsd/man3/getcwd.3 @@ -0,0 +1,190 @@ +.\" $OpenBSD: getcwd.3,v 1.23 2022/07/25 02:25:55 jsg 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. +.\" +.Dd $Mdocdate: July 25 2022 $ +.Dt GETCWD 3 +.Os +.Sh NAME +.Nm getcwd , +.Nm getwd +.Nd get working directory pathname +.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 not +.Dv NULL +and the length of the pathname plus the terminating NUL +character is greater than +.Fa size , +a null pointer is returned and +.Va errno +is set to +.Dv ERANGE . +.Pp +As an extension to +.St -p1003.1-2001 , +if +.Fa buf +is +.Dv NULL , +space is allocated as necessary to store the pathname. +In this case, it is the responsibility of the caller to +.Xr free 3 +the pointer that +.Fn getcwd +returns. +.Pp +The deprecated +.Fn getwd +function is similar to +.Fn getcwd , +but assumes that +.Fa buf +is non-NULL and has a size of +.Dv PATH_MAX +(as defined by the include +file +.In limits.h ) . +It does not allocate memory and is provided for source compatibility only. +If the length of the pathname plus the terminating NUL +character is greater than +.Dv PATH_MAX , +a null pointer is returned. +On error, +.Fn getwd +writes an error message into the memory referenced by +.Fa buf . +.Pp +These functions 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 Pa \&. +and use the +.Xr fchdir 2 +function to return. +.Sh RETURN VALUES +Upon successful completion, a pointer to the pathname is returned. +Otherwise a null pointer is returned and +.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 EFAULT +.Fa buf +points to an invalid address. +.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 pwd 1 , +.Xr chdir 2 , +.Xr malloc 3 , +.Xr strerror 3 +.Sh STANDARDS +The +.Fn getcwd +function conforms to +.St -p1003.1-2001 . +The ability to specify a null pointer and have +.Fn getcwd +allocate memory as necessary is an extension. +.Sh HISTORY +The +.Fn getwd +function first appeared in +.Bx 4.0 . +The +.Fn getcwd +function first appeared in +.At V.1 +and was reimplemented for +.Bx 4.3 Net/2 . +.Pp +In +.Ox 4.0 , +.Fn getcwd +was reimplemented on top of the +.Fn __getcwd +system call. +Its calling convention differs from the standard +function by requiring +.Ar buf +to not be +.Dv NULL +and by returning an integer, +zero on success, and -1 with corresponding errno on failure. +This is visible in the output of +.Xr kdump 1 . +.Sh BUGS +The +.Fn getwd +function does not do sufficient error checking and is not able to return very +long, but valid, paths. +It is provided for compatibility only. diff --git a/static/openbsd/man3/getdelim.3 b/static/openbsd/man3/getdelim.3 new file mode 100644 index 00000000..80b202e2 --- /dev/null +++ b/static/openbsd/man3/getdelim.3 @@ -0,0 +1,171 @@ +.\" $OpenBSD: getdelim.3,v 1.7 2022/12/20 17:59:29 schwarze Exp $ +.\" $NetBSD: getdelim.3,v 1.9 2011/04/20 23:37:51 enami 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 $Mdocdate: December 20 2022 $ +.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 , +storing the input in +.Fa *lineptr . +The buffer is +.Dv NUL Ns No -terminated +and includes the delimiter. +The +.Fa delimiter +character must be representable as an +.Vt 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 +will +.Xr realloc 3 +.Fa *lineptr +as necessary, updating +.Fa *n +to reflect the new size. +It is the responsibility of the caller to +.Xr free 3 +.Fa *lineptr +when it is no longer needed. +Even when it fails, +.Fn getdelim +may update +.Fa *lineptr . +.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 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(\*[Am]line, \*[Am]linesize, fp)) != -1) + fwrite(line, linelen, 1, stdout); + +free(line); +if (ferror(fp)) + err(1, "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 fgets 3 , +.Xr fopen 3 +.Sh STANDARDS +The +.Fn getdelim +and +.Fn getline +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +These functions were ported from +.Nx +to +.Ox 5.2 . diff --git a/static/openbsd/man3/getdiskbyname.3 b/static/openbsd/man3/getdiskbyname.3 new file mode 100644 index 00000000..c4b016a5 --- /dev/null +++ b/static/openbsd/man3/getdiskbyname.3 @@ -0,0 +1,59 @@ +.\" $OpenBSD: getdiskbyname.3,v 1.11 2013/06/05 03:39:22 tedu 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 $Mdocdate: June 5 2013 $ +.Dt GETDISKBYNAME 3 +.Os +.Sh NAME +.Nm getdiskbyname +.Nd get generic disk description by its name +.Sh SYNOPSIS +.In sys/types.h +.In sys/disklabel.h +.Ft struct disklabel * +.Fn getdiskbyname "const char *name" +.Sh DESCRIPTION +The +.Fn getdiskbyname +function takes a disk name (e.g., +.Qq 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. +.Sh SEE ALSO +.Xr disklabel 5 , +.Xr disktab 5 , +.Xr disklabel 8 +.Sh HISTORY +The +.Fn getdiskbyname +function appeared in +.Bx 4.3 . diff --git a/static/openbsd/man3/getdomainname.3 b/static/openbsd/man3/getdomainname.3 new file mode 100644 index 00000000..1eef9433 --- /dev/null +++ b/static/openbsd/man3/getdomainname.3 @@ -0,0 +1,104 @@ +.\" $OpenBSD: getdomainname.3,v 1.29 2022/07/26 14:53:29 deraadt 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 $Mdocdate: July 26 2022 $ +.Dt GETDOMAINNAME 3 +.Os +.Sh NAME +.Nm getdomainname , +.Nm setdomainname +.Nd get/set YP domain name of current host +.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 +The +.Fn getdomainname +function returns the YP domain name for the current processor, as +previously set by +.Fn setdomainname . +The parameter +.Fa namelen +specifies the size of the +.Fa name +array. +If insufficient space is provided, the returned name is truncated. +The returned name is always NUL terminated. +.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 superuser and +is normally used only when the system is bootstrapped. +Under normal operation once the domainname is set, it cannot be +changed. +.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 variable +.Va errno . +.Sh ERRORS +The following errors may be returned by these calls: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa name +parameter gave an +invalid address. +.It Bq Er EPERM +The caller tried to set the domain name and was not the superuser. +.El +.Sh SEE ALSO +.Xr domainname 1 , +.Xr sysctl 2 , +.Xr gethostid 3 , +.Xr gethostname 3 , +.Xr sysctl 8 , +.Xr yp 8 +.Sh HISTORY +The +.Nm +function call appeared in +SunOS 3.x. +.Sh BUGS +Domain names are limited to +.Dv MAXHOSTNAMELEN +(from +.In sys/param.h ) +characters, currently 256. +This includes the terminating NUL character. +.Pp +If the buffer passed to +.Fn getdomainname +is too small, other operating systems may not guarantee termination with NUL. diff --git a/static/openbsd/man3/getdtablesize.3 b/static/openbsd/man3/getdtablesize.3 new file mode 100644 index 00000000..297e1c6e --- /dev/null +++ b/static/openbsd/man3/getdtablesize.3 @@ -0,0 +1,62 @@ +.\" Copyright (c) 1983, 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. +.\" +.\" $OpenBSD: getdtablesize.3,v 1.14 2022/07/17 08:33:01 jsg Exp $ +.\" +.Dd $Mdocdate: July 17 2022 $ +.Dt GETDTABLESIZE 3 +.Os +.Sh NAME +.Nm getdtablesize +.Nd get descriptor table size +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getdtablesize void +.Sh DESCRIPTION +Each process has 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 +returns the size of this table. +.Sh SEE ALSO +.Xr close 2 , +.Xr dup 2 , +.Xr getdtablecount 2 , +.Xr getrlimit 2 , +.Xr open 2 , +.Xr select 2 , +.Xr setrlimit 2 , +.Xr sysctl 2 , +.Xr sysconf 3 +.Sh HISTORY +The +.Fn getdtablesize +function call appeared in +.Bx 4.2 . diff --git a/static/openbsd/man3/getenv.3 b/static/openbsd/man3/getenv.3 new file mode 100644 index 00000000..5a219a5c --- /dev/null +++ b/static/openbsd/man3/getenv.3 @@ -0,0 +1,191 @@ +.\" 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. +.\" +.\" $OpenBSD: getenv.3,v 1.23 2022/08/08 22:40:03 millert Exp $ +.\" +.Dd $Mdocdate: August 8 2022 $ +.Dt GETENV 3 +.Os +.Sh NAME +.Nm getenv , +.Nm putenv , +.Nm setenv , +.Nm unsetenv +.Nd environment variable functions +.Sh SYNOPSIS +.In stdlib.h +.Ft char * +.Fn getenv "const char *name" +.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 . +.Pp +The +.Fn getenv +function obtains the current value of the environment variable +.Fa name . +If the variable +.Fa name +is not in the current environment, a null pointer is returned. +.Pp +The +.Fn setenv +function inserts or resets the environment variable +.Fa name +in the current environment list. +If the variable +.Fa name +does not exist in the list, it is inserted with the given +.Fa value . +If the variable does exist, the argument +.Fa overwrite +is tested; if +.Fa overwrite +is zero, the variable is not reset, otherwise it is reset to the given +.Fa value . +.Pp +The +.Fn putenv +function takes an argument of the form +.Ar name Ns = Ns Ar value . +The memory pointed to by +.Ar string +becomes part of the environment and must not be deallocated by the caller. +If the variable already exists, it will be overwritten. +A common source of bugs is to pass a +.Ar string +argument that is a locally scoped string buffer. +This will result in corruption of the environment after leaving +the scope in which the variable is defined. +For this reason, the +.Fn setenv +function is preferred over +.Fn putenv . +.Pp +The +.Fn unsetenv +function deletes all instances of the variable name pointed to by +.Fa name +from the list. +.Sh RETURN VALUES +.Rv -std putenv setenv unsetenv +.Pp +The +.Fn getenv +function returns a pointer to the requested value, or +.Dv NULL +if it could not be found. +If +.Fn getenv +is successful, the string returned should be considered read-only. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fn setenv +or +.Fn unsetenv +function was passed an empty +.Ar name +or a NULL pointer, or was passed a +.Ar name +containing an +.Sq = +character. +.Pp +The +.Fn putenv +function was passed a +.Ar string +that did not contain an +.Sq = +character, or was passed a +.Ar string +that started with the +.Sq = +character. +.It Bq Er ENOMEM +The +.Fn setenv +or +.Fn putenv +function failed because it was unable to allocate memory for the environment. +.El +.Sh SEE ALSO +.Xr csh 1 , +.Xr sh 1 , +.Xr execve 2 , +.Xr issetugid 2 , +.Xr environ 7 +.Sh STANDARDS +The +.Fn getenv +function conforms to +.St -ansiC . +The +.Fn putenv , +.Fn setenv , +and +.Fn unsetenv +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The function +.Fn getenv +appeared in +.At v7 +and +.Bx 3 . +The functions +.Fn setenv +and +.Fn unsetenv +appeared in +.Bx 4.3 Tahoe . +The +.Fn putenv +function first appeared in +.At V.2 +and was reimplemented for +.Bx 4.3 Reno . +.Sh CAVEATS +Library code must be careful about using +.Fn getenv +to read untrusted environment variables in setuid programs. +The +.Fn issetugid +function is provided for this purpose. diff --git a/static/openbsd/man3/getfsent.3 b/static/openbsd/man3/getfsent.3 new file mode 100644 index 00000000..e40f24fb --- /dev/null +++ b/static/openbsd/man3/getfsent.3 @@ -0,0 +1,136 @@ +.\" $OpenBSD: getfsent.3,v 1.13 2014/01/21 03:15:45 schwarze 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 $Mdocdate: January 21 2014 $ +.Dt GETFSENT 3 +.Os +.Sh NAME +.Nm getfsent , +.Nm getfsspec , +.Nm getfsfile , +.Nm setfsent , +.Nm endfsent +.Nd get file system descriptor file entry +.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 fsck */ +}; +.Ed +.Pp +The fields have meanings described in +.Xr fstab 5 . +.Pp +.Fn setfsent +opens the file (closing any previously opened file) or rewinds it +if it is already open. +.Pp +.Fn endfsent +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. +Lines which are formatted incorrectly are silently ignored. +.Sh RETURN VALUES +The +.Fn getfsent , +.Fn getfsspec , +and +.Fn getfsfile +functions return a null pointer on +.Dv EOF +or error. +The +.Fn setfsent +function returns 0 on failure or 1 on success. +The +.Fn endfsent +function returns nothing. +.Sh FILES +.Bl -tag -width /etc/fstab -compact +.It Pa /etc/fstab +file system table +.El +.Sh SEE ALSO +.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/openbsd/man3/getgrent.3 b/static/openbsd/man3/getgrent.3 new file mode 100644 index 00000000..90ba6a7f --- /dev/null +++ b/static/openbsd/man3/getgrent.3 @@ -0,0 +1,303 @@ +.\" $OpenBSD: getgrent.3,v 1.26 2022/09/11 06:38:10 jmc 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt GETGRENT 3 +.Os +.Sh NAME +.Nm getgrent , +.Nm getgrnam , +.Nm getgrnam_r , +.Nm getgrgid , +.Nm getgrgid_r , +.Nm setgroupent , +.Nm setgrent , +.Nm endgrent +.Nd group database operations +.Sh SYNOPSIS +.In grp.h +.Ft struct group * +.Fn getgrent void +.Ft struct group * +.Fn getgrnam "const char *name" +.Ft int +.Fn getgrnam_r "const char *name" "struct group *grp" "char *buf" "size_t bufsize" "struct group **result" +.Ft struct group * +.Fn getgrgid "gid_t gid" +.Ft int +.Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buf" "size_t bufsize" "struct group **result" +.Ft int +.Fn setgroupent "int stayopen" +.Ft void +.Fn setgrent void +.Ft void +.Fn endgrent void +.Sh DESCRIPTION +These functions operate on the group database file +.Pa /etc/group +which is described +in +.Xr group 5 . +Each line of the database is defined by the structure +.Vt struct 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 +.Fa name +or the group ID pointed to by +.Fa gid , +respectively, returning the first one encountered. +Identical group names or group GIDs may result in undefined behavior. +.Pp +.Fn getgrent +sequentially reads the group database and is intended for programs +that wish to step through the complete list of groups. +.Pp +All three routines will open the group file for reading, if necessary. +.Pp +.Fn setgroupent +opens the file, or rewinds it if it is already open. +If +.Fa stayopen +is non-zero, file descriptors are left open, significantly speeding +subsequent function 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 +.Fn setgrent +is equivalent to +.Fn setgroupent +with an argument of zero. +.Pp +The +.Fn endgrent +function closes any open files. +.Pp +The +.Fn getgrgid_r +and +.Fn getgrnam_r +functions both update the group structure pointed to by +.Fa grp +and store a pointer to that structure at the location pointed to by +.Fa result . +The structure is filled with an entry from the group database with a +matching +.Fa gid +or +.Fa name . +Storage referenced by the group structure will be allocated from the memory +provided with the +.Fa buf +parameter, which is +.Fa bufsiz +characters in size. +The maximum size needed for this buffer can be determined with +.Fn sysconf _SC_GETGR_R_SIZE_MAX . +.Ss YP support +If YP is active, the functions +.Fn getgrent +and +.Fn getgrnam +also use the +.Pa group.byname +YP map and the function +.Fn getgrgid +also uses the +.Pa group.bygid +YP map in addition to the group file, +respecting the order of normal and YP entries in the group file. +.Sh RETURN VALUES +The functions +.Fn getgrent , +.Fn getgrnam , +and +.Fn getgrgid +return a pointer to the group entry if successful; if end-of-file +is reached or an error occurs a +.Dv NULL +pointer is returned. +.Pp +The +.Fn setgroupent +function returns the value 1 if successful, otherwise 0. +.Pp +The +.Fn endgrent +and +.Fn setgrent +functions have no return value. +.Pp +The functions +.Fn getgrgid_r +and +.Fn getgrnam_r +update +.Ar result +to point to +.Ar grp +if a match is found or set it to +.Dv NULL +if no match is found or an error occurs. +They return 0 on success, even if no match is found, +or an error number if an error occurs; see +.Sx ERRORS . +.Sh FILES +.Bl -tag -width /etc/group -compact +.It Pa /etc/group +group database file +.El +.Sh ERRORS +The +.Fn getgrgid_r +and +.Fn getgrnam_r +functions may fail if: +.Bl -tag -width Er +.It Bq Er ERANGE +The storage supplied via +.Fa buf +and +.Fa bufsize +is too small and cannot contain all the strings to be returned in +.Fa grp . +.El +.Pp +The +.Fn getgrent , +.Fn getgrgid , +.Fn getgrgid_r , +.Fn getgrnam , +and +.Fn getgrnam_r +functions may also fail for any of the errors specified for +.Xr fgets 3 , +.Xr getc 3 , +and +.Xr strtoul 3 . +If YP is active, they may also fail due to errors caused by the YP subsystem. +.Pp +The +.Fn setgroupent +function may fail for any of the errors specified for +.Xr fopen 3 . +.Pp +The +.Fn endgrent , +.Fn getgrgid_r , +.Fn getgrnam_r , +and +.Fn setgrent +functions do not set errno. +.Sh SEE ALSO +.Xr getpwent 3 , +.Xr sysconf 3 , +.Xr group 5 , +.Xr yp 8 +.Sh STANDARDS +The functions +.Fn getgrgid , +.Fn getgrgid_r , +.Fn getgrnam , +and +.Fn getgrnam_r +are compliant with the +.St -p1003.1-2008 +specification. +.Pp +The functions +.Fn endgrent , +.Fn getgrent , +and +.Fn setgrent +are compliant with the X/Open System Interfaces option of the +.St -p1003.1-2008 +specification. +.Pp +.Sx YP support +and the +.Fn setgroupent +function are extensions to that specification. +.Sh HISTORY +The functions +.Fn endgrent , +.Fn getgrent , +.Fn getgrnam , +.Fn getgrgid , +and +.Fn setgrent +appeared in +.At v7 . +The +.Fn setgroupent +function appeared in +.Bx 4.3 Reno . +.Pp +The historic function +.Fn setgrfile , +which allowed the specification of alternate group databases, has +been deprecated and is no longer available. +.Sh BUGS +The functions +.Fn getgrent , +.Fn getgrnam , +.Fn getgrgid , +.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. diff --git a/static/openbsd/man3/getgrouplist.3 b/static/openbsd/man3/getgrouplist.3 new file mode 100644 index 00000000..1a8a49c2 --- /dev/null +++ b/static/openbsd/man3/getgrouplist.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: getgrouplist.3,v 1.17 2013/06/05 03:39:22 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt GETGROUPLIST 3 +.Os +.Sh NAME +.Nm getgrouplist +.Nd calculate group access list +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getgrouplist "const char *name" "gid_t basegid" "gid_t *groups" "int *ngroups" +.Sh DESCRIPTION +The +.Fn getgrouplist +function reads through the +.Xr group 5 +file and calculates 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 file. +.Pp +If YP is active and the group file contains no exclusions, the +.Xr netid 5 +file and the +.Pa netid.byname +YP map will be used in addition to the group file. +If the group file contains at least one exclusion, the +.Pa group.byname +YP map will be used in addition to the group file. +.Pp +The resulting group list is returned in the integer array pointed to by +.Fa groups . +The caller specifies the size of the +.Fa groups +array in the integer pointed to by +.Fa ngroups ; +the actual number of groups found is returned in +.Fa ngroups . +.Sh RETURN VALUES +The +.Fn getgrouplist +function returns 0 if successful and \-1 if the size of the group list is +too small to hold all the user's groups. +Here, the group array will be filled with as many groups as will fit. +.Sh FILES +.Bl -tag -width /etc/group -compact +.It Pa /etc/group +group database file +.It Pa /etc/netid +static group lists to override YP data +.El +.Sh SEE ALSO +.Xr setgroups 2 , +.Xr initgroups 3 , +.Xr yp_match 3 , +.Xr group 5 , +.Xr netid 5 , +.Xr yp 8 +.Sh HISTORY +The +.Fn getgrouplist +function first appeared in +.Bx 4.4 . +.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/openbsd/man3/gethostbyname.3 b/static/openbsd/man3/gethostbyname.3 new file mode 100644 index 00000000..06170c3c --- /dev/null +++ b/static/openbsd/man3/gethostbyname.3 @@ -0,0 +1,271 @@ +.\" $OpenBSD: gethostbyname.3,v 1.34 2019/08/30 20:20:50 jmc 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 $Mdocdate: August 30 2019 $ +.Dt GETHOSTBYNAME 3 +.Os +.Sh NAME +.Nm gethostbyname , +.Nm gethostbyname2 , +.Nm gethostbyaddr , +.Nm gethostent , +.Nm sethostent , +.Nm endhostent , +.Nm hstrerror , +.Nm herror +.Nd get network host entry +.Sh SYNOPSIS +.In netdb.h +.Vt extern int h_errno ; +.Ft struct hostent * +.Fn gethostbyname "const char *name" +.Ft struct hostent * +.Fn gethostent void +.Ft void +.Fn sethostent "int stayopen" +.Ft void +.Fn endhostent void +.Ft void +.Fn herror "const char *string" +.Ft const char * +.Fn hstrerror "int err" +.In sys/socket.h +.In netdb.h +.Ft struct hostent * +.Fn gethostbyname2 "const char *name" "int af" +.Ft struct hostent * +.Fn gethostbyaddr "const void *addr" "socklen_t len" "int af" +.Sh DESCRIPTION +The +.Fn gethostbyname , +.Fn gethostbyname2 , +and +.Fn gethostbyaddr +functions each return a pointer to an object with the following structure +describing an Internet host referenced by +.Fa name +or +.Fa addr , +respectively. +This structure contains either information obtained from a name server, +broken-out fields from a line in +.Pa /etc/hosts , +or database entries supplied by the +.Xr yp 8 +system. +.Xr resolv.conf 5 +describes how the particular database is chosen. +.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 returned addresses */ +}; +#define h_addr h_addr_list[0] /* address, for backward compat */ +.Ed +.Pp +The members of this structure are: +.Bl -tag -width h_addr_list +.It Fa h_name +Official name of the host. +.It Fa h_aliases +A +.Dv NULL Ns -terminated +array of alternate names for the host. +.It Fa h_addrtype +The type of address being returned. +.It Fa h_length +The length, in bytes, of the address. +.It Fa h_addr_list +A +.Dv NULL Ns -terminated +array of network addresses for the host. +Host addresses are returned in network byte order. +.It Fa h_addr +The first address in +.Fa h_addr_list ; +this is for backward compatibility. +.El +.Pp +The function +.Fn gethostbyname +will search for the named host in the current domain and its parents +using the search lookup semantics detailed in +.Xr resolv.conf 5 +and +.Xr hostname 7 . +.Pp +.Fn gethostbyname2 +is similar to +.Fn gethostbyname +except that it supports an +.Fa af +of +.Dv AF_INET6 +in addition to +.Dv AF_INET . +.Pp +The +.Fn gethostbyaddr +function will search for the specified address of length +.Fa len +in the address family +.Fa af . +The only address family supported is +.Dv AF_INET . +.Pp +The +.Fn sethostent , +.Fn gethostent , +and +.Fn endhostent +functions are deprecated and no longer have any effect. +They could be used in the past for queries over a persistent TCP +connection or to iterate entries in the +.Xr hosts 5 +file. +.Pp +The +.Fn herror +function prints an error message describing the failure. +If its argument +.Fa string +is not +.Dv NULL , +it is prepended to the message string and separated from it by a colon +.Pq Ql \&: +and a space. +The error message is printed with a trailing newline. +The contents of the error message is the same as that returned by +.Fn hstrerror +with argument +.Va h_errno . +.Sh ENVIRONMENT +.Bl -tag -width RES_OPTIONS +.It Ev RES_OPTIONS +A list of options to override the resolver's internal defaults. +See +.Xr resolv.conf 5 +for more information. +.El +.Sh FILES +.Bl -tag -width /etc/resolv.conf -compact +.It Pa /etc/hosts +.It Pa /etc/resolv.conf +.El +.Sh DIAGNOSTICS +Error return status from +.Fn gethostbyname , +.Fn gethostbyname2 , +and +.Fn 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. +.Pp +The variable +.Va h_errno +can have the following values: +.Bl -tag -width HOST_NOT_FOUND +.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. +.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. +.It Dv NETDB_INTERNAL +An internal error occurred. +This may occur when an address family other than +.Dv AF_INET +or +.Dv AF_INET6 +is specified or when a resource is unable to be allocated. +It is always set by +.Fn gethostent . +.It Dv NETDB_SUCCESS +The function completed successfully. +.El +.Sh SEE ALSO +.Xr getaddrinfo 3 , +.Xr getnameinfo 3 , +.Xr res_init 3 , +.Xr hosts 5 , +.Xr resolv.conf 5 , +.Xr hostname 7 +.Sh HISTORY +The +.Fn endhostent , +.Fn gethostbyaddr , +.Fn gethostbyname , +.Fn gethostent , +and +.Fn sethostent +functions appeared in +.Bx 4.1c . +The function +.Fn herror +was added in +.Bx 4.3 Tahoe , +.Fn hstrerror +in +.Bx 4.4 , +and +.Fn gethostbyname2 +in +.Ox 2.1 . +.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. +.Pp +Only the Internet +address formats are currently understood. +.Pp +YP does not support any address families other than +.Dv AF_INET +and uses +the traditional database format. diff --git a/static/openbsd/man3/gethostid.3 b/static/openbsd/man3/gethostid.3 new file mode 100644 index 00000000..5eb0b6b0 --- /dev/null +++ b/static/openbsd/man3/gethostid.3 @@ -0,0 +1,73 @@ +.\" 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. +.\" +.\" $OpenBSD: gethostid.3,v 1.16 2019/03/03 18:15:24 schwarze Exp $ +.\" +.Dd $Mdocdate: March 3 2019 $ +.Dt GETHOSTID 3 +.Os +.Sh NAME +.Nm gethostid , +.Nm sethostid +.Nd get/set unique identifier of current host +.Sh SYNOPSIS +.In unistd.h +.Ft long +.Fn gethostid void +.Ft int +.Fn sethostid "long hostid" +.Sh DESCRIPTION +The +.Fn sethostid +function establishes a 32-bit identifier for the +current processor that is intended to be unique among all +UNIX systems in existence. +This is normally an Internet address for the local machine. +This call is allowed only to the +superuser 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 2 . +.Sh SEE ALSO +.Xr sysctl 2 , +.Xr gethostname 3 , +.Xr sysctl 8 +.Sh HISTORY +The +.Fn gethostid +and +.Fn sethostid +system calls first appeared in +.Bx 4.1c +and were dropped in +.Bx 4.4 . +.Sh BUGS +32 bits for the identifier is too small. diff --git a/static/openbsd/man3/gethostname.3 b/static/openbsd/man3/gethostname.3 new file mode 100644 index 00000000..cc9376d7 --- /dev/null +++ b/static/openbsd/man3/gethostname.3 @@ -0,0 +1,120 @@ +.\" $OpenBSD: gethostname.3,v 1.30 2022/07/17 08:33:01 jsg 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 $Mdocdate: July 17 2022 $ +.Dt GETHOSTNAME 3 +.Os +.Sh NAME +.Nm gethostname , +.Nm sethostname +.Nd get/set name of current host +.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 +The +.Fn gethostname +function 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. +If insufficient space is provided, the returned name is truncated. +The returned name is always NUL terminated. +If no space is provided, an error is returned. +.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 superuser 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 variable +.Va errno . +.Sh ERRORS +The following errors may be returned by these calls: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa name +parameter gave an invalid address. +.It Bq Er ENOMEM +The +.Ar namelen +parameter was zero. +.It Bq Er EPERM +The caller tried to set the hostname and was not the superuser. +.El +.Sh SEE ALSO +.Xr hostname 1 , +.Xr sysctl 2 , +.Xr getdomainname 3 , +.Xr gethostid 3 , +.Xr sysctl 8 , +.Xr yp 8 +.Sh STANDARDS +The +.Fn gethostname +function call conforms to +.St -xpg4.2 . +.Sh HISTORY +The +.Fn gethostname +function call appeared in +.Bx 4.2 . +.Sh BUGS +Host names are limited to +.Dv MAXHOSTNAMELEN +(from +.In sys/param.h ) +characters, currently 256. +This includes the terminating NUL character. +Note that the corresponding POSIX definition +.Dv HOST_NAME_MAX +in +.In limits.h +does +.Em not +include the terminating NUL character. +.Pp +If the buffer passed to +.Fn gethostname +is smaller than +.Dv MAXHOSTNAMELEN , +other operating systems may not guarantee termination with NUL. diff --git a/static/openbsd/man3/getifaddrs.3 b/static/openbsd/man3/getifaddrs.3 new file mode 100644 index 00000000..8ea08fa3 --- /dev/null +++ b/static/openbsd/man3/getifaddrs.3 @@ -0,0 +1,157 @@ +.\" $OpenBSD: getifaddrs.3,v 1.23 2022/03/29 18:15:52 naddy 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 $Mdocdate: March 29 2022 $ +.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 *ifap" +.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 +.Vt ifaddrs +structures, as defined in the include file +.In ifaddrs.h . +The +.Vt ifaddrs +structure contains at least the following entries: +.Bd -literal + struct ifaddrs *ifa_next; /* Pointer to next struct */ + char *ifa_name; /* Interface name */ + u_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 */ +.Ed +.Bl -tag -width ifa_broadaddr +.It Fa ifa_next +Contains a pointer to the next structure on the list. +This field is set to +.Dv NULL +in the last structure on the list. +.It Fa ifa_name +Contains the interface name. +.It Fa ifa_flags +Contains the interface flags, as set by +.Xr ifconfig 8 . +.It Fa ifa_addr +References either the address of the interface or the link level +address of the interface, if one exists, otherwise it is +.Dv NULL . +(The +.Fa sa_family +field of the +.Fa ifa_addr +field should be consulted to determine the format of the +.Fa ifa_addr +address.) +.It Fa ifa_netmask +References the netmask associated with +.Fa ifa_addr , +if one is set, otherwise it is +.Dv NULL . +.It Fa ifa_broadaddr +This field, which should only be referenced for non-P2P interfaces, +references the broadcast address associated with +.Fa ifa_addr , +if one exists, otherwise it is +.Dv NULL . +.It Fa ifa_dstaddr +This field, which should only be referenced for P2P interfaces, +references the destination address on a P2P interface, +if one exists, otherwise it is +.Dv NULL . +.It Fa ifa_data +References address family specific data. +For +.Dv AF_LINK +addresses it contains a pointer to the +.Vt struct if_data +(as defined in include file +.In net/if.h ) +which contains various interface attributes and statistics. +For all other address families, +.Fa ifa_data +is +.Dv NULL . +.El +.Pp +The data returned by +.Fn getifaddrs +is dynamically allocated and should be freed using +.Fn freeifaddrs +when no longer needed. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn getifaddrs +function 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 2 . +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr socket 2 , +.Xr sysctl 2 , +.Xr netintro 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Fn getifaddrs +function first appeared in BSDI +.Bsx . +The function has been available on +.Ox +since +.Ox 2.7 . +.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/openbsd/man3/getloadavg.3 b/static/openbsd/man3/getloadavg.3 new file mode 100644 index 00000000..8f2ed1c5 --- /dev/null +++ b/static/openbsd/man3/getloadavg.3 @@ -0,0 +1,68 @@ +.\" $OpenBSD: getloadavg.3,v 1.15 2022/07/17 08:33:01 jsg 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. +.\" +.Dd $Mdocdate: July 17 2022 $ +.Dt GETLOADAVG 3 +.Os +.Sh NAME +.Nm getloadavg +.Nd get system load averages +.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 +Upon successful completion, the number of samples retrieved is returned. +If an error occurs, \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +Please see +.Xr sysctl 2 +for a list of possible errors. +.Sh SEE ALSO +.Xr uptime 1 , +.Xr sysctl 2 , +.Xr kvm_getloadavg 3 +.Sh HISTORY +The +.Fn getloadavg +function appeared in +.Bx 4.3 Reno . diff --git a/static/openbsd/man3/getmaxpartitions.3 b/static/openbsd/man3/getmaxpartitions.3 new file mode 100644 index 00000000..7d068899 --- /dev/null +++ b/static/openbsd/man3/getmaxpartitions.3 @@ -0,0 +1,53 @@ +.\" $OpenBSD: getmaxpartitions.3,v 1.9 2025/06/06 22:01:40 schwarze Exp $ +.\" $NetBSD: getmaxpartitions.3,v 1.1 1996/05/16 07:03:30 thorpej 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 REGENTS OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 6 2025 $ +.Dt GETMAXPARTITIONS 3 +.Os +.Sh NAME +.Nm getmaxpartitions +.Nd get the maximum number of partitions allowed per disk +.Sh SYNOPSIS +.Lb libutil +.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. +.Sh SEE ALSO +.Xr sysctl 2 , +.Xr getrawpartition 3 +.Sh HISTORY +The +.Nm +function call appeared in +.Nx 1.2 . diff --git a/static/openbsd/man3/getmntinfo.3 b/static/openbsd/man3/getmntinfo.3 new file mode 100644 index 00000000..143f6935 --- /dev/null +++ b/static/openbsd/man3/getmntinfo.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: getmntinfo.3,v 1.15 2022/07/30 07:19:30 jsg 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. +.\" +.Dd $Mdocdate: July 30 2022 $ +.Dt GETMNTINFO 3 +.Os +.Sh NAME +.Nm getmntinfo +.Nd get information about mounted file systems +.Sh SYNOPSIS +.In sys/types.h +.In sys/mount.h +.Ft int +.Fn getmntinfo "struct statfs **mntbufp" "int flags" +.Sh DESCRIPTION +The +.Fn getmntinfo +function returns an array of +.Vt statfs +structures describing each currently mounted file system (see +.Xr statfs 2 ) . +.Pp +The +.Fn getmntinfo +function passes its +.Fa flags +parameter transparently to +.Xr getfsstat 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 getfsstat 2 +or +.Xr malloc 3 . +.Sh SEE ALSO +.Xr getfsstat 2 , +.Xr mount 2 , +.Xr statfs 2 , +.Xr mount 8 +.Sh HISTORY +The +.Fn getmntinfo +function first appeared in +.Bx 4.3 Reno . +.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/openbsd/man3/getnameinfo.3 b/static/openbsd/man3/getnameinfo.3 new file mode 100644 index 00000000..4e97b5d0 --- /dev/null +++ b/static/openbsd/man3/getnameinfo.3 @@ -0,0 +1,264 @@ +.\" $OpenBSD: getnameinfo.3,v 1.49 2022/09/11 06:38:10 jmc Exp $ +.\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun 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 $Mdocdate: September 11 2022 $ +.Dt GETNAMEINFO 3 +.Os +.Sh NAME +.Nm getnameinfo +.Nd socket address structure to hostname and service name +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netdb.h +.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 used to convert a +.Vt sockaddr +structure to a pair of host name and service strings. +It is a replacement for and provides more flexibility than the +.Xr gethostbyaddr 3 +and +.Xr getservbyport 3 +functions and is the converse of the +.Xr getaddrinfo 3 +function. +.Pp +The +.Vt sockaddr +structure +.Fa sa +should point to either a +.Vt sockaddr_in +or +.Vt sockaddr_in6 +structure (for IPv4 or IPv6 respectively) that is +.Fa salen +bytes long. +.Pp +The host and service names associated with +.Fa sa +are stored in +.Fa host +and +.Fa serv +which have length parameters +.Fa hostlen +and +.Fa servlen . +The maximum value for +.Fa hostlen +is +.Dv NI_MAXHOST +and +the maximum value for +.Fa servlen +is +.Dv NI_MAXSERV , +as defined by +.In netdb.h . +If a length parameter is zero, no string will be stored. +Otherwise, enough space must be provided to store the +host name or service string plus a byte for the NUL terminator. +.Pp +The +.Fa flags +argument is formed by +.Tn OR Ns 'ing +the following values: +.Bl -tag -width "NI_NUMERICHOSTXX" +.It Dv NI_NOFQDN +A fully qualified domain name is not required for local hosts. +The local part of the fully qualified domain name is returned instead. +.It Dv NI_NUMERICHOST +Return the address in numeric form, as if calling +.Xr inet_ntop 3 , +instead of a host name. +.It Dv NI_NAMEREQD +A name is required. +If the host name cannot be found in DNS and this flag is set, +a non-zero error code is returned. +If the host name is not found and the flag is not set, the +address is returned in numeric form. +.It NI_NUMERICSERV +The service name is returned as a digit string representing the port number. +.It NI_DGRAM +Specifies that the service being looked up is a datagram +service, and causes +.Xr getservbyport 3 +to be called with a second argument of +.Dq udp +instead of its default of +.Dq tcp . +This is required for the few ports (512\-514) that have different services +for +.Tn UDP +and +.Tn TCP . +.El +.Pp +This implementation allows numeric IPv6 address notation with scope identifier, +as documented in RFC 4007. +IPv6 link-local address will appear as a string like +.Dq Li fe80::1%ne0 . +Refer to +.Xr getaddrinfo 3 +for more information. +.Sh RETURN VALUES +.Fn getnameinfo +returns zero on success or one of the error codes listed in +.Xr gai_strerror 3 +if an error occurs. +.Sh EXAMPLES +The following code tries to get a numeric host name, and service name, +for a given socket address. +Observe that there is no hardcoded reference to a particular address family. +.Bd -literal -offset indent +struct sockaddr *sa; /* input */ +char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; + +if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, + sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) + errx(1, "could not get numeric hostname"); +printf("host=%s, serv=%s\en", hbuf, sbuf); +.Ed +.Pp +The following version checks if the socket address has a reverse address mapping: +.Bd -literal -offset indent +struct sockaddr *sa; /* input */ +char hbuf[NI_MAXHOST]; + +if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, + NI_NAMEREQD)) + errx(1, "could not resolve hostname"); +printf("host=%s\en", hbuf); +.Ed +.Sh SEE ALSO +.Xr gai_strerror 3 , +.Xr getaddrinfo 3 , +.Xr gethostbyaddr 3 , +.Xr getservbyport 3 , +.Xr inet_ntop 3 , +.Xr res_init 3 , +.Xr hosts 5 , +.Xr resolv.conf 5 , +.Xr services 5 , +.Xr hostname 7 +.Rs +.%A Craig Metz +.%T Protocol Independence Using the Sockets API +.%B Proceedings of the Freenix Track: 2000 USENIX Annual Technical Conference +.%D June 2000 +.Re +.Sh STANDARDS +The +.Fn getnameinfo +function is defined by the +.St -p1003.1g-2000 +draft specification and documented in RFC 3493. +.Pp +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A J. McCann +.%A W. Stevens +.%D February 2003 +.%R RFC 3493 +.%T Basic Socket Interface Extensions for IPv6 +.Re +.Pp +.Rs +.%A S. Deering +.%A B. Haberman +.%A T. Jinmei +.%A E. Nordmark +.%A B. Zill +.%D March 2005 +.%R RFC 4007 +.%T IPv6 Scoped Address Architecture +.Re +.Sh CAVEATS +.Fn getnameinfo +can return both numeric and FQDN forms of the address specified in +.Fa sa . +There is no return value that indicates whether the string returned in +.Fa host +is a result of binary to numeric-text translation (like +.Xr inet_ntop 3 ) , +or is the result of a DNS reverse lookup. +Because of this, malicious parties could set up a PTR record as follows: +.Bd -literal -offset indent +1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 +.Ed +.Pp +and trick the caller of +.Fn getnameinfo +into believing that +.Fa sa +is +.Li 10.1.1.1 +when it is actually +.Li 127.0.0.1 . +.Pp +To prevent such attacks, the use of +.Dv NI_NAMEREQD +is recommended when the result of +.Fn getnameinfo +is used +for access control purposes: +.Bd -literal -offset indent +struct sockaddr *sa; +char addr[NI_MAXHOST]; +struct addrinfo hints, *res; +int error; + +error = getnameinfo(sa, sa->sa_len, addr, sizeof(addr), + NULL, 0, NI_NAMEREQD); +if (error == 0) { + memset(&hints, 0, sizeof(hints)); + hints.ai_socktype = SOCK_DGRAM; /*dummy*/ + hints.ai_flags = AI_NUMERICHOST; + if (getaddrinfo(addr, "0", &hints, &res) == 0) { + /* malicious PTR record */ + freeaddrinfo(res); + printf("bogus PTR record\en"); + return -1; + } + /* addr is FQDN as a result of PTR lookup */ +} else { + /* addr is numeric string */ + error = getnameinfo(sa, sa->sa_len, addr, sizeof(addr), + NULL, 0, NI_NUMERICHOST); +} +.Ed +.Sh BUGS +The implementation of +.Fn getnameinfo +is not thread-safe. +.Pp +.Ox +intentionally uses a different +.Dv NI_MAXHOST +value from what +.Tn "RFC 2553" +suggests, to avoid buffer length handling mistakes. diff --git a/static/openbsd/man3/getnetent.3 b/static/openbsd/man3/getnetent.3 new file mode 100644 index 00000000..da2c4ef4 --- /dev/null +++ b/static/openbsd/man3/getnetent.3 @@ -0,0 +1,147 @@ +.\" $OpenBSD: getnetent.3,v 1.19 2019/08/30 20:20:51 jmc 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 $Mdocdate: August 30 2019 $ +.Dt GETNETENT 3 +.Os +.Sh NAME +.Nm getnetent , +.Nm getnetbyaddr , +.Nm getnetbyname , +.Nm setnetent , +.Nm endnetent +.Nd get network entry +.Sh SYNOPSIS +.In netdb.h +.Ft struct netent * +.Fn getnetent "void" +.Ft struct netent * +.Fn getnetbyname "const char *name" +.Ft struct netent * +.Fn getnetbyaddr "in_addr_t net" "int type" +.Ft void +.Fn setnetent "int stayopen" +.Ft void +.Fn endnetent "void" +.Sh DESCRIPTION +The +.Fn getnetbyname +and +.Fn getnetbyaddr +functions return a pointer to an object with the following structure: +.Bd -literal -offset indent +struct netent { + char *n_name; /* official name of net */ + char **n_aliases; /* alias list */ + int n_addrtype; /* net number type */ + in_addr_t n_net; /* net number */ +}; +.Ed +.Pp +The members of this structure are: +.Bl -tag -width n_addrtype +.It Fa n_name +The official name of the network. +.It Fa n_aliases +A null-terminated list of alternate names for the network. +.It Fa n_addrtype +The type of the network number returned; it is always +.Dv AF_INET . +.It Fa n_net +The network number. +Network numbers are returned in machine byte order. +.El +.Pp +On +.Ox , +these legacy functions perform a lookup in a similar fashion as +.Xr gethostbyname 3 +and +.Xr gethostbyaddr 3 , +respectively. +On other systems, they may use a separate network database file, +.Pa /etc/networks . +.Pp +In contrast to +.Xr gethostbyaddr 3 , +the +.Fa net +argument is expected in machine byte order. +.Pp +The +.Fn setnetent , +.Fn getnetent , +and +.Fn endnetent +functions are deprecated and no longer have any effect. +They could be used in the past to iterate over entries in the former file +.Pa /etc/networks . +.Sh RETURN VALUES +The +.Fn getnetbyaddr +and +.Fn getnetbyname +functions return +.Dv NULL +if the requested entry is not found. +.Pp +The +.Fn getnetent +function always returns +.Dv NULL . +.Sh FILES +.Bl -tag -width /etc/hosts -compact +.It Pa /etc/hosts +The local host and network name database. +.El +.Sh SEE ALSO +.Xr getaddrinfo 3 , +.Xr gethostbyname 3 , +.Xr getnameinfo 3 , +.Xr res_init 3 , +.Xr hosts 5 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2008 . +.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 naive. diff --git a/static/openbsd/man3/getnetgrent.3 b/static/openbsd/man3/getnetgrent.3 new file mode 100644 index 00000000..3e4b3b58 --- /dev/null +++ b/static/openbsd/man3/getnetgrent.3 @@ -0,0 +1,127 @@ +.\" $OpenBSD: getnetgrent.3,v 1.14 2013/06/05 03:39:22 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt GETNETGRENT 3 +.Os +.Sh NAME +.Nm getnetgrent , +.Nm innetgr , +.Nm setnetgrent , +.Nm endnetgrent +.Nd netgroup database operations +.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 +.Pa /etc/netgroup.db +which is described +in +.Xr netgroup 5 . +If that file does not exist, and the system supports YP, +then the netgroup YP databases are used instead. +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 +.Dq 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 , +those fields are considered wildcards. +.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 +.Ar host , +.Ar user , +or +.Ar 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 +.Dq no more netgroup members +or 1 otherwise. +The function +.Fn innetgr +returns 1 for a successful match or 0 otherwise. +The functions +.Fn setnetgrent +and +.Fn endnetgrent +have no return value. +.Sh FILES +.Bl -tag -width /etc/netgroup.db -compact +.It Pa /etc/netgroup.db +netgroup database file +.El +.Sh SEE ALSO +.Xr netgroup 5 +.Sh BUGS +The function +.Fn getnetgrent +returns pointers to dynamically allocated data areas that are +.Xr free 3 Ns 'd when +the function +.Fn endnetgrent +is called. diff --git a/static/openbsd/man3/getopt.3 b/static/openbsd/man3/getopt.3 new file mode 100644 index 00000000..c7e28ff9 --- /dev/null +++ b/static/openbsd/man3/getopt.3 @@ -0,0 +1,365 @@ +.\" 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. +.\" +.\" $OpenBSD: getopt.3,v 1.48 2022/07/25 02:25:55 jsg Exp $ +.\" +.Dd $Mdocdate: July 25 2022 $ +.Dt GETOPT 3 +.Os +.Sh NAME +.Nm getopt +.Nd get option character from command line argument list +.Sh SYNOPSIS +.In unistd.h +.Vt extern char *optarg; +.Vt extern int opterr; +.Vt extern int optind; +.Vt extern int optopt; +.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, +characters followed by a colon, and characters followed by two colons. +A character followed by a single colon indicates that an argument +is to follow the option on the command line. +Two colons indicates that the argument is optional \- this is an +extension not covered by POSIX. +For example, an option string +.Qq x +recognizes an option +.Fl x , +and an option string +.Qq Li x: +recognizes an option and argument +.Fl x Ar argument . +It does not matter to +.Fn getopt +if a following argument has leading whitespace; except in the case where +the argument is optional, denoted with two colons, no leading whitespace +is permitted. +.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 . +.Pp +The variables +.Va opterr +and +.Va optind +are both initialized to 1. +The +.Va optind +variable may be set to another value larger than 0 before a set of calls to +.Fn getopt +in order to skip over more or less +.Fa argv +entries. +An +.Va optind +value of 0 is reserved for compatibility with GNU +.Fn getopt . +.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 +.Ql -- +(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 +The following code accepts the options +.Fl b +and +.Fl f Ar argument +and adjusts +.Va argc +and +.Va argv +after option argument processing has completed. +.Bd -literal -offset indent +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)) == -1) + err(1, "%s", optarg); + break; + default: + usage(); + } +} +argc -= optind; +argv += optind; +.Ed +.Sh DIAGNOSTICS +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 +.Ql \&? . +Setting +.Va opterr +to a zero will disable these error messages. +If +.Fa optstring +has a leading +.Ql \&: +then a missing option argument causes a +.Ql \&: +to be returned in addition to suppressing any error messages. +.Pp +Option arguments are allowed to begin with +.Ql - ; +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 +.Fn getopt +function implements a superset of the functionality specified by +.St -p1003.1 . +.Pp +The following extensions are supported: +.Bl -bullet +.It +The +.Va optreset +variable was added to make it possible to call the +.Fn getopt +function multiple times. +.It +If the +.Va optind +variable is set to 0, +.Fn getopt +will behave as if the +.Va optreset +variable has been set. +This is for compatibility with +.Tn GNU +.Fn getopt . +New code should use +.Va optreset +instead. +.It +If the first character of +.Fa optstring +is a plus sign +.Pq Ql + , +it will be ignored. +This is for compatibility with +.Tn GNU +.Fn getopt . +.It +If the first character of +.Fa optstring +is a dash +.Pq Ql - , +non-options will be returned as arguments to the option character +.Ql \e1 . +This is for compatibility with +.Tn GNU +.Fn getopt . +.It +A single dash +.Pq Ql - +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 +.Ql - +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 +.Ql - +as the first character in +.Fa optstring +to avoid a semantic conflict with +.Tn GNU +.Fn getopt +semantics (see above). +By default, a single dash causes +.Fn getopt +to return \-1. +.El +.Pp +Historic +.Bx +versions of +.Fn getopt +set +.Fa optopt +to the last option character processed. +However, this conflicts with +.St -p1003.1 +which stipulates that +.Fa optopt +be set to the last character that caused an error. +.Sh HISTORY +The +.Fn getopt +function first appeared in +.At III +and was reimplemented for +.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 +It is 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 and can handle mixed +number and letter arguments. +.Bd -literal -offset indent +int aflag = 0, bflag = 0, ch, lastch = '\e0'; +int length = -1, newarg = 1, prevoptind = 1; + +while ((ch = getopt(argc, argv, "0123456789ab")) != -1) { + switch (ch) { + case '0': case '1': case '2': case '3': case '4': + case '5': case '6': case '7': case '8': case '9': + if (newarg || !isdigit(lastch)) + length = 0; + else if (length > INT_MAX / 10) + usage(); + length = (length * 10) + (ch - '0'); + break; + case 'a': + aflag = 1; + break; + case 'b': + bflag = 1; + break; + default: + usage(); + } + lastch = ch; + newarg = optind != prevoptind; + prevoptind = optind; +} +.Ed diff --git a/static/openbsd/man3/getopt_long.3 b/static/openbsd/man3/getopt_long.3 new file mode 100644 index 00000000..88594cbf --- /dev/null +++ b/static/openbsd/man3/getopt_long.3 @@ -0,0 +1,460 @@ +.\" $OpenBSD: getopt_long.3,v 1.25 2022/09/11 06:38:11 jmc Exp $ +.\" $NetBSD: getopt_long.3,v 1.11 2002/10/02 10:54:19 wiz 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 $Mdocdate: September 11 2022 $ +.Dt GETOPT_LONG 3 +.Os +.Sh NAME +.Nm getopt_long , +.Nm getopt_long_only +.Nd get long options from command line argument list +.Sh SYNOPSIS +.In getopt.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_long "int argc" "char * const *argv" "const char *optstring" "const struct option *longopts" "int *longindex" +.Ft int +.Fn getopt_long_only "int argc" "char * const *argv" "const char *optstring" "const struct option *longopts" "int *longindex" +.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 -offset indent +$ 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 +By default, +.Fn getopt_long +permutes +.Ar argv +such that all option arguments are evaluated before any non-options arguments. +If the first character of +.Fa optstring +is a plus sign +.Pq Ql + +or if the environment variable +.Ev POSIXLY_CORRECT +is set, then +.Ar argv +is processed in order and option processing stops as soon as the first +non-option argument is encountered. +.Pp +The +.Fn getopt_long +call requires an array to be initialized describing the long +options. +Each element of the array is a structure: +.Bd -literal -offset indent +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: +.Pp +.Bl -tag -width "optional_argument" -compact -offset indent +.It Dv no_argument +no argument to the option is expected. +.It Dv required_argument +an argument to the option is required. +.It Dv 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 longindex +argument is not +.Dv NULL , +then the integer pointed to by it will be set to the index of the long +option relative to +.Fa longopts . +.Pp +The last element of the +.Fa longopts +array has to be filled with zeroes. +.Pp +The +.Fn getopt_long_only +function behaves identically to +.Fn getopt_long +with the exception that long options may start with +.Sq - +in addition to +.Sq -- . +If an option starting with +.Sq - +does not match a long option but does match a single-character option, +the single-character option is returned. +.Sh RETURN VALUES +If the +.Fa flag +field in +.Vt struct option +is +.Dv NULL , +.Fn getopt_long +and +.Fn getopt_long_only +return the value specified in the +.Fa val +field, which is usually just the corresponding short option. +If +.Fa flag +is not +.Dv NULL , +these functions return 0 and store +.Fa val +in the location pointed to by +.Fa flag . +These functions return +.Sq \&: +if there was a missing option argument, +.Sq \&? +if the user specified an unknown or ambiguous option, and +\-1 when the argument list has been exhausted. +.Sh IMPLEMENTATION DIFFERENCES +This section describes differences to the GNU implementation +found in glibc-2.1.3: +.Bl -bullet +.It +handling of +.Ql - +within the option string (not the first character): +.Bl -tag -width "OpenBSD" +.It GNU +treats a +.Ql - +on the command line as a non-argument. +.It OpenBSD +a +.Ql - +within the option string matches a +.Ql - +(single dash) on the command line. +This functionality is provided for backward compatibility with +programs, such as +.Xr su 1 , +that use +.Ql - +as an option flag. +This practice is wrong, and should not be used in any current development. +.El +.It +handling of +.Ql :: +in the option string in the presence of +.Ev POSIXLY_CORRECT : +.Bl -tag -width "OpenBSD" +.It Both +GNU and +.Ox +ignore +.Ev POSIXLY_CORRECT +here and take +.Ql :: +to mean the preceding option takes an optional argument. +.El +.It +return value in case of missing argument if first character +(after +.Ql + +or +.Ql - ) +in the option string is not +.Ql \&: : +.Bl -tag -width "OpenBSD" +.It GNU +returns +.Ql \&? +.It OpenBSD +returns +.Ql \&: +(since +.Ox Ns 's +.Xr getopt 3 +does). +.El +.It +handling of +.Ql --a +in +.Xr getopt 3 : +.Bl -tag -width "OpenBSD" +.It GNU +parses this as option +.Ql - , +option +.Ql a . +.It OpenBSD +parses this as +.Ql -- , +and returns \-1 (ignoring the +.Ql a ) +(because the original +.Fn getopt +did.) +.El +.It +setting of +.Va optopt +for long options with +.Va flag +.No non- Ns Dv NULL : +.Bl -tag -width "OpenBSD" +.It GNU +sets +.Va optopt +to +.Va val . +.It OpenBSD +sets +.Va optopt +to 0 (since +.Va val +would never be returned). +.El +.It +handling of +.Ql -W +with +.Ql W; +in the option string in +.Xr getopt 3 +(not +.Fn getopt_long ) : +.Bl -tag -width "OpenBSD" +.It GNU +causes a segmentation fault. +.It OpenBSD +no special handling is done; +.Ql W; +is interpreted as two separate options, neither of which take an argument. +.El +.It +setting of +.Va optarg +for long options without an argument that are invoked via +.Ql -W +(with +.Ql W; +in the option string): +.Bl -tag -width "OpenBSD" +.It GNU +sets +.Va optarg +to the option name (the argument of +.Ql -W ) . +.It OpenBSD +sets +.Va optarg +to +.Dv NULL +(the argument of the long option). +.El +.It +handling of +.Ql -W +with an argument that is not (a prefix to) a known long option +(with +.Ql W; +in the option string): +.Bl -tag -width "OpenBSD" +.It GNU +returns +.Ql -W +with +.Va optarg +set to the unknown option. +.It OpenBSD +treats this as an error (unknown option) and returns +.Ql \&? +with +.Va optopt +set to 0 and +.Va optarg +set to +.Dv NULL +(as GNU's man page documents). +.El +.It +The error messages are different. +.It +.Ox +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 +.Va optind +relative to current positions) are the same, though. +(We do fewer variable swaps.) +.El +.Sh ENVIRONMENT +.Bl -tag -width Ev +.It Ev POSIXLY_CORRECT +If set, option processing stops when the first non-option is found and +a leading +.Sq + +in the +.Ar optstring +is ignored. +.El +.Sh EXAMPLES +.Bd -literal +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)) == -1) + err(1, "unable to open %s", optarg); + break; + case 0: + if (daggerset) + fprintf(stderr, "Buffy will use her dagger to " + "apply fluoride to dracula's teeth\en"); + break; + default: + usage(); + } +argc -= optind; +argv += optind; +.Ed +.Sh SEE ALSO +.Xr getopt 3 +.Sh HISTORY +The +.Fn getopt_long +and +.Fn getopt_long_only +functions first appeared in GNU libiberty. +This implementation first appeared in +.Ox 3.3 . +.Sh BUGS +The +.Ar argv +argument is not really +.Dv const +as its elements may be permuted (unless +.Ev POSIXLY_CORRECT +is set). diff --git a/static/openbsd/man3/getpagesize.3 b/static/openbsd/man3/getpagesize.3 new file mode 100644 index 00000000..e9536097 --- /dev/null +++ b/static/openbsd/man3/getpagesize.3 @@ -0,0 +1,56 @@ +.\" $OpenBSD: getpagesize.3,v 1.14 2026/04/12 09:31:01 jsg 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 $Mdocdate: April 12 2026 $ +.Dt GETPAGESIZE 3 +.Os +.Sh NAME +.Nm getpagesize +.Nd get system page size +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getpagesize void +.Sh DESCRIPTION +The +.Fn getpagesize +function 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 system +page size and may not be the same as the underlying +hardware page size. +.Sh SEE ALSO +.Xr pagesize 1 +.Sh HISTORY +The +.Fn getpagesize +function call appeared in +.Bx 4.1c . diff --git a/static/openbsd/man3/getpass.3 b/static/openbsd/man3/getpass.3 new file mode 100644 index 00000000..a83918c2 --- /dev/null +++ b/static/openbsd/man3/getpass.3 @@ -0,0 +1,131 @@ +.\" $OpenBSD: getpass.3,v 1.18 2016/09/03 12:47:28 jmc 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. +.\" +.Dd $Mdocdate: September 3 2016 $ +.Dt GETPASS 3 +.Os +.Sh NAME +.Nm getpass +.Nd get a password +.Sh SYNOPSIS +.In pwd.h +.In unistd.h +.Ft char * +.Fn getpass "const char *prompt" +.Sh DESCRIPTION +.Bf -symbolic +This function is obsolete. +Consider using +.Xr readpassphrase 3 . +.Ef +.Pp +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 +.Dv _PASSWORD_LEN +(currently 128, as defined in the +.In pwd.h +include file) +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 +The calling process should zero the password with +.Xr explicit_bzero 3 +as soon as possible to +avoid leaving the cleartext password visible in the process's address +space. +.Sh RETURN VALUES +Upon successful completion, +.Fn getpass +returns a pointer to a NUL-terminated string of at most +.Dv _PASSWORD_LEN +characters. +If an error is encountered, the terminal state is restored and +a null pointer is returned. +.Sh FILES +.Bl -tag -width /dev/tty -compact +.It Pa /dev/tty +.El +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINTR +The +.Fn getpass +function was interrupted by a signal. +.It Bq Er EIO +The process is a member of a background process attempting to read +from its controlling terminal, the process is ignoring or blocking +the SIGTTIN signal or the process group is orphaned. +.It Bq Er EMFILE +The process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +The system file table is full. +.El +.Sh SEE ALSO +.Xr crypt 3 , +.Xr readpassphrase 3 +.Sh STANDARDS +Historically, +.Bx +versions of +.Fn getpass +have accepted a password on the standard input if +.Pa /dev/tty +is unavailable. +This contradicts +.St -xpg4.2 +but the +.Ox +implementation is conformant in all other respects. +Removed from +.St -p1003.1-2001 . +.Sh HISTORY +A +.Fn getpass +function appeared in +.At v7 . +.Sh CAVEATS +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. diff --git a/static/openbsd/man3/getpeereid.3 b/static/openbsd/man3/getpeereid.3 new file mode 100644 index 00000000..4475bbd7 --- /dev/null +++ b/static/openbsd/man3/getpeereid.3 @@ -0,0 +1,121 @@ +.\" $OpenBSD: getpeereid.3,v 1.4 2022/09/11 06:38:10 jmc 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 $Mdocdate: September 11 2022 $ +.Dt GETPEEREID 3 +.Os +.Sh NAME +.Nm getpeereid +.Nd get effective user and group identification of locally-connected peer +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn getpeereid "int s" "uid_t *euid" "gid_t *egid" +.Sh DESCRIPTION +.Fn getpeereid +returns the effective user ID and group ID of the peer connected to +a +.Ux Ns -domain +socket (see +.Xr unix 4 ) . +The argument +.Fa s +must be of type +.Dv SOCK_STREAM +or +.Dv SOCK_SEQPACKET . +.Pp +One common use is for +.Ux Ns -domain +servers to determine the credentials of clients that have connected to it. +.Pp +.Fn getpeereid +takes three parameters: +.Bl -bullet +.It +.Fa s +contains the file descriptor of the socket whose peer credentials +should be looked up. +.It +.Fa euid +points to a +.Vt uid_t +variable into which the effective user ID for the connected peer will +be stored. +.It +.Fa egid +points to a +.Vt gid_t +variable into which the effective group ID for the connected peer will +be stored. +.El +.Sh RETURN VALUES +If the call succeeds, a 0 is returned and +.Fa euid +and +.Fa egid +are set to the effective user ID and group ID of the connected peer. +Otherwise, +.Va errno +is set and a value of \-1 is returned. +.Sh ERRORS +On failure, +.Va errno +is set to one of the following: +.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 EOPNOTSUPP +The socket is not in the +.Ux Ns -domain . +.It Bq Er ENOTCONN +The socket is not connected. +.It Bq Er ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr bind 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr getsockopt 2 , +.Xr socket 2 , +.Xr unix 4 +.Sh HISTORY +The +.Fn getpeereid +function call appeared in +.Ox 3.0 . diff --git a/static/openbsd/man3/getprogname.3 b/static/openbsd/man3/getprogname.3 new file mode 100644 index 00000000..5542abc8 --- /dev/null +++ b/static/openbsd/man3/getprogname.3 @@ -0,0 +1,81 @@ +.\" $OpenBSD: getprogname.3,v 1.6 2023/02/22 06:31:51 guenther 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 $Mdocdate: February 22 2023 $ +.Dt GETPROGNAME 3 +.Os +.Sh NAME +.Nm getprogname , +.Nm setprogname +.Nd get or set the name of the current program +.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. +.Pp +The +.Fn setprogname +function sets the name of the program to be the last path component of the +.Fa name +argument. +Internally, only the pointer to the given string is kept as the program name, +so it should not be modified and the storage for the string must remain valid +for the rest of the program's lifetime. +.Sh SEE ALSO +.Xr err 3 , +.Xr setproctitle 3 +.Sh HISTORY +The +.Fn getprogname +and +.Fn setprogname +functions first appeared in +.Ox 5.4 +as function-based wrappers around the +.Bx 4.4 +.Va __progname +interface. +.Sh CAVEATS +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/openbsd/man3/getprotoent.3 b/static/openbsd/man3/getprotoent.3 new file mode 100644 index 00000000..cc2c6983 --- /dev/null +++ b/static/openbsd/man3/getprotoent.3 @@ -0,0 +1,213 @@ +.\" $OpenBSD: getprotoent.3,v 1.18 2013/06/05 03:39:23 tedu 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 $Mdocdate: June 5 2013 $ +.Dt GETPROTOENT 3 +.Os +.Sh NAME +.Nm getprotoent , +.Nm getprotoent_r , +.Nm getprotobynumber , +.Nm getprotobynumber_r , +.Nm getprotobyname , +.Nm getprotobyname_r , +.Nm setprotoent , +.Nm setprotoent_r , +.Nm endprotoent , +.Nm endprotoent_r +.Nd get protocol entry +.Sh SYNOPSIS +.In netdb.h +.Ft struct protoent * +.Fn getprotoent "void" +.Ft int +.Fn getprotoent_r "struct protoent *protoent" "struct protoent_data *protoent_data" +.Ft struct protoent * +.Fn getprotobyname "const char *name" +.Ft int +.Fn getprotobyname_r "const char *name" "struct protoent *protoent" "struct protoent_data *protoent_data" +.Ft struct protoent * +.Fn getprotobynumber "int proto" +.Ft int +.Fn getprotobynumber_r "int proto" "struct protoent *protoent" "struct protoent_data *protoent_data" +.Ft void +.Fn setprotoent "int stayopen" +.Ft void +.Fn setprotoent_r "int stayopen" "struct protoent_data *protoent_data" +.Ft void +.Fn endprotoent "void" +.Ft void +.Fn endprotoent_r "struct protoent_data *protoent_data" +.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 database, +.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 +.It Fa p_name +The official name of the protocol. +.It Fa p_aliases +A null-terminated list of alternate 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 protocol database 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 +and +.Fn getprotobynumber +functions sequentially search from the beginning of the file until a +matching protocol name or protocol number is found, or until +.Dv EOF +is encountered. +.Pp +The +.Fn getprotoent_r , +.Fn getprotobyport_r , +.Fn getprotobyname_r , +.Fn setprotoent_r , +and +.Fn endprotoent_r +functions are reentrant versions of the above functions that take a +pointer to a +.Vt protoent_data +structure which is used to store state information. +The structure must be zero-filled before it is used +and should be considered opaque for the sake of portability. +.Pp +The +.Fn getprotoent_r , +.Fn getprotobyport_r , +and +.Fn getprotobyname_r +functions +also take a pointer to a +.Vt protoent +structure which is used to store the results of the database lookup. +.Sh RETURN VALUES +The +.Fn getprotoent , +.Fn getprotobyport , +and +.Fn getprotobyname +functions return a pointer to a +.Vt protoent +structure on success or a null pointer if end-of-file +is reached or an error occurs. +.Pp +The +.Fn getprotoent_r , +.Fn getprotobyport_r , +and +.Fn getprotobyname_r +functions return 0 on success or \-1 if end-of-file +is reached or an error occurs. +.Sh FILES +.Bl -tag -width /etc/protocols -compact +.It Pa /etc/protocols +.El +.Sh SEE ALSO +.Xr protocols 5 +.Sh STANDARDS +The +.Fn getprotoent , +.Fn getprotobynumber , +.Fn getprotobyname , +.Fn setprotoent , +and +.Fn endprotoent +functions conform to +.St -p1003.1-2004 . +.Pp +The +.Fn getprotoent_r , +.Fn getprotobyport_r , +.Fn getprotobyname_r , +.Fn setprotoent_r , +and +.Fn endprotoent_r +functions are not currently standardized. +This implementation follows the API used by HP, IBM, and Digital. +.Sh HISTORY +The +.Fn getprotoent , +.Fn getprotobynumber , +.Fn getprotobyname , +.Fn setprotoent , +and +.Fn endprotoent +functions appeared in +.Bx 4.2 . +.Pp +The +.Fn getprotoent_r , +.Fn getprotobyport_r , +.Fn getprotobyname_r , +.Fn setprotoent_r , +and +.Fn endprotoent_r +functions appeared in +.Ox 3.7 . +.Sh BUGS +The non-reentrant 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/openbsd/man3/getpwent.3 b/static/openbsd/man3/getpwent.3 new file mode 100644 index 00000000..3b04c762 --- /dev/null +++ b/static/openbsd/man3/getpwent.3 @@ -0,0 +1,190 @@ +.\" $OpenBSD: getpwent.3,v 1.33 2022/09/11 06:38:10 jmc 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt GETPWENT 3 +.Os +.Sh NAME +.Nm getpwent , +.Nm setpwent , +.Nm endpwent +.Nd sequential password database access +.Sh SYNOPSIS +.In pwd.h +.Ft struct passwd * +.Fn getpwent void +.Ft void +.Fn setpwent void +.Ft void +.Fn endpwent void +.Sh DESCRIPTION +These functions operate on the password database file which is described in +.Xr passwd 5 . +Each entry in the database is defined by the structure +.Vt struct 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 access class */ + char *pw_gecos; /* Honeywell login info */ + char *pw_dir; /* home directory */ + char *pw_shell; /* default shell */ + time_t pw_expire; /* account expiration */ +}; +.Ed +.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 +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. +However the file descriptors are automatically closed when +.Xr execve 2 +is called. +.Pp +.Fn setpwent +causes +.Fn getpwent +to +.Dq rewind +to the beginning of the database. +.Pp +The +.Fn endpwent +function closes any file descriptors opened by +.Fn setpwent +or +.Fn getpwent . +.Pp +These routines have been written to +.Dq shadow +the password file, that is, +allow only certain programs to have access to the encrypted password. +If the process which calls them has an effective UID of 0 or has the +.Dq _shadow +group in its group vector, the encrypted password will be returned, otherwise, +the password field of the returned structure will point to the string +.Ql * . +.Sh YP SUPPORT +If YP is active, +.Fn getpwent +also uses the +.Pa master.passwd.byname +YP map (if available) or the +.Pa passwd.byname +YP map. +This is in addition to the passwd file, +and respects the order of both normal and YP +entries in the passwd file. +.Sh RETURN VALUES +The +.Fn getpwent +function returns a valid pointer to a passwd structure on success +or a null pointer if end-of-file is reached or an error occurs. +Subsequent calls to +.Fn getpwent , +.Fn getpwnam , +.Fn getpwnam_shadow , +.Fn getpwuid +or +.Fn getpwuid_shadow +may invalidate the returned pointer or overwrite the contents +of the passwd structure it points to. +.Pp +The +.Fn endpwent +and +.Fn setpwent +functions have no return value. +.Sh FILES +.Bl -tag -width /etc/master.passwd -compact +.It Pa /etc/pwd.db +insecure password database file +.It Pa /etc/spwd.db +secure password database file +.It Pa /etc/master.passwd +current password file +.It Pa /etc/passwd +legacy password file +.El +.Sh ERRORS +The +.Fn getpwent +function may fail for any of the errors specified for +.Xr dbopen 3 +and its +.Fn get +routine. +.Pp +If YP is active, it may also fail due to errors caused by the YP subsystem. +.Sh SEE ALSO +.Xr getlogin 2 , +.Xr getgrent 3 , +.Xr getgrouplist 3 , +.Xr getpwnam 3 , +.Xr pw_dup 3 , +.Xr passwd 5 , +.Xr Makefile.yp 8 , +.Xr pwd_mkdb 8 , +.Xr vipw 8 , +.Xr yp 8 +.Sh STANDARDS +These functions are compliant with the X/Open System Interfaces option of the +.St -p1003.1-2008 +specification. +.Sh HISTORY +The +.Fn getpwent , +.Fn setpwent , +and +.Fn endpwent +functions appeared in +.At v7 . +.Pp +The historic function +.Fn setpwfile , +which allowed the specification of alternate password databases, +has been deprecated and is no longer available. +.Sh BUGS +The routines +.Fn getpwent , +.Fn endpwent , +and +.Fn setpwent +are fairly useless in a networked environment and should be +avoided, if possible. diff --git a/static/openbsd/man3/getpwnam.3 b/static/openbsd/man3/getpwnam.3 new file mode 100644 index 00000000..9bab7230 --- /dev/null +++ b/static/openbsd/man3/getpwnam.3 @@ -0,0 +1,291 @@ +.\" $OpenBSD: getpwnam.3,v 1.14 2022/09/11 06:38:10 jmc 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt GETPWNAM 3 +.Os +.Sh NAME +.Nm getpwnam , +.Nm getpwuid , +.Nm getpwnam_r , +.Nm getpwuid_r , +.Nm getpwnam_shadow , +.Nm getpwuid_shadow , +.Nm setpassent +.Nd password database operations +.Sh SYNOPSIS +.In pwd.h +.Ft struct passwd * +.Fn getpwnam "const char *login" +.Ft struct passwd * +.Fn getpwuid "uid_t uid" +.Ft int +.Fn getpwnam_r "const char *login" "struct passwd *pwstore" "char *buf" "size_t bufsize" "struct passwd **result" +.Ft int +.Fn getpwuid_r "uid_t uid" "struct passwd *pwstore" "char *buf" "size_t bufsize" "struct passwd **result" +.Ft struct passwd * +.Fn getpwnam_shadow "const char *login" +.Ft struct passwd * +.Fn getpwuid_shadow "uid_t uid" +.Ft int +.Fn setpassent "int stayopen" +.Sh DESCRIPTION +These functions operate on the password database file which is described in +.Xr passwd 5 . +Each entry in the database is defined by the structure +.Vt struct 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 access class */ + char *pw_gecos; /* Honeywell login info */ + 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 login name or user ID, +respectively, always returning the first one encountered. +.Pp +The +.Fn getpwnam_r +and +.Fn getpwuid_r +functions both update the passwd structure pointed to by +.Fa pwstore +and store a pointer to that structure at the location pointed to by +.Fa result . +The structure is filled with an entry from the password database with a +matching +.Fa name +or +.Fa uid . +Storage referenced by the passwd structure will be allocated from +the memory provided with the +.Fa buf +parameter, which is +.Fa bufsiz +characters in size. +The maximum size needed for this buffer can be determined with +.Fn sysconf _SC_GETPW_R_SIZE_MAX . +.Pp +.Fn setpassent +accomplishes two purposes. +First, it causes +.Xr getpwent 3 +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 the lookup routines. +These file descriptors can be closed by a call to +.Xr endpwent 3 . +.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. +However the file descriptors are automatically closed when +.Xr execve 2 +is called. +.Pp +These routines have been written to +.Dq shadow +the password file, that is, +allow only certain programs to have access to the encrypted password. +The default functions will not return the true encrypted password, but +instead only the string +.Ql * . +If the process which calls them has an effective UID of 0 or has the +.Dq _shadow +group in its group vector, and wishes to access the encrypted password, +it should use the +.Fn getpwnam_shadow +and +.Fn getpwuid_shadow +functions. +.Ss YP support +If YP is active, the functions +.Fn getpwnam +and +.Fn getpwnam_r +also use the +.Pa master.passwd.byname +YP map (if available) or the +.Pa passwd.byname +YP map; and the functions +.Fn getpwuid +and +.Fn getpwuid_r +also use the +.Pa master.passwd.byuid +YP map (if available) or the +.Pa passwd.byuid +YP map. +This is in addition to the passwd file, +and respects the order of both normal and YP +entries in the passwd file. +.Sh RETURN VALUES +The functions +.Fn getpwnam , +.Fn getpwnam_shadow , +.Fn getpwuid , +and +.Fn getpwuid_shadow +return a pointer to a passwd structure if a match is found or a null +pointer if no match is found or an error occurs. +Subsequent calls to +.Fn getpwent , +.Fn getpwnam , +.Fn getpwnam_shadow , +.Fn getpwuid +or +.Fn getpwuid_shadow +may invalidate the returned pointer or overwrite the contents +of the passwd structure it points to. +.Pp +The functions +.Fn getpwnam_r +and +.Fn getpwuid_r +update +.Fa result +to point to +.Fa pwstore +if a match is found or set it to +.Dv NULL +if no match is found or an error occurs. +They return 0 on success, even if no match is found, +or an error number if an error occurs; see +.Sx ERRORS . +.Pp +The +.Fn setpassent +function returns 0 on failure or 1 on success. +.Sh FILES +.Bl -tag -width /etc/master.passwd -compact +.It Pa /etc/pwd.db +insecure password database file +.It Pa /etc/spwd.db +secure password database file +.It Pa /etc/master.passwd +current password file +.It Pa /etc/passwd +legacy password file +.El +.Sh ERRORS +The +.Fn getpwnam_r +and +.Fn getpwuid_r +functions may fail if: +.Bl -tag -width Er +.It Bq Er ERANGE +The storage supplied via +.Fa buf +and +.Fa bufsize +is too small and cannot contain all the strings to be returned in +.Fa pwstore . +.El +.Pp +The +.Fn getpwnam , +.Fn getpwnam_r , +.Fn getpwuid , +and +.Fn getpwuid_r +functions may also fail for any of the errors specified for +.Xr dbopen 3 +and its +.Fn get +routine. +.Pp +If YP is active, they may also fail due to errors caused by the YP +subsystem. +.Sh SEE ALSO +.Xr getlogin 2 , +.Xr getgrent 3 , +.Xr getgrouplist 3 , +.Xr getpwent 3 , +.Xr pw_dup 3 , +.Xr sysconf 3 , +.Xr passwd 5 , +.Xr Makefile.yp 8 , +.Xr pwd_mkdb 8 , +.Xr vipw 8 , +.Xr yp 8 +.Sh STANDARDS +The +.Fn getpwnam , +.Fn getpwnam_r , +.Fn getpwuid , +and +.Fn getpwuid_r +functions are compliant with the +.St -p1003.1-2008 +specification. +.Pp +.Sx YP support +and the +.Fn setpassent +function are extensions to that specification. +.Sh HISTORY +A predecessor to +.Fn getpwuid , +.Fn getpw , +first appeared in +.At v4 . +The +.Fn getpwnam +and +.Fn getpwuid +functions appeared in +.At v7 , +.Fn setpassent +in +.Bx 4.3 Reno , +and +.Fn getpwnam_shadow +and +.Fn getpwuid_shadow +in +.Ox 5.9 . diff --git a/static/openbsd/man3/getrawpartition.3 b/static/openbsd/man3/getrawpartition.3 new file mode 100644 index 00000000..5a4cdf32 --- /dev/null +++ b/static/openbsd/man3/getrawpartition.3 @@ -0,0 +1,62 @@ +.\" $OpenBSD: getrawpartition.3,v 1.11 2025/06/06 22:01:40 schwarze Exp $ +.\" $NetBSD: getrawpartition.3,v 1.1 1996/05/16 07:03:32 thorpej 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 REGENTS OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 6 2025 $ +.Dt GETRAWPARTITION 3 +.Os +.Sh NAME +.Nm getrawpartition +.Nd get the system raw partition +.Sh SYNOPSIS +.Lb libutil +.In util.h +.Ft int +.Fn getrawpartition void +.Sh DESCRIPTION +.Fn getrawpartition +returns the partition number +.Pf ( Sq a +== 0, +.Sq b +== 1, ...) of the +.Dq raw +partition of the system's disks. +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 sysctl 2 , +.Xr getmaxpartitions 3 +.Sh HISTORY +The +.Nm +function call appeared in +.Nx 1.2 . diff --git a/static/openbsd/man3/getrpcent.3 b/static/openbsd/man3/getrpcent.3 new file mode 100644 index 00000000..eeb7076f --- /dev/null +++ b/static/openbsd/man3/getrpcent.3 @@ -0,0 +1,122 @@ +.\" $OpenBSD: getrpcent.3,v 1.13 2013/06/05 03:39:23 tedu Exp $ +.\" +.\" Copyright (c) 2010, Oracle America, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer in the documentation and/or other materials +.\" provided with the distribution. +.\" * Neither the name of the "Oracle America, Inc." nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt GETRPCENT 3 +.Os +.Sh NAME +.Nm getrpcent , +.Nm getrpcbyname , +.Nm getrpcbynumber , +.Nm endrpcent , +.Nm setrpcent +.Nd get RPC entry +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft struct rpcent * +.Fn getrpcent void +.Ft struct rpcent * +.Fn getrpcbyname "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 database, +.Pa /etc/rpc : +.Bd -literal -offset 2n +struct rpcent { + char *r_name; /* name of server for this rpc program */ + char **r_aliases; /* alias list */ + int 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 alternate 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 database 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 DIAGNOSTICS +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/openbsd/man3/getrpcport.3 b/static/openbsd/man3/getrpcport.3 new file mode 100644 index 00000000..09180937 --- /dev/null +++ b/static/openbsd/man3/getrpcport.3 @@ -0,0 +1,61 @@ +.\" $OpenBSD: getrpcport.3,v 1.10 2013/06/05 03:39:23 tedu Exp $ +.\" +.\" Copyright (c) 2010, Oracle America, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer in the documentation and/or other materials +.\" provided with the distribution. +.\" * Neither the name of the "Oracle America, Inc." nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt GETRPCPORT 3 +.Os +.Sh NAME +.Nm getrpcport +.Nd get RPC port number +.Sh SYNOPSIS +.In rpc/rpc.h +.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/openbsd/man3/getrrsetbyname.3 b/static/openbsd/man3/getrrsetbyname.3 new file mode 100644 index 00000000..314f3166 --- /dev/null +++ b/static/openbsd/man3/getrrsetbyname.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: getrrsetbyname.3,v 1.22 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" 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 INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM 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: September 11 2022 $ +.Dt GETRRSETBYNAME 3 +.Os +.Sh NAME +.Nm freerrset , +.Nm getrrsetbyname +.Nd retrieve DNS records +.Sh SYNOPSIS +.In netdb.h +.Ft int +.Fn getrrsetbyname "const char *hostname" "unsigned int rdclass" \ +"unsigned int rdtype" "unsigned int flags" "struct rrsetinfo **res" +.Ft void +.Fn freerrset "struct rrsetinfo *rrset" +.Sh DESCRIPTION +.Fn getrrsetbyname +gets a set of resource records associated with a +.Fa hostname , +.Fa rdclass , +and +.Fa rdtype . +.Fa hostname +is a pointer to a NUL-terminated string. +The +.Fa flags +field is currently unused and must be zero. +.Pp +After a successful call to +.Fn getrrsetbyname , +.Fa *res +is a pointer to an +.Vt rrsetinfo +structure, containing a list of one or more +.Vt rdatainfo +structures containing resource records and potentially another list of +.Vt rdatainfo +structures containing SIG resource records associated with those records. +The members +.Li rri_rdclass +and +.Li rri_rdtype +are copied from the parameters. +.Li rri_ttl +and +.Li rri_name +are properties of the obtained rrset. +The resource records contained in +.Li rri_rdatas +and +.Li rri_sigs +are in uncompressed DNS wire format. +Properties of the rdataset are represented in the +.Li rri_flags +bitfield. +If the +.Dv RRSET_VALIDATED +bit is set, the data has been DNSSEC +validated and the signatures verified. +.Pp +The following structures are used: +.Bd -literal -offset indent +struct rdatainfo { + unsigned int rdi_length; /* length of data */ + unsigned char *rdi_data; /* record data */ +}; + +struct rrsetinfo { + unsigned int rri_flags; /* RRSET_VALIDATED ... */ + unsigned int rri_rdclass; /* class number */ + unsigned int rri_rdtype; /* RR type number */ + unsigned int rri_ttl; /* time to live */ + unsigned int rri_nrdatas; /* size of rdatas array */ + unsigned int rri_nsigs; /* size of sigs array */ + char *rri_name; /* canonical name */ + struct rdatainfo *rri_rdatas; /* individual records */ + struct rdatainfo *rri_sigs; /* individual signatures */ +}; +.Ed +.Pp +All of the information returned by +.Fn getrrsetbyname +is dynamically allocated: the +.Vt rrsetinfo +and +.Vt rdatainfo +structures, +and the canonical host name strings pointed to by the +.Vt rrsetinfo +structure. +Memory allocated for the dynamically allocated structures created by +a successful call to +.Fn getrrsetbyname +is released by +.Fn freerrset . +.Li rrset +is a pointer to a +.Vt struct rrsetinfo +created by a call to +.Fn getrrsetbyname . +.\" .Pp +.\" If the EDNS0 option is activated in +.\" .Xr resolv.conf 5 , +.\" .Fn getrrsetbyname +.\" will request DNSSEC authentication using the EDNS0 DNSSEC OK (DO) bit. +.Sh RETURN VALUES +.Fn getrrsetbyname +returns zero on success, and one of the following error +codes if an error occurred: +.Bl -tag -width ERRSET_NOMEMORY +.It Bq Er ERRSET_NONAME +The name does not exist. +.It Bq Er ERRSET_NODATA +The name exists, but does not have data of the desired type. +.It Bq Er ERRSET_NOMEMORY +Memory could not be allocated. +.It Bq Er ERRSET_INVAL +A parameter is invalid. +.It Bq Er ERRSET_FAIL +Other failure. +.El +.Sh SEE ALSO +.Xr res_init 3 , +.Xr resolv.conf 5 +.Sh HISTORY +.Fn getrrsetbyname +first appeared in +.Ox 3.0 . +The API first appeared in ISC BIND version 9. +.Sh AUTHORS +.An Jakob Schlyter Aq Mt jakob@openbsd.org +.Sh CAVEATS +The +.Dv RRSET_VALIDATED +flag in +.Li rri_flags +is set if the AD (authenticated data) bit in the DNS answer is +set. +This flag +.Em should not +be trusted unless the transport between the nameserver and the resolver +is secure (e.g. IPsec, trusted network, loopback communication). +.Sh BUGS +The data in +.Li *rdi_data +should be returned in uncompressed wire format. +Currently, the data is in compressed format and the caller can't +uncompress since it doesn't have the full message. diff --git a/static/openbsd/man3/getservent.3 b/static/openbsd/man3/getservent.3 new file mode 100644 index 00000000..29dd3eb5 --- /dev/null +++ b/static/openbsd/man3/getservent.3 @@ -0,0 +1,220 @@ +.\" $OpenBSD: getservent.3,v 1.21 2013/06/05 03:39:23 tedu 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 $Mdocdate: June 5 2013 $ +.Dt GETSERVENT 3 +.Os +.Sh NAME +.Nm getservent , +.Nm getservent_r , +.Nm getservbyport , +.Nm getservbyport_r , +.Nm getservbyname , +.Nm getservbyname_r , +.Nm setservent , +.Nm setservent_r , +.Nm endservent , +.Nm endservent_r +.Nd get service entry +.Sh SYNOPSIS +.In netdb.h +.Ft struct servent * +.Fn getservent "void" +.Ft int +.Fn getservent_r "struct servent *servent" "struct servent_data *servent_data" +.Ft struct servent * +.Fn getservbyname "const char *name" "const char *proto" +.Ft int +.Fn getservbyname_r "const char *name" "const char *proto" "struct servent *servent" "struct servent_data *servent_data" +.Ft struct servent * +.Fn getservbyport "int port" "const char *proto" +.Ft int +.Fn getservbyport_r "int port" "const char *proto" "struct servent *servent" "struct servent_data *servent_data" +.Ft void +.Fn setservent "int stayopen" +.Ft void +.Fn setservent_r "int stayopen" "struct servent_data *servent_data" +.Ft void +.Fn endservent "void" +.Ft void +.Fn endservent_r "struct servent_data *servent_data" +.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 database, +.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 alternate names for the service. +.It Fa s_port +The port number at which the service resides. +Port numbers 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 services database 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 (specified in network byte order) +is found, or until +.Dv EOF +is encountered. +If a protocol name is also supplied (non-null), +searches must also match the protocol. +.Pp +The +.Fn getservent_r , +.Fn getservbyport_r , +.Fn getservbyname_r , +.Fn setservent_r , +and +.Fn endservent_r +functions are reentrant versions of the above functions that take a +pointer to a +.Fa servent_data +structure which is used to store state information. +The structure must be zero-filled before it is used +and should be considered opaque for the sake of portability. +.Pp +The +.Fn getservent_r , +.Fn getservbyport_r , +and +.Fn getservbyname_r +functions +also take a pointer to a +.Fa servent +structure which is used to store the results of the database lookup. +.Sh RETURN VALUES +The +.Fn getservent , +.Fn getservbyport , +and +.Fn getservbyname +functions return a pointer to a +.Fa servent +structure on success or a null pointer if end-of-file +is reached or an error occurs. +.Pp +The +.Fn getservent_r , +.Fn getservbyport_r , +and +.Fn getservbyname_r +functions return 0 on success or \-1 if end-of-file +is reached or an error occurs. +.Sh FILES +.Bl -tag -width /etc/services -compact +.It Pa /etc/services +.El +.Sh SEE ALSO +.Xr getprotoent 3 , +.Xr services 5 +.Sh STANDARDS +The +.Fn getservent , +.Fn getservbynumber , +.Fn getservbyname , +.Fn setservent , +and +.Fn endservent +functions conform to +.St -p1003.1-2004 . +.Pp +The +.Fn getservent_r , +.Fn getservbyport_r , +.Fn getservbyname_r , +.Fn setservent_r , +and +.Fn endservent_r +functions are not currently standardized. +This implementation follows the API used by HP, IBM, and Digital. +.Sh HISTORY +The +.Fn getservent , +.Fn getservbyport , +.Fn getservbyname , +.Fn setservent , +and +.Fn endservent +functions appeared in +.Bx 4.2 . +.Pp +The +.Fn getservent_r , +.Fn getservbyport_r , +.Fn getservbyname_r , +.Fn setservent_r , +and +.Fn endservent_r +functions appeared in +.Ox 3.7 . +.Sh BUGS +The non-reentrant 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/openbsd/man3/getsubopt.3 b/static/openbsd/man3/getsubopt.3 new file mode 100644 index 00000000..fee3840b --- /dev/null +++ b/static/openbsd/man3/getsubopt.3 @@ -0,0 +1,162 @@ +.\" $OpenBSD: getsubopt.3,v 1.16 2022/08/04 06:20:24 jsg 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 $Mdocdate: August 4 2022 $ +.Dt GETSUBOPT 3 +.Os +.Sh NAME +.Nm getsubopt +.Nd get sub options from an argument +.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 +.Ar name Ns = Ns Ar value , +the location referenced by +.Fa valuep +will be set to point to the start of the +.Dq 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 NUL at the end of the string if no more tokens are present. +The comma, space, or tab character ending the token just parsed, +and the equal sign separating name and value if any, are replaced +with NUL bytes in the original +.Pf * Fa optionp +input string. +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 +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("illegal sub option %s", + suboptarg); + else + error("missing sub option"); + break; + } + } + break; + } +} +.Ed +.Sh SEE ALSO +.Xr getopt 3 , +.Xr strsep 3 +.Sh STANDARDS +The +.Fn getsubopt +function conforms to +.St -p1003.1-2008 . +.Pp +Allowing space and tab characters to separate tokens +and the external variable +.Va suboptarg +are extensions to that standard. +.Sh HISTORY +The +.Fn getsubopt +function first appeared in +.Bx 4.3 Net/2 . diff --git a/static/openbsd/man3/getttyent.3 b/static/openbsd/man3/getttyent.3 new file mode 100644 index 00000000..4fbae12d --- /dev/null +++ b/static/openbsd/man3/getttyent.3 @@ -0,0 +1,179 @@ +.\" $OpenBSD: getttyent.3,v 1.12 2013/06/05 03:39:22 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt GETTTYENT 3 +.Os +.Sh NAME +.Nm getttyent , +.Nm getttynam , +.Nm setttyent , +.Nm endttyent +.Nd get ttys file entry +.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 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 -offset indent +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 */ +#define TTY_RTSCTS 0x08 /* set 'CRTSCTS' on open */ +#define TTY_SOFTCAR 0x10 /* ignore hardware carrier */ +#define TTY_MDMBUF 0x20 /* set 'MDMBUF' on open */ + int ty_status; /* flag values */ + char *ty_window; /* command for window manager */ + char *ty_comment; /* comment field */ +}; +.Ed +.Pp +The fields are as follows: +.Bl -tag -width ty_comment +.It Fa ty_name +Name of the character-special file. +.It Fa ty_getty +Name of the command invoked by +.Xr init 8 +to initialize tty line characteristics. +.It Fa ty_type +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 +.Dq 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 +Command to execute for a window system associated with the line. +.It Fa ty_comment +Any trailing comment field, with any leading hash marks +.Pq Sq \&# +or whitespace removed. +.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. +.Fn setttyent +rewinds the file if open, or opens the file if it is unopened. +.Fn endttyent +closes any open files. +.Pp +.Fn getttynam +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 +function and +.Fn endttyent +return 0 on failure or 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 gettytab 5 , +.Xr termcap 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 . +.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/openbsd/man3/getusershell.3 b/static/openbsd/man3/getusershell.3 new file mode 100644 index 00000000..6f76e2ee --- /dev/null +++ b/static/openbsd/man3/getusershell.3 @@ -0,0 +1,94 @@ +.\" $OpenBSD: getusershell.3,v 1.14 2013/06/05 03:39:22 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt GETUSERSHELL 3 +.Os +.Sh NAME +.Nm getusershell , +.Nm setusershell , +.Nm endusershell +.Nd get legal user shells +.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 legal user shell as defined by the +system manager in the file +.Pa /etc/shells . +If +.Pa /etc/shells +is unreadable or does not exist, +.Fn getusershell +behaves as if only +.Pa /bin/sh , +.Pa /bin/csh +and +.Pa /bin/ksh +were listed in the file. +.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 DIAGNOSTICS +The routine +.Fn getusershell +returns a null pointer on +.Dv EOF . +.Sh SEE ALSO +.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/openbsd/man3/getwc.3 b/static/openbsd/man3/getwc.3 new file mode 100644 index 00000000..442b49ef --- /dev/null +++ b/static/openbsd/man3/getwc.3 @@ -0,0 +1,113 @@ +.\" $OpenBSD: getwc.3,v 1.6 2017/12/01 11:18:40 schwarze Exp $ +.\" +.\" $NetBSD: getwc.3,v 1.7 2003/09/08 17:54:32 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. +.\" +.\" @(#)getc.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd $Mdocdate: December 1 2017 $ +.Dt GETWC 3 +.Os +.Sh NAME +.Nm fgetwc , +.Nm getwc , +.Nm getwchar +.Nd get next wide character from input stream +.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 void +.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 getc 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 . diff --git a/static/openbsd/man3/glob.3 b/static/openbsd/man3/glob.3 new file mode 100644 index 00000000..a855db5e --- /dev/null +++ b/static/openbsd/man3/glob.3 @@ -0,0 +1,499 @@ +.\" $OpenBSD: glob.3,v 1.39 2022/09/11 06:38:10 jmc 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt GLOB 3 +.Os +.Sh NAME +.Nm glob , +.Nm globfree +.Nd generate pathnames matching a pattern +.Sh SYNOPSIS +.In glob.h +.Ft int +.Fn glob "const char *pattern" "int flags" "const int (*errfunc)(const char *, int)" "glob_t *pglob" +.Ft void +.Fn globfree "glob_t *pglob" +.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 +.In glob.h +defines the structure type +.Vt 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. +.Fn glob +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 number of matched pathnames is stored in the +.Fa gl_pathc +field, and a pointer to a list of pointers to pathnames in 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 OR of any of the following values defined in +.In 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 +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 +null pointers, +followed by +.Fa gl_pathc +pathname pointers, followed by a 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 the number of total pathnames set to 1, and the number of matched +pathnames set to 0. +.It Dv GLOB_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 GLOB_NOESCAPE +flag is set, a backslash character is treated as an ordinary character. +.It Dv GLOB_NOSORT +By default, the pathnames are sorted in ascending 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_ALTDIRFUNC +.It Dv GLOB_ALTDIRFUNC +The following additional fields in the +.Fa pglob +structure have been +initialized with alternate functions for +.Fn 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 *); + struct dirent *(*gl_readdir)(void *); + void (*gl_closedir)(void *); + int (*gl_lstat)(const char *, struct stat *); + int (*gl_stat)(const char *, struct stat *); +.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. +.Xr ( csh 1 +does the same thing to ease typing of +.Xr find 1 +patterns.) +.It Dv GLOB_KEEPSTAT +Retain a copy of the +.Xr stat 2 +information retrieved for matching paths in the +.Fa gl_statv +array: +.Bd -literal -offset indent +struct stat **gl_statv; +.Ed +.Pp +This option may be used to avoid +.Xr lstat 2 +lookups in cases where they are expensive. +.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_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 +.Ql * , +.Ql \&? , +or +.Ql \&[ . +.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_QUOTE +This option has no effect and is included for backwards +compatibility with older sources. +.It Dv GLOB_TILDE +Expand patterns that start with +.Ql ~ +to user name home directories. +.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 2048, 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 +.Ql */../*/.. . +.El +.Pp +If, during the search, a directory is encountered that cannot be opened +or read and +.Fa errfunc +is non-null, +.Fn glob +calls +.Fn (*errfunc) path errno . +This may be unintuitive: a pattern like +.Dq */Makefile +will try to +.Xr stat 2 +.Dq foo/Makefile +even if +.Dq 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 . +.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 +.Ql * , +.Ql \&? , +or +.Ql \&[ , +cleared if not. +.It Fa gl_pathv +Contains a pointer to a null-terminated list of matched pathnames. +However, if +.Fa gl_pathc +is zero, the contents of +.Fa gl_pathv +are undefined. +.It Fa gl_statv +If the +.Dv GLOB_KEEPSTAT +flag was set, +.Fa gl_statv +contains a pointer to a null-terminated list of matched +.Xr stat 2 +objects corresponding to the paths in +.Fa gl_pathc . +.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_NOCHECK +.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 or more +patterns were matched. +.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 did not match a pathname and +.Dv GLOB_NOCHECK +was not set. +.It Dv GLOB_NOSYS +The requested function is not supported by this version of +.Fn glob . +.El +.Pp +The arguments +.Fa pglob\->gl_pathc +and +.Fa pglob\->gl_pathv +are still set as specified above. +.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 ERRORS +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 . +.Sh SEE ALSO +.Xr sh 1 , +.Xr fnmatch 3 , +.Xr regex 3 , +.Xr glob 7 +.Sh STANDARDS +The +.Fn glob +function is expected to conform to +.St -p1003.2 +and +.St -xpg4.2 . +Note, however, that the flags +.Dv GLOB_ALTDIRFUNC , +.Dv GLOB_BRACE , +.Dv GLOB_KEEPSTAT , +.Dv GLOB_MAGCHAR , +.Dv GLOB_NOMAGIC , +.Dv GLOB_QUOTE , +.Dv GLOB_TILDE , +and +.Dv GLOB_LIMIT +and the fields +.Fa gl_matchc , +.Fa gl_statv +and +.Fa gl_flags +should not be used by applications striving for strict standards conformance. +.Sh HISTORY +A stand-alone program, +.Pa /etc/glob , +first appeared in +.At v1 . +In PWB/UNIX 1.0 this functionality was incorporated into the shell itself. +.Pp +The +.Fn glob +and +.Fn globfree +functions in their current form first appeared in the C library of +.Bx 4.3 Reno . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_COLLATE +.Xr locale 1 +category can affect the sort order; see CAVEATS in +.Xr setlocale 3 +for details. +.Sh BUGS +Patterns longer than +.Dv PATH_MAX +may cause unchecked errors. diff --git a/static/openbsd/man3/hash.3 b/static/openbsd/man3/hash.3 new file mode 100644 index 00000000..c4246a67 --- /dev/null +++ b/static/openbsd/man3/hash.3 @@ -0,0 +1,160 @@ +.\" $OpenBSD: hash.3,v 1.21 2022/03/31 17:27:15 naddy Exp $ +.\" $NetBSD: hash.3,v 1.6 1996/05/03 21:26:50 cgd Exp $ +.\" +.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. +.\" +.\" 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 $Mdocdate: March 31 2022 $ +.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 +.Fn dbopen +routine 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 +include file as follows: +.Bd -literal -offset indent +typedef struct { + unsigned int bsize; + unsigned int ffactor; + unsigned int nelem; + unsigned int cachesize; + u_int32_t (*hash)(const void *, size_t); + int lorder; +} HASHINFO; +.Ed +.Pp +The elements of this structure are as follows: +.Bl -tag -width XXXXXX -offset indent +.It Fa bsize +.Fa bsize +defines the hash table bucket size, and is, by default, +the block size of the underlying filesystem. +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 the same as +.Fa bsize . +.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 , ffactor , 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 ndbm 3 +are provided, although 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 recno 3 +.Rs +.%T "Dynamic Hash Tables" +.%A Per-Ake Larson +.%J Communications of the ACM +.%D April 1988 +.Re +.Rs +.%T "A New Hash Package for UNIX" +.%A Margo Seltzer +.%J USENIX Proceedings +.%D Winter 1991 +.Re +.Sh BUGS +Only big and little endian byte order is supported. diff --git a/static/openbsd/man3/hcreate.3 b/static/openbsd/man3/hcreate.3 new file mode 100644 index 00000000..90bde199 --- /dev/null +++ b/static/openbsd/man3/hcreate.3 @@ -0,0 +1,234 @@ +.\" $OpenBSD: hcreate.3,v 1.8 2018/01/30 11:37:58 jmc Exp $ +.\" $NetBSD: hcreate.3,v 1.8 2010/05/01 06:18:03 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 $Mdocdate: January 30 2018 $ +.Dt HCREATE 3 +.Os +.Sh NAME +.Nm hcreate , +.Nm hdestroy , +.Nm hsearch +.Nd manage hash search table +.Sh SYNOPSIS +.In search.h +.Ft int +.Fn hcreate "size_t nel" +.Ft void +.Fn hdestroy "void" +.Ft ENTRY * +.Fn hsearch "ENTRY item" "ACTION action" +.Sh DESCRIPTION +The +.Fn hcreate , +.Fn hdestroy , +and +.Fn hsearch +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 +Note that the comparison +.Fa key +must be allocated using +.Xr malloc 3 +or +.Xr calloc 3 +if action is +.Dv ENTER +and +.Fn hdestroy +will be called. +This is because +.Fn hdestroy +will call +.Xr free 3 +for each comparison +.Fa key +(but not +.Fa data ) . +Typically the comparison +.Fa key +is allocated by using +.Xr strdup 3 . +.Sh RETURN VALUES +If successful, the +.Fn hcreate +function returns a non-zero value. +Otherwise, a value of 0 is returned and +.Va errno +is set to indicate the error. +.Pp +If successful, the +.Fn hsearch +function returns a pointer to a 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. +.Sh ERRORS +The +.Fn hcreate +and +.Fn hsearch +functions will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory is available. +.El +.Sh SEE ALSO +.Xr bsearch 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 . +.Sh CAVEATS +At least the following limitations can be mentioned: +.Bl -bullet +.It +The interface permits the use of only one hash table at a time. +.It +Individual hash table entries can be added, but not deleted. +.It +The standard is indecipherable about the +internal memory usage of the functions, +mentioning only that +.Do +.Fn hcreate +and +.Fn hsearch +functions may use +.Fn malloc +to allocate space +.Dc . +This limits the portability of the functions, +given that other implementations may not +.Xr free 3 +the buffer pointed by +.Fa key . +.El diff --git a/static/openbsd/man3/history.3 b/static/openbsd/man3/history.3 new file mode 100644 index 00000000..ed0cb9f8 --- /dev/null +++ b/static/openbsd/man3/history.3 @@ -0,0 +1,640 @@ +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Information Network Services +.\" Case Western Reserve University +.\" chet@ins.CWRU.Edu +.\" +.\" Last Change: Thu Jan 31 16:08:07 EST 2002 +.\" +.TH HISTORY 3 "2002 January 31" "GNU History 4.3" +.\" +.\" 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-2002 by the Free Software Foundation, Inc. +.if n The GNU History Library is Copyright (C) 1989-2002 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" +.PP +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 +.PP +An event designator is a reference to a command line entry 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 line 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 starting with +.IR string . +.TP +.B !?\fIstring\fR\fB[?]\fR +Refer to the most recent command containing +.IR string . +The trailing \fB?\fP may be omitted if +.I string +is followed immediately by a newline. +.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/\fIstring1\fP/\fIstring2\fP/'' +(see \fBModifiers\fP below). +.TP +.B !# +The entire command line typed so far. +.PD +.SS Word Designators +.PP +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 argument. +.TP +.B % +The word matched by the most recent `?\fIstring\fR?' search. +.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. +.PD +.PP +If a word designator is supplied without an event specification, the +previous command is used as the event. +.SS Modifiers +.PP +After the optional word designator, there may appear a sequence of +one or more of the following modifiers, each preceded by a `:'. +.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. +.TP +.B s/\fIold\fP/\fInew\fP/ +Substitute +.I new +for the first occurrence of +.I old +in the event line. Any delimiter can be used 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. +.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. +.PD +.SH "PROGRAMMING WITH HISTORY FUNCTIONS" +This section describes how to use the History library in other programs. +.SS Introduction to History +.PP +The 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 +If the programmer desires, he can 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 +.PP +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; + 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" +.PP +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. + +.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. + +.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 you can dispose of the 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. + +.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, starting from +\fBhistory_base\fP. +If there is no entry there, or if \fIoffset\fP +is greater than the history length, return a \fBNULL\fP pointer. + +.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" +Move the current history offset forward to the next history entry, and +return the a pointer to that entry. If there is no next entry, 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 ocurred 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 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, single-quoted words are not scanned for the history expansion +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@ins.CWRU.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@ins.CWRU.Edu . diff --git a/static/openbsd/man3/htobe64.3 b/static/openbsd/man3/htobe64.3 new file mode 100644 index 00000000..e41c9124 --- /dev/null +++ b/static/openbsd/man3/htobe64.3 @@ -0,0 +1,164 @@ +.\" $OpenBSD: htobe64.3,v 1.2 2024/08/03 23:06:56 guenther 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 $Mdocdate: August 3 2024 $ +.Dt HTOBE64 3 +.Os +.Sh NAME +.Nm htobe64 , +.Nm htobe32 , +.Nm htobe16 , +.Nm be64toh , +.Nm be32toh , +.Nm be16toh , +.Nm betoh64 , +.Nm betoh32 , +.Nm betoh16 , +.Nm htole64 , +.Nm htole32 , +.Nm htole16 , +.Nm le64toh , +.Nm le32toh , +.Nm le16toh , +.Nm letoh64 , +.Nm letoh32 , +.Nm letoh16 , +.Nm swap64 , +.Nm swap32 , +.Nm swap16 +.Nd convert values between different byte orderings +.Sh SYNOPSIS +.In endian.h +.Ft uint64_t +.Fn htobe64 "uint64_t host64" +.Ft uint32_t +.Fn htobe32 "uint32_t host32" +.Ft uint16_t +.Fn htobe16 "uint16_t host16" +.Ft uint64_t +.Fn be64toh "uint64_t big64" +.Ft uint32_t +.Fn be32toh "uint32_t big32" +.Ft uint16_t +.Fn be16toh "uint16_t big16" +.Ft uint64_t +.Fn betoh64 "uint64_t big64" +.Ft uint32_t +.Fn betoh32 "uint32_t big32" +.Ft uint16_t +.Fn betoh16 "uint16_t big16" +.Ft uint64_t +.Fn htole64 "uint64_t host64" +.Ft uint32_t +.Fn htole32 "uint32_t host32" +.Ft uint16_t +.Fn htole16 "uint16_t host16" +.Ft uint64_t +.Fn letoh64 "uint64_t little64" +.Ft uint64_t +.Fn le64toh "uint64_t little64" +.Ft uint32_t +.Fn le32toh "uint32_t little32" +.Ft uint16_t +.Fn le16toh "uint16_t little16" +.Ft uint32_t +.Fn letoh32 "uint32_t little32" +.Ft uint16_t +.Fn letoh16 "uint16_t little16" +.Ft uint64_t +.Fn swap64 "uint64_t val64" +.Ft uint32_t +.Fn swap32 "uint32_t val32" +.Ft uint16_t +.Fn swap16 "uint16_t val16" +.Sh DESCRIPTION +These routines convert 16, 32 and 64-bit quantities between different +byte orderings. +The +.Dq swap +functions reverse the byte ordering of +the given quantity; the others convert either from/to the native +byte order used by the host to/from either little- or big-endian (a.k.a +network) order. +.Pp +Apart from the swap functions, +the names containing +.Dq be +convert between host and big-endian (most significant byte first) order +of the given quantity, while the names containing +.Dq le +convert between host and little-endian (least significant byte first) order +of the given quantity. +.Pp +All these functions use the numbers +16, 32, or 64 for specifying the bitwidth of the quantities they operate on. +Currently all supported architectures are either big- or little-endian +so either the +.Dq be +or +.Dq le +variants are implemented as null macros. +.Sh SEE ALSO +.Xr htonl 3 +.Sh STANDARDS +The +.Fn htobe64 , +.Fn htobe32 , +.Fn htobe16 , +.Fn be64toh , +.Fn be32toh , +.Fn be16toh , +.Fn htole64 , +.Fn htole32 , +.Fn htole16 , +.Fn le64toh , +.Fn le32toh , +and +.Fn le16toh +functions conform to +.St -p1003.1-2024 . +The other functions are extensions that should not be used +when portability is required. +.Sh HISTORY +The +.Nm swap{size} +and +.Nm {src-order}to{dst-order}{size} +functions appeared in +.Bx 4.2 . +The +.Nm {src-order}{size}to{dst-order} +functions appeared in +.Ox 5.6 . +.Sh BUGS +The perceived antagonism between +.Sq host +and +.Sq network +byte order does not allow PDP-11 users to sleep soundly at night. diff --git a/static/openbsd/man3/htonl.3 b/static/openbsd/man3/htonl.3 new file mode 100644 index 00000000..65fa9a53 --- /dev/null +++ b/static/openbsd/man3/htonl.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: htonl.3,v 1.6 2022/09/11 06:38:10 jmc 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 $Mdocdate: September 11 2022 $ +.Dt HTONL 3 +.Os +.Sh NAME +.Nm htonl , +.Nm htons , +.Nm ntohl , +.Nm ntohs +.Nd convert values between host and network byte orderings +.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 different +byte orderings. +.Pp +The +.Fn htonl +and +.Fn htons +functions convert quantities from host to network byte order while the +.Fn ntohl +and +.Fn ntohs +functions convert in the other direction. +.Pp +The last letter +.Pf ( Sq s +or +.Sq l ) +is a mnemonic +for the traditional names for such quantities, +short and long, respectively. +Today, the C concept of +.Vt short +and +.Vt long +integers need not coincide with this traditional misunderstanding. +On machines which have a byte order which is the same as the network +order, routines are defined as null macros. +.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 gethostbyname 3 , +.Xr getservent 3 , +.Xr htobe64 3 +.Sh STANDARDS +The +.Fn htonl , +.Fn htons , +.Fn ntohl , +and +.Fn ntohs +functions conform to +.St -p1003.1 . +.Sh HISTORY +These functions appeared in +.Bx 4.2 . +.Sh BUGS +On the alpha, amd64, i386, and some mips and arm architectures, +bytes are handled backwards from most everyone else in the world. +This is not expected to be fixed in the near future. diff --git a/static/openbsd/man3/hypot.3 b/static/openbsd/man3/hypot.3 new file mode 100644 index 00000000..a134a0e4 --- /dev/null +++ b/static/openbsd/man3/hypot.3 @@ -0,0 +1,124 @@ +.\" $OpenBSD: hypot.3,v 1.27 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt HYPOT 3 +.Os +.Sh NAME +.Nm hypot , +.Nm hypotf , +.Nm hypotl , +.Nm cabs , +.Nm cabsf , +.Nm cabsl +.Nd Euclidean distance and complex absolute value functions +.Sh SYNOPSIS +.Lb libm +.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 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" +.Sh DESCRIPTION +The +.Fn hypot , +.Fn hypotf +and +.Fn hypotl +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 "infinity" "v" No = Fn hypot "v" "infinity" No = +infinity +for all +.Fa v , +including NaN. +.Pp +The +.Fn cabs , +.Fn cabsf +and +.Fn cabsl +functions return the absolute value of the complex number +.Fa z . +.Sh ERRORS (due to Roundoff, etc.) +Below 0.97 +.Em ulps . +Consequently +.Fn hypot "5.0" "12.0" No = 13.0 +exactly; +in general, hypot and cabs return an integer whenever an +integer might be expected. +.Sh NOTES +As might be expected, +.Fn hypot "v" "NaN" +and +.Fn hypot "NaN" "v" +are NaN for all +.Em finite +.Fa v . +Programmers might be surprised at first to discover that +.Fn hypot "\(+-infinity" "NaN" No = +infinity . +This is intentional; it happens because +.Fn hypot "infinity" "v" No = +infinity +for +.Em all +.Fa v , +finite or infinite. +Hence +.Fn hypot "infinity" "v" +is independent of +.Fa v . +The IEEE NaN is designed to disappear +when it turns out to be irrelevant, as it does in +.Fn hypot "infinity" "NaN" . +.Sh SEE ALSO +.Xr fpclassify 3 , +.Xr sqrt 3 +.Sh HISTORY +A +.Fn hypot +function first appeared in +.At v2 , +and +.Fn cabs +in +.At v7 . diff --git a/static/openbsd/man3/i2a_ASN1_STRING.3 b/static/openbsd/man3/i2a_ASN1_STRING.3 new file mode 100644 index 00000000..c16259e5 --- /dev/null +++ b/static/openbsd/man3/i2a_ASN1_STRING.3 @@ -0,0 +1,256 @@ +.\" $OpenBSD: i2a_ASN1_STRING.3,v 1.6 2025/06/08 22:40:30 schwarze Exp $ +.\" +.\" Copyright (c) 2019, 2021 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 $Mdocdate: June 8 2025 $ +.Dt I2A_ASN1_STRING 3 +.Os +.Sh NAME +.Nm i2a_ASN1_STRING , +.Nm i2a_ASN1_INTEGER , +.Nm i2a_ASN1_ENUMERATED , +.Nm a2i_ASN1_STRING , +.Nm a2i_ASN1_INTEGER , +.Nm a2i_ASN1_ENUMERATED +.Nd hexadecimal dump of an ASN.1 string +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.Ft int +.Fo i2a_ASN1_STRING +.Fa "BIO *out_bio" +.Fa "const ASN1_STRING *a" +.Fa "int type" +.Fc +.Ft int +.Fo i2a_ASN1_INTEGER +.Fa "BIO *out_bio" +.Fa "const ASN1_INTEGER *a" +.Fc +.Ft int +.Fo i2a_ASN1_ENUMERATED +.Fa "BIO *out_bio" +.Fa "const i2a_ASN1_ENUMERATED *a" +.Fc +.Ft int +.Fo a2i_ASN1_STRING +.Fa "BIO *in_bio" +.Fa "ASN1_STRING *out_string" +.Fa "char *buffer" +.Fa "int size" +.Fc +.Ft int +.Fo a2i_ASN1_INTEGER +.Fa "BIO *in_bio" +.Fa "ASN1_INTEGER *out_string" +.Fa "char *buffer" +.Fa "int size" +.Fc +.Ft int +.Fo a2i_ASN1_ENUMERATED +.Fa "BIO *in_bio" +.Fa "ASN1_ENUMERATED *out_string" +.Fa "char *buffer" +.Fa "int size" +.Fc +.Sh DESCRIPTION +The functions +.Fn i2a_ASN1_STRING , +.Fn i2a_ASN1_INTEGER , +and +.Fn i2a_ASN1_ENUMERATED +write a hexadecimal representation of +.Fa a +to +.Fa out_bio . +The +.Fa type +argument is ignored. +.Pp +Each byte of +.Xr ASN1_STRING_get0_data 3 +is written as a number consisting of two upper-case hexadecimal digits. +After each group of 70 digits, a backslash and a linefeed +are inserted before the next digit. +.Pp +If the +.Xr ASN1_STRING_length 3 +of +.Fa a +is 0, instead a pair of zero digits +.Pq Qq 00 +is written by +.Fn i2a_ASN1_INTEGER +and +.Fn i2a_ASN1_ENUMERATED +and a single zero digit +.Pq Qq 0 +by +.Fn i2a_ASN1_STRING . +If +.Fa a +is a +.Dv NULL +pointer, nothing is written. +.Pp +If +.Fa a +represents a negative integer, +.Fn i2a_ASN1_INTEGER +prepends a minus sign to the output. +.Pp +The functions +.Fn a2i_ASN1_STRING , +.Fn a2i_ASN1_INTEGER , +and +.Fn a2i_ASN1_ENUMERATED +parse a hexadecimal representation of an ASN.1 string into +.Fa out_string . +Both lower-case and upper-case hexadecimal digits are accepted. +Every pair of input digits is converted into one output byte. +.Pp +On every input line, the trailing newline character and an optional +carriage return character preceding it are ignored. +The trailing newline need not be present on the last line. +If there is a backslash character before the newline character, +parsing is continued on the next input line. +.Pp +At least one pair of input digits is required by +.Fn a2i_ASN1_INTEGER +and +.Fn a2i_ASN1_ENUMERATED , +whereas +.Fn a2i_ASN1_STRING +converts empty input to an empty string. +.Pp +These functions are able to parse the output of +.Fn i2a_ASN1_ENUMERATED . +They can parse the output of +.Fn i2a_ASN1_INTEGER +unless +.Fa a +was negative, and they can parse the output of +.Fn i2a_ASN1_STRING +unless the +.Xr ASN1_STRING_length 3 +of +.Fa a +was 0. +.Pp +Parsing fails if an input line contains an odd number of input +digits or if memory allocation fails. +.Pp +These functions use the +.Fa buffer +provided by the caller and assume it is at least +.Fa size +bytes long. +It is unspecified what the buffer contains after the functions return. +.Sh RETURN VALUES +The functions +.Fn i2a_ASN1_STRING , +.Fn i2a_ASN1_INTEGER , +and +.Fn i2a_ASN1_ENUMERATED +return the number of bytes written or \-1 if +.Xr BIO_write 3 +fails. +In particular, they all return 0 when +.Fa a +is a +.Dv NULL +pointer. +.Fn i2a_ASN1_STRING +returns 1 for an empty string or an even number greater than 1 +for a string that is not empty. +.Fn i2a_ASN1_INTEGER +returns an even number greater than 1 for positive input +or an odd number greater than 2 for negative input. +.Fn i2a_ASN1_ENUMERATED +always returns a non-negative even number when successful. +.Pp +The functions +.Fn a2i_ASN1_STRING , +.Fn a2i_ASN1_INTEGER , +and +.Fn a2i_ASN1_ENUMERATED +are intended to return 1 for success or 0 for failure, but see the +.Sx BUGS +section for a number of traps. +.Sh SEE ALSO +.Xr a2i_ipadd 3 , +.Xr ASN1_STRING_length 3 , +.Xr ASN1_STRING_new 3 , +.Xr ASN1_STRING_print_ex 3 , +.Xr i2a_ASN1_OBJECT 3 , +.Xr i2s_ASN1_INTEGER 3 +.Sh HISTORY +.Fn i2a_ASN1_INTEGER +and +.Fn a2i_ASN1_INTEGER +first appeared in SSLeay 0.6.0. +.Fn i2a_ASN1_STRING +and +.Fn a2i_ASN1_STRING +first appeared in SSLeay 0.6.5. +.Fn a2i_ASN1_STRING +has been part of the public API since SSLeay 0.6.5 and +.Fn i2a_ASN1_STRING +since SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn i2a_ASN1_ENUMERATED +and +.Fn a2i_ASN1_ENUMERATED +first appeared in OpenSSL 0.9.2 and have been available since +.Ox 2.6 . +.Sh BUGS +If the first call to +.Xr BIO_gets 3 +does not return any data, even if that is caused by a fatal I/O error, +if the BIO type does not support the +.Dq gets +operation, or if it is caused by the BIO being non-blocking, +.Fn a2i_ASN1_STRING +immediately succeeds and returns an empty +.Fa out_string . +.Pp +If +.Fn BIO_gets 3 +returns a partial line, for example because the given +.Fa size +is insufficient to contain one of the input lines +or for reasons specific to the BIO type, +.Fn a2i_ASN1_STRING , +.Fn a2i_ASN1_INTEGER , +and +.Fn a2i_ASN1_ENUMERATED +may fail or silently return a truncated result. +The caller is responsible for providing a +.Fa buffer +of sufficient size to contain the longest possible input line +and for choosing a BIO of a type that only returns complete +input lines and does not perform partial reads. +.Pp +The functions +.Fn a2i_ASN1_STRING , +.Fn a2i_ASN1_INTEGER , +and +.Fn a2i_ASN1_ENUMERATED +do not support non-blocking BIOs. +Reading is terminated as soon as +.Xr BIO_gets 3 +returns a value less than 1. diff --git a/static/openbsd/man3/i2d_CMS_bio_stream.3 b/static/openbsd/man3/i2d_CMS_bio_stream.3 new file mode 100644 index 00000000..403f7c29 --- /dev/null +++ b/static/openbsd/man3/i2d_CMS_bio_stream.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: i2d_CMS_bio_stream.3,v 1.7 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2008 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt I2D_CMS_BIO_STREAM 3 +.Os +.Sh NAME +.Nm i2d_CMS_bio_stream +.Nd output CMS_ContentInfo structure in BER format +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/cms.h +.Ft int +.Fo i2d_CMS_bio_stream +.Fa "BIO *out" +.Fa "CMS_ContentInfo *cms" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn i2d_CMS_bio_stream +outputs a +.Vt CMS_ContentInfo +structure in BER format. +.Pp +It is otherwise identical to the function +.Xr SMIME_write_CMS 3 . +.Pp +This function is effectively a version of +.Xr i2d_CMS_bio 3 +supporting streaming. +.Sh RETURN VALUES +.Fn i2d_CMS_bio_stream +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr CMS_ContentInfo_new 3 , +.Xr CMS_encrypt 3 , +.Xr CMS_sign 3 , +.Xr ERR_get_error 3 , +.Xr PEM_write_bio_CMS_stream 3 , +.Xr SMIME_write_CMS 3 +.Sh HISTORY +.Fn i2d_CMS_bio_stream +first appeared in OpenSSL 1.0.0 +and has been available since +.Ox 6.7 . +.Sh BUGS +The prefix "i2d" is arguably wrong because the function outputs BER +format. diff --git a/static/openbsd/man3/i2d_PKCS7_bio_stream.3 b/static/openbsd/man3/i2d_PKCS7_bio_stream.3 new file mode 100644 index 00000000..3636960a --- /dev/null +++ b/static/openbsd/man3/i2d_PKCS7_bio_stream.3 @@ -0,0 +1,95 @@ +.\" $OpenBSD: i2d_PKCS7_bio_stream.3,v 1.12 2025/06/08 22:40:30 schwarze Exp $ +.\" OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 +.\" +.\" This file was written by Dr. Stephen Henson . +.\" Copyright (c) 2007, 2008, 2009, 2013 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt I2D_PKCS7_BIO_STREAM 3 +.Os +.Sh NAME +.Nm i2d_PKCS7_bio_stream +.Nd output PKCS7 structure in BER format +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/pkcs7.h +.Ft int +.Fo i2d_PKCS7_bio_stream +.Fa "BIO *out" +.Fa "PKCS7 *p7" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn i2d_PKCS7_bio_stream +outputs a +.Vt PKCS7 +structure in BER format. +It is otherwise identical to the function +.Xr SMIME_write_PKCS7 3 . +This function is effectively a version of +.Xr i2d_PKCS7_bio 3 +supporting streaming. +.Sh RETURN VALUES +.Fn i2d_PKCS7_bio_stream +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr BIO_new 3 , +.Xr ERR_get_error 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +.Xr PEM_write_PKCS7 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_new 3 , +.Xr SMIME_write_PKCS7 3 +.Sh HISTORY +.Fn i2d_PKCS7_bio_stream +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Sh BUGS +The prefix "i2d" is arguably wrong because the function outputs BER +format. diff --git a/static/openbsd/man3/ibuf_add.3 b/static/openbsd/man3/ibuf_add.3 new file mode 100644 index 00000000..052bea37 --- /dev/null +++ b/static/openbsd/man3/ibuf_add.3 @@ -0,0 +1,722 @@ +.\" $OpenBSD: ibuf_add.3,v 1.12 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Claudio Jeker +.\" Copyright (c) 2010 Nicholas Marriott +.\" +.\" 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 MIND, 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: June 13 2025 $ +.Dt IBUF_ADD 3 +.Os +.Sh NAME +.Nm ibuf_add , +.Nm ibuf_add_h16 , +.Nm ibuf_add_h32 , +.Nm ibuf_add_h64 , +.Nm ibuf_add_ibuf , +.Nm ibuf_add_n16 , +.Nm ibuf_add_n32 , +.Nm ibuf_add_n64 , +.Nm ibuf_add_n8 , +.Nm ibuf_add_strbuf , +.Nm ibuf_add_zero , +.Nm ibuf_close , +.Nm ibuf_data , +.Nm ibuf_dynamic , +.Nm ibuf_fd_avail , +.Nm ibuf_fd_get , +.Nm ibuf_fd_set , +.Nm ibuf_free , +.Nm ibuf_from_buffer , +.Nm ibuf_from_ibuf , +.Nm ibuf_get , +.Nm ibuf_get_ibuf , +.Nm ibuf_get_h16 , +.Nm ibuf_get_h32 , +.Nm ibuf_get_h64 , +.Nm ibuf_get_n16 , +.Nm ibuf_get_n32 , +.Nm ibuf_get_n64 , +.Nm ibuf_get_n8 , +.Nm ibuf_get_strbuf , +.Nm ibuf_get_string , +.Nm ibuf_left , +.Nm ibuf_open , +.Nm ibuf_read , +.Nm ibuf_reserve , +.Nm ibuf_rewind , +.Nm ibuf_seek , +.Nm ibuf_set , +.Nm ibuf_set_h16 , +.Nm ibuf_set_h32 , +.Nm ibuf_set_h64 , +.Nm ibuf_set_n16 , +.Nm ibuf_set_n32 , +.Nm ibuf_set_n64 , +.Nm ibuf_set_n8 , +.Nm ibuf_set_maxsize , +.Nm ibuf_size , +.Nm ibuf_skip , +.Nm ibuf_truncate , +.Nm ibuf_write , +.Nm msgbuf_clear , +.Nm msgbuf_concat , +.Nm msgbuf_free , +.Nm msgbuf_get , +.Nm msgbuf_new , +.Nm msgbuf_new_reader , +.Nm msgbuf_queuelen , +.Nm msgbuf_read , +.Nm msgbuf_write , +.Nm ibufq_concat , +.Nm ibufq_flush , +.Nm ibufq_free , +.Nm ibufq_new , +.Nm ibufq_pop , +.Nm ibufq_push , +.Nm ibufq_queuelen +.Nd save buffer API for basic IO +.Sh SYNOPSIS +.Lb libutil +.In imsg.h +.Fd #define IBUF_READ_SIZE 65535 +.Ft int +.Fn ibuf_add "struct ibuf *buf" "const void *data" "size_t len" +.Ft int +.Fn ibuf_add_h16 "struct ibuf *buf" "uint64_t value" +.Ft int +.Fn ibuf_add_h32 "struct ibuf *buf" "uint64_t value" +.Ft int +.Fn ibuf_add_h64 "struct ibuf *buf" "uint64_t value" +.Ft int +.Fn ibuf_add_ibuf "struct ibuf *buf" "const struct ibuf *from" +.Ft int +.Fn ibuf_add_n16 "struct ibuf *buf" "uint64_t value" +.Ft int +.Fn ibuf_add_n32 "struct ibuf *buf" "uint64_t value" +.Ft int +.Fn ibuf_add_n64 "struct ibuf *buf" "uint64_t value" +.Ft int +.Fn ibuf_add_n8 "struct ibuf *buf" "uint64_t value" +.Ft int +.Fn ibuf_add_strbuf "struct ibuf *buf" "const char *str" "size_t len" +.Ft int +.Fn ibuf_add_zero "struct ibuf *buf" "size_t len" +.Ft void +.Fn ibuf_close "struct msgbuf *msgbuf" "struct ibuf *buf" +.Ft void * +.Fn ibuf_data "struct ibuf *buf" +.Ft struct ibuf * +.Fn ibuf_dynamic "size_t len" "size_t max" +.Ft int +.Fn ibuf_fd_avail "struct ibuf *buf" +.Ft int +.Fn ibuf_fd_get "struct ibuf *buf" +.Ft void +.Fn ibuf_fd_set "struct ibuf *buf" "int fd" +.Ft void +.Fn ibuf_free "struct ibuf *buf" +.Ft void +.Fn ibuf_from_buffer "struct ibuf *buf" "void *data" "size_t len" +.Ft void +.Fn ibuf_from_ibuf "struct ibuf *buf" "const ibuf *from" +.Ft int +.Fn ibuf_get "struct ibuf *buf" "void *data" "size_t len" +.Ft int +.Fn ibuf_get_ibuf "struct ibuf *buf" "size_t len" "struct ibuf *new" +.Ft int +.Fn ibuf_get_h16 "struct ibuf *buf" "uint16_t *value" +.Ft int +.Fn ibuf_get_h32 "struct ibuf *buf" "uint32_t *value" +.Ft int +.Fn ibuf_get_h64 "struct ibuf *buf" "uint64_t *value" +.Ft int +.Fn ibuf_get_n16 "struct ibuf *buf" "uint16_t *value" +.Ft int +.Fn ibuf_get_n32 "struct ibuf *buf" "uint32_t *value" +.Ft int +.Fn ibuf_get_n64 "struct ibuf *buf" "uint64_t *value" +.Ft int +.Fn ibuf_get_n8 "struct ibuf *buf" "uint8_t *value" +.Ft int +.Fn ibuf_get_strbuf "struct ibuf *buf" "char *str" "size_t len" +.Ft char * +.Fn ibuf_get_string "struct ibuf *buf" "size_t len" +.Ft size_t +.Fn ibuf_left "const struct ibuf *buf" +.Ft struct ibuf * +.Fn ibuf_open "size_t len" +.Ft int +.Fn ibuf_read "int fd" "struct msgbuf *msgbuf" +.Ft void * +.Fn ibuf_reserve "struct ibuf *buf" "size_t len" +.Ft void +.Fn ibuf_rewind "struct ibuf *buf" +.Ft void * +.Fn ibuf_seek "struct ibuf *buf" "size_t pos" "size_t len" +.Ft int +.Fn ibuf_set "struct ibuf *buf" "size_t pos" "const void *data" \ + "size_t len" +.Ft int +.Fn ibuf_set_h16 "struct ibuf *buf" "size_t pos" "uint64_t value" +.Ft int +.Fn ibuf_set_h32 "struct ibuf *buf" "size_t pos" "uint64_t value" +.Ft int +.Fn ibuf_set_h64 "struct ibuf *buf" "size_t pos" "uint64_t value" +.Ft int +.Fn ibuf_set_n16 "struct ibuf *buf" "size_t pos" "uint64_t value" +.Ft int +.Fn ibuf_set_n32 "struct ibuf *buf" "size_t pos" "uint64_t value" +.Ft int +.Fn ibuf_set_n64 "struct ibuf *buf" "size_t pos" "uint64_t value" +.Ft int +.Fn ibuf_set_n8 "struct ibuf *buf" "size_t pos" "uint64_t value" +.Ft int +.Fn ibuf_set_maxsize "struct ibuf *buf" "size_t max" +.Ft size_t +.Fn ibuf_size "const struct ibuf *buf" +.Ft int +.Fn ibuf_skip "struct ibuf *buf" "size_t len" +.Ft int +.Fn ibuf_truncate "struct ibuf *buf" "size_t len" +.Ft int +.Fn ibuf_write "int fd" "struct msgbuf *msgbuf" +.Ft void +.Fn msgbuf_clear "struct msgbuf *msgbuf" +.Ft void +.Fn msgbuf_concat "struct msgbuf *msgbuf" "struct ibufqueue *from" +.Ft void +.Fn msgbuf_free "struct msgbuf *msgbuf" +.Ft struct ibuf * +.Fn msgbuf_get "struct msgbuf *msgbuf" +.Ft struct msgbuf * +.Fn msgbuf_new void +.Ft struct msgbuf * +.Fn msgbuf_new_reader "size_t hdrsz" \ + "struct ibuf *(*readhdr)(struct ibuf *, void *, int *)" "void *arg" +.Ft uint32_t +.Fn msgbuf_queuelen "struct msgbuf *msgbuf" +.Ft int +.Fn msgbuf_read "int fd" "struct msgbuf *msgbuf" +.Ft int +.Fn msgbuf_write "int fd" "struct msgbuf *msgbuf" +.Ft void +.Fn ibufq_concat "struct ibufqueue *to" "struct ibufqueue *from" +.Ft void +.Fn ibufq_flush "struct ibufqueue *bufq" +.Ft void +.Fn ibufq_free "struct ibufqueue *bufq" +.Ft struct ibufqueue * +.Fn ibufq_new void +.Ft struct ibuf * +.Fn ibufq_pop "struct ibufqueue *bufq" +.Ft void +.Fn ibufq_push "struct ibufqueue *bufq" "struct ibuf *buf" +.Ft uint32_t +.Fn ibufq_queuelen "struct ibufqueue *bufq" +.Sh DESCRIPTION +The ibuf API defines functions to manipulate buffers, used for example to +construct imsgs with +.Xr imsg_create 3 . +A +.Vt struct ibuf +is a single buffer. +It has a maximum size, a read and a write position. +Buffers should be either constructed with the various +.Fn ibuf_add +and +.Fn ibuf_set +functions or consumed with the various +.Fn ibuf_get +functions. +A +.Vt struct msgbuf +is used to queue the output buffers for transmission. +.Pp +.Fn ibuf_add +appends a block of data to +.Fa buf . +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_add_h16 , +.Fn ibuf_add_h32 , +and +.Fn ibuf_add_h64 +add a 2-byte, 4-byte, and 8-byte +.Fa value +to +.Fa buf +in host byte order. +This function checks +.Fa value +to not overflow. +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_add_ibuf +appends the buffer +.Fa from +to +.Fa buf . +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_add_n8 , +.Fn ibuf_add_n16 , +.Fn ibuf_add_n32 , +and +.Fn ibuf_add_n64 +add a 1-byte, 2-byte, 4-byte, and 8-byte +.Fa value +to +.Fa buf +in network byte order. +This function checks +.Fa value +to not overflow. +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_add_strbuf +appends a fixed-size buffer containing a string, +zero-padded to +.Fa len , +which must be large enough to allow at least one NUL. +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_add_zero +appends a block of zeros to +.Fa buf . +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_close +appends +.Fa buf +to +.Fa msgbuf +ready to be sent. +.Pp +.Fn ibuf_data +returns the pointer to the internal buffer. +This function should only be used together with +.Fn ibuf_size +to process a previously generated buffer. +.Pp +.Fn ibuf_dynamic +allocates a resizeable buffer of initial length +.Fa len +and maximum size +.Fa max . +Buffers allocated with +.Fn ibuf_dynamic +are automatically grown if necessary when data is added. +.Pp +.Fn ibuf_fd_avail , +.Fn ibuf_fd_get +and +.Fn ibuf_fd_set +are functions to check, get and set the file descriptor assigned to +.Fa buf . +After calling +.Fn ibuf_fd_set +the file descriptor is part of the +.Fa buf +and will be transmitted or closed by the ibuf API. +Any previously set file descriptor will be closed before assigning a +new descriptor. +.Fn ibuf_fd_get +returns the file descriptor and passes the responsibility to track the +descriptor back to the program. +.Fn ibuf_fd_avail +returns true if there is a file descriptor set on +.Fa buf . +.Pp +.Fn ibuf_free +frees +.Fa buf +and any associated storage, and closes any file descriptor set with +.Fn ibuf_fd_set . +If +.Fa buf +is a NULL pointer, no action occurs. +.Pp +.Fn ibuf_from_buffer +initializes the passed +.Fa buf +to point at +.Fa data +and spanning +.Fa len +bytes. +The returned buffer can be read using the various +.Fn ibuf_get +functions. +.Fn ibuf_from_ibuf +duplicates the +.Fa from +ibuf into +.Fa buf +without modifying +.Fa from . +This allows safely peeking into an ibuf without consuming data. +.Pp +.Fn ibuf_get +consumes a block of data from +.Fa buf +spanning +.Fa len +bytes. +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_get_ibuf +consumes +.Fa len +bytes from the buffer +.Fa buf +and returns it in +.Fa new +covering this region. +The data in this buffer is only valid as long as +.Fa buf +remains valid. +There is no need to deallocate +.Fa new +using +.Fn ibuf_free . +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_get_h16 , +.Fn ibuf_get_h32 , +and +.Fn ibuf_get_h64 +get a 2-byte, 4-byte, and 8-byte +.Fa value +from +.Fa buf +without altering byte order. +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_get_n8 , +.Fn ibuf_get_n16 , +.Fn ibuf_get_n32 , +and +.Fn ibuf_get_n64 +get a 1-byte, 2-byte, 4-byte, and 8-byte +.Fa value +from +.Fa buf +converting the value from network to host byte order. +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_get_strbuf +copies +.Fa len +bytes from the buffer +.Fa buf +into +.Fa str , +ensuring that it is NUL-terminated. +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_get_string +consumes +.Fa len +bytes from the buffer +.Fa buf +and returns the result of passing the bytes and len to +.Xr strndup 3 . +The returned pointer should be passed to +.Xr free 3 +when it is no longer needed. +On error NULL is returned. +.Pp +The +.Fn ibuf_open +function allocates a fixed-length buffer. +The buffer may not be resized and may contain a maximum of +.Fa len +bytes. +On success +.Fn ibuf_open +returns a pointer to the buffer; on failure it returns NULL. +.Pp +The +.Fn ibuf_read +routine receives pending messages using +.Xr read 2 . +It calls the +.Fn readhdr +callback to obtain a +.Vt struct ibuf +of the appropriate size. +It returns 1 on success, 0 if the connection was closed and \-1 on error +and the global variable errno is set to indicate the error. +The errors +.Er EINTR +and +.Er EAGAIN +are treated as follows: +.Er EINTR +will automatically retry the read operation while +.Er EAGAIN +will be ignored with a 1 return. +The application will then retry the operation at a later stage. +.Pp +.Fn ibuf_reserve +is used to reserve +.Fa len +bytes in +.Fa buf . +A pointer to the start of the reserved space is returned, or NULL on error. +.Pp +.Fn ibuf_rewind +resets the read offset to the start of the buffer. +.Pp +.Fn ibuf_seek +returns a pointer to the part of the buffer at offset +.Fa pos +and of extent +.Fa len . +NULL is returned if the requested range is outside the part of the buffer +in use. +.Pp +.Fn ibuf_set +replaces a part of +.Fa buf +at offset +.Fa pos +with the +.Fa data +of extent +.Fa len . +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_set_h16 , +.Fn ibuf_set_h32 +and +.Fn ibuf_set_h64 +replace a 2-byte, 4-byte or 8-byte +.Fa value +at offset +.Fa pos +in the buffer +.Fa buf +in host byte order. +This function checks +.Fa value +to not overflow. +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_set_n8 , +.Fn ibuf_set_n16 , +.Fn ibuf_set_n32 +and +.Fn ibuf_set_n64 +replace a 1-byte, 2-byte, 4-byte or 8-byte +.Fa value +at offset +.Fa pos +in the buffer +.Fa buf +in network byte order. +This function checks +.Fa value +to not overflow. +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_set_maxsize +reduces the maximum payload of +.Fa buf +to +.Fa max . +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_size +and +.Fn ibuf_left +are functions which return the total bytes used and available in +.Fa buf , +respectively. +.Pp +.Fn ibuf_skip +advances the read position in +.Fa buf +by +.Fa len +bytes. +0 is returned on success and \-1 on failure. +.Pp +.Fn ibuf_truncate +truncates the buffer to +.Fa len +bytes if necessary zero extending the buffer. +0 is returned on success and \-1 on failure. +.Pp +The +.Fn ibuf_write +routine transmits as many pending buffers as possible from +.Fa msgbuf +using +.Xr writev 2 . +It returns 0 if it succeeds, -1 on error and the global variable +.Va errno +is set to indicate the error. +The errors +.Er EINTR , +.Er EAGAIN , +and +.Er ENOBUFS +are treated as follows: +.Er EINTR +will automatically retry the write operation while the other errors are +ignored with a 0 return. +The application will then retry the operation at a later stage. +.Pp +.Fn msgbuf_clear +empties a msgbuf, removing and discarding any queued buffers. +.Pp +.Fn msgbuf_concat +moves all queued buffers from the ibufqueue +.Fa from +to the msgbuf. +Afterwards the ibufqueue +.Fa from +is empty. +.Pp +.Fn msgbuf_free +function frees the +.Fa msgbuf +allocated by +.Fn msgbuf_new +or +.Fn msgbuf_new_reader . +.Fn msgbuf_get +returns the next pending message. +It should be called in a loop until NULL is returned. +The ibuf returned must be freed by calling +.Fa ibuf_free . +.Pp +.Fn msgbuf_new +allocates a new message buffer structure which can be used with +.Fn ibuf_write +or +.Fn msbuf_write . +On error NULL is returned. +.Pp +.Fn msgbuf_new_reader +allocates a new message buffer structure which can additionally be used with +.Fn ibuf_read +and +.Fn msgbuf_read . +The +.Fa hdrsz +argument defines the size of the ibuf passed to the +.Fa readhdr +callback. +The +.Fa readhdr +callback parses the header and returns a new +.Vt struct ibuf +of the size of the full message. +It can take ownership of the file descriptor passed in its +.Vt "int *" +argument. +It should return NULL on error and set the global variable +.Va errno +appropriately. +The +.Fa arg +pointer is passed to the +.Fa readhdr +callback. +On error +.Fn msgbuf_new_reader +returns NULL. +.Pp +.Fn msgbuf_queuelen +returns the number of messages queued in +.Fa msgbuf . +This function returns 0 if no messages are pending for transmission. +.Pp +The +.Fn msgbuf_read +routine receives pending messages using +.Xr recvmsg 2 and supports file descriptor passing. +The function calls the +.Fn readhdr +callback function to get the total size of message. +It returns 1 on success, 0 if the connection was closed and \-1 on error +and the global variable errno is set to indicate the error. +The errors +.Er EINTR +and +.Er EAGAIN +are treated as follows: +.Er EINTR +will automatically retry the read operation while +.Er EAGAIN +will be ignored with a 1 return. +The application will then retry the operation at a later stage. +.Pp +The +.Fn msgbuf_write +routine calls +.Xr sendmsg 2 +to transmit buffers queued in +.Fa msgbuf +and supports file descriptor passing. +It returns 0 if it succeeds, -1 on error and the global variable +.Va errno +is set to indicate the error. +The errors +.Er EINTR , +.Er EAGAIN , +and +.Er ENOBUFS +are treated as follows: +.Er EINTR +will automatically retry the write operation while the other errors are +ignored with a 0 return. +The application will then retry the operation at a later stage. +.Pp +The ibufqueue API can be used to implement additional buffer queues. +This can be useful in multithreaded applications to pass ibufs between +different threads. +.Pp +.Fn ibufq_new +allocates a new ibufqueue. +On error NULL is returned. +.Pp +.Fn ibufq_free +frees a previously allocated ibufqueue. +All queued ibufs are flushed before. +.Pp +.Fn ibufq_flush +frees any queued buffer. +.Pp +.Fn ibufq_push +and +.Fn ibufq_pop +queue and dequeue ibufs onto the ibufqueue +.Fa bufq . +.Pp +.Fn ibufq_queuelen +returns the number of buffers enqueued on +.Fa bufq . +.Pp +.Fn ibufq_concat +moves all buffers from +.Fa from +to +.Fa to . +.Sh SEE ALSO +.Xr socketpair 2 , +.Xr imsg_add 3 , +.Xr unix 4 diff --git a/static/openbsd/man3/icdb_new.3 b/static/openbsd/man3/icdb_new.3 new file mode 100644 index 00000000..9fc07bda --- /dev/null +++ b/static/openbsd/man3/icdb_new.3 @@ -0,0 +1,68 @@ +.\" $OpenBSD: icdb_new.3,v 1.2 2016/09/04 19:05:09 jmc Exp $ +.\" +.\" Copyright (c) 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 $Mdocdate: September 4 2016 $ +.Dt ICBB_NEW 3 +.Os +.Sh NAME +.Nm icdb_new , +.Nm icdb_open , +.Nm icdb_get , +.Nm icdb_lookup , +.Nm icdb_nentries , +.Nm icdb_entries , +.Nm icdb_update , +.Nm icdb_add , +.Nm icdb_rehash , +.Nm icdb_save , +.Nm icdb_close +.Nd simple database +.Sh SYNOPSIS +.In icbd.h +.Ft struct icdb * +.Fn icdb_new "uint32_t version" "uint32_t nentries" "uint32_t entrysize" +.Ft struct icdb * +.Fn icdb_open "const char *name" "int flags" "uint32_t version" +.Ft int +.Fn icdb_get "struct icdb *db" "void *entry" "uint32_t idx" +.Ft int +.Fn icdb_lookup "struct icdb *db" "int keynum" "const void *key" "void *entry" "uint32_t *idxp" +.Ft int +.Fn icdb_nentries "struct icdb *db" +.Ft const void * +.Fn icdb_entries "struct icdb *db" +.Ft int +.Fn icdb_update "struct icdb *db" "const void *entry" "int offset" +.Ft int +.Fn icdb_add "struct icdb *db" "const void *entry" +.Ft int +.Fn icdb_rehash "struct icdb *db" +.Ft int +.Fn icdb_save "struct icdb *db" "int fd" +.Ft int +.Fn icdb_close "struct icdb *db" +.Sh DESCRIPTION +These functions provide access to a simple memory mapped database format. +.Sh EXAMPLES +Look how easy it is to use. +.Sh STANDARDS +These functions are not standardized. +.Sh HISTORY +The icdb functions were introduced in +.Ox 6.0 . +.Sh AUTHORS +.An Ted Unangst Aq Mt tedu@openbsd.org diff --git a/static/openbsd/man3/if_indextoname.3 b/static/openbsd/man3/if_indextoname.3 new file mode 100644 index 00000000..9d00d66b --- /dev/null +++ b/static/openbsd/man3/if_indextoname.3 @@ -0,0 +1,143 @@ +.\" $OpenBSD: if_indextoname.3,v 1.17 2025/06/13 18:34:00 schwarze 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: @(#)rcmd.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt IF_NAMETOINDEX 3 +.Os +.Sh NAME +.Nm if_nametoindex , +.Nm if_indextoname , +.Nm if_nameindex , +.Nm if_freenameindex +.Nd convert interface index to name, and vice versa +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.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 +These functions map interface indexes to interface names (such as +.Dq lo0 ) , +and vice versa. +.Pp +The +.Fn if_nametoindex +function converts an interface name specified by the +.Fa ifname +argument to an interface index (positive integer value). +If the specified interface does not exist, 0 will be returned. +.Pp +.Fn if_indextoname +converts an interface index specified by the +.Fa ifindex +argument to an interface name. +The +.Fa ifname +argument must point to a buffer of at least +.Dv IF_NAMESIZE +bytes into which the interface name corresponding to the specified index is +returned. +.Pf ( Dv IF_NAMESIZE +is also defined in +.In net/if.h +and its value includes a terminating NUL byte at the end of the +interface name.) +This pointer is also the return value of the function. +If there is no interface corresponding to the specified index, +.Dv NULL +is returned. +.Pp +.Fn if_nameindex +returns an array of +.Vt if_nameindex +structures. +.Vt if_nameindex +is also defined in +.In net/if.h , +and is as follows: +.Bd -literal -offset indent +struct if_nameindex { + unsigned int if_index; /* 1, 2, ... */ + char *if_name; /* NUL-terminated name */ +}; +.Ed +.Pp +The end of the array of structures is indicated by a structure with +an +.Fa if_index +of 0 and an +.Fa if_name +of +.Dv NULL . +The function returns a null pointer on error. +The memory used for this array of structures along with the interface +names pointed to by the +.Fa if_name +members is obtained dynamically. +This memory is freed by the +.Fn if_freenameindex +function. +.Pp +.Fn if_freenameindex +takes a pointer that was returned by +.Fn if_nameindex +as argument +.Pq Fa ptr , +and it reclaims the region allocated. +.Sh DIAGNOSTICS +.Fn if_nametoindex +returns 0 on error, positive integer on success. +.Fn if_indextoname +and +.Fn if_nameindex +return +.Dv NULL +on errors. +.Sh SEE ALSO +.Xr getifaddrs 3 , +.Xr netintro 4 +.Sh STANDARDS +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A J. McCann +.%A W. Stevens +.%D February 2003 +.%R RFC 3493 +.%T Basic Socket Interface Extensions for IPv6 +.Re diff --git a/static/openbsd/man3/ilogb.3 b/static/openbsd/man3/ilogb.3 new file mode 100644 index 00000000..0fa17b48 --- /dev/null +++ b/static/openbsd/man3/ilogb.3 @@ -0,0 +1,88 @@ +.\" $OpenBSD: ilogb.3,v 1.9 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ILOGB 3 +.Os +.Sh NAME +.Nm ilogb , +.Nm ilogbf , +.Nm ilogbl +.Nd extract exponent +.Sh SYNOPSIS +.Lb libm +.In math.h +.Ft int +.Fn ilogb "double x" +.Ft int +.Fn ilogbf "float x" +.Ft int +.Fn ilogbl "long double x" +.Sh DESCRIPTION +.Fn ilogb +returns +.Fa x Ns 's exponent +.Fa n , +in integer format. +.Fn ilogb \(+-infinity +returns +.Dv INT_MAX , +.Fn ilogb NaN +returns +.Dv FP_ILOGBNAN +and +.Fn ilogb 0 +returns +.Dv FP_ILOGB0 . +The +.Fn ilogbf +function is a single precision version of +.Fn ilogb . +The +.Fn ilogbl +function is an extended precision version of +.Fn ilogb . +.Sh SEE ALSO +.Xr ffs 3 , +.Xr frexp 3 +.Sh STANDARDS +.St -ieee754 +.Sh HISTORY +The +.Nm ilogb , +.Nm ilogbf +and +.Nm ilogbl +functions appeared in +.Bx 4.3 , +.Nx 1.1 +and +.Ox 4.5 , +respectively. diff --git a/static/openbsd/man3/imaxabs.3 b/static/openbsd/man3/imaxabs.3 new file mode 100644 index 00000000..340be61b --- /dev/null +++ b/static/openbsd/man3/imaxabs.3 @@ -0,0 +1,70 @@ +.\" 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. +.\" +.\" $OpenBSD: imaxabs.3,v 1.8 2019/01/18 07:32:17 schwarze Exp $ +.\" +.Dd $Mdocdate: January 18 2019 $ +.Dt IMAXABS 3 +.Os +.Sh NAME +.Nm imaxabs +.Nd integer absolute value function +.Sh SYNOPSIS +.In inttypes.h +.In stdint.h +.Ft intmax_t +.Fn imaxabs "intmax_t j" +.Sh DESCRIPTION +The +.Fn imaxabs +function computes the absolute value of the intmax_t variable +.Fa j . +.Sh RETURN VALUES +The +.Fn imaxabs +function returns the absolute value. +.Sh SEE ALSO +.Xr abs 3 , +.Xr cabs 3 , +.Xr floor 3 , +.Xr hypot 3 , +.Xr labs 3 +.Sh STANDARDS +The +.Fn imaxabs +function conforms to +.St -isoC-99 . +.Sh CAVEATS +The result of applying +.Fn imaxabs +to +.Dv INTMAX_MIN +is undefined. diff --git a/static/openbsd/man3/imaxdiv.3 b/static/openbsd/man3/imaxdiv.3 new file mode 100644 index 00000000..70168acb --- /dev/null +++ b/static/openbsd/man3/imaxdiv.3 @@ -0,0 +1,65 @@ +.\" 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. +.\" +.\" $OpenBSD: imaxdiv.3,v 1.8 2022/09/11 06:38:11 jmc Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt IMAXDIV 3 +.Os +.Sh NAME +.Nm imaxdiv +.Nd return quotient and remainder from division +.Sh SYNOPSIS +.In inttypes.h +.Ft imaxdiv_t +.Fn imaxdiv "intmax_t num" "intmax_t denom" +.Sh DESCRIPTION +The +.Fn imaxdiv +function computes the value +.Fa num Ns / Ns Fa denom +and returns the quotient and remainder in a structure named +.Vt imaxdiv_t +that contains two +.Vt intmax_t +members named +.Fa quot +and +.Fa rem . +.Sh SEE ALSO +.Xr div 3 , +.Xr ldiv 3 , +.Xr lldiv 3 +.Sh STANDARDS +The +.Fn imaxdiv +function conforms to +.St -isoC-99 . diff --git a/static/openbsd/man3/imsg_init.3 b/static/openbsd/man3/imsg_init.3 new file mode 100644 index 00000000..2b91b043 --- /dev/null +++ b/static/openbsd/man3/imsg_init.3 @@ -0,0 +1,515 @@ +.\" $OpenBSD: imsg_init.3,v 1.46 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Claudio Jeker +.\" Copyright (c) 2010 Nicholas Marriott +.\" +.\" 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 MIND, 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: June 13 2025 $ +.Dt IMSG_ADD 3 +.Os +.Sh NAME +.Nm imsg_add , +.Nm imsg_close , +.Nm imsg_compose , +.Nm imsg_compose_ibuf , +.Nm imsg_composev , +.Nm imsg_create , +.Nm imsg_forward , +.Nm imsg_free , +.Nm imsg_get_buf , +.Nm imsg_get_data , +.Nm imsg_get_fd , +.Nm imsg_get_ibuf , +.Nm imsg_get_id , +.Nm imsg_get_len , +.Nm imsg_get_pid , +.Nm imsg_get_strbuf , +.Nm imsg_get_type , +.Nm imsg_ibufq_pop , +.Nm imsg_ibufq_push , +.Nm imsg_set_maxsize , +.Nm imsgbuf_allow_fdpass , +.Nm imsgbuf_clear , +.Nm imsgbuf_flush , +.Nm imsgbuf_get , +.Nm imsgbuf_init , +.Nm imsgbuf_queuelen , +.Nm imsgbuf_read , +.Nm imsgbuf_set_maxsize , +.Nm imsgbuf_write +.Nd IPC messaging functions +.Sh SYNOPSIS +.Lb libutil +.In imsg.h +.Fd #define IMSG_HEADER_SIZE sizeof(struct imsg_hdr) +.Fd #define MAX_IMSGSIZE 16384 +.Ft int +.Fn imsg_add "struct ibuf *msg" "const void *data" "size_t datalen" +.Ft void +.Fn imsg_close "struct imsgbuf *imsgbuf" "struct ibuf *msg" +.Ft int +.Fn imsg_compose "struct imsgbuf *imsgbuf" "uint32_t type" "uint32_t id" \ + "pid_t pid" "int fd" "const void *data" "size_t datalen" +.Ft int +.Fn imsg_compose_ibuf "struct imsgbuf *imsgbuf" "uint32_t type" \ + "uint32_t id" "pid_t pid" "struct ibuf *buf" +.Ft struct ibuf * +.Fn imsg_create "struct imsgbuf *imsgbuf" "uint32_t type" "uint32_t id" \ + "pid_t pid" "size_t datalen" +.Ft int +.Fn imsg_forward "struct imsgbuf *imsgbuf" "struct imsg *msg" +.Ft void +.Fn imsg_free "struct imsg *imsg" +.Ft int +.Fn imsg_get_buf "struct imsg *imsg" "void *data" "size_t len" +.Ft int +.Fn imsg_get_data "struct imsg *imsg" "void *data" "size_t len" +.Ft int +.Fn imsg_get_fd "struct imsg *imsg" +.Ft int +.Fn imsg_get_ibuf "struct imsg *imsg" "struct ibuf *ibuf" +.Ft uint32_t +.Fn imsg_get_id "struct imsg *imsg" +.Ft size_t +.Fn imsg_get_len "struct imsg *imsg" +.Ft pid_t +.Fn imsg_get_pid "struct imsg *imsg" +.Ft int +.Fn imsg_get_strbuf "struct imsg *imsg" "char *str" "size_t len" +.Ft uint32_t +.Fn imsg_get_type "struct imsg *imsg" +.Ft int +.Fn imsg_ibufq_pop "struct ibufqueue *bufq" "struct imsg *imsg" +.Ft void +.Fn imsg_ibufq_push "struct ibufqueue *bufq" "struct imsg *imsg" +.Ft int +.Fn imsg_set_maxsize "struct ibuf *msg" "size_t max" +.Ft void +.Fn imsgbuf_allow_fdpass "struct imsgbuf *imsgbuf" +.Ft void +.Fn imsgbuf_clear "struct imsgbuf *imsgbuf" +.Ft int +.Fn imsgbuf_flush "struct imsgbuf *imsgbuf" +.Ft int +.Fn imsgbuf_get "struct imsgbuf *imsgbuf" "struct imsg *imsg" +.Ft int +.Fn imsgbuf_init "struct imsgbuf *imsgbuf" "int fd" +.Ft uint32_t +.Fn imsgbuf_queuelen "struct imsgbuf *imsgbuf" +.Ft int +.Fn imsgbuf_read "struct imsgbuf *imsgbuf" +.Ft int +.Fn imsgbuf_set_maxsize "struct imsgbuf *imsgbuf" "uint32_t max" +.Ft int +.Fn imsgbuf_write "struct imsgbuf *imsgbuf" +.In sys/uio.h +.Ft int +.Fn imsg_composev "struct imsgbuf *imsgbuf" "uint32_t type" "uint32_t id" \ + "pid_t pid" "int fd" "const struct iovec *iov" "int iovcnt" +.Sh DESCRIPTION +The +.Nm imsg +functions provide a simple mechanism for communication between local processes +using sockets. +Each transmitted message is guaranteed to be presented to the receiving program +whole. +They are commonly used in privilege separated processes, where processes with +different rights are required to cooperate. +.Pp +.Fn imsgbuf_init +initializes +.Fa imsgbuf +as one side of a channel associated with +.Fa fd . +The file descriptor is used to send and receive messages, +but is not closed by any of the imsg functions. +It returns 0 if successful and -1 on failure. +.Pp +.Fn imsgbuf_allow_fdpass +enables file descriptor passing in both directions for this +.Fa imsgbuf . +.Pp +.Fn imsgbuf_set_maxsize +changes the default maximum payload size +to +.Fa max . +It returns 0 if successful and -1 on failure. +.Pp +The +.Fn imsgbuf_clear +function frees any data allocated as part of an imsgbuf. +This function does not close the file descriptor used for communication. +.Pp +The +.Fn imsgbuf_read +routine reads pending data with +.Xr recvmsg 2 +and queues it as individual messages on +.Fa imsgbuf . +It returns 1 on success, 0 if the connection is closed, or \-1 on error +and the global variable +.Va errno +is set to indicate the error. +The errors +.Er EINTR +and +.Er EAGAIN +are treated as follows. +.Er EINTR +will automatically retry the read operation while the other errors are +ignored with a 1 return. +.Pp +.Fn imsgbuf_write +writes out queued messages. +It returns 0 if it succeeds, -1 on error and the global variable +.Va errno +is set to indicate the error. +The errors +.Er EINTR , +.Er EAGAIN , +and +.Er ENOBUFS +are treated as follows. +.Er EINTR +will automatically retry the write operation while the other errors are +ignored with a 0 return. +.Pp +.Fn imsgbuf_flush +calls +.Fn imsgbuf_write +in a loop until all imsgs in the output buffer are sent. +It returns 0 if it succeeds, \-1 otherwise and the global variable +.Va errno +is set to indicate the error. +.Fn imsgbuf_flush +should not be called on non-blocking sockets since it will busy loop if the +socket is not available. +.Pp +.Fn imsgbuf_get +fills in an individual imsg pending on +.Fa imsgbuf +into the structure pointed to by +.Fa imsg . +It returns 1 on success, 0 if no messages are ready, or \-1 for an error. +Received messages are returned as a +.Em struct imsg , +which must be freed by +.Fn imsg_free +when no longer required. +.Pp +.Fn imsgbuf_queuelen +returns the number of messages ready to be sent. +This function returns 0 if no messages are pending for transmission. +.Pp +.Fn imsg_create , +.Fn imsg_add +and +.Fn imsg_close +are generic construction routines for messages that are to be sent using an +imsgbuf. +.Pp +.Fn imsg_create +creates a new message with header specified by +.Fa type , +.Fa id +and +.Fa pid . +A +.Fa pid +of zero uses the process ID returned by +.Xr getpid 2 +when +.Fa imsgbuf +was initialized. +In addition to this common imsg header, +.Fa datalen +bytes of space may be reserved for attaching to this imsg. +This space is populated using +.Fn imsg_add . +.Fn imsg_create +returns a pointer to a new message if it succeeds, NULL otherwise. +.Pp +.Fn imsg_add +appends to +.Fa msg +.Fa datalen +bytes of ancillary data pointed to by +.Fa data . +It returns +.Fa datalen +if it succeeds, otherwise +.Fa msg +is freed and \-1 is returned. +.Pp +.Fn imsg_set_maxsize +reduces the maximum payload of +.Fa msg +to +.Fa max . +The routine returns 0 if it succeeds, \-1 otherwise. +.Pp +.Fn imsg_close +completes creation of +.Fa msg +by adding it to +.Fa imsgbuf +output buffer. +.Pp +.Fn imsg_compose +is used to quickly create and queue an imsg. +It takes the same parameters as the +.Fn imsg_create , +.Fn imsg_add +and +.Fn imsg_close +routines, +except that only one ancillary data buffer can be provided. +Additionally, the file descriptor +.Fa fd +may be passed over the socket to the other process. +If +.Fa fd +is given, it is closed in the sending program after the message is sent. +A value of \-1 indicates no file descriptor should be passed. +This routine returns 1 if it succeeds, \-1 otherwise. +.Pp +.Fn imsg_composev +is similar to +.Fn imsg_compose . +It takes the same parameters, except that the ancillary data buffer is specified +by +.Fa iovec . +.Pp +.Fn imsg_compose_ibuf +is similar to +.Fn imsg_compose . +It takes the same parameters, except that the ancillary data buffer is specified +by an ibuf +.Fa buf . +This routine returns 1 if it succeeds, \-1 otherwise. +In either case the buffer +.Fa buf +is consumed by the function. +.Pp +.Fn imsg_forward +forwards a just received +.Fa msg +unaltered on +.Fa imsgbuf . +File descriptors are not forwarded by this function. +It is possible to call +.Fn imsg_forward +more than once per message. +.Pp +The accessors +.Fn imsg_get_type , +.Fn imsg_get_pid , +.Fn imsg_get_id , +and +.Fn imsg_get_len , +return the +.Fa type , +.Fa pid , +.Fa id , +and payload length used in +.Fn imsg_create +to build the +.Fa imsg . +If there is no payload +.Fn imsg_get_len +returns 0. +.Pp +.Fn imsg_get_fd +returns the file descriptor and passes the responsibility to track the +descriptor back to the program. +Unclaimed file descriptors are closed by +.Fn imsg_free . +.Pp +.Fn imsg_get_data +and +.Fn imsg_get_ibuf +are used to extract the payload of an +.Fa imsg . +.Fn imsg_get_data +can be used if the structure of the payload is known and can be extracted +in one go. +0 is returned on success and \-1 on failure. +.Fn imsg_get_ibuf +initializes the passed +.Fa ibuf +to hold the payload which can be read using +.Xr ibuf_get 3 . +The +.Fa ibuf +remains valid until +.Fn imsg_free +is called and there is no need to call +.Fn ibuf_free +on this stack based buffer. +The function returns 0 on success, \-1 otherwise. +.Pp +.Fn imsg_get_buf +and +.Fn imsg_get_strbuf +read +.Fa len +bytes from the +.Fa imsg +and copy them into +.Fa buf +or +.Fa str , +respectively. +.Fn imsg_get_strbuf +ensures that +.Fa str +is NUL-terminated. +The functions return 0 on success, \-1 otherwise. +.Pp +.Fn imsg_set_maxsize +reduces the maximum payload of +.Fa msg +to +.Fa max . +The routine returns 0 if it succeeds, \-1 otherwise. +.Pp +.Fn imsg_ibufq_pop +and +.Fn imsg_ibufq_push +allow to requeue an imsg onto the ibufqueue +.Fa bufq . +.Fn imsg_ibufq_pop +returns 1 on success, 0 if no messages are ready, or \-1 for an error. +See +.Xr ibufq_new 3 for more info. +.Pp +MAX_IMSGSIZE is defined as the maximum size of a single imsg, currently +16384 bytes. +.Sh EXAMPLES +In a typical program, a channel between two processes is created with +.Xr socketpair 2 , +and an +.Em imsgbuf +created around one file descriptor in each process: +.Bd -literal -offset indent +struct imsgbuf parent_ibuf, child_ibuf; +int imsg_fds[2]; + +if (socketpair(AF_UNIX, SOCK_STREAM, PF_UNSPEC, imsg_fds) == -1) + err(1, "socketpair"); + +switch (fork()) { +case -1: + err(1, "fork"); +case 0: + /* child */ + close(imsg_fds[0]); + if (imsgbuf_init(&child_ibuf, imsg_fds[1]) == -1) + err(1, NULL); + exit(child_main(&child_ibuf)); +} + +/* parent */ +close(imsg_fds[1]); +if (imsgbuf_init(&parent_ibuf, imsg_fds[0]) == -1) + err(1, NULL); +exit(parent_main(&parent_ibuf)); +.Ed +.Pp +Messages may then be composed and queued on the +.Em imsgbuf , +for example using the +.Fn imsg_compose +function: +.Bd -literal -offset indent +enum imsg_type { + IMSG_A_MESSAGE, + IMSG_MESSAGE2 +}; + +int +child_main(struct imsgbuf *imsgbuf) +{ + int idata; + ... + idata = 42; + imsg_compose(imsgbuf, IMSG_A_MESSAGE, + 0, 0, -1, &idata, sizeof idata); + ... +} +.Ed +.Pp +A mechanism such as +.Xr poll 2 +or the +.Xr event 3 +library is used to monitor the socket file descriptor. +When the socket is ready for writing, queued messages are transmitted with +.Fn imsgbuf_write : +.Bd -literal -offset indent + if (imsgbuf_write(imsgbuf) == -1) { + if (errno == EPIPE) + /* handle closed connection */ + else + /* handle write failure */ + } +.Ed +.Pp +And when ready for reading, messages are first received using +.Fn imsgbuf_read +and then extracted with +.Fn imsgbuf_get : +.Bd -literal -offset indent +void +dispatch_imsg(struct imsgbuf *imsgbuf) +{ + struct imsg imsg; + int n, idata; + + switch (imsgbuf_read(imsgbuf)) { + case -1: + /* handle read error */ + break; + case 0: + /* handle closed connection */ + break; + } + + for (;;) { + if ((n = imsgbuf_get(imsgbuf, &imsg)) == -1) { + /* handle read error */ + break; + } + if (n == 0) /* no more messages */ + return; + + switch (imsg_get_type(&imsg)) { + case IMSG_A_MESSAGE: + if (imsg_get_data(&imsg, &idata, + sizeof(idata)) == -1) { + /* handle corrupt message */ + } + /* handle message received */ + break; + ... + } + + imsg_free(&imsg); + } +} +.Ed +.Sh SEE ALSO +.Xr socketpair 2 , +.Xr ibuf_add 3 , +.Xr unix 4 diff --git a/static/openbsd/man3/in.3 b/static/openbsd/man3/in.3 new file mode 100644 index 00000000..4c4f2ef9 --- /dev/null +++ b/static/openbsd/man3/in.3 @@ -0,0 +1,9 @@ +.Dd July 28, 2016 +.Dt IN 3 +.Os +.Sh NAME +.Nm \&In +.Nd indexing of include macros +.Sh SYNOPSIS +.In in.h +.Fd #include diff --git a/static/openbsd/man3/inet6_opt_init.3 b/static/openbsd/man3/inet6_opt_init.3 new file mode 100644 index 00000000..87244507 --- /dev/null +++ b/static/openbsd/man3/inet6_opt_init.3 @@ -0,0 +1,328 @@ +.\" $OpenBSD: inet6_opt_init.3,v 1.9 2025/06/13 18:34:00 schwarze 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 $Mdocdate: June 13 2025 $ +.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-Hop and Destination +options. +These functions use the +formatting rules specified in Appendix B in RFC 2460, i.e. that the +largest field is placed last in the option. +The function prototypes +for these functions are all contained in the header file +.In netinet/in.h . +.\" +.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 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 +function 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 RFC 2460. +.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 to 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 RFC 2460. +.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 +RFC 3542 gives comprehensive examples in Section 23. +KAME also provides examples in the +.Pa advapitest +directory of its kit. +.\" +.Sh DIAGNOSTICS +All the functions return +\-1 +on an error. +.\" +.Sh STANDARDS +.Rs +.%A S. Deering +.%A R. Hinden +.%D December 1998 +.%R RFC 2460 +.%T Internet Protocol, Version 6 (IPv6) Specification +.Re +.Pp +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%D May 2003 +.%R RFC 3542 +.%T Advanced Sockets Application Program Interface (API) for IPv6 +.Re +.Sh HISTORY +The implementation first appeared in KAME advanced networking kit. +.\" diff --git a/static/openbsd/man3/inet6_rth_space.3 b/static/openbsd/man3/inet6_rth_space.3 new file mode 100644 index 00000000..7304266f --- /dev/null +++ b/static/openbsd/man3/inet6_rth_space.3 @@ -0,0 +1,220 @@ +.\" $OpenBSD: inet6_rth_space.3,v 1.9 2025/06/13 18:34:00 schwarze 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 $Mdocdate: June 13 2025 $ +.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 header file +.In netinet/in.h . +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. +The builder functions are described first, 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. +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. +KAME also provides examples in the advapitest directory of its kit. +.\" +.Sh DIAGNOSTICS +The +.Fn inet6_rth_space +and +.Fn inet6_rth_getaddr +functions return 0 on errors. +.Pp +The +.Fn inet6_rth_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 STANDARDS +.Rs +.%A S. Deering +.%A R. Hinden +.%D December 1998 +.%R RFC 2460 +.%T Internet Protocol, Version 6 (IPv6) Specification +.Re +.Pp +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%D May 2003 +.%R RFC 3542 +.%T Advanced Sockets Application Programming Interface (API) for IPv6 +.Re +.Sh HISTORY +The implementation first appeared in KAME advanced networking kit. diff --git a/static/openbsd/man3/inet_addr.3 b/static/openbsd/man3/inet_addr.3 new file mode 100644 index 00000000..cbb9e14f --- /dev/null +++ b/static/openbsd/man3/inet_addr.3 @@ -0,0 +1,195 @@ +.\" $OpenBSD: inet_addr.3,v 1.7 2024/03/06 07:29:37 bentley Exp $ +.\" $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem 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 $Mdocdate: March 6 2024 $ +.Dt INET_ADDR 3 +.Os +.Sh NAME +.Nm inet_aton , +.Nm inet_addr , +.Nm inet_network , +.Nm inet_ntoa +.Nd Internet Protocol version 4 (IPv4) address manipulation routines +.Sh SYNOPSIS +.In arpa/inet.h +.Ft int +.Fn inet_aton "const char *cp" "struct in_addr *addr" +.Ft in_addr_t +.Fn inet_addr "const char *cp" +.Ft in_addr_t +.Fn inet_network "const char *cp" +.Ft char * +.Fn inet_ntoa "struct in_addr in" +.Sh DESCRIPTION +The functions presented here only support IPv4 addresses. +In order to support IPv6 addresses as well, +.Xr inet_ntop 3 +and +.Xr inet_pton 3 +should be used rather than the functions presented here. +Scoped IPv6 addresses are supported via +.Xr getaddrinfo 3 +and +.Xr getnameinfo 3 . +.Pp +The routines +.Fn inet_aton , +.Fn inet_addr , +and +.Fn inet_network +interpret character strings representing +numbers expressed in the Internet standard +.Dq dot +notation. +.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 was invalid. +.Pp +The +.Fn inet_addr +and +.Fn inet_network +functions return numbers suitable for use +as Internet addresses and Internet network +numbers, respectively. +Both functions return the constant +.Dv INADDR_NONE +if the specified character string is malformed. +.Pp +The routine +.Fn inet_ntoa +takes an Internet address and returns an +ASCII string representing the address in dot notation. +.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 dot 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 +(such as AMD64 or ARM 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 rightmost 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 rightmost 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 dot notation +may be decimal, octal, or hexadecimal, as specified +in the C language (i.e., a leading 0x or 0X implies +hexadecimal; a leading 0 implies octal; +otherwise, the number is interpreted as decimal). +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr htonl 3 , +.Xr inet_lnaof 3 , +.Xr inet_net_ntop 3 , +.Xr inet_ntop 3 , +.Xr hosts 5 +.Sh STANDARDS +The +.Nm inet_addr +and +.Nm inet_ntoa +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Nm inet_addr +and +.Nm inet_network +functions appeared in +.Bx 4.2 . +The +.Nm inet_aton +and +.Nm inet_ntoa +functions appeared in +.Bx 4.3 . +.Sh BUGS +The value +.Dv INADDR_NONE +(0xffffffff) is a valid broadcast address, but +.Fn inet_addr +cannot return that value without indicating failure. +Also, +.Fn inet_addr +should have been designed to return a +.Vt struct in_addr . +The newer +.Fn inet_aton +function does not share these problems, and almost all existing code +should be modified to use +.Fn inet_aton +instead. +.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. diff --git a/static/openbsd/man3/inet_lnaof.3 b/static/openbsd/man3/inet_lnaof.3 new file mode 100644 index 00000000..6151f7fe --- /dev/null +++ b/static/openbsd/man3/inet_lnaof.3 @@ -0,0 +1,89 @@ +.\" $OpenBSD: inet_lnaof.3,v 1.4 2019/08/30 20:06:07 jmc Exp $ +.\" $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem 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 $Mdocdate: August 30 2019 $ +.Dt INET_LNAOF 3 +.Os +.Sh NAME +.Nm inet_makeaddr , +.Nm inet_netof , +.Nm inet_lnaof +.Nd routines for manipulating classful Internet Protocol version 4 (IPv4) addresses +.Sh SYNOPSIS +.In arpa/inet.h +.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_lnaof "struct in_addr in" +.Sh DESCRIPTION +As originally designed, +IP version 4 split each address into a network part and local network +address part, encoding that split into the address itself. +It is frequency-encoded; +the most-significant bit is clear in Class A addresses, +in which the high-order 8 bits are the network number. +Class B addresses use the high-order 16 bits as the network field, +and Class C addresses have a 24-bit network part. +.Pp +The routine +.Fn inet_makeaddr +takes an Internet network number and a local +network address and constructs an Internet address +from it. +.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. +.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 SEE ALSO +.Xr gethostbyname 3 , +.Xr inet_addr 3 , +.Xr inet_net_ntop 3 , +.Xr hosts 5 +.Sh HISTORY +The +.Nm inet_makeaddr , +.Nm inet_lnaof , +and +.Nm inet_netof +functions appeared in +.Bx 4.2 . diff --git a/static/openbsd/man3/inet_net_ntop.3 b/static/openbsd/man3/inet_net_ntop.3 new file mode 100644 index 00000000..4212af3b --- /dev/null +++ b/static/openbsd/man3/inet_net_ntop.3 @@ -0,0 +1,195 @@ +.\" $OpenBSD: inet_net_ntop.3,v 1.4 2022/09/11 06:38:10 jmc Exp $ +.\" $NetBSD: inet_net.3,v 1.1 1997/06/18 02:25:27 lukem 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 REGENTS OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt INET_NET_NTOP 3 +.Os +.Sh NAME +.Nm inet_net_ntop , +.Nm inet_net_pton +.Nd Internet network number manipulation routines +.Sh SYNOPSIS +.In sys/socket.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). +.Fa bits +is the number of bits in +.Fa src +that are the network number. +It returns +.Dv NULL +if a system 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. +It will be set to +.Er ENOENT +if the Internet network number was not valid). +.Pp +Caution: +The +.Fa dst +field should be zeroed before calling +.Fn inet_net_pton +as the function will only fill the number of bytes necessary to +encode the network number in network byte order. +.Pp +The only values for +.Fa af +currently supported are +.Dv AF_INET +and +.Dv AF_INET6 . +.Fa size +is the size of the result buffer +.Fa dst . +.Sh NETWORK NUMBERS (IP VERSION 4) +The external representation of Internet network numbers may be specified in +one of the following forms: +.Bd -literal -offset indent +a +a.b +a.b.c +a.b.c.d +.Ed +.Pp +Any of the above four forms may have +.Dq Li /bits +appended where +.Dq Li bits +is in the range +.Li 0-32 +and is used to explicitly specify the number of bits in the network address. +When +.Dq Li /bits +is not specified, the number of bits in the network address is calculated +as the larger of the number of bits in the class to which the address +belongs and the number of bits provided rounded up modulo 8. +Examples: +.Pp +.Bl -tag -width 10.1.2.3/24 -offset indent -compact +.It Li 10 +an 8-bit network number (class A), value +.Li 10.0.0.0 . +.It Li 192 +a 24-bit network number (class C), value +.Li 192.0.0.0 . +.It Li 10.10 +a 16-bit network number, value +.Li 10.10.0.0 . +.It Li 10.1.2 +a 24-bit network number, value +.Li 10.1.2.0 . +.It Li 10.1.2.3 +a 32-bit network number, value +.Li 10.1.2.3 . +.It Li 10.1.2.3/24 +a 24-bit network number (explicit), value +.Li 10.1.2.3 . +.El +.Pp +Note that when the number of bits is specified using +.Dq Li /bits +notation, the value of the address still includes all bits supplied +in the external representation, even those bits which are the host +part of an Internet address. +Also, unlike +.Xr inet_pton 3 +where the external representation is assumed to be a host address, the +external representation for +.Fn inet_net_pton +is assumed to be a network address. +Thus +.Dq Li 10.1 +is assumed to be +.Dq Li 10.1.0.0 +not +.Dq Li 10.0.0.1 +.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) +See +.Xr inet_pton 3 +for valid external representations of IP version 6 addresses. +A valid external representation may have +.Dq Li /bits +appended where +.Dq Li bits +is in the range +.Li 0-128 +and is used to explicitly specify the number of bits in the network address. +When +.Dq Li /bits +is not specified, 128 is used. +Note that when the number of bits is specified using +.Dq Li /bits +notation, the value of the address still includes all bits supplied +in the external representation, even those bits which are the host +part of an Internet address. +.Sh SEE ALSO +.Xr htonl 3 , +.Xr inet_pton 3 , +.Xr inet 4 , +.Xr hosts 5 +.Sh HISTORY +The +.Nm inet_net_ntop +and +.Nm inet_net_pton +functions first appeared in BIND 4.9.4. diff --git a/static/openbsd/man3/inet_ntop.3 b/static/openbsd/man3/inet_ntop.3 new file mode 100644 index 00000000..e5c1c574 --- /dev/null +++ b/static/openbsd/man3/inet_ntop.3 @@ -0,0 +1,213 @@ +.\" $OpenBSD: inet_ntop.3,v 1.6 2022/09/11 06:38:10 jmc Exp $ +.\" $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem 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 $Mdocdate: September 11 2022 $ +.Dt INET_NTOP 3 +.Os +.Sh NAME +.Nm inet_ntop , +.Nm inet_pton +.Nd convert Internet addresses between presentation and network formats +.Sh SYNOPSIS +.In sys/socket.h +.In arpa/inet.h +.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 +.Fn inet_pton +function converts a presentation format address (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 1 if the address was valid for the specified address family; +0 if the address wasn't parseable 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 function +.Fn inet_ntop +converts an address from network format to presentation format. +It returns +.Dv NULL +if a system +error occurs (in which case, +.Va errno +will have been set), or it returns a pointer to the destination string. +.Pp +All Internet addresses are returned in network +order (bytes ordered from left to right). +.Sh INTERNET ADDRESSES (IP VERSION 4) +Values must be specified using the standard dot notation: +.Bd -literal -offset indent +a.b.c.d +.Ed +.Pp +All four parts must be decimal numbers between 0 and 255, inclusive, +and are 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 +(such as AMD64 or ARM 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. +.Sh INTERNET ADDRESSES (IP VERSION 6) +In order to support scoped IPv6 addresses, +.Xr getaddrinfo 3 +and +.Xr getnameinfo 3 +are recommended rather than the functions presented here. +.Pp +The presentation format of an IPv6 address is given in RFC 4291: +.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 +.Dq \&:\&: +indicates multiple groups +of 16 bits of zeros. +The +.Dq \&:\&: +can only appear once in an +address. +The +.Dq \&:\&: +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 SEE ALSO +.Xr gethostbyname 3 , +.Xr inet_addr 3 , +.Xr inet_net_ntop 3 , +.Xr hosts 5 +.Sh STANDARDS +The +.Nm inet_ntop +and +.Nm inet_pton +functions conform to the IETF IPv6 BSD API and address formatting +specifications, as well as +.St -p1003.1-2008 . +.Sh HISTORY +The +.Nm inet_pton +and +.Nm inet_ntop +functions appeared in BIND 4.9.4. +.Sh CAVEATS +Note that +.Nm inet_pton +does not accept 1-, 2-, or 3-part dotted addresses; +all four parts must be specified and must be in decimal +(and not octal or hexadecimal). +This is a narrower input set than that accepted by +.Nm inet_aton . +.Pp +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A J. McCann +.%A W. Stevens +.%D February 2003 +.%R RFC 3493 +.%T Basic Socket Interface Extensions for IPv6 +.Re +.Pp +.Rs +.%A R. Hinden +.%A S. Deering +.%D February 2006 +.%R RFC 4291 +.%T IP Version 6 Addressing Architecture +.Re diff --git a/static/openbsd/man3/initgroups.3 b/static/openbsd/man3/initgroups.3 new file mode 100644 index 00000000..1e81a232 --- /dev/null +++ b/static/openbsd/man3/initgroups.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: initgroups.3,v 1.16 2015/02/05 02:33:09 schwarze 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 $Mdocdate: February 5 2015 $ +.Dt INITGROUPS 3 +.Os +.Sh NAME +.Nm initgroups +.Nd initialize supplementary group IDs +.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 +.Dv NGROUPS_MAX +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 superuser. +.Sh SEE ALSO +.Xr setgroups 2 , +.Xr getgrouplist 3 +.Sh HISTORY +The +.Fn initgroups +function appeared in +.Bx 4.2 . +.Sh BUGS +The +.Xr getgrouplist 3 +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/openbsd/man3/insque.3 b/static/openbsd/man3/insque.3 new file mode 100644 index 00000000..136c08ba --- /dev/null +++ b/static/openbsd/man3/insque.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: insque.3,v 1.12 2020/04/26 16:36:14 schwarze Exp $ +.\" 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. +.\" +.\" +.Dd $Mdocdate: April 26 2020 $ +.Dt INSQUE 3 +.Os +.Sh NAME +.Nm insque , +.Nm remque +.Nd legacy doubly linked lists +.Sh SYNOPSIS +.In search.h +.Ft void +.Fn insque "void *elem" "void *pred" +.Ft void +.Fn remque "void *elem" +.Sh DESCRIPTION +.Bf -symbolic +These interfaces have been superseded by the +.Xr queue 3 +macros and are provided for compatibility with legacy code. +.Ef +.Pp +.Fn insque +and +.Fn remque +manipulate a legacy variety of intrusive doubly linked lists. +A list can be either circular or linear. +Each element in the list must be of the following form: +.Bd -literal -offset indent +struct qelem { + struct qelem *q_forw; + struct qelem *q_back; + char q_data[]; +}; +.Ed +.Pp +The first two members of the struct must be pointers of the +same type that point to the next and previous elements in +the list, respectively. +Any subsequent data in the struct is application-dependent. +.Pp +The +.Fn insque +function inserts +.Fa elem +into a list immediately after +.Fa pred . +.Pp +The +.Fn remque +function removes +.Fa elem +from the list. +.Pp +These functions are not atomic. +.Sh SEE ALSO +.Xr queue 3 +.Sh STANDARDS +The +.Fn insque +and +.Fn remque +functions conform to the X/Open System Interfaces option of the +.St -p1003.1-2008 +specification. +.Sh HISTORY +The +.Fn insque +and +.Fn remque +functions are derived from the +.Li insque +and +.Li remque +instructions on the VAX. +They first appeared in +.Bx 4.2 . diff --git a/static/openbsd/man3/isalnum.3 b/static/openbsd/man3/isalnum.3 new file mode 100644 index 00000000..43a5d59e --- /dev/null +++ b/static/openbsd/man3/isalnum.3 @@ -0,0 +1,125 @@ +.\" $OpenBSD: isalnum.3,v 1.13 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISALNUM 3 +.Os +.Sh NAME +.Nm isalnum , +.Nm isalnum_l +.Nd alphanumeric single-byte character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isalnum "int c" +.Ft int +.Fn isalnum_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn isalnum +function tests for any character for which +.Xr isalpha 3 +or +.Xr isdigit 3 +is true, and +.Fn isalnum_l +tests for any character for which +.Xr isalpha_l 3 +or +.Xr isdigit_l 3 +is true. +.Pp +In the C locale, the complete list of alphanumeric characters +is A\(enZ, a\(enz, 0, and 1\(en9. +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +these functions may return non-zero for additional characters, +and the results of +.Fn isalnum +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 iswalnum 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 , +and +.Fn isalnum_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn isalnum +function first appeared in +.At v7 , +and +.Fn isalnum_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/isalpha.3 b/static/openbsd/man3/isalpha.3 new file mode 100644 index 00000000..d1cb880e --- /dev/null +++ b/static/openbsd/man3/isalpha.3 @@ -0,0 +1,126 @@ +.\" $OpenBSD: isalpha.3,v 1.14 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISALPHA 3 +.Os +.Sh NAME +.Nm isalpha , +.Nm isalpha_l +.Nd alphabetic single-byte character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isalpha "int c" +.Ft int +.Fn isalpha_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn isalpha +and +.Fn isalpha_l +functions test whether +.Fa c +represents a letter. +.Pp +In the C locale, the complete list of alphabetic characters +is A\(enZ and a\(enz. +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +these functions may return non-zero for additional characters, +and the results of +.Fn isalnum +may depend on the +.Ev LC_CTYPE +.Xr locale 1 , +but they never return non-zero for any character for which +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr ispunct 3 , +or +.Xr isspace 3 +is true. +.Sh SEE ALSO +.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 iswalpha 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 , +and +.Fn isalpha_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn isalpha +function first appeared in +.At v7 , +and +.Fn isalpha_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/isascii.3 b/static/openbsd/man3/isascii.3 new file mode 100644 index 00000000..8df4f24d --- /dev/null +++ b/static/openbsd/man3/isascii.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: isascii.3,v 1.15 2021/06/29 16:34:52 schwarze 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. +.\" +.Dd $Mdocdate: June 29 2021 $ +.Dt ISASCII 3 +.Os +.Sh NAME +.Nm isascii +.Nd ASCII character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isascii "int c" +.Sh DESCRIPTION +The +.Fn isascii +function tests for an ASCII character, +which is any character in the range from 0 to 0177, inclusive. +.Sh RETURN VALUES +The +.Fn isascii +function returns zero if the character tests false or +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 , +.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 . +.Sh HISTORY +The +.Fn isascii +function first appeared in +.At v7 . diff --git a/static/openbsd/man3/isblank.3 b/static/openbsd/man3/isblank.3 new file mode 100644 index 00000000..fb7f5d3f --- /dev/null +++ b/static/openbsd/man3/isblank.3 @@ -0,0 +1,123 @@ +.\" $OpenBSD: isblank.3,v 1.14 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISBLANK 3 +.Os +.Sh NAME +.Nm isblank , +.Nm isblank_l +.Nd blank-space single-byte character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isblank "int c" +.Ft int +.Fn isblank_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn isblank +and +.Fn isblank_l +functions test for blank-space characters. +In the C locale, the complete list of blank-space characters is: +.Pp +.Bl -tag -width xxxxx -offset indent -compact +.It Sq \0 +Space character. +.It Li \et +Horizontal tab. +.El +.Pp +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +these functions may return non-zero for additional characters, +and the results of +.Fn isblank +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 iswblank 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn isblank +function conforms to +.St -isoC-99 , +and +.Fn isblank_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn isblank +function has been available since +.Bx 4.4 , +and +.Fn isblank_l +since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/iscntrl.3 b/static/openbsd/man3/iscntrl.3 new file mode 100644 index 00000000..86e9e8ef --- /dev/null +++ b/static/openbsd/man3/iscntrl.3 @@ -0,0 +1,116 @@ +.\" $OpenBSD: iscntrl.3,v 1.14 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISCNTRL 3 +.Os +.Sh NAME +.Nm iscntrl , +.Nm iscntrl_l +.Nd control single-byte character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn iscntrl "int c" +.Ft int +.Fn iscntrl_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn iscntrl +and +.Fn iscntrl_l +functions tests for any control character. +.Pp +In the C locale, the complete list of control characters +consists of the characters numbered 0x00\(en0x1f and 0x7f. +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +results of these functions may differ, and the results of +.Fn iscntrl +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 iswcntrl 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 , +and +.Fn iscntrl_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn iscntrl +function first appeared in +.At v7 , +and +.Fn iscntrl_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/isdigit.3 b/static/openbsd/man3/isdigit.3 new file mode 100644 index 00000000..3ca4afe1 --- /dev/null +++ b/static/openbsd/man3/isdigit.3 @@ -0,0 +1,116 @@ +.\" $OpenBSD: isdigit.3,v 1.14 2023/01/20 17:21:12 millert Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: January 20 2023 $ +.Dt ISDIGIT 3 +.Os +.Sh NAME +.Nm isdigit , +.Nm isdigit_l +.Nd decimal-digit single-byte character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isdigit "int c" +.Ft int +.Fn isdigit_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn isdigit +and +.Fn isdigit_l +functions test for any decimal-digit character. +In the C locale, the complete list of decimal digits is 0 and 1\(en9. +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +different +.Fa c +arguments may correspond to the digits, and the results of +.Fn isdigit +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 iswdigit 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 , +and +.Fn isdigit_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn isdigit +function first appeared in +.At v7 , +and +.Fn isdigit_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/isduid.3 b/static/openbsd/man3/isduid.3 new file mode 100644 index 00000000..51b02780 --- /dev/null +++ b/static/openbsd/man3/isduid.3 @@ -0,0 +1,62 @@ +.\" $OpenBSD: isduid.3,v 1.5 2025/06/06 22:01:40 schwarze Exp $ +.\" +.\" * Copyright (c) Joel Sing +.\" +.\" 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: June 6 2025 $ +.Dt ISDUID 3 +.Os +.Sh NAME +.Nm isduid +.Nd disklabel UID test +.Sh SYNOPSIS +.Lb libutil +.In util.h +.Ft int +.Fn isduid "char *duid" "int dflags" +.Sh DESCRIPTION +The +.Fn isduid +function tests the string +.Fa duid +to see if it is a valid +.Xr disklabel 8 +UID. +The +.Fa dflags +are specified using the same flags as used by +.Xr opendev 3 . +.Pp +If the OPENDEV_PART flag is included in +.Fa dflags , +the disklabel UID must consist of a 16-character hexadecimal string. +Otherwise the disklabel UID must consist of a 16-character hexadecimal string +followed by a +.Sq \&. +and a partition letter. +.Sh RETURN VALUES +The +.Fn isduid +function returns non-zero if +.Fa duid +is a valid DUID, otherwise zero is returned. +.Sh SEE ALSO +.Xr opendev 3 , +.Xr disklabel 5 , +.Xr disklabel 8 +.Sh HISTORY +The +.Fn isduid +function first appeared in +.Ox 4.9 . diff --git a/static/openbsd/man3/isfdtype.3 b/static/openbsd/man3/isfdtype.3 new file mode 100644 index 00000000..66ebad86 --- /dev/null +++ b/static/openbsd/man3/isfdtype.3 @@ -0,0 +1,73 @@ +.\" $OpenBSD: isfdtype.3,v 1.10 2019/01/25 00:19:25 millert Exp $ +.\" +.\" Copyright (c) 2002 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 $Mdocdate: January 25 2019 $ +.Dt ISFDTYPE 3 +.Os +.Sh NAME +.Nm isfdtype +.Nd determine whether a file descriptor is of a specific type +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn isfdtype "int fd" "int fdtype" +.Sh DESCRIPTION +The +.Fn isfdtype +function checks whether or not the file descriptor +.Fa fd +is of type +.Fa fdtype . +.Pp +A list of possible file types may be found in +.Xr stat 2 +and the +.In sys/stat.h +include file. +.Sh RETURN VALUES +The +.Fn isfdtype +function returns 1 if +.Fa fd +is of type +.Fa fdtype +and 0 if it is not. +If +.Fn isfdtype +fails, a value of \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er EBADF +.Fa fd +is not a valid open file descriptor. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr stat 2 +.Sh HISTORY +The +.Fn isfdtype +function first appeared in +.Ox 3.3 . diff --git a/static/openbsd/man3/isgraph.3 b/static/openbsd/man3/isgraph.3 new file mode 100644 index 00000000..ccf9d002 --- /dev/null +++ b/static/openbsd/man3/isgraph.3 @@ -0,0 +1,122 @@ +.\" $OpenBSD: isgraph.3,v 1.13 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISGRAPH 3 +.Os +.Sh NAME +.Nm isgraph , +.Nm isgraph_l +.Nd printing single-byte character test (space character exclusive) +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isgraph "int c" +.Ft int +.Fn isgraph_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn isgraph +and +.Fn isgraph_l +functions tests for any printing character except space +.Pq Sq \ \& . +.Pp +In the C locale, the complete list of printing characters +consists of the characters numbered 0x21\(en0x7e, which is +the union of the characters for which +.Xr isalnum 3 +or +.Xr ispunct 3 +is true. +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +results of these functions may differ, and the results of +.Fn isgraph +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 iswgraph 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 , +and +.Fn isgraph_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn isgraph +function first appeared in +.At III , +and +.Fn isgraph_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/isgreater.3 b/static/openbsd/man3/isgreater.3 new file mode 100644 index 00000000..32b29c36 --- /dev/null +++ b/static/openbsd/man3/isgreater.3 @@ -0,0 +1,101 @@ +.\" $OpenBSD: isgreater.3,v 1.5 2025/06/07 23:56:57 schwarze 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: src/lib/libc/gen/isgreater.3,v 1.3 2005/02/06 03:23:31 das Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ISGREATER 3 +.Os +.Sh NAME +.Nm isgreater , +.Nm isgreaterequal , +.Nm isless , +.Nm islessequal , +.Nm islessgreater , +.Nm isunordered +.Nd compare two floating-point numbers +.Sh SYNOPSIS +.Lb libm +.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 at least one of the arguments is NaN. +For any pair of floating-point values, one +of the relationships (less, greater, equal, unordered) holds. +.Sh SEE ALSO +.Xr fpclassify 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 +.Ox 4.4 . diff --git a/static/openbsd/man3/islower.3 b/static/openbsd/man3/islower.3 new file mode 100644 index 00000000..0b0cf01a --- /dev/null +++ b/static/openbsd/man3/islower.3 @@ -0,0 +1,125 @@ +.\" $OpenBSD: islower.3,v 1.14 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISLOWER 3 +.Os +.Sh NAME +.Nm islower , +.Nm islower_l +.Nd lower-case single-byte character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn islower "int c" +.Ft int +.Fn islower_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn islower +and +.Fn islower_l +functions test whether +.Fa c +represents a lower-case letter. +.Pp +In the C locale, the complete list of lower-case letters is a\(enz. +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +these functions may return non-zero for additional characters, +and the results of +.Fn islower +may depend on the +.Ev LC_CTYPE +.Xr locale 1 , +but they never return non-zero for any character for which +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr ispunct 3 , +or +.Xr isspace 3 +is true. +.Sh SEE ALSO +.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 iswlower 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 , +and +.Fn islower_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn islower +function first appeared in +.At v7 , +AND +.Fn islower_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/isprint.3 b/static/openbsd/man3/isprint.3 new file mode 100644 index 00000000..21fded50 --- /dev/null +++ b/static/openbsd/man3/isprint.3 @@ -0,0 +1,122 @@ +.\" $OpenBSD: isprint.3,v 1.13 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISPRINT 3 +.Os +.Sh NAME +.Nm isprint , +.Nm isprint_l +.Nd printing single-byte character test (space character inclusive) +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isprint "int c" +.Ft int +.Fn isprint_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn isprint +and +.Fn isprint_l +functions test for any printing character including space +.Pq Sq \ \& . +.Pp +In the C locale, the complete list of printing characters +consists of the characters numbered 0x20\(en0x7e, which is +the union of the characters for which +.Xr isalnum 3 +or +.Xr ispunct 3 +is true, and the space character. +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +results of these functions may differ, and the results of +.Fn isprint +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 iswprint 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 , +and +.Fn isprint_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn isprint +function first appeared in +.At v7 , +and +.Fn isprint_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/ispunct.3 b/static/openbsd/man3/ispunct.3 new file mode 100644 index 00000000..64e198d2 --- /dev/null +++ b/static/openbsd/man3/ispunct.3 @@ -0,0 +1,123 @@ +.\" $OpenBSD: ispunct.3,v 1.13 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISPUNCT 3 +.Os +.Sh NAME +.Nm ispunct , +.Nm ispunct_l +.Nd punctuation single-byte character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn ispunct "int c" +.Ft int +.Fn ispunct_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn ispunct +and +.Fn ispunct_l +test for any punctuation characters. +.Pp +In the C locale, the complete list of punctuation characters is: +.Pp +.Dl !\(dq#$%&\(aq()*+,\-./:;<=>?@[\e]\(ha_\(ga{|}\(ti +.Pp +These are all characters for which +.Xr isgraph 3 +is true but +.Xr isalnum 3 +is not. +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +results of these functions may differ, and the results of +.Fn ispunct +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 iswpunct 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 , +and +.Fn ispunct_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn ispunct +function first appeared in +.At v7 , +and +.Fn ispunct_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/isspace.3 b/static/openbsd/man3/isspace.3 new file mode 100644 index 00000000..78e25e62 --- /dev/null +++ b/static/openbsd/man3/isspace.3 @@ -0,0 +1,132 @@ +.\" $OpenBSD: isspace.3,v 1.15 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISSPACE 3 +.Os +.Sh NAME +.Nm isspace , +.Nm isspace_l +.Nd whitespace single-byte character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isspace "int c" +.Ft int +.Fn isspace_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn isspace +and +.Fn isspace_l +functions test for whitespace characters. +.Pp +In the C locale, the complete list of whitespace characters is: +.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 +And vertical tab. +.El +.Pp +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +these functions may return non-zero for additional characters, +and the results of +.Fn isspace +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 iswspace 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 , +and +.Fn isspace_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn isspace +function first appeared in +.At v7 , +and +.Fn isspace_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/isupper.3 b/static/openbsd/man3/isupper.3 new file mode 100644 index 00000000..5c053000 --- /dev/null +++ b/static/openbsd/man3/isupper.3 @@ -0,0 +1,125 @@ +.\" $OpenBSD: isupper.3,v 1.15 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISUPPER 3 +.Os +.Sh NAME +.Nm isupper , +.Nm isupper_l +.Nd upper-case singly-byte character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isupper "int c" +.Ft int +.Fn isupper_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn isupper +and +.Fn isupper_l +functions test whether +.Fa c +represents an upper-case letter. +.Pp +In the C locale, the complete list of upper-case letters is A\(enZ. +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +these functions may return non-zero for additional characters, +and the results of +.Fn isupper +may depend on the +.Ev LC_CTYPE +.Xr locale 1 , +but they never return non-zero for any character for which +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr ispunct 3 , +or +.Xr isspace 3 +is true. +.Sh SEE ALSO +.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 iswupper 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 , +and +.Fn isupper_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn isupper +function first appeared in +.At v7 , +and +.Fn isupper_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/iswalnum.3 b/static/openbsd/man3/iswalnum.3 new file mode 100644 index 00000000..2297f0f4 --- /dev/null +++ b/static/openbsd/man3/iswalnum.3 @@ -0,0 +1,166 @@ +.\" $OpenBSD: iswalnum.3,v 1.6 2017/09/05 03:16:13 schwarze Exp $ +.\" $NetBSD: iswalnum.3,v 1.8 2003/09/08 17:54:31 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 $Mdocdate: September 5 2017 $ +.Dt ISWALNUM 3 +.Os +.Sh NAME +.Nm iswalnum , +.Nm iswalnum_l , +.Nm iswalpha , +.Nm iswalpha_l , +.Nm iswblank , +.Nm iswblank_l , +.Nm iswcntrl , +.Nm iswcntrl_l , +.Nm iswdigit , +.Nm iswdigit_l , +.Nm iswgraph , +.Nm iswgraph_l , +.Nm iswlower , +.Nm iswlower_l , +.Nm iswprint , +.Nm iswprint_l , +.Nm iswpunct , +.Nm iswpunct_l , +.Nm iswspace , +.Nm iswspace_l , +.Nm iswupper , +.Nm iswupper_l , +.Nm iswxdigit , +.Nm iswxdigit_l +.Nd wide-character classification utilities +.Sh SYNOPSIS +.In wctype.h +.Ft int +.Fn iswalnum "wint_t wc" +.Ft int +.Fn iswalnum_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswalpha "wint_t wc" +.Ft int +.Fn iswalpha_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswblank "wint_t wc" +.Ft int +.Fn iswblank_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswcntrl "wint_t wc" +.Ft int +.Fn iswcntrl_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswdigit "wint_t wc" +.Ft int +.Fn iswdigit_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswgraph "wint_t wc" +.Ft int +.Fn iswgraph_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswlower "wint_t wc" +.Ft int +.Fn iswlower_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswprint "wint_t wc" +.Ft int +.Fn iswprint_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswpunct "wint_t wc" +.Ft int +.Fn iswpunct_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswspace "wint_t wc" +.Ft int +.Fn iswspace_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswupper "wint_t wc" +.Ft int +.Fn iswupper_l "wint_t wc" "locale_t locale" +.Ft int +.Fn iswxdigit "wint_t wc" +.Ft int +.Fn iswxdigit_l "wint_t wc" "locale_t locale" +.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. +.Pp +The two-argument variants use the specified +.Fa locale , +while the others use the thread-specific locale set with +.Xr uselocale 3 , +falling back to the global locale set with +.Xr setlocale 3 . +.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 iswctype 3 , +.Xr isxdigit 3 , +.Xr newlocale 3 , +.Xr setlocale 3 , +.Xr towlower 3 +.Sh STANDARDS +The one-argument functions conform to +.St -isoC-99 , +the two-argument functions to +.St -p1003.1-2008 . +.Sh CAVEATS +The argument +.Fa wc +must be +.Dv WEOF +or a valid +.Fa wchar_t +value with the current locale; otherwise, the result is undefined. diff --git a/static/openbsd/man3/iswctype.3 b/static/openbsd/man3/iswctype.3 new file mode 100644 index 00000000..0405f0eb --- /dev/null +++ b/static/openbsd/man3/iswctype.3 @@ -0,0 +1,95 @@ +.\" $OpenBSD: iswctype.3,v 1.5 2017/09/05 03:16:13 schwarze Exp $ +.\" $NetBSD: iswctype.3,v 1.5 2003/04/16 13:34:40 wiz Exp $ +.\" +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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 $Mdocdate: September 5 2017 $ +.Dt ISWCTYPE 3 +.Os +.Sh NAME +.Nm iswctype , +.Nm iswctype_l +.Nd test whether a wide character belongs to a character class +.Sh SYNOPSIS +.In wctype.h +.Ft int +.Fn iswctype "wint_t wc" "wctype_t charclass" +.Ft int +.Fn iswctype_l "wint_t wc" "wctype_t charclass" "locale_t locale" +.Sh DESCRIPTION +These functions test whether the wide character +.Fa wc +belongs to +.Fa charclass . +.Pp +The behaviour is undefined if +.Fa charclass +or +.Fa wc +is invalid. +When +.Fa charclass +is retrieved with +.Xr wctype 3 , +it becomes invalid when the thread-specific character encoding locale +is changed with +.Xr uselocale 3 +or when the global character encoding locale is changed with +.Xr setlocale 3 . +When +.Fa charclass +is retrieved with +.Xr wctype_l 3 , +it is only valid for use with the same +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false +or non-zero if the character tests true. +.Sh SEE ALSO +.Xr iswalnum 3 , +.Xr newlocale 3 , +.Xr setlocale 3 , +.Xr towctrans 3 , +.Xr wctype 3 +.Sh STANDARDS +The +.Fn iswctype +function conforms to +.St -isoC-amd1 , +and +.Fn iswctype_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn iswctype +function has been available since +.Ox 3.8 , +and +.Fn iswctype_l +since +.Ox 6.2 . diff --git a/static/openbsd/man3/isxdigit.3 b/static/openbsd/man3/isxdigit.3 new file mode 100644 index 00000000..0934287b --- /dev/null +++ b/static/openbsd/man3/isxdigit.3 @@ -0,0 +1,117 @@ +.\" $OpenBSD: isxdigit.3,v 1.12 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt ISXDIGIT 3 +.Os +.Sh NAME +.Nm isxdigit , +.Nm isxdigit_l +.Nd hexadecimal-digit single-byte character test +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isxdigit "int c" +.Ft int +.Fn isxdigit_l "int c" "locale_t locale" +.Sh DESCRIPTION +The +.Fn isxdigit +and +.Fn isxdigit_l +functions test for any hexadecimal-digit character. +.Pp +In the C locale, the complete list of hexadecimal digits +is 0, 1\(en9, A\(enF, and a\(enf. +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +These functions return zero if the character tests false or +non-zero if the character tests true. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +these functions may return non-zero for additional characters, +and the results of +.Fn isxdigit +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 iswxdigit 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 , +and +.Fn isxdigit_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn isxdigit +function first appeared in +.At v7 , +and +.Fn isdigit_l +has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/j0.3 b/static/openbsd/man3/j0.3 new file mode 100644 index 00000000..c7051774 --- /dev/null +++ b/static/openbsd/man3/j0.3 @@ -0,0 +1,161 @@ +.\" $OpenBSD: j0.3,v 1.18 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.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 SYNOPSIS +.Lb libm +.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 +and +.Fn j1 +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 function +.Fn jn +computes the +.Em Bessel function of the first kind of the integer order +.Fa n +for the real value +.Fa x . +The functions +.Fn j0f , +.Fn j1f , +and +.Fn jnf +are single precision versions of +.Fn j0 , +.Fn j1 , +and +.Fn jn , +respectively. +.Pp +The functions +.Fn y0 +and +.Fn y1 +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 function +.Fn yn +computes 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). +The functions +.Fn y0f , +.Fn y1f , +and +.Fn ynf +are single precision versions of +.Fn y0 , +.Fn y1 , +and +.Fn yn , +respectively. +.Sh RETURN VALUES +If these functions are successful, +the computed value is returned, otherwise the global variable +.Va errno +is set to +.Er EDOM +or +.Er ERANGE . +.Sh HISTORY +The functions +.Fn j0 , +.Fn j1 , +.Fn jn , +.Fn y0 , +.Fn y1 , +and +.Fn yn +first appeared in +.At v7 . diff --git a/static/openbsd/man3/key_defined.3 b/static/openbsd/man3/key_defined.3 new file mode 100644 index 00000000..765bd10b --- /dev/null +++ b/static/openbsd/man3/key_defined.3 @@ -0,0 +1,60 @@ +.\" $OpenBSD: key_defined.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 2003-2006,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 2003 +.\" +.\" $Id: key_defined.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH key_defined 3 2022-02-12 "ncurses 6.4" "Library calls" +.SH NAME +\fBkey_defined\fP \- check if a keycode is defined +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint key_defined(const char *\fIdefinition\fB);\fR +.SH DESCRIPTION +This is an extension to the curses library. +It permits an application to determine if a string is currently bound +to any keycode. +.SH RETURN VALUE +If the string is bound to a keycode, its value (greater than zero) is returned. +If no keycode is bound, zero is returned. +If the string conflicts with longer strings +which are bound to keys, \-1 is returned. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on +Version 7, BSD or System V implementations. +It is recommended that +any code depending on them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBdefine_key\fP(3). +.SH AUTHOR +Thomas Dickey. diff --git a/static/openbsd/man3/keybound.3 b/static/openbsd/man3/keybound.3 new file mode 100644 index 00000000..278d351b --- /dev/null +++ b/static/openbsd/man3/keybound.3 @@ -0,0 +1,63 @@ +.\" $OpenBSD: keybound.3,v 1.4 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1999-2008,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1999 +.\" +.\" $Id: keybound.3,v 1.4 2023/10/17 09:52:08 nicm Exp $ +.TH keybound 3 2022-02-12 "ncurses 6.4" "Library calls" +.SH NAME +\fBkeybound\fP \- return definition of keycode +.SH SYNOPSIS +\fB#include \fP +.sp +\fBchar * keybound(int \fIkeycode\fB, int \fIcount);\fR +.SH DESCRIPTION +This is an extension to the curses library. +It permits an application to determine the string which is defined +in the terminfo for specific keycodes. +.SH RETURN VALUE +The \fIkeycode\fP parameter must be greater than zero, else NULL is returned. +If it does not correspond to a defined key, then NULL is returned. +The \fIcount\fP parameter is used to allow the application to iterate +through multiple definitions, counting from zero. +When successful, +the function returns a string which must be freed by the caller. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on +Version 7, BSD or System V implementations. +It is recommended that +any code depending on them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBdefine_key\fP(3), +\fBkeyok\fP(3). +.SH AUTHOR +Thomas Dickey. diff --git a/static/openbsd/man3/keynote.3 b/static/openbsd/man3/keynote.3 new file mode 100644 index 00000000..34af729a --- /dev/null +++ b/static/openbsd/man3/keynote.3 @@ -0,0 +1,939 @@ +.\" $OpenBSD: keynote.3,v 1.56 2025/06/05 18:59:11 schwarze Exp $ +.\" +.\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) +.\" +.\" This code was written by Angelos D. Keromytis in Philadelphia, PA, USA, +.\" in April-May 1998 +.\" +.\" Copyright (C) 1998, 1999 by Angelos D. Keromytis. +.\" +.\" Permission to use, copy, and modify this software with or without fee +.\" is hereby granted, provided that this entire notice is included in +.\" all copies of any software which is or includes a copy or +.\" modification of this software. +.\" You may use this code under the GNU public license if you so wish. Please +.\" contribute changes back to the author. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTY. IN PARTICULAR, THE AUTHORS MAKES NO +.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE +.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR +.\" PURPOSE. +.\" +.Dd $Mdocdate: June 5 2025 $ +.Dt KN_INIT 3 +.\" .TH KeyNote 3 local +.Os +.Sh NAME +.Nm kn_init , +.Nm kn_add_assertion , +.Nm kn_remove_assertion , +.Nm kn_add_action , +.Nm kn_remove_action , +.Nm kn_add_authorizer , +.Nm kn_remove_authorizer , +.Nm kn_do_query , +.Nm kn_get_failed , +.Nm kn_cleanup_action_environment , +.Nm kn_close , +.Nm kn_query , +.Nm kn_read_asserts , +.Nm kn_keycompare , +.Nm kn_get_authorizer , +.Nm kn_get_licensees , +.Nm kn_encode_base64 , +.Nm kn_decode_base64 , +.Nm kn_encode_hex , +.Nm kn_decode_hex , +.Nm kn_encode_key , +.Nm kn_decode_key , +.Nm kn_sign_assertion , +.Nm kn_verify_assertion , +.Nm kn_free_key , +.Nm kn_get_string +.Nd a trust-management system library +.Sh SYNOPSIS +.Lb libkeynote libm libcrypto +.In sys/types.h +.In regex.h +.In keynote.h +.Bd -literal +struct environment { + char *env_name; + char *env_value; + int env_flags; + regex_t env_regex; + struct environment *env_next; +}; + +struct keynote_deckey { + int dec_algorithm; + void *dec_key; +}; + +struct keynote_binary { + int bn_len; + char *bn_key; +}; + +struct keynote_keylist { + int key_alg; + void *key_key; + char *key_stringkey; + struct keynote_keylist *key_next; +}; +.Ed +.Vt extern int keynote_errno; +.Ft int +.Fn kn_init "void" +.Ft int +.Fn kn_add_assertion "int sessid" "char *assertion" "int len" "int flags" +.Ft int +.Fn kn_remove_assertion "int sessid" "int assertid" +.Ft int +.Fn kn_add_action "int sessid" "char *name" "char *value" "int flags" +.Ft int +.Fn kn_remove_action "int sessid" "char *name" +.Ft int +.Fn kn_add_authorizer "int sessid" "char *principal" +.Ft int +.Fn kn_remove_authorizer "int sessid" "char *principal" +.Ft int +.Fn kn_do_query "int sessid" "char **returnvalues" "int numvalues" +.Ft int +.Fn kn_get_failed "int sessid" "int type" "int seq" +.Ft int +.Fn kn_cleanup_action_environment "int sessid" +.Ft int +.Fn kn_close "int sessid" +.Ft int +.Fo kn_query +.Fa "struct environment *env" +.Fa "char **returnvalues" +.Fa "int numvalues" +.Fa "char **trusted" +.Fa "int *trustedlen" +.Fa "int numtrusted" +.Fa "char **untrusted" +.Fa "int *untrustedlen" +.Fa "int numuntrusted" +.Fa "char **authorizers" +.Fa "int numauthorizers" +.Fc +.Ft char ** +.Fn kn_read_asserts "char *array" "int arraylen" "int *numassertions" +.Ft int +.Fn kn_keycompare "void *key1" "void *key2" "int algorithm" +.Ft void * +.Fn kn_get_authorizer "int sessid" "int assertid" "int *algorithm" +.Ft struct keynote_keylist * +.Fn kn_get_licensees "int sessid" "int assertid" +.Ft int +.Fn kn_encode_base64 "unsigned char const *src" "unsigned int srclen" "char *dst" "unsigned int dstlen" +.Ft int +.Fn kn_decode_base64 "char const *src" "unsigned char *dst" "unsigned int dstlen" +.Ft int +.Fn kn_encode_hex "unsigned char *src" "char **dst" "int srclen" +.Ft int +.Fn kn_decode_hex "char *src" "char **dst" +.Ft char * +.Fn kn_encode_key "struct keynote_deckey *dc" "int iencoding" "int encoding" "int keytype" +.Ft int +.Fn kn_decode_key "struct keynote_deckey *dc" "char *key" "int keytype" +.Ft char * +.Fn kn_sign_assertion "char *assertion" "int len" "char *key" "char *algorithm" "int vflag" +.Ft int +.Fn kn_verify_assertion "char *assertion" "int len" +.Ft void +.Fn kn_free_key "struct keynote_deckey *" +.Ft char * +.Fn kn_get_string "char *" +.Sh DESCRIPTION +For more details on +.Nm keynote , +see RFC 2704. +.Pp +.Va keynote_errno +contains an error code if some library call failed. +Failed calls return \-1 (if their return value is integer), or +.Dv NULL +(if their return value is a pointer) and set +.Va keynote_errno . +The defined error codes are: +.Bl -tag -width "ERROR_NOTFOUND" -offset indent +.It Li ERROR_MEMORY +Some memory allocation or usage error was encountered. +.It Li ERROR_SYNTAX +Some syntactic or logical error was encountered. +.It Li ERROR_NOTFOUND +One of the arguments referred to a nonexistent structure or entry. +.El +.Pp +If no errors were encountered, +.Va keynote_errno +will be set to 0. +This variable should be reset to 0 if an error was encountered, +prior to calling other library routines. +.Pp +The main interface to +.Nm +is centered around the concept of a session. +A session describes a collection of policies, assertions, action +authorizers, return values, and action attributes that the +.Nm +system uses to evaluate a query. +Information is not shared between sessions. +Policies, credentials, action authorizers, and action +attributes can be added or deleted at any point during the lifetime of +a session. +Furthermore, an application can discover which assertions failed to be +evaluated, and in what way, during a query. +.Pp +For those applications that only need to do a simple query, there +exists a single call that takes as arguments all the necessary +information and performs all the necessary steps. +This is essentially a wrapper that calls the session API functions as +necessary. +.Pp +Finally, there exist functions for doing ASCII to hexadecimal and +Base64 encoding (and vice versa), for encoding/decoding keys between +ASCII and binary formats, and for signing and verifying assertions. +.Pp +The description of all +.Nm +library functions follows. +.Pp +.Fn kn_init +creates a new +.Nm +session, and performs any necessary initializations. +On success, this function returns the new session ID, which is used by +all subsequent calls with a +.Fa sessid +argument. +On failure, it returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_MEMORY . +.Pp +.Fn kn_add_assertion +adds the assertion pointed to by the array +.Fa assertion , +of length +.Fa len +in the session identified by +.Fa sessid . +The first argument can be discarded after the call to this function. +The following flags are defined: +.Bl -tag -width ASSERT_FLAG_LOCAL -offset indent +.It ASSERT_FLAG_LOCAL +Mark this assertion as ultimately trusted. +Trusted assertions need not be signed, and the +.Fa Authorizer +and +.Fa Licensees +fields can have non-key entries. +.El +.Pp +At least one (trusted) assertion should have +.Dv POLICY +as the +.Fa Authorizer . +On success, this function will return an assertion ID which can be +used to remove the assertion from the session, by using +.Fn kn_remove_assertion . +On failure, \-1 is returned, and +.Va keynote_errno +is set to +.Er ERROR_NOTFOUND +if the session was not found, +.Er ERROR_SYNTAX +if the assertion was syntactically incorrect, or +.Er ERROR_MEMORY +if necessary memory could not be allocated. +.Pp +.Fn kn_remove_assertion +removes the assertion identified by +.Fa assertid +from the session identified by +.Fa sessid . +On success, this function returns 0. +On failure, it returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_NOTFOUND . +.Pp +.Fn kn_add_action +inserts the variable +.Fa name +in the action environment of session +.Fa sessid , +with the value +.Fa value . +The same attribute may be added more than once, but only the last +instance will be used (memory resources are consumed however). +.Pp +The +.Fa flags +specified are formed by or'ing the following values: +.Bl -tag -width ENVIRONMENT_FLAG_REGEX -offset indent +.It ENVIRONMENT_FLAG_FUNC +In this case, +.Fa value +is a pointer to a function that takes as argument a string and returns +a string. +This is used to implement callbacks for getting action attribute values. +The argument passed to such a callback function is a string identifying +the action attribute whose value is requested, and should return a pointer +to string containing that value (this pointer will not be freed by the +library), the empty string if the value was not found, or a +.Dv NULL +to indicate an error (and may set +.Va keynote_errno +appropriately). +Prior to first use (currently, at the time the attribute is added to the +session environment), such functions are called with +.Dv KEYNOTE_CALLBACK_INITIALIZE +as the argument (defined in keynote.h) so that they can perform any special +initializations. +Furthermore, when the session is deleted, all such functions will be called +with +.Dv KEYNOTE_CALLBACK_CLEANUP +to perform any special cleanup (such as free any allocated memory). +A function may be called with either of these arguments more than once, +if it has been defined as the callback function for more than one attribute. +.It ENVIRONMENT_FLAG_REGEX +In this case, +.Fa name +is a regular expression that may match more than one attribute. +In case of conflict between a regular expression and a +.Dq simple +attribute, the latter will be given priority. +In case of conflict between two regular expression attributes, the one added +later will be given priority. +A callback function should never change the current +.Nm +session, start/invoke/operate on another session, or call one of the +session-API functions. +.El +.Pp +The combination of the two flags may be used to specify callback +functions that handle large sets of attributes (even to the extent of +having one callback function handling all attribute references). +This is particularly useful when the action attribute set is particularly +large. +.Pp +On success, +.Fn kn_add_action +returns 0. +On failure, it returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_NOTFOUND +if the session was not found, +.Er ERROR_SYNTAX +if the +.Fa name +was invalid (e.g., started with an underscore character) or was +.Dv NULL , +or +.Er ERROR_MEMORY +if necessary memory could not be allocated. +.Pp +.Fn kn_remove_action +removes action attribute +.Fa name +from the environment of session +.Fa sessid . +Notice that if more than one instances of +.Fa name +exist, only the one added last will be deleted. +On success, this function returns 0. +On failure, it returns \-1 and +.Va keynote_errno +is set to +.Er ERROR_NOTFOUND +if the session or the attribute were not found, or +.Er ERROR_SYNTAX +if the name was invalid. +If the attribute value was a callback, that function will be called with +the define +.Dv KEYNOTE_CALLBACK_CLEANUP +as the argument. +.Pp +.Fn kn_add_authorizer +adds the principal pointed to by +.Fa principal +to the action authorizers list of session +.Fa sessid . +The principal is typically an ASCII-encoded key. +On success, this function will return 0. +On failure, it returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_NOTFOUND +if the session was not found, +.Er ERROR_SYNTAX +if the encoding was invalid, or +.Er ERROR_MEMORY +if necessary memory could not be allocated. +.Pp +.Fn kn_remove_authorizer +removes +.Fa principal +from the action authorizer list of session +.Fa sessid . +On success, this function returns 0. +On failure, it returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_NOTFOUND +if the session was not found. +.Pp +.Fn kn_do_query +evaluates the request based on the assertions, action attributes, and +action authorizers added to session +.Fa sessid . +.Fa returnvalues +is an ordered array of strings that contain the return values. +The lowest-ordered return value is contained in +.Fa returnvalues Ns Bq 0 , +and the highest-ordered value is +.Fa returnvalues Ns Bq Fa numvalues No \- 1 . +If +.Fa returnvalues +is +.Dv NULL , +the +.Fa returnvalues +from the previous call to +.Fn kn_do_query +will be used. +The programmer SHOULD NOT free +.Fa returnvalues +after the call to +.Fn kn_do_query +if this feature is used, as the array is not replicated internally. +On success, this function returns an index into the +.Fa returnvalues +array. +On failure, it returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_NOTFOUND +if the session was not found or the authorizers list was empty, +.Er ERROR_SYNTAX +if no +.Fa returnvalues +have been specified, or +.Er ERROR_MEMORY +if necessary memory could not be allocated. +.Pp +.Fn kn_get_failed +returns the assertion ID of the +.Fa num'th +assertion (starting from zero) in session +.Fa sessid +that was somehow invalid during evaluation. +This function is typically called after +.Fn kn_do_query +is used to evaluate a request. +.Fa type +specifies the type of failure the application is interested in. +It can be set to: +.Bl -tag -width KEYNOTE_ERROR_SIGNATURE -offset indent +.It KEYNOTE_ERROR_ANY +to indicate interest in any error. +.It KEYNOTE_ERROR_SYNTAX +for syntactic or semantic errors. +.It KEYNOTE_ERROR_MEMORY +for memory-related problems. +.It KEYNOTE_ERROR_SIGNATURE +if the assertion could not be cryptographically verified. +.El +.Pp +These values are defined in keynote.h. +An application can then delete the offending assertion using +.Fn kn_remove_assertion . +For example, to remove all assertion whose signature failed, an application +could do something like: +.Bd -literal + while ((assertid = kn_get_failed(sessid, KEYNOTE_ERROR_SIGNATURE, 0) + != -1) + kn_remove_assertion(sessid, assertid); +.Ed +.Pp +On success, +.Fn kn_get_failed +returns an assertion ID. +On failure, or when no assertion matching the given criteria is found, +it returns \-1 and set +.Va keynote_errno +to +.Er ERROR_NOTFOUND . +.Pp +.Fn kn_cleanup_action_environment +removes all action attributes from the action environment of session +.Fa sessid . +It returns 0 on success. +.Pp +.Fn kn_close +closes session +.Fa sessid +and frees all related resources, deleting action attributes, action +authorizers, and assertions. +On success, this function returns 0. +On failure, it returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_NOTFOUND +if the session was not found. +.Pp +.Fn kn_read_asserts +parses the string +.Fa array +of length +.Fa arraylen +and returns an array of pointers to strings containing copies of +the assertions found in +.Fa array . +Both the array of pointers and the strings are allocated by +.Fn kn_read_asserts +dynamically, and thus should be freed by the programmer when they are +no longer needed. +.Fa numassertions +contains the number of assertions (and thus strings in the returned +array) found in +.Fa array . +On failure, this function returns +.Dv NULL +and sets +.Va keynote_errno +to +.Er ERROR_MEMORY +if necessary memory could not be allocated, or +.Er ERROR_SYNTAX +if +.Fa array +was +.Dv NULL . +Note that if there were no assertions found in +.Fa array , +a valid pointer will be returned, but +.Fa numassertions +will contain the value zero on return. +The returned pointer should be freed by the programmer. +.Pp +.Fn kn_keycompare +compares +.Fa key1 +and +.Fa key2 +(which must be of the same +.Fa algorithm ) +and returns 1 if equal and 0 otherwise. +.Pp +.Fn kn_get_authorizer +returns the authorizer key (in binary format) for assertion +.Fa assertid +in session +.Fa sessid . +It also sets the +.Fa algorithm +argument to the algorithm of the authorizer key. +On failure, +.Fn kn_get_authorizer +returns +.Dv NULL , +and sets +.Va keynote_errno +to +.Er ERROR_NOTFOUND . +.Pp +.Fn kn_get_licensees +returns the licensee key(s) for assertion +.Fa assertid +in session +.Fa sessid . +The keys are returned in a linked list of +.Fa struct keynote_keylist +structures. +On failure, +.Fn kn_get_licensees +returns +.Dv NULL . +and sets +.Va keynote_errno +to +.Er ERROR_NOTFOUND . +.Pp +.Fn kn_query +takes as arguments a list of action attributes in +.Fa env , +a list of return values in +.Fa returnvalues +(the number of returnvalues is indicated by +.Fa numvalues ) , +a number +.Pf ( Fa numtrusted ) +of locally-trusted assertions in +.Fa trusted +(the length of each assertion is given by the respective element of +.Fa trustedlen ) , +a number +.Pf ( Fa numuntrusted ) +of assertions that need to be cryptographically verified in +.Fa untrusted +(the length of each assertion is given by the respective element of +.Fa untrustedlen ) , +and a number +.Pf ( Fa numauthorizers ) +of action authorizers in +.Fa authorizers . +.Fa env +is a linked list of +.Fa struct environment +structures. +The +.Fa env_name , +.Fa env_value , +and +.Fa env_flags +fields correspond to the +.Fa name , +.Fa value , +and +.Fa flags +arguments to +.Fn kn_add_assertion +respectively. +.Fa env_regex +is not used. +On success, this function returns an index in +.Fa returnvalues +indicating the returned value to the query. +On failure, it returns \-1 and sets +.Va keynote_errno +to the same values as +.Fn kn_do_query , +or to +.Er ERROR_MEMORY +if a trusted or untrusted assertion could not be added to the session due +to lack of memory resources. +Syntax errors in assertions will not be reported by +.Fn kn_query . +.Pp +.Fn kn_encode_base64 +converts the data of length +.Fa srclen +contained in +.Fa src +in Base64 encoding and stores them in +.Fa dst +which is of length +.Fa dstlen . +The actual length of the encoding stored in +.Fa dst +is returned. +.Fa dst +should be long enough to also contain the trailing +string terminator. +If +.Fa dst +is not long enough to contain the encoded data, this function returns +\-1 and sets +.Va keynote_errno +to +.Er ERROR_SYNTAX . +.Pp +.Fn kn_decode_base64 +decodes the Base64-encoded data stored in +.Fa src +and stores the result in +.Fa dst , +which is of length +.Fa dstlen . +The actual length of the decoded data is returned on success. +On failure, this function returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_SYNTAX , +denoting either an invalid Base64 encoding or insufficient space in +.Fa dst . +.Pp +.Fn kn_encode_hex +encodes in ASCII-hexadecimal format the data of length +.Fa srclen +contained in +.Fa src . +This function allocates a chunk of memory to store the result, which +is returned in +.Fa dst . +Thus, this function should be used as follows: +.Bd -literal + char *dst; + + kn_encode_hex(src, &dst, srclen); +.Ed +.Pp +The length of the allocated buffer will be (2 * srclen + 1). +On success, this function returns 0. +On failure, it returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_MEMORY +if it failed to allocate enough memory, +.Er ERROR_SYNTAX +if +.Fa dst +was +.Dv NULL . +.Pp +.Fn kn_decode_hex +decodes the ASCII hex-encoded string in +.Fa src +and stores the result in a memory chunk allocated by the function. +A pointer to that memory is stored in +.Fa dst . +The length of the allocated memory will be (strlen(src) / 2). +On success, this function returns 0. +On failure, it returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_MEMORY +if it could not allocate enough memory, or +.Er ERROR_SYNTAX +if +.Fa dst +was +.Dv NULL , +or the length of +.Fa src +is not even. +.Pp +.Fn kn_encode_key +ASCII-encodes a cryptographic key. +The binary representation of the key is contained in +.Fa dc . +The field +.Fa dec_key +in that structure is a pointer to some cryptographic algorithm +dependent information describing the key. +In this implementation, this pointer should be a +.Fa DSA * +or +.Fa RSA * +for DSA or RSA keys respectively, as used in the SSL library, or a +.Fa keynote_binary * +for cryptographic keys whose algorithm +.Nm +does not know about but the application wishes to include in the +action authorizers (and thus need to be canonicalized). +The field +.Fa dec_algorithm +describes the cryptographic algorithm, and may be one of +.Dv KEYNOTE_ALGORITHM_DSA , +.Dv KEYNOTE_ALGORITHM_RSA , +or +.Dv KEYNOTE_ALGORITHM_BINARY +in this implementation. +.Pp +.Fa iencoding +describes how the key should be binary-encoded. +This implementation supports +.Dv INTERNAL_ENC_PKCS1 +for RSA keys, +.Dv INTERNAL_ENC_ASN1 +for DSA keys, and +.Dv INTERNAL_ENC_NONE +for BINARY keys. +.Fa encoding +describes what ASCII encoding should be applied to the key. +Valid values are +.Dv ENCODING_HEX +and +.Dv ENCODING_BASE64 , +for hexadecimal and Base64 encoding respectively. +.Fa keytype +is one of +.Dv KEYNOTE_PUBLIC_KEY +or +.Dv KEYNOTE_PRIVATE_KEY +to indicate whether the key is public or private. +Private keys have the string +.Dv KEYNOTE_PRIVATE_KEY_PREFIX +(defined in keynote.h) prefixed to the algorithm name. +On success, this function returns a string containing the encoded key. +On failure, it returns +.Dv NULL +and sets +.Va keynote_errno +to +.Er ERROR_NOTFOUND +if the +.Fa dc +argument was invalid, +.Er ERROR_MEMORY +if it failed to allocate the necessary memory, or +.Er ERROR_SYNTAX +if the key to be converted was invalid. +.Pp +.Fn kn_decode_key +decodes the ASCII-encoded string contained in +.Fa key . +The result is placed in +.Fa dc , +with +.Fa dec_algorithm +describing the algorithm (see +.Fn kn_encode_key ) , +and +.Fa dec_key +pointing to an algorithm-dependent structure. +In this implementation, this is an SSLeay/OpenSSL-defined +.Fa DSA * +for DSA keys, +.Fa RSA * +for RSA and X.509-based keys, and a +.Fa keynote_binary * +for BINARY keys. +.Fa keytype +takes the values +.Dv KEYNOTE_PUBLIC_KEY +or +.Dv KEYNOTE_PRIVATE_KEY +to specify a public or private key, where applicable. +On success, this function returns 0. +On failure, it returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_MEMORY +if necessary memory could not be allocated, or +.Er ERROR_SYNTAX +if the key or the ASCII encoding was malformed. +.Pp +.Fn kn_sign_assertion +produces the cryptographic signature for the assertion of length +.Fa len +stored in +.Fa assertion , +using the ASCII-encoded cryptographic key contained in +.Fa key . +The type of signature to be produced is described by the string +.Fa algorithm . +Possible values for this string are +.Dv SIG_RSA_SHA1_PKCS1_HEX , +.Dv SIG_RSA_SHA1_PKCS1_BASE64 , +.Dv SIG_RSA_MD5_HEX +and +.Dv SIG_RSA_MD5_HEX +for RSA keys, +.Dv SIG_DSA_SHA1_HEX +and +.Dv SIG_DSA_SHA1_BASE64 +for DSA keys, +.Dv SIG_X509_SHA1_HEX +and +.Dv SIG_X509_SHA1_BASE64 +for X.509-based keys. +No other cryptographic signatures are currently +supported by this implementation. +If +.Fa vflag +is set to 1, then the generated signature will also be verified. +On success, this function returns a string containing the ASCII-encoded +signature, without modifying the +.Fa assertion . +On failure, it returns +.Dv NULL +and sets +.Va keynote_errno +to +.Er ERROR_NOTFOUND +if one of the arguments was +.Dv NULL , +.Er ERROR_MEMORY +if necessary memory could not be allocated, or +.Er ERROR_SYNTAX +if the +.Fa algorithm , +the +.Fa key , +or the +.Fa assertion +(if signature verification was requested) was invalid. +.Pp +.Fn kn_verify_assertion +verifies the cryptographic signature on the assertion of length +.Fa len +contained in string +.Fa assertion . +On success, this function returns +.Dv SIGRESULT_TRUE +if the signature could be verified, or +.Dv SIGRESULT_FALSE +otherwise. +On failure, this function returns \-1 and sets +.Va keynote_errno +to +.Er ERROR_MEMORY +if necessary memory could not be allocated, or +.Er ERROR_SYNTAX +if the assertion contained a syntactic error, or the cryptographic +algorithm was not supported. +.Pp +.Fn kn_free_key +frees a cryptographic key. +.Pp +.Fn kn_get_string +parses the argument, treating it as a +.Xr keynote 4 +(quoted) string. +This is useful for parsing key files. +On success, this function returns a pointer to the parsing result. +The result is dynamically allocated and should be freed after use. +On failure, +.Dv NULL +is returned. +.Sh FILES +.Bl -tag -width libkeynote.a -compact +.It Pa keynote.h +.It Pa libkeynote.a +.El +.Sh DIAGNOSTICS +The return values of all the functions have been given along with the +function description above. +.Sh SEE ALSO +.Xr keynote 1 , +.Xr keynote 4 , +.Xr keynote 5 +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A J. Lacy +.%D 1996 +.%J IEEE Symposium on Security and Privacy +.%T Decentralized Trust Management +.Re +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A M. Strauss +.%D 1998 +.%J Financial Crypto Conference +.%T Compliance-Checking in the PolicyMaker Trust Management System +.Re +.Sh STANDARDS +.Rs +.%A M. Blaze +.%A J. Feigenbaum +.%A J. Ioannidis +.%A A. Keromytis +.%D September 1999 +.%R RFC 2704 +.%T The KeyNote Trust-Management System Version 2 +.Re +.Sh AUTHORS +.An Angelos D. Keromytis Aq Mt angelos@cs.columbia.edu +.Sh WEB PAGE +.Lk https://www1.cs.columbia.edu/~angelos/keynote.html diff --git a/static/openbsd/man3/keyok.3 b/static/openbsd/man3/keyok.3 new file mode 100644 index 00000000..26a41aad --- /dev/null +++ b/static/openbsd/man3/keyok.3 @@ -0,0 +1,62 @@ +.\" $OpenBSD: keyok.3,v 1.5 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1997 +.\" +.\" $Id: keyok.3,v 1.5 2023/10/17 09:52:08 nicm Exp $ +.TH keyok 3 2022-02-12 "ncurses 6.4" "Library calls" +.SH NAME +\fBkeyok\fP \- enable or disable a keycode +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint keyok(int \fIkeycode\fB, bool \fIenable\fB);\fR +.SH DESCRIPTION +This is an extension to the curses library. +It permits an application to disable specific keycodes, rather than +use the \fBkeypad\fP function to disable all keycodes. +Keys that have been disabled can be re-enabled. +.SH RETURN VALUE +The keycode must be greater than zero, else \fBERR\fP is returned. +If it does not correspond to a defined key, then \fBERR\fP is returned. +If the \fIenable\fP parameter is true, then the key must have been disabled, +and vice versa. +Otherwise, the function returns \fBOK\fP. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on +Version 7, BSD or System V implementations. +It is recommended that +any code depending on them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBdefine_key\fP(3). +.SH AUTHOR +Thomas Dickey. diff --git a/static/openbsd/man3/killpg.3 b/static/openbsd/man3/killpg.3 new file mode 100644 index 00000000..712953bc --- /dev/null +++ b/static/openbsd/man3/killpg.3 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1980, 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. +.\" +.\" $OpenBSD: killpg.3,v 1.14 2017/05/07 21:19:29 millert Exp $ +.\" +.Dd $Mdocdate: May 7 2017 $ +.Dt KILLPG 3 +.Os +.Sh NAME +.Nm killpg +.Nd send signal to a process group +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn killpg "pid_t pgrp" "int sig" +.Sh DESCRIPTION +The +.Fn killpg +function 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 superuser. +As a single special case the continue signal SIGCONT may be sent +to any process with the same session ID as the caller. +.Sh RETURN VALUES +.Rv -std +.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 superuser 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 STANDARDS +The +.Fn killpg +function conforms to the X/Open System Interfaces option of the +.St -p1003.1-2008 +specification. +.Pp +The handling of process group 0 is an extension to that standard. +.Sh HISTORY +The +.Fn killpg +function call appeared in +.Bx 4.0 . diff --git a/static/openbsd/man3/kvm.3 b/static/openbsd/man3/kvm.3 new file mode 100644 index 00000000..4f8456c3 --- /dev/null +++ b/static/openbsd/man3/kvm.3 @@ -0,0 +1,109 @@ +.\" $OpenBSD: kvm.3,v 1.10 2020/06/25 12:20:17 kn Exp $ +.\" $NetBSD: kvm.3,v 1.2 1996/03/18 22:33:11 thorpej 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 $Mdocdate: June 25 2020 $ +.Dt KVM 3 +.Os +.Sh NAME +.Nm kvm +.Nd kernel memory interface +.Sh DESCRIPTION +The +.Nm kvm +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 SEE ALSO +.Xr kvm_dump 3 , +.Xr kvm_geterr 3 , +.Xr kvm_getfiles 3 , +.Xr kvm_getloadavg 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_read 3 +.Sh STANDARDS +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. diff --git a/static/openbsd/man3/kvm_dump.3 b/static/openbsd/man3/kvm_dump.3 new file mode 100644 index 00000000..b5b23261 --- /dev/null +++ b/static/openbsd/man3/kvm_dump.3 @@ -0,0 +1,104 @@ +.\" $OpenBSD: kvm_dump.3,v 1.14 2025/06/06 21:53:13 schwarze Exp $ +.\" $NetBSD: kvm_dump.3,v 1.1 1996/03/18 21:11:12 leo 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 $Mdocdate: June 6 2025 $ +.Dt KVM_DUMP_MKHEADER 3 +.Os +.Sh NAME +.Nm kvm_dump_mkheader , +.Nm kvm_dump_wrtheader , +.Nm kvm_dump_inval +.Nd crash dump support functions +.Sh SYNOPSIS +.Lb libkvm +.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 +.Dv CORE_CPU +section and the section header of the +.Dv CORE_DATA +section. +The data is written to the file pointed at by +.Fa fp . +The +.Fa dumpsize +argument is only used to properly set the segment size of the +.Dv 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 return 0 on success, \-1 on failure. +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 +.Sh HISTORY +These functions first appeared in +.Nx 1.1a . diff --git a/static/openbsd/man3/kvm_geterr.3 b/static/openbsd/man3/kvm_geterr.3 new file mode 100644 index 00000000..d7aad6b6 --- /dev/null +++ b/static/openbsd/man3/kvm_geterr.3 @@ -0,0 +1,75 @@ +.\" $OpenBSD: kvm_geterr.3,v 1.10 2025/06/06 21:53:13 schwarze Exp $ +.\" $NetBSD: kvm_geterr.3,v 1.2 1996/03/18 22:33:20 thorpej 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 $Mdocdate: June 6 2025 $ +.Dt KVM_GETERR 3 +.Os +.Sh NAME +.Nm kvm_geterr +.Nd get error message on kvm descriptor +.Sh SYNOPSIS +.Lb libkvm +.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_getprocs 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_read 3 +.Sh BUGS +This routine cannot be used to access error conditions due to a failed +.Xr kvm_openfiles 3 +call, since failure is indicated by returning a +.Dv NULL +descriptor. +Therefore, errors on open are output to the special error buffer +passed to +.Xr kvm_openfiles 3 . +This option is not available to +.Xr kvm_open 3 . diff --git a/static/openbsd/man3/kvm_getfiles.3 b/static/openbsd/man3/kvm_getfiles.3 new file mode 100644 index 00000000..fe3e206e --- /dev/null +++ b/static/openbsd/man3/kvm_getfiles.3 @@ -0,0 +1,147 @@ +.\" $OpenBSD: kvm_getfiles.3,v 1.20 2025/06/06 21:53:13 schwarze Exp $ +.\" $NetBSD: kvm_getfiles.3,v 1.3 1996/03/18 22:33:23 thorpej 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 $Mdocdate: June 6 2025 $ +.Dt KVM_GETFILES 3 +.Os +.Sh NAME +.Nm kvm_getfiles +.Nd survey open files +.Sh SYNOPSIS +.Lb libkvm +.In kvm.h +.In sys/types.h +.In sys/sysctl.h +.Ft struct kinfo_file * +.Fn kvm_getfiles "kvm_t *kd" "int op" "int arg" "size_t elemsize" "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. +The value of +.Fa op +describes the filtering predicate as follows: +.Pp +.Bl -tag -width 20n -offset indent -compact +.It Dv KERN_FILE_BYFILE +all open files with type +.Fa arg +(0 for all files) +.It Dv KERN_FILE_BYPID +files opened by process ID +.Fa arg +(\-1 for all processes) +.It Dv KERN_FILE_BYUID +files opened by processes with effective user ID +.Fa arg +(\-1 for all users) +.El +.Pp +Files associated with a process will include information about +the process that has the file open. +.Pp +For +.Dv KERN_FILE_BYFILE +the recognized file types are defined in +.In sys/file.h : +.Pp +.Bl -tag -width 20n -offset indent -compact +.It Dv DTYPE_VNODE +files and devices +.It Dv DTYPE_SOCKET +sockets, regardless of domain +.It Dv DTYPE_PIPE +pipes and FIFOs +.It Dv DTYPE_KQUEUE +kqueues +.El +.Pp +Only the first +.Fa elemsize +bytes of each array entry are returned. +If the size of the +.Vt kinfo_file +structure increases in size in a future release of +.Ox , +the kernel will only return the requested amount of data for +each array entry and programs that use +.Fn kvm_getfiles +will continue to function without the need for recompilation. +.Sh RETURN VALUES +The files are returned as a contiguous array of +.Vt kinfo_file +structures. +The number of structures found is returned in the reference parameter +.Fa cnt . +This memory is owned by kvm and will be overwritten by subsequent calls to +.Fn kvm_getfiles +and destroyed by +.Fn kvm_close . +Data should be copied out if it needs to be saved. +.Pp +.Fn kvm_getfiles +will return +.Dv NULL +on failure. +.Sh ERRORS +.Fn kvm_getfiles +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Could not allocate enough memory for internal buffer. +.It Bq Er ESRCH +The +.Fa op +argument has +.Dv KERN_FILE_BYPID +value and the process specified by +.Fa arg +was not found. +.El +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_geterr 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_read 3 +.Sh BUGS +This routine does not belong in the kvm interface. diff --git a/static/openbsd/man3/kvm_getloadavg.3 b/static/openbsd/man3/kvm_getloadavg.3 new file mode 100644 index 00000000..419f0bd6 --- /dev/null +++ b/static/openbsd/man3/kvm_getloadavg.3 @@ -0,0 +1,64 @@ +.\" $OpenBSD: kvm_getloadavg.3,v 1.12 2025/06/06 21:53:13 schwarze Exp $ +.\" $NetBSD: kvm_getloadavg.3,v 1.2 1996/03/18 22:33:26 thorpej 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 $Mdocdate: June 6 2025 $ +.Dt KVM_GETLOADAVG 3 +.Os +.Sh NAME +.Nm kvm_getloadavg +.Nd get load average of the system +.Sh SYNOPSIS +.Lb libkvm +.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 indicated by +.Fa kd , +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 getloadavg 3 , +.Xr kvm 3 diff --git a/static/openbsd/man3/kvm_getprocs.3 b/static/openbsd/man3/kvm_getprocs.3 new file mode 100644 index 00000000..7d039ef9 --- /dev/null +++ b/static/openbsd/man3/kvm_getprocs.3 @@ -0,0 +1,188 @@ +.\" $OpenBSD: kvm_getprocs.3,v 1.22 2025/06/06 21:53:13 schwarze Exp $ +.\" $NetBSD: kvm_getprocs.3,v 1.13 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_getprocs.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd $Mdocdate: June 6 2025 $ +.Dt KVM_GETPROCS 3 +.Os +.Sh NAME +.Nm kvm_getprocs , +.Nm kvm_getargv , +.Nm kvm_getenvv +.Nd access user process state +.Sh SYNOPSIS +.Lb libkvm +.In sys/param.h +.In sys/sysctl.h +.In kvm.h +.Ft struct kinfo_proc * +.Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "size_t elemsize" "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" +.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 Dv KERN_PROC_KTHREAD +all processes (user-level plus kernel threads) +.It Dv KERN_PROC_ALL +all user-level processes +.It Dv KERN_PROC_PID +processes with process ID +.Fa arg +.It Dv KERN_PROC_PGRP +processes with process group +.Fa arg +.It Dv KERN_PROC_SESSION +processes with session +.Fa arg +.It Dv KERN_PROC_TTY +processes with +.Xr tty 4 +.Fa arg +.It Dv KERN_PROC_UID +processes with effective user ID +.Fa arg +.It Dv KERN_PROC_RUID +processes with real user ID +.Fa arg +.El +.Pp +Only the first +.Fa elemsize +bytes of each array entry are returned. +If the size of the +.Vt kinfo_proc +structure increases in size in a future release of +.Ox , +the library will only return the requested amount of data for +each array entry and programs that use +.Fn kvm_getprocs +will continue to function without the need for recompilation. +The number of processes found is returned in the reference parameter +.Fa cnt . +The processes are returned as a contiguous array of +.Vt kinfo_proc +structures, the definition for which is available in +.In sys/sysctl.h . +This memory is locally allocated, and subsequent calls to +.Fn kvm_getprocs +and +.Fn kvm_close +will overwrite this storage. +.Pp +.Fn kvm_getprocs +sets the thread ID field accordingly for each thread except for the +process (main thread) which has it set to \-1. +.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 execve 2 +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 +.Va 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 +.Li argv +pointers and string storage is owned by the +.Xr kvm 3 +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. +.Sh RETURN VALUES +.Fn kvm_getprocs , +.Fn kvm_getargv , +and +.Fn kvm_getenvv +all return +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_geterr 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_read 3 +.Sh BUGS +These routines do not belong in the +.Xr kvm 3 +interface. diff --git a/static/openbsd/man3/kvm_nlist.3 b/static/openbsd/man3/kvm_nlist.3 new file mode 100644 index 00000000..b67df2b0 --- /dev/null +++ b/static/openbsd/man3/kvm_nlist.3 @@ -0,0 +1,92 @@ +.\" $OpenBSD: kvm_nlist.3,v 1.11 2025/06/06 21:53:13 schwarze Exp $ +.\" $NetBSD: kvm_nlist.3,v 1.3 1996/03/18 22:33:48 thorpej 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 $Mdocdate: June 6 2025 $ +.Dt KVM_NLIST 3 +.Os +.Sh NAME +.Nm kvm_nlist +.Nd retrieve symbol table names from a kernel image +.Sh SYNOPSIS +.Lb libkvm +.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 +.Fa n_name +field is +.Dv NULL +(see +.Xr nlist 3 ) . +Each symbol is looked up using the +.Fa n_name +field, and if found, the +corresponding +.Fa n_type +and +.Fa n_value +fields are filled in. +These fields are set +to 0 if the symbol is not found. +.Pp +The program +.Xr kvm_mkdb 8 +builds a database from the running kernel's namelist. +If the database matches the opened kernel, +.Fn kvm_nlist +uses it to speed lookups. +.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 /var/db/kvm_bsd.db -compact +.It Pa /var/db/kvm_bsd.db +.El +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_geterr 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_open 3 , +.Xr kvm_read 3 , +.Xr kvm_mkdb 8 diff --git a/static/openbsd/man3/kvm_open.3 b/static/openbsd/man3/kvm_open.3 new file mode 100644 index 00000000..72111e19 --- /dev/null +++ b/static/openbsd/man3/kvm_open.3 @@ -0,0 +1,203 @@ +.\" $OpenBSD: kvm_open.3,v 1.19 2025/06/06 21:53:13 schwarze Exp $ +.\" $NetBSD: kvm_open.3,v 1.2 1996/03/18 22:33:52 thorpej 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 $Mdocdate: June 6 2025 $ +.Dt KVM_OPEN 3 +.Os +.Sh NAME +.Nm kvm_open , +.Nm kvm_openfiles , +.Nm kvm_close +.Nd initialize kernel virtual memory access +.Sh SYNOPSIS +.Lb libkvm +.In fcntl.h +.In kvm.h +.Ft kvm_t * +.Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr" +.Ft kvm_t * +.Fn kvm_openfiles "const char *execfile" "const char *corefile" "const 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, +which is indicated by +.Dv _PATH_KSYMS , +if it exists, otherwise +.Dv _PATH_UNIX +is used. +Both are defined 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 , +no swap device will be used. +.Pp +The +.Fa flags +argument indicates read/write access as in +.Xr open 2 +and applies only to the core file. +Only +.Dv O_RDONLY , +.Dv O_WRONLY , +and +.Dv O_RDWR +are permitted. +A special value +.Dv KVM_NO_FILES +can be specified which will cause no files to be opened and the handle +can only be used on live kernels on a limited subset of all kvm operations. +.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 +.Dv _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_geterr 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_nlist 3 , +.Xr kvm_read 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/openbsd/man3/kvm_read.3 b/static/openbsd/man3/kvm_read.3 new file mode 100644 index 00000000..4f7adb24 --- /dev/null +++ b/static/openbsd/man3/kvm_read.3 @@ -0,0 +1,88 @@ +.\" $OpenBSD: kvm_read.3,v 1.10 2025/06/06 21:53:13 schwarze Exp $ +.\" $NetBSD: kvm_read.3,v 1.2 1996/03/18 22:34:01 thorpej 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 $Mdocdate: June 6 2025 $ +.Dt KVM_READ 3 +.Os +.Sh NAME +.Nm kvm_read , +.Nm kvm_write +.Nd read or write kernel virtual memory +.Sh SYNOPSIS +.Lb libkvm +.In kvm.h +.Ft ssize_t +.Fn kvm_read "kvm_t *kd" "u_long addr" "void *buf" "size_t nbytes" +.Ft ssize_t +.Fn kvm_write "kvm_t *kd" "u_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 +.Xr kvm_open 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 successful completion, the number of bytes actually transferred is +returned. +Otherwise, \-1 is returned. +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_geterr 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 diff --git a/static/openbsd/man3/labs.3 b/static/openbsd/man3/labs.3 new file mode 100644 index 00000000..f3fd6fd5 --- /dev/null +++ b/static/openbsd/man3/labs.3 @@ -0,0 +1,88 @@ +.\" 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. +.\" +.\" $OpenBSD: labs.3,v 1.17 2019/01/18 07:32:17 schwarze Exp $ +.\" +.Dd $Mdocdate: January 18 2019 $ +.Dt LABS 3 +.Os +.Sh NAME +.Nm labs , +.Nm llabs , +.Nm qabs +.Nd return the absolute value of a long integer +.Sh SYNOPSIS +.In limits.h +.In stdlib.h +.Ft long +.Fn labs "long i" +.Ft long long +.Fn llabs "long long j" +.Ft quad_t +.Fn qabs "quad_t j" +.Sh DESCRIPTION +The +.Fn labs +function returns the absolute value of the long integer +.Fa i . +The +.Fn llabs +function returns the absolute value of the long long integer +.Fa j . +.Pp +The +.Fn qabs +function is a deprecated equivalent of +.Fn llabs . +.Sh SEE ALSO +.Xr abs 3 , +.Xr cabs 3 , +.Xr floor 3 , +.Xr imaxabs 3 +.Sh STANDARDS +The +.Fn labs +and +.Fn llabs +functions conform to +.St -isoC-99 . +.Sh CAVEATS +The results of applying +.Fn labs +to +.Dv LONG_MIN +and +.Fn llabs +to +.Dv LLONG_MIN +are undefined, and +.Fn qabs +is not portable in the first place. diff --git a/static/openbsd/man3/ldexp.3 b/static/openbsd/man3/ldexp.3 new file mode 100644 index 00000000..67742cda --- /dev/null +++ b/static/openbsd/man3/ldexp.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: ldexp.3,v 1.9 2025/06/06 21:50:10 schwarze 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. +.\" +.Dd $Mdocdate: June 6 2025 $ +.Dt LDEXP 3 +.Os +.Sh NAME +.Nm ldexp , +.Nm ldexpf , +.Nm ldexpl +.Nd multiply floating-point number by integral power of 2 +.Sh SYNOPSIS +.Lb libm +.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 +function multiplies a floating-point number by an integral +power of 2. +The +.Fn ldexpf +function is a single precision version of +.Fn ldexp . +The +.Fn ldexpl +function is an extended precision version of +.Fn ldexp . +.Sh RETURN VALUES +The +.Fn ldexp , +.Fn ldexpf +and +.Fn ldexpl +functions return the value of +.Fa x +times 2 raised to the power +.Fa exp . +.Pp +If the resultant value would cause an overflow, +the global variable +.Va errno +is set to +.Er ERANGE +and the value +.Dv HUGE +is returned. +.Sh SEE ALSO +.Xr frexp 3 , +.Xr modf 3 +.Sh STANDARDS +The +.Fn ldexp +function conforms to +.St -ansiC . diff --git a/static/openbsd/man3/ldiv.3 b/static/openbsd/man3/ldiv.3 new file mode 100644 index 00000000..c7ddc85a --- /dev/null +++ b/static/openbsd/man3/ldiv.3 @@ -0,0 +1,71 @@ +.\" 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. +.\" +.\" $OpenBSD: ldiv.3,v 1.14 2022/09/11 06:38:11 jmc Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt LDIV 3 +.Os +.Sh NAME +.Nm ldiv +.Nd return quotient and remainder from division +.Sh SYNOPSIS +.In stdlib.h +.Ft ldiv_t +.Fn ldiv "long num" "long denom" +.Sh DESCRIPTION +The +.Fn ldiv +function computes the value +.Fa num Ns / Ns Fa denom +and returns the quotient and remainder in a structure named +.Vt ldiv_t +that contains two +.Vt long integer +members named +.Fa quot +and +.Fa rem . +.Sh SEE ALSO +.Xr div 3 , +.Xr imaxdiv 3 , +.Xr lldiv 3 +.Sh STANDARDS +The +.Fn ldiv +function conforms to +.St -ansiC . +.Sh HISTORY +An +.Fn ldiv +function with similar functionality, but a different calling convention, +first appeared in +.At v4 . diff --git a/static/openbsd/man3/legacy_coding.3 b/static/openbsd/man3/legacy_coding.3 new file mode 100644 index 00000000..0c8f84b9 --- /dev/null +++ b/static/openbsd/man3/legacy_coding.3 @@ -0,0 +1,75 @@ +.\"*************************************************************************** +.\" Copyright 2020-2021,2022 Thomas E. Dickey * +.\" Copyright 2005-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey +.\" +.\" $Id: legacy_coding.3,v 1.2 2023/10/17 09:52:08 nicm Exp $ +.TH legacy_coding 3 2022-02-12 "ncurses 6.4" "Library calls" +.SH NAME +\fBuse_legacy_coding\fP \- override locale-encoding checks +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint use_legacy_coding(int \fIlevel\fB);\fR +.SH DESCRIPTION +The \fBuse_legacy_coding\fP function is an extension to the curses library. +It allows the caller to change the result of \fBunctrl\fP, +and suppress related checks within the library that would normally +cause nonprinting characters to be rendered in visible form. +This affects only 8-bit characters. +.PP +The \fIlevel\fP parameter controls the result: +.RS +.TP 5 +0 +the library functions normally, +rendering nonprinting characters as described in \fBunctrl\fP. +.TP +1 +the library ignores \fBisprintf\fP for codes in the range 160-255. +.TP +2 +the library ignores \fBisprintf\fP for codes in the range 128-255. +It also modifies the output of \fBunctrl\fP, showing codes in the +range 128-159 as is. +.RE +.SH RETURN VALUE +If the screen has not been initialized, +or the \fIlevel\fP parameter is out of range, +the function returns \fBERR\fP. +Otherwise, it returns the previous level: \fB0\fP, \fB1\fP or \fB2\fP. +.SH PORTABILITY +This routine is specific to ncurses. +It was not supported on Version 7, BSD or System V implementations. +It is recommended that any code depending on ncurses extensions +be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBunctrl\fP(3). +.SH AUTHOR +Thomas Dickey (to support lynx's font-switching feature). diff --git a/static/openbsd/man3/lgamma.3 b/static/openbsd/man3/lgamma.3 new file mode 100644 index 00000000..08dc93ff --- /dev/null +++ b/static/openbsd/man3/lgamma.3 @@ -0,0 +1,194 @@ +'\" e +.\" $OpenBSD: lgamma.3,v 1.29 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt LGAMMA 3 +.Os +.Sh NAME +.Nm lgamma , +.Nm lgammaf , +.Nm lgammal , +.Nm lgamma_r , +.Nm lgammaf_r , +.Nm lgammal_r , +.Nm tgamma , +.Nm tgammaf , +.Nm tgammal , +.Nm gamma , +.Nm gammaf +.Nd log gamma functions +.Sh SYNOPSIS +.Lb libm +.In math.h +.Vt extern int signgam ; +.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 *signgamp" +.Ft float +.Fn lgammaf_r "float x" "int *signgamp" +.Ft long double +.Fn lgammal_r "long double x" "int *signgamp" +.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 +returns ln\||\(*G(x)| where +.Bd -filled -offset indent +.EQ +GAMMA left ( x right ) = +int from 0 to inf t sup {x - 1} e sup -t dt +.EN +\ \ \ for x > 0 and +.br +.EQ +GAMMA left ( x right ) = +pi over { GAMMA left ( 1 - x right ) sin left ( pi x right ) } +.EN +\ \ \ for x < 1. +.Ed +.Pp +The external integer +.Va signgam +returns the sign of \(*G(x). +The +.Fn lgammaf +function is a single precision version of +.Fn lgamma . +The +.Fn lgammal +function is an extended precision version of +.Fn lgamma . +.Pp +The +.Fn lgamma_r , +.Fn lgammaf_r , +and +.Fn lgammal_r +functions are thread-safe versions of +.Fn lgamma , +.Fn lgammaf , +and +.Fn lgammal +that return the sign via the +.Fa signgamp +pointer instead of modifying +.Va signgam . +.Pp +The +.Fn tgamma x , +.Fn tgammaf x +and +.Fn tgammal x +functions return \(*G(x), with no effect on +.Va signgam . +.Sh IDIOSYNCRASIES +Do not use the expression +.Sq 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 +.Va signgam +be correct. +.Pp +For arguments in its range, +.Fn tgamma +is preferred, as for positive arguments +it is accurate to within one unit in the last place. +.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. +.Sh STANDARDS +The +.Fn lgamma , +.Fn lgammaf , +.Fn lgammal , +.Fn tgamma , +.Fn tgammaf , +and +.Fn tgammal +functions are expected to conform to +.St -isoC-99 . +.Pp +The +.Fn lgamma_r , +.Fn lgammaf_r , +and +.Fn lgammal_r +functions are +.Bx +extensions. +.Pp +.Fn gamma +and +.Fn gammaf +are deprecated aliases for +.Fn lgamma +and +.Fn lgammaf , +respectively. +.Sh HISTORY +A +.Fn gamma +function first appeared in +.At v5 . +The +.Fn lgamma +function first appeared in +.Bx 4.3 . +The +.Fn tgamma +function first appeared in +.Ox 4.4 , +and is based on the +.Fn gamma +function that appeared in +.Bx 4.4 +as a function to compute \(*G(x). diff --git a/static/openbsd/man3/lh_new.3 b/static/openbsd/man3/lh_new.3 new file mode 100644 index 00000000..cc0b3d6b --- /dev/null +++ b/static/openbsd/man3/lh_new.3 @@ -0,0 +1,555 @@ +.\" $OpenBSD: lh_new.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL doc/crypto/lhash.pod 1bc74519 May 20 08:11:46 2016 -0400 +.\" selective merge up to: +.\" OpenSSL doc/man3/OPENSSL_LH_COMPFUNC.pod 24a535ea Sep 22 13:14:20 2020 +0100 +.\" +.\" -------------------------------------------------------------------------- +.\" Major patches to this file were contributed by +.\" Ulf Moeller , Geoff Thorpe , +.\" and Ben Laurie . +.\" -------------------------------------------------------------------------- +.\" Copyright (c) 2000, 2001, 2002, 2008, 2009 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" -------------------------------------------------------------------------- +.\" Parts of this file are derived from SSLeay documentation, +.\" which is covered by the following Copyright and license: +.\" -------------------------------------------------------------------------- +.\" +.\" Copyright (C) 1995-1998 Tim Hudson (tjh@cryptsoft.com) +.\" All rights reserved. +.\" +.\" This package is an SSL implementation written +.\" by Eric Young (eay@cryptsoft.com). +.\" The implementation was written so as to conform with Netscapes SSL. +.\" +.\" This library is free for commercial and non-commercial use as long as +.\" the following conditions are aheared to. The following conditions +.\" apply to all code found in this distribution, be it the RC4, RSA, +.\" lhash, DES, etc., code; not just the SSL code. The SSL documentation +.\" included with this distribution is covered by the same copyright terms +.\" except that the holder is Tim Hudson (tjh@cryptsoft.com). +.\" +.\" Copyright remains Eric Young's, and as such any Copyright notices in +.\" the code are not to be removed. +.\" If this package is used in a product, Eric Young should be given +.\" attribution as the author of the parts of the library used. +.\" This can be in the form of a textual message at program startup or +.\" in documentation (online or textual) provided with the package. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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 cryptographic software written by +.\" Eric Young (eay@cryptsoft.com)" +.\" The word 'cryptographic' can be left out if the rouines from the +.\" library being used are not cryptographic related :-). +.\" 4. If you include any Windows specific code (or a derivative thereof) +.\" from the apps directory (application code) you must include an +.\" acknowledgement: "This product includes software written by +.\" Tim Hudson (tjh@cryptsoft.com)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY ERIC 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 THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" The licence and distribution terms for any publically available version or +.\" derivative of this code cannot be changed. i.e. this code cannot simply be +.\" copied and put under another distribution licence +.\" [including the GNU Public Licence.] +.\" +.Dd $Mdocdate: June 8 2025 $ +.Dt LH_NEW 3 +.Os +.Sh NAME +.Nm lh_new , +.Nm lh_free , +.Nm lh_insert , +.Nm lh_delete , +.Nm lh_retrieve , +.Nm lh_doall , +.Nm lh_doall_arg , +.Nm lh_error , +.Nm LHASH_COMP_FN_TYPE , +.Nm LHASH_HASH_FN_TYPE , +.Nm LHASH_DOALL_FN_TYPE , +.Nm LHASH_DOALL_ARG_FN_TYPE , +.Nm lh_strhash +.Nd dynamic hash table +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/lhash.h +.Fn DECLARE_LHASH_OF +.Ft LHASH * +.Fn lh__new void +.Ft void +.Fo lh__free +.Fa "LHASH_OF() *table" +.Fc +.Ft * +.Fo lh__insert +.Fa "LHASH_OF() *table" +.Fa " *data" +.Fc +.Ft * +.Fo lh__delete +.Fa "LHASH_OF() *table" +.Fa " *data" +.Fc +.Ft * +.Fo lh__retrieve +.Fa "LHASH_OF() *table" +.Fa " *data" +.Fc +.Ft void +.Fo lh__doall +.Fa "LHASH_OF() *table" +.Fa "LHASH_DOALL_FN_TYPE func" +.Fc +.Ft void +.Fo lh__doall_arg +.Fa "LHASH_OF() *table" +.Fa "LHASH_DOALL_ARG_FN_TYPE func" +.Fa "" +.Fa " *arg" +.Fc +.Ft int +.Fo lh__error +.Fa "LHASH_OF() *table" +.Fc +.Ft typedef int +.Fo (*LHASH_COMP_FN_TYPE) +.Fa "const void *" +.Fa "const void *" +.Fc +.Ft typedef unsigned long +.Fo (*LHASH_HASH_FN_TYPE) +.Fa "const void *" +.Fc +.Ft typedef void +.Fo (*LHASH_DOALL_FN_TYPE) +.Fa "const void *" +.Fc +.Ft typedef void +.Fo (*LHASH_DOALL_ARG_FN_TYPE) +.Fa "const void *" +.Fa "const void *" +.Fc +.Ft unsigned long +.Fo lh_strhash +.Fa "const char *c" +.Fc +.Sh 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 +.Fn lh__new +creates a new +.Vt LHASH_OF() +structure to store arbitrary data entries, and provides the hash and +compare callbacks to be used in organising the table's entries. +The hash 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 compare 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 +hash and compare callbacks hash and compare these types, then the +.Fn DECLARE_LHASH_HASH_FN +and +.Fn IMPLEMENT_LHASH_COMP_FN +macros can be used to create callback wrappers of the prototypes +required by +.Fn lh__new . +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 doall callbacks, are +defined as; +.Bd -literal -offset 2n +#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 +.Ed +.Pp +An example of a hash table storing (pointers to) structures of type +\&'STUFF' could be defined as follows; +.Bd -literal -offset 2n +/* Calculate the hash value of 'tohash' (implemented elsewhere) */ +unsigned long STUFF_hash(const STUFF *tohash); +/* Order 'arg1' and 'arg2' (implemented elsewhere) */ +int stuff_cmp(const STUFF *arg1, const STUFF *arg2); +/* Create 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)); + /* ... */ +} +.Ed +.Pp +.Fn lh__free +frees the +.Vt LHASH_OF() +structure +.Fa table . +Allocated hash table entries will not be freed; consider using +.Fn lh__doall +to deallocate any remaining entries in the hash table (see below). +.Pp +.Fn lh__insert +inserts the structure pointed to by +.Fa data +into +.Fa table . +If there already is an entry with the same key, the old value is +replaced. +Note that +.Fn lh__insert +stores pointers, the data are not copied. +.Pp +.Fn lh__delete +deletes an entry from +.Fa table . +.Pp +.Fn lh__retrieve +looks up an entry in +.Fa table . +Normally, +.Fa data +is a structure with the key field(s) set; the function will return a +pointer to a fully populated structure. +.Pp +.Fn lh__doall +will, for every entry in the hash table, call +.Fa func +with the data item as its parameter. +For +.Fn lh__doall +and +.Fn lh__doall_arg , +function pointer casting should be avoided in the callbacks (see +.Sx NOTES ) +\(em 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: +.Bd -literal -offset 2n +/* Clean up resources belonging to 'a' (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); +.Ed +.Pp +A callback may delete entries from the hash table, however, it is +not safe to insert new entries. +.Pp +.Fn lh__doall_arg +is the same as +.Fn lh__doall +except that +.Fa func +will be called with +.Fa arg +as the second argument and +.Fa func +should be of type +.Vt LHASH_DOALL_ARG_FN_TYPE +(a callback prototype that is passed both the table entry and an extra +argument). +As with +.Fn lh__doall , +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): +.Bd -literal -offset 2n +/* Print item 'a' to 'output_bio' (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); +.Ed +.Pp +.Fn lh__error +can be used to determine if an error occurred in the last operation. +.Sh RETURN VALUES +.Fn lh__new +returns +.Dv NULL +on error, otherwise a pointer to the new +.Vt LHASH +structure. +.Pp +When a hash table entry is replaced, +.Fn lh__insert +returns the value being replaced. +.Dv NULL +is returned on normal operation and on error. +.Pp +.Fn lh__delete +returns the entry being deleted. +.Dv NULL +is returned if there is no such value in the hash table. +.Pp +.Fn lh__retrieve +returns the hash table entry if it has been found, or +.Dv NULL +otherwise. +.Pp +.Fn lh__error +returns 1 if an error occurred in the last operation, or 0 otherwise. +.Sh NOTES +The various LHASH macros and callback types exist to make it possible to +write type-checked code without resorting to function-prototype casting +\(em 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 LHASH code regards table entries as constant data. +As such, it internally represents +.Fn lh__insert Ap ed +items with a +.Vt const void * +pointer type. +This is why callbacks such as those used by +.Fn lh__doall +and +.Fn lh__doall_arg +declare their prototypes with "const", even for the parameters that pass +back the table items' data pointers \(em 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) \(em 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 +.Fn lh__doall +or +.Fn lh__doall_arg +callbacks (see the "STUFF_cleanup" example above). +If so, the caller can either cast the "const" away (if they're 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 are 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 INTERNALS +The following description is based on the SSLeay documentation: +.Pp +The lhash library implements a hash table described in the +.Em Communications of the ACM +in 1991. +What makes this hash table different is that as the table fills, +the hash table is increased (or decreased) in size via +.Xr reallocarray 3 . +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 +.Vt LHASH +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 +.Fa up_load +has a default value of 1 and +.Fa down_load +has a default value of 2. +These numbers can be modified by the application by just playing +with the +.Fa up_load +and +.Fa down_load +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 +.Fa 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 +.Vt unsigned long +compares and 10 linked list traverses. +This will be much less expensive that 10 calls to your compare function. +.Pp +.Fn lh_strhash +is a demo string hashing function. +Since the LHASH routines would normally be passed structures, this +routine would not normally be passed to +.Fn lh__new , +rather it would be used in the function passed to +.Fn lh__new . +.Sh SEE ALSO +.Xr crypto 3 +.Sh HISTORY +.Fn lh_new , +.Fn lh_free , +.Fn lh_insert , +.Fn lh_delete , +.Fn lh_retrieve , +.Fn lh_doall , +and +.Fn lh_strhash +appeared in SSLeay 0.4 or earlier. +.Fn lh_doall_arg +first appeared in SSLeay 0.5.1. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn lh__error +was added in SSLeay 0.9.1b. +.Pp +In OpenSSL 0.9.7, all lhash functions that were passed function pointers +were changed for better type safety, and the function types +.Vt LHASH_COMP_FN_TYPE , +.Vt LHASH_HASH_FN_TYPE , +.Vt LHASH_DOALL_FN_TYPE , +and +.Vt LHASH_DOALL_ARG_FN_TYPE +became available. +.Pp +In OpenSSL 1.0.0, the lhash interface was revamped for even better type +checking. +.Sh BUGS +.Fn lh__insert +returns +.Dv NULL +both for success and error. diff --git a/static/openbsd/man3/link_ntoa.3 b/static/openbsd/man3/link_ntoa.3 new file mode 100644 index 00000000..89536774 --- /dev/null +++ b/static/openbsd/man3/link_ntoa.3 @@ -0,0 +1,78 @@ +.\" $OpenBSD: link_ntoa.3,v 1.2 2015/09/10 10:14:20 jmc 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. +.\" +.Dd $Mdocdate: September 10 2015 $ +.Dt LINK_NTOA 3 +.Os +.Sh NAME +.Nm link_ntoa +.Nd elementary address specification routine for link level access +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/if_dl.h +.Ft char * +.Fn link_ntoa "const struct sockaddr_dl *sdl" +.Sh DESCRIPTION +The +.Fn link_ntoa +function 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. +.Sh RETURN VALUES +.Fn link_ntoa +always returns a NUL-terminated string. +.Sh SEE ALSO +.Xr ifconfig 8 +.Sh HISTORY +The +.Fn link_ntoa +function appeared in +.Bx 4.3 Reno . +.Sh BUGS +The returned values for +.Fn link_ntoa +reside in a static memory area. +.Pp +If the +.Fa 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. diff --git a/static/openbsd/man3/lldiv.3 b/static/openbsd/man3/lldiv.3 new file mode 100644 index 00000000..539d7b51 --- /dev/null +++ b/static/openbsd/man3/lldiv.3 @@ -0,0 +1,73 @@ +.\" 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. +.\" +.\" $OpenBSD: lldiv.3,v 1.9 2022/09/11 06:38:11 jmc Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt LLDIV 3 +.Os +.Sh NAME +.Nm lldiv , +.Nm qdiv +.Nd return quotient and remainder from division +.Sh SYNOPSIS +.In stdlib.h +.Ft lldiv_t +.Fn lldiv "long long num" "long long denom" +.Ft qdiv_t +.Fn qdiv "quad_t num" "quad_t denom" +.Sh DESCRIPTION +The +.Fn lldiv +function computes the value +.Fa num Ns / Ns Fa denom +and returns the quotient and remainder in a structure named +.Vt lldiv_t +that contains two +.Vt long long integer +members named +.Fa quot +and +.Fa rem . +.Pp +The +.Fn qdiv +function is a deprecated equivalent of +.Fn lldiv . +.Sh SEE ALSO +.Xr div 3 , +.Xr imaxdiv 3 , +.Xr ldiv 3 +.Sh STANDARDS +The +.Fn lldiv +function conforms to +.St -isoC-99 . diff --git a/static/openbsd/man3/localeconv.3 b/static/openbsd/man3/localeconv.3 new file mode 100644 index 00000000..8818330a --- /dev/null +++ b/static/openbsd/man3/localeconv.3 @@ -0,0 +1,198 @@ +.\" $OpenBSD: localeconv.3,v 1.4 2022/09/11 06:38:10 jmc Exp $ +.\" $NetBSD: setlocale.3,v 1.3 1997/07/14 23:19:47 kleink 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 $Mdocdate: September 11 2022 $ +.Dt LOCALECONV 3 +.Os +.Sh NAME +.Nm localeconv +.Nd retrieve parameters for locale-dependent formatting of numbers +.Sh SYNOPSIS +.In locale.h +.Ft struct lconv * +.Fn localeconv "void" +.Sh DESCRIPTION +The +.Fn localeconv +function returns a pointer to a static structure +which provides parameters for +.Xr locale 1 Ns -dependent +formatting of numbers. +On +.Ox , +nothing in the returned structure ever changes. +On other operating systems, the contents of the structure may vary +according to the +.Dv LC_NUMERIC +and +.Dv LC_MONETARY +locale categories. +.Pp +It provides the following fields of type +.Vt char * : +.Bl -tag -width mon_decimal_point +.It Fa decimal_point +The decimal point character, except for currency values. +.It Fa thousands_sep +The separator between groups of digits +before the decimal point, except for currency values. +.It Fa grouping +The sizes of the groups of digits, except for currency values. +This is a pointer to a vector of integers, each of size +.Vt 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 international currency symbol. +.It Fa currency_symbol +The local currency symbol. +.It Fa mon_decimal_point +The decimal point character for currency values. +.It Fa mon_thousands_sep +The separator for digit groups in currency values. +.It Fa mon_grouping +Like +.Fa grouping +but for currency values. +.It Fa positive_sign +The character used to denote non-negative currency values, +usually the empty string. +.It Fa negative_sign +The character used to denote negative currency values, +usually a minus sign. +.El +.Pp +It also provides the following fields of type +.Vt char : +.Bl -tag -width mon_decimal_point +.It Fa int_frac_digits +The number of digits after the decimal point +in an international-style currency value. +.It Fa frac_digits +The number of digits after the decimal point +in the local style for currency values. +.It Fa p_cs_precedes +1 if the currency symbol precedes the currency value +for non-negative values, 0 if it follows. +.It Fa p_sep_by_space +1 if a space is inserted between the currency symbol +and the currency value for non-negative 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 non-negative quantity and the +.Fa currency_symbol , +coded as follows: +.Pp +.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 +.It Fa n_sign_posn +Like +.Fa p_sign_posn +but for negative currency values. +.It Fa int_p_cs_precedes +Like +.Fa p_cs_precedes +but for the international symbol. +.It Fa int_n_cs_precedes +Like +.Fa n_cs_precedes +but for the international symbol. +.It Fa int_p_sep_by_space +Like +.Fa p_sep_by_space +but for the international symbol. +.It Fa int_n_sep_by_space +Like +.Fa n_sep_by_space +but for the international symbol. +.It Fa int_p_sign_posn +Like +.Fa p_sign_posn +but for the international symbol. +.It Fa int_n_sign_posn +Like +.Fa n_sign_posn +but for the international 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 SEE ALSO +.Xr locale 1 , +.Xr nl_langinfo 3 , +.Xr setlocale 3 +.Sh STANDARDS +The +.Fn localeconv +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn localeconv +function first appeared in +.Bx 4.3 Net/2 . diff --git a/static/openbsd/man3/lockf.3 b/static/openbsd/man3/lockf.3 new file mode 100644 index 00000000..d2561f54 --- /dev/null +++ b/static/openbsd/man3/lockf.3 @@ -0,0 +1,259 @@ +.\" $OpenBSD: lockf.3,v 1.14 2022/09/11 06:38:10 jmc Exp $ +.\" $NetBSD: lockf.3,v 1.1 1997/12/20 20:23:17 kleink 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 $Mdocdate: September 11 2022 $ +.Dt LOCKF 3 +.Os +.Sh NAME +.Nm lockf +.Nd record locking on files +.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 +.Pq Dv O_WRONLY +or read/write +.Pq 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 +The +.Dv F_ULOCK +function 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 +The +.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) of 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 the file if +.Fa 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 +.Fa size +is non-zero and the offset of the last byte of +the requested section is the maximum value for an object of type +.Vt 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 the global variable +.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 +.Sh STANDARDS +The +.Fn lockf +function conforms to +.St -xpg4.2 . diff --git a/static/openbsd/man3/logb.3 b/static/openbsd/man3/logb.3 new file mode 100644 index 00000000..7a37c7a6 --- /dev/null +++ b/static/openbsd/man3/logb.3 @@ -0,0 +1,117 @@ +.\" $OpenBSD: logb.3,v 1.11 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt LOGB 3 +.Os +.Sh NAME +.Nm logb , +.Nm logbf , +.Nm logbl , +.Nm scalb , +.Nm scalbf , +.Nm scalbl , +.Nm significand , +.Nm significandf +.Nd IEEE test functions +.Sh SYNOPSIS +.Lb libm +.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 long double +.Fn scalbl "long double x" "long double 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 not otherwise recommended. +.Pp +.Fn logb x +returns +.Fa x Ns 's exponent +.Fa n , +a signed integer converted to double\-precision floating\-point. +.Fn logb \(+-infinity += +infinity; +.Fn logb 0 += -infinity with a division by zero exception. +.Fn logbf +is the single precision form of +.Fn logb . +.Fn logbl +is the extended precision form of +.Fn logb . +.Pp +.Fn scalb x n +returns +.Fa x Ns *(2** Ns Fa n ) +computed by exponent manipulation. +.Fn scalbf +is the single precision form of +.Fn scalb . +.Fn scalbl +is the extended precision form of +.Fn scalb . +.Pp +.Fn significand x +returns +.Fa sig , +where +.Fa x +:= +.Fa sig No * 2** Ns Fa n +with 1 \(<= +.Fa sig +< 2. +.Fn significand x +is not defined when +.Fa x +is 0, \(+-infinity, or NaN. +.Fn significandf +is the single precision for of +.Fn significand . +.Sh SEE ALSO +.Xr fpclassify 3 , +.Xr ilogb 3 , +.Xr scalbn 3 +.Sh STANDARDS +.St -ieee754 diff --git a/static/openbsd/man3/login.3 b/static/openbsd/man3/login.3 new file mode 100644 index 00000000..16209344 --- /dev/null +++ b/static/openbsd/man3/login.3 @@ -0,0 +1,107 @@ +.\" $OpenBSD: login.3,v 1.7 2025/06/06 22:01:40 schwarze 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 $Mdocdate: June 6 2025 $ +.Dt LOGIN 3 +.Os +.Sh NAME +.Nm login , +.Nm logout , +.Nm logwtmp +.Nd login utility functions +.Sh SYNOPSIS +.Lb libutil +.In utmp.h +.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/openbsd/man3/login_cap.3 b/static/openbsd/man3/login_cap.3 new file mode 100644 index 00000000..6116906f --- /dev/null +++ b/static/openbsd/man3/login_cap.3 @@ -0,0 +1,342 @@ +.\" +.\" 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. +.\" +.\" $OpenBSD: login_cap.3,v 1.27 2026/01/16 17:06:50 schwarze Exp $ +.\" BSDI $From: login_cap.3,v 1.4 1997/11/07 16:22:27 jch Exp $ +.\" +.Dd $Mdocdate: January 16 2026 $ +.Dt LOGIN_GETCLASS 3 +.Os +.Sh NAME +.Nm login_getclass , +.Nm login_getstyle , +.Nm login_getcapbool , +.Nm login_getcapnum , +.Nm login_getcapsize , +.Nm login_getcapstr , +.Nm login_getcaptime , +.Nm login_close , +.Nm setclasscontext , +.Nm setusercontext +.Nd query login.conf database about a user class +.Sh SYNOPSIS +.In sys/types.h +.In login_cap.h +.Ft login_cap_t * +.Fn login_getclass "char *class" +.Ft char * +.Fn login_getstyle "login_cap_t *lc" "char *style" "char *type" +.Ft int +.Fn login_getcapbool "login_cap_t *lc" "char *cap" "unsigned int def" +.Ft quad_t +.Fn login_getcapnum "login_cap_t *lc" "char *cap" "quad_t def" "quad_t err" +.Ft quad_t +.Fn login_getcapsize "login_cap_t *lc" "char *cap" "quad_t def" "quad_t err" +.Ft char * +.Fn login_getcapstr "login_cap_t *lc" "char *cap" "char *def" "char *err" +.Ft quad_t +.Fn login_getcaptime "login_cap_t *lc" "char *cap" "quad_t def" "quad_t err" +.Ft void +.Fn login_close "login_cap_t *lc" +.Ft int +.Fn setclasscontext "char *class" "unsigned int flags" +.Ft int +.Fn setusercontext "login_cap_t *lc" "struct passwd *pwd" "uid_t uid" "unsigned int flags" +.Sh DESCRIPTION +The +.Fn login_getclass +function extracts the entry specified by +.Ar class +(or +.Li default +if +.Ar class +is +.Dv NULL +or the empty string) from +.Pa /etc/login.conf +(see +.Xr login.conf 5 ) . +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 +Once +.Ar lc +has been returned by +.Fn login_getclass , +any of the other +.Fn login_* +functions may be called. +The +.Fn login_getstyle +function is used to obtain the style of authentication that should be used for +this user class. +The +.Ar style +argument may either be +.Dv NULL +or the desired style of authentication. +If +.Dv NULL , +the first available authentication style will be used. +The +.Ar type +argument refers to the type of authentication being performed. +This is used to override the standard +.Li auth +entry in the database. +By convention this should be of the form "auth-type". +Future releases may remove the requirement for the "auth-" prefix and add +it if it is missing. +If +.Ar type +is +.Dv NULL +then only "auth" will be looked at +(see +.Xr login.conf 5 ) . +The +.Fn login_getstyle +function will return +.Dv NULL +if the desired style of authentication is not available, +or if no style is available. +.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 +.Ar cap . +If the field is found, its value is returned. +If the field is not found, the value specified by +.Ar def +is returned. +If an error is encountered while trying to find the field, +.Ar 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 +.Ar def +if no capabilities were found for this class (typically meaning that +the default class was used and the +.Pa /etc/login.conf +file is missing). +It returns a non-zero value if +.Ar cap , +with no value, was found, +zero otherwise. +.Pp +The +.Fn setclasscontext +function takes +.Ar class , +the name of a user class, and sets the resources defined by that +class according to +.Ar flags . +Only the +.Dv LOGIN_SETPATH , +.Dv LOGIN_SETPRIORITY , +.Dv LOGIN_SETRESOURCES , +.Dv LOGIN_SETRTABLE , +and +.Dv LOGIN_SETUMASK +bits are used +(see +.Fn setusercontext +below). +It returns 0 on success and \-1 on failure. +.Pp +The +.Fn setusercontext +function sets the resources according to +.Ar flags . +The +.Ar lc +argument, if not +.Dv NULL , +contains the class information that should be used. +The +.Ar pwd +argument, if not +.Dv NULL , +provides information about the user. +Both +.Ar lc +and +.Ar pwd +cannot be +.Dv NULL . +The +.Ar uid +argument is used in place of the user ID contained in the +.Ar pwd +structure when calling +.Xr setuid 2 . +The +.Fn setusercontext +function returns 0 on success and -1 on failure. +The various bits available to be or-ed together to make up +.Ar flags +are: +.Bl -tag -width LOGIN_SETRESOURCESXX +.It Dv LOGIN_SETENV +Sets environment variables specified by the +.Li setenv +keyword. +.It Dv LOGIN_SETGROUP +Set the group ID and call +.Xr initgroups 3 +if the +.Ar pwd +argument is non-NULL. +.It Dv LOGIN_SETLOGIN +Sets the login name using +.Xr setlogin 2 +if the +.Ar pwd +argument is non-NULL. +.It Dv LOGIN_SETPATH +Sets the +.Ev PATH +environment variable to the value of the +.Li path +keyword if specified, or to the value of +.Dv _PATH_DEFPATH +in +.In paths.h +if not. +.It Dv LOGIN_SETPRIORITY +Sets the priority, using +.Xr setpriority 2 , +to the value of the +.Li priority +keyword if specified, or to +.Li 0 +if not. +.It Dv LOGIN_SETRESOURCES +Sets the various system resources using +.Xr setrlimit 2 . +.It Dv LOGIN_SETRTABLE +Sets the routing table to the value of the +.Li rtable +keyword, if specified, +using +.Xr setrtable 2 . +.It Dv LOGIN_SETUMASK +Sets the umask, using +.Xr umask 2 , +to the value of the +.Li umask +keyword if specified, or to +.Li 022 +if not. +.It Dv LOGIN_SETUSER +Sets the user ID to +.Ar uid +using +.Xr setuid 2 . +.It Dv LOGIN_SETALL +Sets all of the above. +.It Dv LOGIN_SETXDGENV +Ensures the presence and usability of a runtime directory for +applications run by +.Ar uid . +Sets the +.Ev XDG_RUNTIME_DIR +variable to the full path of the directory if successfully set up. +Mostly useful to login managers so not part of +.Dv LOGIN_SETALL . +.El +.Sh SEE ALSO +.Xr setlogin 2 , +.Xr setpriority 2 , +.Xr setrlimit 2 , +.Xr setrtable 2 , +.Xr setuid 2 , +.Xr umask 2 , +.Xr initgroups 3 , +.Xr login.conf 5 +.Sh HISTORY +The +.Nm +function first appeared in +.Ox 2.8 . +.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 non-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/openbsd/man3/login_fbtab.3 b/static/openbsd/man3/login_fbtab.3 new file mode 100644 index 00000000..cbd640b5 --- /dev/null +++ b/static/openbsd/man3/login_fbtab.3 @@ -0,0 +1,54 @@ +.\" $OpenBSD: login_fbtab.3,v 1.16 2025/06/06 22:01:40 schwarze Exp $ +.\" +.\" Copyright 1995 by Wietse Venema. All rights reserved. Some individual +.\" files may be covered by other copyrights. +.\" +.\" This material was originally written and compiled by Wietse Venema at +.\" Eindhoven University of Technology, The Netherlands, in 1990, 1991, +.\" 1992, 1993, 1994 and 1995. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that this entire copyright notice +.\" is duplicated in all such copies. +.\" +.\" This software is provided "as is" and without any expressed or implied +.\" warranties, including, without limitation, the implied warranties of +.\" merchantibility and fitness for any particular purpose. +.\" +.Dd $Mdocdate: June 6 2025 $ +.Dt LOGIN_FBTAB 3 +.Os +.Sh NAME +.Nm login_fbtab +.Nd implement device security based on fbtab(5) +.Sh SYNOPSIS +.Lb libutil +.In sys/types.h +.In util.h +.Ft void +.Fn login_fbtab "const char *tty" "uid_t uid" "gid_t gid" +.Sh DESCRIPTION +The +.Fn login_fbtab +function reads the +.Pa /etc/fbtab +file and implements device security as described in the +.Xr fbtab 5 +manual page. +.Sh FILES +.Bl -tag -width /etc/fbtab -compact +.It Pa /etc/fbtab +.El +.Sh DIAGNOSTICS +Problems are reported via the +.Xr syslogd 8 +daemon with the severity of +.Dv LOG_ERR . +.Sh SEE ALSO +.Xr fbtab 5 +.Sh AUTHORS +.An Wietse Venema Aq Mt wietse@wzv.win.tue.nl +.br +Eindhoven University of Technology +.br +The Netherlands diff --git a/static/openbsd/man3/lrint.3 b/static/openbsd/man3/lrint.3 new file mode 100644 index 00000000..1d57086f --- /dev/null +++ b/static/openbsd/man3/lrint.3 @@ -0,0 +1,113 @@ +.\" $OpenBSD: lrint.3,v 1.5 2025/06/07 10:33:06 schwarze Exp $ +.\" $NetBSD: lrint.3,v 1.1 2005/09/16 15:26:47 wiz 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 $Mdocdate: June 7 2025 $ +.Dt LRINT 3 +.Os +.Sh NAME +.Nm llrint , +.Nm llrintf , +.Nm llrintl , +.Nm lrint , +.Nm lrintf , +.Nm lrintl +.Nd convert to integer +.Sh SYNOPSIS +.Lb libm +.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 rint 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/openbsd/man3/lround.3 b/static/openbsd/man3/lround.3 new file mode 100644 index 00000000..bb5c90b8 --- /dev/null +++ b/static/openbsd/man3/lround.3 @@ -0,0 +1,100 @@ +.\" $OpenBSD: lround.3,v 1.7 2025/06/13 18:34:00 schwarze 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/lround.3,v 1.4 2005/06/15 19:04:04 ru Exp $ +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt LROUND 3 +.Os +.Sh NAME +.Nm llround , +.Nm llroundf , +.Nm llroundl , +.Nm lround , +.Nm lroundf , +.Nm lroundl +.Nd convert to nearest integral value +.Sh SYNOPSIS +.Lb libm +.In math.h +.Ft long long +.Fn llround "double x" +.Ft long long +.Fn llroundf "float x" +.Ft long long +.Fn llroundl "long double x" +.Ft long +.Fn lround "double x" +.Ft long +.Fn lroundf "float x" +.Ft long +.Fn lroundl "long double x" +.Sh DESCRIPTION +The +.Fn lround +function returns the integer nearest to its argument +.Fa x , +rounding away from zero in halfway cases. +If the rounded result is too large to be represented as a +.Vt long +value, an invalid exception is raised and the return value is undefined. +Otherwise, if +.Fa x +is not an integer, +.Fn lround +may raise an inexact exception. +When the rounded result is representable as a +.Vt long , +the expression +.Fn lround x +is equivalent to +.Po Vt long Pc Ns Fn round x +(although the former may be more efficient). +.Pp +The +.Fn llround , +.Fn llroundf , +.Fn llroundl , +.Fn lroundf +and +.Fn lroundl +functions differ from +.Fn lround +only in their input and output types. +.Sh SEE ALSO +.Xr lrint 3 , +.Xr rint 3 +.Sh STANDARDS +The +.Fn llround , +.Fn llroundf , +.Fn llroundl , +.Fn lround , +.Fn lroundf , +and +.Fn lroundl +functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/lsearch.3 b/static/openbsd/man3/lsearch.3 new file mode 100644 index 00000000..d82c55c8 --- /dev/null +++ b/static/openbsd/man3/lsearch.3 @@ -0,0 +1,106 @@ +.\" $OpenBSD: lsearch.3,v 1.14 2015/11/30 17:03:05 jmc 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. +.\" +.\" @(#)lsearch.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd $Mdocdate: November 30 2015 $ +.Dt LSEARCH 3 +.Os +.Sh NAME +.Nm lsearch , +.Nm lfind +.Nd linear searching routines +.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 +function +is a comparison routine which is used to compare two elements. +It takes two arguments which point to the +.Fa key +object and to an array member, in that order, and must return an integer +less than, equivalent to, or greater than zero if the +.Fa key +object is considered, respectively, to be less than, equal to, or greater +than the array member. +.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 dbopen 3 +.Sh STANDARDS +The +.Fn lsearch +and +.Fn lfind +functions conform to the X/Open System Interfaces option of the +.St -p1003.1-2008 +specification. diff --git a/static/openbsd/man3/malloc.3 b/static/openbsd/man3/malloc.3 new file mode 100644 index 00000000..ee13b01b --- /dev/null +++ b/static/openbsd/man3/malloc.3 @@ -0,0 +1,860 @@ +.\" +.\" 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. +.\" +.\" $OpenBSD: malloc.3,v 1.147 2025/06/04 00:38:01 yasuoka Exp $ +.\" +.Dd $Mdocdate: June 4 2025 $ +.Dt MALLOC 3 +.Os +.Sh NAME +.Nm malloc , +.Nm calloc , +.Nm realloc , +.Nm free , +.Nm reallocarray , +.Nm recallocarray , +.Nm freezero , +.Nm aligned_alloc , +.Nm malloc_conceal , +.Nm calloc_conceal +.Nd memory allocation and deallocation +.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 free "void *ptr" +.Ft void * +.Fn reallocarray "void *ptr" "size_t nmemb" "size_t size" +.Ft void * +.Fn recallocarray "void *ptr" "size_t oldnmemb" "size_t nmemb" "size_t size" +.Ft void +.Fn freezero "void *ptr" "size_t size" +.Ft void * +.Fn aligned_alloc "size_t alignment" "size_t size" +.Ft void * +.Fn malloc_conceal "size_t size" +.Ft void * +.Fn calloc_conceal "size_t nmemb" "size_t size" +.Vt const char * const +.Va malloc_options ; +.Sh DESCRIPTION +The standard functions +.Fn malloc , +.Fn calloc , +and +.Fn realloc +allocate +.Em objects , +regions of memory to store values. +The +.Fn malloc +function allocates uninitialized space for an object of +the specified +.Fa size . +.Fn malloc +maintains multiple lists of free objects according to size, allocating +from the appropriate list or requesting memory from the kernel. +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 an array of +.Fa nmemb +objects, each of the specified +.Fa size . +The space is initialized to zero. +.Pp +The +.Fn realloc +function changes the size of the object pointed to by +.Fa ptr +to +.Fa size +bytes and returns a pointer to the (possibly moved) object. +If +.Fa ptr +is not +.Dv NULL , +it must be a pointer returned by an earlier call to an allocation or +reallocation function that was not freed in between. +The contents of the object 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 object is indeterminate and uninitialized. +If the space cannot be allocated, the object +pointed to by +.Fa ptr +is unchanged. +If +.Fa ptr +is +.Dv NULL , +.Fn realloc +behaves like +.Fn malloc +and allocates a new object. +.Pp +The +.Fn free +function causes the space pointed to by +.Fa ptr +to be either placed on a list of free blocks to make it available for future +allocation or, when appropriate, to be returned to the kernel using +.Xr munmap 2 . +If +.Fa ptr +is +.Dv NULL , +no action occurs. +If +.Fa ptr +was previously freed by +.Fn free +or a reallocation function, +the behavior is undefined and the double free is a security concern. +.Pp +Designed for safe allocation of arrays, +the +.Fn reallocarray +function is similar to +.Fn realloc +except it operates on +.Fa nmemb +members of size +.Fa size +and checks for integer overflow in the calculation +.Fa nmemb +* +.Fa size . +.Pp +Used for the allocation of memory holding sensitive data, +the +.Fn recallocarray +and +.Fn freezero +functions guarantee that memory becoming unallocated is explicitly +.Em discarded , +meaning pages of memory are disposed via +.Xr munmap 2 +and cached free objects are cleared with +.Xr explicit_bzero 3 . +.Pp +The +.Fn recallocarray +function is similar to +.Fn reallocarray +except it ensures newly allocated memory is cleared similar to +.Fn calloc . +If +.Fa ptr +is +.Dv NULL , +.Fa oldnmemb +is ignored and the call is equivalent to +.Fn calloc . +If +.Fa ptr +is not +.Dv NULL , +.Fa oldnmemb +must be a value such that +.Fa oldnmemb +* +.Fa size +is the size of the earlier allocation that returned +.Fa ptr , +otherwise the behavior is undefined. +.Pp +The +.Fn freezero +function is similar to the +.Fn free +function except it ensures memory is explicitly discarded. +If +.Fa ptr +is +.Dv NULL , +no action occurs. +If +.Fa ptr +is not +.Dv NULL , +the +.Fa size +argument must be equal to or smaller than the size of the earlier allocation +that returned +.Fa ptr . +.Fn freezero +guarantees the memory range starting at +.Fa ptr +with length +.Fa size +is discarded while deallocating the whole object originally allocated. +.Pp +The +.Fn aligned_alloc +function allocates +.Fa size +bytes of memory such that the allocation's base address is a multiple of +.Fa alignment . +The requested +.Fa alignment +must be a power of 2. +If +.Fa size +is not a multiple of +.Fa alignment , +behavior is undefined. +.Pp +The +.Fn malloc_conceal +and +.Fn calloc_conceal +functions behave the same as +.Fn malloc +and +.Fn calloc +respectively, +with the exception that the allocation returned is marked with the +.Dv MAP_CONCEAL +.Xr mmap 2 +flag and calling +.Fn free +on the allocation will discard the contents explicitly. +A reallocation of a concealed allocation will leave these properties intact. +.Sh MALLOC OPTIONS +Upon the first call to the +.Fn malloc +family of functions, an initialization sequence inspects the +value of the +.Va vm.malloc_conf +.Xr sysctl 2 , +next checks the environment for a variable called +.Ev MALLOC_OPTIONS , +and finally looks at the global variable +.Va malloc_options +in the program. +Since +.Fn malloc +might already get called before the beginning of +.Fn main , +either initialize +.Va malloc_options +to a string literal at file scope or do not declare it at all. +.Pp +Each of the three strings is scanned for the flags documented below. +Unless otherwise noted uppercase means on, lowercase means off. +During initialization, flags occurring later modify the behaviour +that was requested by flags processed earlier. +.Bl -tag -width indent +.It Cm C +.Dq Canaries . +Add canaries at the end of allocations in order to detect +heap overflows. +The canary's content is checked when +.Nm free +is called. +If it has been corrupted, the process is aborted. +.It Cm D +.Dq Dump . +.Fn malloc +will dump a leak report using +.Xr utrace 2 +at exit. +To record the dump: +.Pp +.Dl $ MALLOC_OPTIONS=D ktrace -tu program ... +.Pp +To view the leak report: +.Pp +.Dl $ kdump -u malloc ... +.Pp +By default, the immediate caller of a +.Nm +function will be recorded. +Use malloc option +.Cm 2 , +.Cm 3 +or +.Cm 4 +to record deeper call stacks. +These malloc options imply +.Cm D . +.It Cm F +.Dq Freecheck . +Enable more extensive double free and write after free detection. +All chunks in the delayed free list will be checked for double frees and +write after frees. +Unused pages on the freelist are read and write protected to +cause a segmentation fault upon access. +.It Cm G +.Dq Guard . +Enable guard pages. +Each page size or larger allocation is followed by a guard page that will +cause a segmentation fault upon any access. +.It Cm J +.Dq More junking . +Increase the junk level by one if it is smaller than 2. +.It Cm j +.Dq Less junking . +Decrease the junk level by one if it is larger than 0. +Junking writes some junk bytes into the area allocated. +Junk is bytes of 0xdb when allocating; +small allocations are initially junked with 0xdf as are freed allocations. +By default the junk level is 1: after free, +small chunks are completely junked; +for pages the first part is junked. +After a delay, +the filling pattern is validated and the process is aborted if the pattern +was modified. +For junk level 2, junking is done on allocation as well and without size +restrictions. +If the junk level is zero, no junking is performed. +.It Cm R +.Dq realloc . +Always reallocate when +.Fn realloc +is called, even if the initial allocation was big enough. +.\".Pp +.\".It Cm U +.\".Dq utrace . +.\"Generate entries for +.\".Xr ktrace 1 +.\"for all operations. +.\"Consult the source for this one. +.It Cm S +.\" Malloc option S is vaguely documented on purpose. +Enable all options suitable for security auditing. +.It Cm U +.Dq Free unmap . +Enable use after free protection for larger allocations. +Unused pages on the freelist are read and write protected to +cause a segmentation fault upon access. +.It Cm V +.Dq Verbose . +Use with +.Cm D +to get a verbose dump of malloc's internal state. +.It Cm X +.Dq xmalloc . +Rather than return failure to handle out-of-memory conditions gracefully, +.Xr abort 3 +the program with a diagnostic message on stderr. +.It Cm < +.Dq Halve the cache size . +Decrease the size of the free page cache by a factor of two. +.It Cm > +.Dq Double the cache size . +Increase the size of the free page cache by a factor of two. +.El +.Pp +If a program changes behavior if any of these options (except +.Cm X ) +are used, +it is buggy. +.Pp +The default size of the cache is 64 single page allocations. +It also caches a number of larger regions. +Multi-threaded programs use multiple pools. +.Sh RETURN VALUES +Upon successful completion, the allocation functions +return a pointer to the allocated space; otherwise, +.Dv NULL +is returned and +.Va errno +is set to +.Er ENOMEM . +The function +.Fn aligned_alloc +returns +.Dv NULL +and sets +.Va errno +to +.Er EINVAL +if +.Fa alignment +is not a power of 2. +.Pp +If +.Fa nmemb +or +.Fa size +is equal to 0, a unique pointer to an access protected, +zero sized object is returned. +Access via this pointer will generate a +.Dv SIGSEGV +exception. +.Pp +If multiplying +.Fa nmemb +and +.Fa size +results in integer overflow, +.Fn calloc , +.Fn reallocarray +and +.Fn recallocarray +return +.Dv NULL +and set +.Va errno +to +.Er ENOMEM . +.Pp +If +.Fa ptr +is not +.Dv NULL +and multiplying +.Fa oldnmemb +and +.Fa size +results in integer overflow, +.Fn recallocarray +returns +.Dv NULL +and sets +.Va errno +to +.Er EINVAL . +.Sh IDIOMS +Consider +.Fn calloc +or the extensions +.Fn reallocarray +and +.Fn recallocarray +when there is multiplication in the +.Fa size +argument of +.Fn malloc +or +.Fn realloc . +For example, avoid this common idiom as it may lead to integer overflow: +.Bd -literal -offset indent +if ((p = malloc(num * size)) == NULL) + err(1, NULL); +.Ed +.Pp +A drop-in replacement is the +.Ox +extension +.Fn reallocarray : +.Bd -literal -offset indent +if ((p = reallocarray(NULL, num, size)) == NULL) + err(1, NULL); +.Ed +.Pp +Alternatively, +.Fn calloc +may be used at the cost of initialization overhead. +.Pp +When using +.Fn realloc , +be careful to avoid the following idiom: +.Bd -literal -offset indent +size += 50; +if ((p = realloc(p, size)) == NULL) + return (NULL); +.Ed +.Pp +Do not adjust the variable describing how much memory has been allocated +until the allocation has been successful. +This can cause aberrant program behavior if the incorrect size value is used. +In most cases, the above sample will also result in a leak of 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 ((newp = realloc(p, newsize)) == NULL) { + free(p); + p = NULL; + size = 0; + return (NULL); +} +p = newp; +size = newsize; +.Ed +.Pp +As with +.Fn malloc , +it is important to ensure the new size value will not overflow; +i.e. avoid allocations like the following: +.Bd -literal -offset indent +if ((newp = realloc(p, num * size)) == NULL) { + ... +.Ed +.Pp +Instead, use +.Fn reallocarray : +.Bd -literal -offset indent +if ((newp = reallocarray(p, num, size)) == NULL) { + ... +.Ed +.Pp +Calling +.Fn realloc +with a +.Dv NULL +.Fa ptr +is equivalent to calling +.Fn malloc . +Instead of this idiom: +.Bd -literal -offset indent +if (p == NULL) + newp = malloc(newsize); +else + newp = realloc(p, newsize); +.Ed +.Pp +Use the following: +.Bd -literal -offset indent +newp = realloc(p, newsize); +.Ed +.Pp +The +.Fn recallocarray +function should be used for resizing objects containing sensitive data like +keys. +To avoid leaking information, +it guarantees memory is cleared before placing it on the internal free list. +Deallocation of such an object should be done by calling +.Fn freezero . +.Sh ENVIRONMENT +.Bl -tag -width "MALLOC_OPTIONS" +.It Ev MALLOC_OPTIONS +String of option flags. +.El +.Sh EXAMPLES +If +.Fn malloc +must be used with multiplication, be sure to test for overflow: +.Bd -literal -offset indent +size_t num, size; +\&... + +/* Check for size_t overflow */ +if (size && num > SIZE_MAX / size) + errc(1, EOVERFLOW, "overflow"); + +if ((p = malloc(num * size)) == NULL) + err(1, NULL); +.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(num * size)) == NULL) + err(1, NULL); +.Ed +.Pp +Assuming the implementation checks for integer overflow as +.Ox +does, it is much easier to use +.Fn calloc , +.Fn reallocarray , +or +.Fn recallocarray . +.Pp +The above examples could be simplified to: +.Bd -literal -offset indent +if ((p = reallocarray(NULL, num, size)) == NULL) + err(1, NULL); +.Ed +.Pp +or at the cost of initialization: +.Bd -literal -offset indent +if ((p = calloc(num, size)) == NULL) + err(1, NULL); +.Ed +.Pp +Set a systemwide reduction of the cache to a quarter of the +default size and use guard pages: +.Pp +.Dl # sysctl vm.malloc_conf='G<<' +.Sh DIAGNOSTICS +If any of the functions detect an error condition, +a message will be printed to file descriptor +2 (not using stdio). +Errors will result in the process being aborted. +.Pp +Here is a brief description of the error messages and what they mean: +.Bl -tag -width Ds +.It Dq out of memory +If the +.Cm X +option is specified, it is an error for the allocation functions +to return +.Dv NULL . +.It Dq bogus pointer (double free?) +An attempt to +.Fn free +or +reallocate an unallocated pointer was made. +.It Dq double free +There was an attempt to free an allocation that had already been freed. +.It Dq write to free mem Va address Ns [ Va start Ns .. Ns Va end Ns ]@ Ns Va size +An allocation has been modified after it was freed, +or a chunk that was never allocated was written to. +The +.Va range +at which corruption was detected is printed between [ and ]. +.Pp +Enabling option +.Cm D +allows malloc to print information about where the allocation +was done. +.It Dq modified chunk-pointer +The pointer passed to +.Fn free +or a reallocation function has been modified. +.It Dq canary corrupted Va address Ns [ Va offset Ns ]@ Ns Va length Ns / Ns Va size +A byte after the requested +.Va length +has been overwritten, +indicating a heap overflow. +The +.Va offset +at which corruption was detected is printed between [ and ], +the requested +.Va length +of the allocation is printed before the / and the +.Va size +of the allocation after the /. +.It Dq recorded size Va oldsize No inconsistent with Va size +.Fn recallocarray +or +.Fn freezero +has detected that the given old size does not match the recorded size in its +meta data. +Enabling option +.Cm C +allows +.Fn recallocarray +to catch more of these cases. +.It Dq recursive call +An attempt was made to call recursively into these functions, i.e., from a +signal handler. +This behavior is not supported. +In particular, signal handlers should +.Em not +use any of the +.Fn malloc +functions nor utilize any other functions which may call +.Fn malloc +(e.g., +.Xr stdio 3 +routines). +.It Dq unknown char in Ev MALLOC_OPTIONS +We found something we didn't understand. +.It any other error +.Fn malloc +detected an internal error; +consult sources and/or wizards. +.El +.Sh SEE ALSO +.Xr brk 2 , +.Xr mmap 2 , +.Xr munmap 2 , +.Xr sysctl 2 , +.Xr alloca 3 , +.Xr getpagesize 3 , +.Xr posix_memalign 3 +.Sh STANDARDS +The +.Fn malloc , +.Fn calloc , +.Fn realloc , +and +.Fn free +functions conform to +.St -ansiC . +The +.Fn aligned_alloc +function conforms to +.St -isoC-2011 . +The +.Fn reallocarray +function conforms to +.St -p1003.1-2024 . +.Pp +If +.Fa nmemb +or +.Fa size +are 0, the return value is implementation defined; +other conforming implementations may return +.Dv NULL +in this case. +.Pp +The +.Ev MALLOC_OPTIONS +environment variable, the +.Va vm.malloc_conf +sysctl and the +.Sx DIAGNOSTICS +output are extensions to the standard. +.Sh HISTORY +A +.Fn free +internal kernel function and a predecessor to +.Fn malloc , +.Fn alloc , +first appeared in +.At v1 . +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 which appeared in +.Fx 2.2 +and was included in +.Ox 2.0 . +These implementations were all +.Xr sbrk 2 +based. +In +.Ox 3.8 , +Thierry Deval rewrote +.Nm +to use the +.Xr mmap 2 +system call, +making the page addresses returned by +.Nm +random. +A rewrite by Otto Moerbeek introducing a new central data structure and more +randomization appeared in +.Ox 4.4 . +.Pp +The +.Fn reallocarray +function appeared in +.Ox 5.6 . +The +.Fn recallocarray +function appeared in +.Ox 6.1 . +The +.Fn freezero +function appeared in +.Ox 6.2 . +The +.Fn aligned_alloc +function appeared in +.Ox 6.5 . +The +.Fn malloc_conceal +and +.Fn calloc_conceal +functions appeared in +.Ox 6.6 . +.Sh CAVEATS +When using +.Fn malloc , +be wary of signed integer and +.Vt size_t +overflow especially when there is multiplication in the +.Fa size +argument. +.Pp +Signed integer overflow will cause undefined behavior which compilers +typically handle by wrapping back around to negative numbers. +Depending on the input, this can result in allocating more or less +memory than intended. +.Pp +An unsigned overflow has defined behavior which will wrap back around and +return less memory than intended. +.Pp +A signed or unsigned integer overflow is a +.Em security +risk if less memory is returned than intended. +Subsequent code may corrupt the heap by writing beyond the memory that was +allocated. +An attacker may be able to leverage this heap corruption to execute arbitrary +code. +.Pp +Consider using +.Fn calloc , +.Fn reallocarray +or +.Fn recallocarray +instead of using multiplication in +.Fn malloc +and +.Fn realloc +to avoid these problems on +.Ox . +.Pp +The mechanism to record caller functions when using malloc options +.Cm 2 , +.Cm 3 , +or +.Cm 4 +is not guaranteed to work for all platforms, compilers or compilation +options, +and might even crash your program. +Use +.Em only +for debugging purposes. diff --git a/static/openbsd/man3/mblen.3 b/static/openbsd/man3/mblen.3 new file mode 100644 index 00000000..d798c6a3 --- /dev/null +++ b/static/openbsd/man3/mblen.3 @@ -0,0 +1,177 @@ +.\" $OpenBSD: mblen.3,v 1.6 2025/06/07 09:45:07 schwarze Exp $ +.\" $NetBSD: mblen.3,v 1.4 2003/04/16 13:34:40 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 $Mdocdate: June 7 2025 $ +.Dt MBLEN 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mblen +.Nd get number of bytes in a multibyte character +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn mblen "const char *s" "size_t n" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn mblen +function returns the number of bytes +in the first multibyte character of the multibyte string +.Fa s . +It examines at most the first +.Fa n +bytes of +.Fa s . +.Pp +In state-dependent encodings, +.Fa s +may point to special sequence bytes changing the shift state. +Although such sequence bytes correspond to no wide character, +they affect the internal conversion state of the +.Fn mblen +function, and are treated +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 function in +.Em libc +never changes the internal state of +.Fn mblen , +except for calling +.Xr setlocale 3 +with an +.Dv LC_CTYPE +that differs from the current locale. +Such +.Xr setlocale 3 +calls cause the internal state of this function to become indeterminate. +.Pp +The behaviour of +.Fn mblen +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +There are 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" +In this case, +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 +The +.Fn mblen +function 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 in the valid multibyte character pointed to by +.Fa s . +There are no cases when this value is greater than +.Fa n +or 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 , +.Fn mblen +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 +The +.Fn mblen +function 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/openbsd/man3/mbrlen.3 b/static/openbsd/man3/mbrlen.3 new file mode 100644 index 00000000..2801edae --- /dev/null +++ b/static/openbsd/man3/mbrlen.3 @@ -0,0 +1,212 @@ +.\" $OpenBSD: mbrlen.3,v 1.6 2022/03/29 18:15:52 naddy Exp $ +.\" $NetBSD: mbrlen.3,v 1.5 2003/09/08 17:54:31 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 $Mdocdate: March 29 2022 $ +.Dt MBRLEN 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbrlen +.Nd get number of bytes in a multibyte character (restartable) +.\" ---------------------------------------------------------------------- +.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 returns the number of bytes +in the first multibyte character of the multibyte string +.Fa s . +It examines at most the first +.Fa n +bytes of +.Fa s . +.Pp +.Fn mbrlen +is equivalent to the following call, except that +.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 automatically initialized +to the initial conversion state at startup time of the program. +.Pp +In state-dependent encodings, +.Fa s +may point to special sequence bytes changing the shift state. +Although such sequence bytes correspond to no wide character, +they affect the conversion state object pointed to by +.Fa ps , +and +.Fn mbrlen +treats the special sequence bytes +as if they were part of the subsequent multibyte character. +.Pp +Unlike +.Xr mblen 3 , +.Fn mbrlen +accepts the byte sequence if it is not a complete character +but the initial part of some valid character. +In this case, this function accepts all such bytes +and saves 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 +There are the special cases: +.Bl -tag -width 0123456789 +.It "s == NULL" +.Fn mbrlen +sets the conversion state object pointed to by +.Fa ps +to the initial conversion 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 +.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 the +.Fa ps +argument. +.Pp +Calling any other function in +.Em libc +never changes the internal state of +.Fn mbrlen , +except for calling +.Xr setlocale 3 +with an +.Dv LC_CTYPE +that differs from the current locale. +Such +.Xr setlocale 3 +calls cause the internal state of this function to become indeterminate. +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +The +.Fn mbrlen +function returns: +.Bl -tag -width "(size_t)-2" +.It "0" +.Fa s +points to a NUL byte +.Pq Sq \e0 . +.It "positive" +The value returned is +the number of bytes in the valid multibyte character pointed to by +.Fa s . +There are no cases where this value is greater than +.Fa n +or the value of the +.Dv MB_CUR_MAX +macro. +.It "(size_t)-2" +The first +.Fa n +bytes of +.Fa s +contain an incomplete multibyte character that can potentially be +completed by reading more bytes. +When +.Fa n +is at least +.Dv MB_CUR_MAX , +this can only occur if +.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 cases: +.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 +.Vt 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 . +ISO/IEC 9899/AMD1:1995 +.Pq Dq ISO C90, Amendment 1 . +The restrict qualifier is added at +.\" .St -isoC99 . +ISO/IEC 9899/1999 +.Pq Dq ISO C99 . diff --git a/static/openbsd/man3/mbrtoc16.3 b/static/openbsd/man3/mbrtoc16.3 new file mode 100644 index 00000000..ca82643f --- /dev/null +++ b/static/openbsd/man3/mbrtoc16.3 @@ -0,0 +1,265 @@ +.\" $OpenBSD: mbrtoc16.3,v 1.1 2023/08/20 15:02:51 schwarze Exp $ +.\" +.\" Copyright 2023 Ingo Schwarze +.\" Copyright 2010 Stefan Sperling +.\" +.\" 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: August 20 2023 $ +.Dt MBRTOC16 3 +.Os +.Sh NAME +.Nm mbrtoc16 +.Nd convert one UTF-8 encoded character to UTF-16 +.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 mbs" +.Fc +.Sh DESCRIPTION +The +.Fn mbrtoc16 +function examines at most +.Fa n +bytes of the multibyte character byte string pointed to by +.Fa s , +converts those bytes to a wide character, +and encodes the wide character using UTF-16. +In some cases, it is necessary to call this function +twice to convert a single character. +.Pp +Conversion happens in accordance with the conversion state +.Pf * Fa mbs , +which must be initialized to zero before the application's first call to +.Fn mbrtoc16 . +For this function, +.Pf * Fa mbs +stores information about both the state of the UTF-8 input encoding +and the state of the UTF-16 output encoding. +If the previous call did not return +.Po Vt size_t Pc Ns \-1 , +.Fa mbs +can safely be reused without reinitialization. +.Pp +The input encoding that +.Fn mbrtoc16 +uses for +.Fa s +is determined by the +.Dv LC_CTYPE +category of the current locale. +If the locale is changed without reinitialization of +.Pf * Fa mbs , +the behaviour is undefined. +.Pp +Unlike +.Xr mbtowc 3 , +.Fn mbrtoc16 +accepts an incomplete byte sequence pointed to by +.Fa s +which does not form a complete character but is potentially part of +a valid character. +In this case, the function consumes all such bytes. +The conversion state saved in +.Pf * Fa mbs +will be used to restart the suspended conversion during the next call. +.Pp +On systems other than +.Ox +that support state-dependent encodings, +.Fa s +may point to a special sequence of bytes called a +.Dq shift sequence ; +see +.Xr mbrtowc 3 +for details. +.Pp +The following arguments cause special processing: +.Bl -tag -width 012345678901 +.It Fa pc16 No == Dv NULL +The conversion from a multibyte character to a wide character is performed +and the conversion state may be affected, but the resulting wide character +is discarded. +.It Fa s No == Dv NULL +The arguments +.Fa pc16 +and +.Fa n +are ignored and starting or continuing the conversion with an empty string +is attempted, discarding the conversion result. +.It Fa mbs No == Dv NULL +An internal +.Vt mbstate_t +object specific to the +.Fn mbrtoc16 +function is used instead of the +.Fa mbs +argument. +This internal object is automatically initialized at program startup +and never changed by any +.Em libc +function except +.Fn mbrtoc16 . +.Pp +If +.Fn mbrtoc16 +is called with a +.Dv NULL +.Fa mbs +argument and that call returns +.Po Vt size_t Pc Ns \-1 , +the internal conversion state of +.Fn mbrtoc16 +becomes permanently undefined and there is no way +to reset it to any defined state. +Consequently, after such a mishap, it is not safe to call +.Fn mbrtoc16 +with a +.Dv NULL +.Fa mbs +argument ever again until the program is terminated. +.El +.Sh RETURN VALUES +.Bl -tag -width 012345678901 +.It 0 +The bytes pointed to by +.Fa s +form a terminating NUL character. +If +.Fa pc16 +is not +.Dv NULL , +a NUL wide character has been stored in +.Pf * Fa pc16 . +.It positive +.Fa s +points to a valid character, and the value returned is the number of +bytes completing the character. +If +.Fa pc16 +is not +.Dv NULL , +the first UTF-16 code unit of the corresponding wide character +has been stored in +.Pf * Fa pc16 . +If it is an UTF-16 high surrogate, the function needs to be called +again to retrieve a second UTF-16 code unit, the low surrogate. +On +.Ox , +this happens if and only if the return value is 4, +but this equivalence does not hold on other operating systems +that support input encodings other than UTF-8. +.It Po Vt size_t Pc Ns \-1 +.Fa s +points to an illegal byte sequence which does not form a valid multibyte +character in the current locale, or +.Fa mbs +points to an invalid or uninitialized object. +.Va errno +is set to +.Er EILSEQ +or +.Er EINVAL , +respectively. +The conversion state object pointed to by +.Fa mbs +is left in an undefined state and must be reinitialized before being +used again. +.It Po Vt size_t Pc Ns \-2 +.Fa s +points to an incomplete byte sequence of length +.Fa n +which has been consumed and contains part of a valid multibyte character. +The character may be completed by calling the same function again with +.Fa s +pointing to one or more subsequent bytes of the multibyte character and +.Fa mbs +pointing to the conversion state object used during conversion of the +incomplete byte sequence. +.It Po Vt size_t Pc Ns \-3 +The second 16-bit code unit resulting from a previous call +has been stored into +.Pf * Fa pc16 , +without consuming any additional bytes from +.Fa s . +.El +.Sh ERRORS +.Fn mbrtoc16 +causes an error in the following cases: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa s +points to an invalid multibyte character. +.It Bq Er EINVAL +.Fa mbs +points to an invalid or uninitialized +.Vt mbstate_t +object. +.El +.Sh SEE ALSO +.Xr c16rtomb 3 , +.Xr mbrtowc 3 , +.Xr setlocale 3 +.Sh STANDARDS +.Fn mbrtoc16 +conforms to +.St -isoC-2011 . +.Sh HISTORY +.Fn mbrtoc16 +has been available since +.Ox 7.4 . +.Sh CAVEATS +On operating systems other than +.Ox +that support input encodings other than UTF-8, inspecting the return value +is insufficient to tell whether the function needs to be called again. +If the return value is positive, inspecting +.Pf * Fa pc16 +is also required to make that decision. +Consequently, passing a +.Dv NULL +pointer for the +.Fa pc16 +argument is discouraged because it can result +in a well-defined but unknown output encoding state. +The simplest way to recover from such an unknown state is to +reinitialize the object pointed to by +.Fa mbs . +.Pp +The C11 standard only requires the +.Fa pc16 +argument to be encoded according to UTF-16 +if the predefined environment macro +.Dv __STDC_UTF_16__ +is defined with a value of 1. +On +.Ox , +.In uchar.h +provides this definition. +Other operating systems which do not define +.Dv __STDC_UTF_16__ +could theoretically use a different, +implementation-defined output encoding for +.Fa pc16 +instead of UTF-16. +Writing portable code for an arbitrary output encoding is impossible +because the rules when and how often the function needs to be called +again depend on the output encoding; the rules explained above are +specific to UTF-16. +Using UTF-16 as the output encoding of +.Fn wcrtoc16 +becomes mandatory in C23. diff --git a/static/openbsd/man3/mbrtowc.3 b/static/openbsd/man3/mbrtowc.3 new file mode 100644 index 00000000..fada9f4a --- /dev/null +++ b/static/openbsd/man3/mbrtowc.3 @@ -0,0 +1,332 @@ +.\" $OpenBSD: mbrtowc.3,v 1.7 2023/09/12 08:33:37 jsg Exp $ +.\" $NetBSD: mbrtowc.3,v 1.5 2003/09/08 17:54:31 wiz Exp $ +.\" +.\" Copyright (c)2023 Ingo Schwarze +.\" Copyright (c)2010 Stefan Sperling +.\" 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 $Mdocdate: September 12 2023 $ +.Dt MBRTOWC 3 +.Os +.Sh NAME +.Nm mbrtowc , +.Nm mbrtoc32 +.Nd convert a multibyte character to a wide character (restartable) +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fo mbrtowc +.Fa "wchar_t * restrict wc" +.Fa "const char * restrict s" +.Fa "size_t n" +.Fa "mbstate_t * restrict mbs" +.Fc +.In uchar.h +.Ft size_t +.Fo mbrtoc32 +.Fa "char32_t * restrict wc" +.Fa "const char * restrict s" +.Fa "size_t n" +.Fa "mbstate_t * restrict mbs" +.Fc +.Sh DESCRIPTION +The +.Fn mbrtowc +and +.Fn mbrtoc32 +functions examine at most +.Fa n +bytes of the multibyte character byte string pointed to by +.Fa s , +convert those bytes to a wide character, and store the wide character into +.Pf * Fa wc +if +.Fa wc +is not +.Dv NULL +and +.Fa s +points to a valid character. +.Pp +Conversion happens in accordance with the conversion state +.Pf * Fa mbs , +which must be initialized to zero before the application's first call to +.Fn mbrtowc +or +.Fn mbrtoc32 . +If the previous call did not return +.Po Vt size_t Pc Ns \-1 , +.Fa mbs +can safely be reused without reinitialization. +.Pp +The input encoding that +.Fn mbrtowc +and +.Fn mbrtoc32 +use for +.Fa s +is determined by the +.Dv LC_CTYPE +category of the current locale. +If the locale is changed without reinitialization of +.Pf * Fa mbs , +the behaviour is undefined. +.Pp +Unlike +.Xr mbtowc 3 , +.Fn mbrtowc +and +.Fn mbrtoc32 +accept an incomplete byte sequence pointed to by +.Fa s +which does not form a complete character but is potentially part of +a valid character. +In this case, both functions consume all such bytes. +The conversion state saved in +.Pf * Fa mbs +will be used to restart the suspended conversion during the next call. +.Pp +On systems other than +.Ox +that support state-dependent encodings, +.Fa s +may point to a special sequence of bytes called a +.Dq shift sequence . +Shift sequences switch between character code sets available within an +encoding scheme. +One encoding scheme using shift sequences is ISO/IEC 2022-JP, which +can switch e.g. from ASCII (which uses one byte per character) to +JIS X 0208 (which uses two bytes per character). +Shift sequence bytes correspond to no individual wide character, so +.Fn mbrtowc +and +.Fn mbrtoc32 +treat them as if they were part of the subsequent multibyte character. +Therefore they do contribute to the number of bytes in the multibyte character. +.Pp +The following arguments cause special processing: +.Bl -tag -width 012345678901 +.It Fa wc No == Dv NULL +The conversion from a multibyte character to a wide character is performed +and the conversion state may be affected, but the resulting wide character +is discarded. +This can be used to find out how many bytes are contained in the +multibyte character pointed to by +.Fa s . +.It Fa s No == Dv NULL +The arguments +.Fa wc +and +.Fa n +are ignored and starting or continuing the conversion with an empty string +is attempted, discarding the conversion result. +If conversion succeeds, this call always returns zero. +Unlike +.Xr mbtowc 3 , +the value returned does not indicate whether the current encoding of +the locale is state-dependent, i.e. uses shift sequences. +.It Fa mbs No == Dv NULL +.Fn mbrtowc +and +.Fn mbrtoc32 +each use their own internal state object instead of the +.Fa mbs +argument. +Both internal state objects are initialized at startup time of the program, +and no other libc function ever changes either of them. +.Pp +If +.Fn mbrtowc +or +.Fn mbrtoc32 +is called with a +.Dv NULL +.Fa mbs +argument and that call returns +.Po Vt size_t Pc Ns \-1 , +the internal conversion state of the respective function becomes +permanently undefined and there is no way to reset it to any defined state. +Consequently, after such a mishap, it is not safe +to call the same function with a +.Dv NULL +.Fa mbs +argument ever again until the program is terminated. +.El +.Sh RETURN VALUES +.Bl -tag -width 012345678901 +.It 0 +The bytes pointed to by +.Fa s +form a terminating NUL character. +If +.Fa wc +is not +.Dv NULL , +a NUL wide character has been stored in the wchar_t object pointed to by +.Fa wc . +.It positive +.Fa s +points to a valid character, and the value returned is the number of +bytes completing the character. +If +.Fa wc +is not +.Dv NULL , +the corresponding wide character has been stored in the wchar_t object +pointed to by +.Fa wc . +.It Po Vt size_t Pc Ns \-1 +.Fa s +points to an illegal byte sequence which does not form a valid multibyte +character in the current locale, or +.Fa mbs +points to an invalid or uninitialized object. +.Va errno +is set to +.Er EILSEQ +or +.Er EINVAL , +respectively. +The conversion state object pointed to by +.Fa mbs +is left in an undefined state and must be reinitialized before being +used again. +.Pp +Because applications using +.Fn mbrtowc +or +.Fn mbrtoc32 +are shielded from the specifics of the multibyte character encoding scheme, +it is impossible to repair byte sequences containing encoding errors. +Such byte sequences must be treated as invalid and potentially malicious input. +Applications must stop processing the byte string pointed to by +.Fa s +and either discard any wide characters already converted, or cope with +truncated input. +.It Po Vt size_t Pc Ns \-2 +.Fa s +points to an incomplete byte sequence of length +.Fa n +which has been consumed and contains part of a valid multibyte character. +The character may be completed by calling the same function again with +.Fa s +pointing to one or more subsequent bytes of the multibyte character and +.Fa mbs +pointing to the conversion state object used during conversion of the +incomplete byte sequence. +.It Po Vt size_t Pc Ns \-3 +The next character resulting from a previous call has been stored into +.Fa wc , +without consuming any additional bytes from +.Fa s . +This never happens for +.Fn mbrtowc , +and on +.Ox , +it never happens for +.Fn mbrtoc32 +either. +.El +.Sh ERRORS +.Fn mbrtowc +and +.Fn mbrtoc32 +cause an error in the following cases: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa s +points to an invalid multibyte character. +.It Bq Er EINVAL +.Fa mbs +points to an invalid or uninitialized +.Vt mbstate_t +object. +.El +.Sh SEE ALSO +.Xr mbrlen 3 , +.Xr mbtowc 3 , +.Xr setlocale 3 , +.Xr wcrtomb 3 +.Sh STANDARDS +.Fn mbrtowc +conforms to +.St -isoC-amd1 . +The restrict qualifier was added at +.St -isoC-99 . +.Pp +.Fn mbrtoc32 +conforms to +.St -isoC-2011 . +.Sh HISTORY +.Fn mbrtowc +has been available since +.Ox 3.8 +and has provided support for UTF-8 since +.Ox 4.8 . +.Pp +.Fn mbrtoc32 +has been available since +.Ox 7.4 . +.Sh CAVEATS +.Fn mbrtowc +and +.Fn mbrtoc32 +are not suitable for programs that care about internals of the character +encoding scheme used by the byte string pointed to by +.Fa s . +.Pp +It is possible that these functions +fail because of locale configuration errors. +An +.Dq invalid +character sequence may simply be encoded in a different encoding than that +of the current locale. +.Pp +The special cases for +.Fa s No == Dv NULL +and +.Fa mbs No == Dv NULL +do not make any sense. +Instead of passing +.Dv NULL +for +.Fa mbs , +.Xr mbtowc 3 +can be used. +.Pp +Earlier versions of this man page implied that calling +.Fn mbrtowc +with a +.Dv NULL +.Fa s +argument would always set +.Fa mbs +to the initial conversion state. +But this is true only if the previous call to +.Fn mbrtowc +using +.Fa mbs +did not return (size_t)-1 or (size_t)-2. +It is recommended to zero the mbstate_t object instead. diff --git a/static/openbsd/man3/mbsinit.3 b/static/openbsd/man3/mbsinit.3 new file mode 100644 index 00000000..3e1787ab --- /dev/null +++ b/static/openbsd/man3/mbsinit.3 @@ -0,0 +1,78 @@ +.\" $OpenBSD: mbsinit.3,v 1.4 2022/03/29 18:15:52 naddy Exp $ +.\" $NetBSD: mbsinit.3,v 1.4 2003/04/16 13:34:40 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 $Mdocdate: March 29 2022 $ +.Dt MBSINIT 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbsinit +.Nd determines whether the state object is in initial state +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fn mbsinit "const mbstate_t *ps" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +.Fn mbsinit +determines whether the state object pointed to by +.Fa ps +is in initial conversion state, or not. +.Pp +.Fa ps +may be a +.Dv 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 in initial state. +.It non-zero +The current state is in initial state or +.Fa ps +is a +.Dv NULL +pointer. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +No errors are defined. +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mbsinit +function conforms to +.\" .St -isoC-amd1 . +ISO/IEC 9899/AMD1:1995 +.Pq Dq ISO C90, Amendment 1 . diff --git a/static/openbsd/man3/mbsrtowcs.3 b/static/openbsd/man3/mbsrtowcs.3 new file mode 100644 index 00000000..bed81ad2 --- /dev/null +++ b/static/openbsd/man3/mbsrtowcs.3 @@ -0,0 +1,198 @@ +.\" $OpenBSD: mbsrtowcs.3,v 1.5 2013/06/05 03:39:22 tedu Exp $ +.\" $NetBSD: mbsrtowcs.3,v 1.6 2003/09/08 17:54:31 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 $Mdocdate: June 5 2013 $ +.Dt MBSRTOWCS 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbsrtowcs , +.Nm mbsnrtowcs +.Nd converts a multibyte character string to a wide-character string \ +(restartable) +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn mbsrtowcs "wchar_t * restrict dst" "const char ** restrict src" "size_t len" \ +"mbstate_t * restrict ps" +.Ft size_t +.Fn mbsnrtowcs "wchar_t * restrict dst" "const char ** restrict src" "size_t nmc" \ +"size_t len" "mbstate_t * restrict ps" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn mbsrtowcs +function converts the multibyte character string indirectly pointed to by +.Fa src +to the corresponding wide-character string and stores it in the +array pointed to by +.Fa dst . +The conversion stops due to the following reasons: +.Bl -bullet +.It +The conversion reaches a null byte. +In this case, the null byte is also converted. +.It +The conversion has already stored +.Fa len +wide characters. +.It +The conversion encounters an invalid character. +.El +.Pp +The +.Fn mbsnrtowcs +function is equivalent to +.Fn mbsrtowcs +except that it will additionally stop the conversion after processing +.Fa nmc +bytes. +.Pp +Each character is converted as if +.Xr mbrtowc 3 +is continuously called. +.Pp +After conversion, +if +.Fa dst +is not a null pointer, +the pointer object pointed to by +.Fa src +is a null pointer (if the conversion is stopped due to reaching a null byte) +or the address just past the last byte processed. +.Pp +If +.Fa dst +is not a +null pointer and the conversion is stopped due to reaching a null byte, +the state object pointed to by +.Fa ps +is set to an initial state after the conversion has taken place. +.Pp +The behaviour of the +.Fn mbsrtowcs +and +.Fn mbsnrtowcs +functions is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +There are two special cases: +.Bl -tag -width 012345678901 +.It "dst == NULL" +The conversion takes place, but the resultant wide-character string +is discarded. +In this case, the pointer object pointed to by +.Fa src +is not modified and +.Fa len +is ignored. +.It "ps == NULL" +The +.Fn mbsrtowcs +and +.Fn mbsnrtowcs +functions use their own internal state objects to keep the conversion state, +instead of +.Fa ps +as mentioned in this manual page. +.Pp +Calling any other functions in +.Em libc +never change these internal states, +which are initialized at startup time of the program. +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +The +.Fn mbsrtowcs +and +.Fn mbsnrtowcs +functions return: +.Bl -tag -width 012345678901 +.It 0 or positive +The value returned is the number of elements stored in the array pointed to by +.Fa dst , +except for a terminating null wide character (if any). +If +.Fa dst +is not null and the value returned is equal to +.Fa len , +the wide-character string pointed to by +.Fa dst +is not null terminated. +If +.Fa dst +is a null pointer, the value returned is the number of elements to contain +the whole string converted, except for a terminating null wide character. +.It (size_t)-1 +The array indirectly pointed to by +.Fa src +contains a byte sequence forming invalid character. +In this case, +.Va errno +is set to indicate the error. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +The +.Fn mbsrtowcs +and +.Fn mbsnrtowcs +functions may return the following errors: +.Bl -tag -width Er +.It Bq Er EILSEQ +The pointer pointed to by +.Fa src +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 mbrtowc 3 , +.Xr mbstowcs 3 , +.Xr setlocale 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mbsrtowcs +function conforms to +.\" .St -isoC-amd1 . +ISO/IEC 9899/AMD1:1995 +.Pq Dq ISO C90, Amendment 1 . +The restrict qualifier is added at +.\" .St -isoC99 . +ISO/IEC 9899/1999 +.Dq Pq ISO C99 . +.Pp +The +.Fn mbsnrtowcs +function conforms to +.St -p1003.1-2008 . diff --git a/static/openbsd/man3/mbstowcs.3 b/static/openbsd/man3/mbstowcs.3 new file mode 100644 index 00000000..698098e7 --- /dev/null +++ b/static/openbsd/man3/mbstowcs.3 @@ -0,0 +1,126 @@ +.\" $OpenBSD: mbstowcs.3,v 1.8 2015/10/24 23:07:41 mmcc Exp $ +.\" $NetBSD: mbstowcs.3,v 1.6 2003/09/08 17:54:31 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 $Mdocdate: October 24 2015 $ +.Dt MBSTOWCS 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbstowcs +.Nd converts a multibyte character string to a wide-character string +.\" ---------------------------------------------------------------------- +.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 null-terminated multibyte character string pointed to by +.Fa s +to the corresponding wide-character string and stores up to +.Fa n +wide characters in 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 begin 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 +The value returned is the number of elements stored in the array pointed to by +.Fa pwcs , +except for a terminating null wide character (if any). +If +.Fa pwcs +is not null and the value returned is equal to +.Fa n , +the wide-character string pointed to by +.Fa pwcs +is not null 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 null wide character. +.It (size_t)-1 +The array indirectly pointed to by +.Fa s +contains a byte sequence forming invalid character. +In this case, +.Fn mbstowcs +sets +.Va errno +to indicate the error. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +.Fn mbstowcs +may cause an error in the following cases: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa s +points to the string containing invalid or incomplete multibyte character. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr mbtowc 3 , +.Xr setlocale 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mbstowcs +function conforms to +.St -ansiC . +The restrict qualifier is added at +.\" .St -isoC99 . +ISO/IEC 9899/199 +.Pq Dq ISO C99 . diff --git a/static/openbsd/man3/mbtowc.3 b/static/openbsd/man3/mbtowc.3 new file mode 100644 index 00000000..2c8d80ff --- /dev/null +++ b/static/openbsd/man3/mbtowc.3 @@ -0,0 +1,249 @@ +.\" $OpenBSD: mbtowc.3,v 1.8 2023/11/11 01:38:23 schwarze Exp $ +.\" $NetBSD: mbtowc.3,v 1.5 2003/09/08 17:54:31 wiz Exp $ +.\" +.\" Copyright (c) 2016, 2023 Ingo Schwarze +.\" Copyright (c) 2010, 2015 Stefan Sperling +.\" 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 $Mdocdate: November 11 2023 $ +.Dt MBTOWC 3 +.Os +.Sh NAME +.Nm mbtowc +.Nd converts a multibyte character to a wide character +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn mbtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" +.Sh DESCRIPTION +The +.Fn mbtowc +function 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 . +This function may inspect at most +.Fa n +bytes of the array pointed to by +.Fa s . +.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 returns an error and the internal state will +be undefined. +.Pp +If a call to +.Fn mbtowc +results in an undefined internal state, parsing of the string starting at +.Fa s +cannot continue, not even at a later byte, and +.Fn mbtowc +must be called with +.Ar s +set to +.Dv NULL +to reset the internal state before it can safely be used again +on a different string. +.Pp +The behaviour of +.Fn mbtowc +is affected by the +.Dv LC_CTYPE +category of the current locale. +Calling any other functions in +.Em libc +never changes the internal +state of +.Fn mbtowc , +except for calling +.Xr setlocale 3 +with the +.Dv LC_CTYPE +category set to a different locale. +Such +.Xr setlocale 3 +calls cause the internal state of this function to be undefined. +.Pp +In state-dependent encodings such as ISO/IEC 2022-JP, +.Fa s +may point to the special sequence of bytes to change the shift-state. +Because such sequence bytes do not correspond to any individual wide character, +.Fn mbtowc +treats them as if they were part of the subsequent multibyte character. +.Pp +The following special cases apply to the arguments: +.Bl -tag -width 012345678901 +.It s == NULL +.Fn mbtowc +initializes its own internal state to the initial state, and +determines whether the current encoding is state-dependent. +.Fn mbtowc +returns 0 if the encoding is state-independent, +otherwise non-zero. +.Fa pwc +is ignored. +.It pwc == NULL +.Fn mbtowc +behaves just as if +.Fa pwc +was not +.Dv NULL , +including modifications to internal state, +except that the result of the conversion is discarded. +This can be used to determine the size of the wide character +representation of a multibyte string. +Another use case is a check for illegal or incomplete multibyte sequences. +.It n == 0 +In this case, +the first +.Fa n +bytes of the array pointed to by +.Fa s +never form a complete character and +.Fn mbtowc +always fails. +.El +.Sh RETURN VALUES +Normally, +.Fn mbtowc +returns: +.Bl -tag -width 012345678901 +.It 0 +.Fa s +points to a null byte +.Pq Sq \e0 . +.It positive +Number of bytes for the valid multibyte character pointed to by +.Fa s . +There are no cases where 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. +.Va errno +is set to indicate the error. +.El +.Pp +When +.Fa s +is +.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 EXAMPLES +The following program parses a UTF-8 string and reports encoding errors: +.Bd -literal +#include +#include +#include +#include + +int +main(void) +{ + char s[LINE_MAX]; + wchar_t wc; + int i, len; + + setlocale(LC_CTYPE, "C.UTF-8"); + if (fgets(s, sizeof(s), stdin) == NULL) + *s = '\e0'; + for (i = 0, len = 1; len != 0; i += len) { + switch (len = mbtowc(&wc, s + i, MB_CUR_MAX)) { + case 0: + printf("byte %d end of string 0x00\en", i); + break; + case -1: + printf("byte %d invalid 0x%0.2hhx\en", i, s[i]); + len = 1; + break; + default: + printf("byte %d U+%0.4X %lc\en", i, wc, wc); + break; + } + } + return 0; +} +.Ed +.Pp +Recovering from encoding errors and continuing to parse the rest of the +string as shown above is only possible for state-independent character +encodings. +For full generality, the error handling can be modified +to reset the internal state. +In that case, the rest of the string has to be skipped +if the encoding is state-dependent: +.Bd -literal + case -1: + printf("byte %d invalid 0x%0.2hhx\en", i, s[i]); + len = !mbtowc(NULL, NULL, MB_CUR_MAX); + break; +.Ed +.Sh ERRORS +.Fn mbtowc +will set +.Va errno +in the following cases: +.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 . +Setting +.Va errno +is an +.St -p1003.1-2008 +extension. +.Sh CAVEATS +On error, callers of +.Fn mbtowc +cannot tell whether the multibyte character was invalid or incomplete. +To treat incomplete data differently from invalid data the +.Xr mbrtowc 3 +function can be used instead. diff --git a/static/openbsd/man3/memccpy.3 b/static/openbsd/man3/memccpy.3 new file mode 100644 index 00000000..49b8ab5d --- /dev/null +++ b/static/openbsd/man3/memccpy.3 @@ -0,0 +1,81 @@ +.\" $OpenBSD: memccpy.3,v 1.14 2024/12/11 23:28:20 jsg 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. +.\" +.\" @(#)memccpy.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt MEMCCPY 3 +.Os +.Sh NAME +.Nm memccpy +.Nd copy string until character found +.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 +.Vt 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. +.Pp +If the +.Fa src +and +.Fa dst +strings overlap, the behavior is undefined. +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr memcpy 3 , +.Xr memmove 3 , +.Xr strcpy 3 , +.Xr strlcpy 3 +.Sh HISTORY +The +.Fn memccpy +function first appeared in +.At V +and was reimplemented for +.Bx 4.3 . diff --git a/static/openbsd/man3/memchr.3 b/static/openbsd/man3/memchr.3 new file mode 100644 index 00000000..fa5809fa --- /dev/null +++ b/static/openbsd/man3/memchr.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: memchr.3,v 1.14 2024/12/11 23:28:20 jsg 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. +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt MEMCHR 3 +.Os +.Sh NAME +.Nm memchr , +.Nm memrchr +.Nd locate byte in byte string +.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 +.Vt unsigned char ) +in string +.Fa b . +.Pp +The +.Fn memrchr +function behaves like +.Fn memchr , +except that it locates the last occurrence of +.Fa c +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 strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 , +.Xr wmemchr 3 +.Sh STANDARDS +The +.Fn memchr +function conforms to +.St -ansiC . +.Pp +The +.Fn memrchr +function is an +.Ox +extension. +.Sh HISTORY +The +.Fn memchr +function first appeared in +.At V +and was reimplemented for +.Bx 4.3 . diff --git a/static/openbsd/man3/memcmp.3 b/static/openbsd/man3/memcmp.3 new file mode 100644 index 00000000..ace8f792 --- /dev/null +++ b/static/openbsd/man3/memcmp.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: memcmp.3,v 1.11 2024/12/11 23:28:20 jsg 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. +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt MEMCMP 3 +.Os +.Sh NAME +.Nm memcmp +.Nd compare byte string +.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 +.Vt unsigned char +values, so that +.Sq Li \e200 +is greater than +.Sq Li \&\e0 , +for example). +Zero-length strings are always identical. +.Sh SEE ALSO +.Xr bcmp 3 , +.Xr strcasecmp 3 , +.Xr strcmp 3 , +.Xr strcoll 3 , +.Xr strxfrm 3 , +.Xr timingsafe_memcmp 3 , +.Xr wmemcmp 3 +.Sh STANDARDS +The +.Fn memcmp +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn memcmp +function first appeared in +.At V +and was reimplemented for +.Bx 4.3 . diff --git a/static/openbsd/man3/memcpy.3 b/static/openbsd/man3/memcpy.3 new file mode 100644 index 00000000..b093afc9 --- /dev/null +++ b/static/openbsd/man3/memcpy.3 @@ -0,0 +1,79 @@ +.\" $OpenBSD: memcpy.3,v 1.11 2024/12/11 23:28:20 jsg 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. +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt MEMCPY 3 +.Os +.Sh NAME +.Nm memcpy +.Nd copy bytes +.Sh SYNOPSIS +.In string.h +.Ft void * +.Fn memcpy "void *dst" "const void *src" "size_t len" +.Sh DESCRIPTION +The +.Fn memcpy +function copies +.Fa len +bytes from buffer +.Fa src +to buffer +.Fa dst . +If the two buffers may overlap, +.Xr memmove 3 +must be used instead. +.Sh RETURN VALUES +The +.Fn memcpy +function returns the original value of +.Fa dst . +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr memccpy 3 , +.Xr memmove 3 , +.Xr strcpy 3 , +.Xr strlcpy 3 , +.Xr wmemcpy 3 +.Sh STANDARDS +The +.Fn memcpy +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn memcpy +function first appeared in +.At V +and was reimplemented for +.Bx 4.3 . diff --git a/static/openbsd/man3/memmem.3 b/static/openbsd/man3/memmem.3 new file mode 100644 index 00000000..eeb621f8 --- /dev/null +++ b/static/openbsd/man3/memmem.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: memmem.3,v 1.5 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2005 Pascal Gloor +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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 $Mdocdate: June 13 2025 $ +.Dt MEMMEM 3 +.Os +.Sh NAME +.Nm memmem +.Nd locate a byte substring in a byte string +.Sh SYNOPSIS +.In string.h +.Ft void * +.Fo memmem +.Fa "const void *big" "size_t big_len" +.Fa "const void *little" "size_t little_len" +.Fc +.Sh DESCRIPTION +The +.Fn memmem +function +locates the first occurrence of the byte string +.Fa little +in the byte string +.Fa big . +.Sh RETURN VALUES +If +.Fa little +is zero length, +.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 SEE ALSO +.Xr memchr 3 , +.Xr strchr 3 , +.Xr strstr 3 +.Sh STANDARDS +The +.Fn memmem +function conforms to +.St -p1003.1-2024 . +.Sh HISTORY +The +.Fn memmem +function first appeared in +.Ox 5.4 . diff --git a/static/openbsd/man3/memmove.3 b/static/openbsd/man3/memmove.3 new file mode 100644 index 00000000..8665e4ab --- /dev/null +++ b/static/openbsd/man3/memmove.3 @@ -0,0 +1,76 @@ +.\" $OpenBSD: memmove.3,v 1.9 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt MEMMOVE 3 +.Os +.Sh NAME +.Nm memmove +.Nd copy bytes +.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 buffer +.Fa src +to buffer +.Fa dst . +The two buffers 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 , +.Xr strlcpy 3 , +.Xr wmemmove 3 +.Sh STANDARDS +The +.Fn memmove +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn memmove +function first appeared in +.Bx 4.3 Reno . diff --git a/static/openbsd/man3/memset.3 b/static/openbsd/man3/memset.3 new file mode 100644 index 00000000..34f2ca78 --- /dev/null +++ b/static/openbsd/man3/memset.3 @@ -0,0 +1,75 @@ +.\" $OpenBSD: memset.3,v 1.10 2024/12/11 23:28:20 jsg 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. +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt MEMSET 3 +.Os +.Sh NAME +.Nm memset +.Nd write a byte to byte string +.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 +.Vt unsigned char ) +to the string +.Fa b . +.Sh RETURN VALUES +The +.Fn memset +function returns the original value of +.Fa b . +.Sh SEE ALSO +.Xr bzero 3 , +.Xr swab 3 , +.Xr wmemset 3 +.Sh STANDARDS +The +.Fn memset +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn memset +function first appeared in +.At V +and was reimplemented for +.Bx 4.3 . diff --git a/static/openbsd/man3/menu.3 b/static/openbsd/man3/menu.3 new file mode 100644 index 00000000..3390a367 --- /dev/null +++ b/static/openbsd/man3/menu.3 @@ -0,0 +1,214 @@ +'\" t +.\" $OpenBSD: menu.3,v 1.5 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2021,2023 Thomas E. Dickey * +.\" Copyright 1998-2014,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu.3,v 1.5 2023/10/17 09:52:10 nicm Exp $ +.TH menu 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBmenu\fP \- curses extension for programming menus +.SH SYNOPSIS +\fB#include \fP +.SH DESCRIPTION +The \fBmenu\fP library provides terminal-independent facilities for composing +menu systems on character-cell terminals. +The library includes: item routines, +which create and modify menu items; and menu routines, which group items into +menus, display menus on the screen, and handle interaction with the user. +.PP +The \fBmenu\fP library uses the \fBcurses\fP libraries, and a curses +initialization routine such as \fBinitscr\fP must be called before using any of +these functions. +To use the \fBmenu\fP library, link with the options +\fB\-lmenu \-lcurses\fP. +. +.SS Current Default Values for Item Attributes +. +The \fBmenu\fP library maintains a default value for item attributes. +You can +get or set this default by calling the appropriate \fBget_\fP or \fBset_\fP +routine with a \fBNULL\fP item pointer. +Changing this default with a +\fBset_\fP function affects future item creations, but does not change the +rendering of items already created. +. +.SS Routine Name Index +. +The following table lists each \fBmenu\fP routine and the name of +the manual page on which it is described. +.PP +.TS +l l . +\fBcurses\fP Routine Name Manual Page Name += +current_item \fBmitem_current\fP(3) +free_item \fBmitem_new\fP(3) +free_menu \fBmenu_new\fP(3) +item_count \fBmenu_items\fP(3) +item_description \fBmitem_name\fP(3) +item_index \fBmitem_current\fP(3) +item_init \fBmenu_hook\fP(3) +item_name \fBmitem_name\fP(3) +item_opts \fBmitem_opts\fP(3) +item_opts_off \fBmitem_opts\fP(3) +item_opts_on \fBmitem_opts\fP(3) +item_term \fBmenu_hook\fP(3) +item_userptr \fBmitem_userptr\fP(3) +item_value \fBmitem_value\fP(3) +item_visible \fBmitem_visible\fP(3) +menu_back \fBmenu_attributes\fP(3) +menu_driver \fBmenu_driver\fP(3) +menu_fore \fBmenu_attributes\fP(3) +menu_format \fBmenu_format\fP(3) +menu_grey \fBmenu_attributes\fP(3) +menu_init \fBmenu_hook\fP(3) +menu_items \fBmenu_items\fP(3) +menu_mark \fBmenu_mark\fP(3) +menu_opts \fBmenu_opts\fP(3) +menu_opts_off \fBmenu_opts\fP(3) +menu_opts_on \fBmenu_opts\fP(3) +menu_pad \fBmenu_attributes\fP(3) +menu_pattern \fBmenu_pattern\fP(3) +menu_request_by_name \fBmenu_requestname\fP(3) +menu_request_name \fBmenu_requestname\fP(3) +menu_spacing \fBmenu_spacing\fP(3) +menu_sub \fBmenu_win\fP(3) +menu_term \fBmenu_hook\fP(3) +menu_userptr \fBmenu_userptr\fP(3) +menu_win \fBmenu_win\fP(3) +new_item \fBmitem_new\fP(3) +new_menu \fBmenu_new\fP(3) +pos_menu_cursor \fBmenu_cursor\fP(3) +post_menu \fBmenu_post\fP(3) +scale_menu \fBmenu_win\fP(3) +set_current_item \fBmitem_current\fP(3) +set_item_init \fBmenu_hook\fP(3) +set_item_opts \fBmitem_opts\fP(3) +set_item_term \fBmenu_hook\fP(3) +set_item_userptr \fBmitem_userptr\fP(3) +set_item_value \fBmitem_value\fP(3) +set_menu_back \fBmenu_attributes\fP(3) +set_menu_fore \fBmenu_attributes\fP(3) +set_menu_format \fBmenu_format\fP(3) +set_menu_grey \fBmenu_attributes\fP(3) +set_menu_init \fBmenu_hook\fP(3) +set_menu_items \fBmenu_items\fP(3) +set_menu_mark \fBmenu_mark\fP(3) +set_menu_opts \fBmitem_opts\fP(3) +set_menu_pad \fBmenu_attributes\fP(3) +set_menu_pattern \fBmenu_pattern\fP(3) +set_menu_spacing \fBmenu_spacing\fP(3) +set_menu_sub \fBmenu_win\fP(3) +set_menu_term \fBmenu_hook\fP(3) +set_menu_userptr \fBmenu_userptr\fP(3) +set_menu_win \fBmenu_win\fP(3) +set_top_row \fBmitem_current\fP(3) +top_row \fBmitem_current\fP(3) +unpost_menu \fBmenu_post\fP(3) +.TE +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fP on error. +Routines that return +an integer return one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NO_MATCH +Character failed to match. +.TP 5 +.B E_NO_ROOM +Menu is too large for its window. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.TP 5 +.B E_NOT_POSTED +The menu has not been posted. +.TP 5 +.B E_NOT_SELECTABLE +The designated item cannot be selected. +.TP 5 +.B E_POSTED +The menu is already posted. +.TP 5 +.B E_REQUEST_DENIED +The menu driver could not process the request. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_UNKNOWN_COMMAND +The menu driver code saw an unknown request code. +.SH NOTES +The header file \fB\fP automatically includes the header files +\fB\fP and \fB\fP. +.PP +In your library list, libmenu.a should be before libncurses.a; that is, +you should say \*(``\-lmenu \-lncurses\*('', not the other way around +(which would give a link-error when using static libraries). +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.PP +The menu facility was documented in SVr4.2 in +\fICharacter User Interface Programming (UNIX SVR4.2)\fP. +.PP +It is not part of X/Open Curses. +.PP +Aside from ncurses, there are few implementations: +.bP +systems based on SVr4 source code, e.g., Solaris. +.bP +NetBSD curses. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for ncurses by Eric S. Raymond. +.SH SEE ALSO +\fBcurses\fP(3) and related pages whose names begin \*(``menu_\*('' +for detailed descriptions of the entry points. +.PP +This describes \fBncurses\fP +version 6.4 (patch 20230826). diff --git a/static/openbsd/man3/menu_attributes.3 b/static/openbsd/man3/menu_attributes.3 new file mode 100644 index 00000000..493496e4 --- /dev/null +++ b/static/openbsd/man3/menu_attributes.3 @@ -0,0 +1,114 @@ +'\" t +.\" $OpenBSD: menu_attributes.3,v 1.4 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_attributes.3,v 1.4 2023/10/17 09:52:10 nicm Exp $ +.TH menu_attributes 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.SH NAME +\fBmenu_back\fP, +\fBmenu_fore\fP, +\fBmenu_grey\fP, +\fBmenu_pad\fP, +\fBset_menu_back\fP, +\fBset_menu_fore\fP, +\fBset_menu_grey\fP, +\fBset_menu_pad\fP \- color and attribute control for menus +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_menu_fore(MENU *\fImenu\fB, chtype \fIattr\fB);\fR +.br +\fBchtype menu_fore(const MENU *\fImenu\fB);\fR +.sp +\fBint set_menu_back(MENU *\fImenu\fB, chtype \fIattr\fB);\fR +.br +\fBchtype menu_back(const MENU *\fImenu\fB);\fR +.sp +\fBint set_menu_grey(MENU *\fImenu\fB, chtype \fIattr\fB);\fR +.br +\fBchtype menu_grey(const MENU *\fImenu\fB);\fR +.sp +\fBint set_menu_pad(MENU *\fImenu\fB, int \fIpad\fB);\fR +.br +\fBint menu_pad(const MENU *\fImenu\fB);\fR +.SH DESCRIPTION +The function \fBset_menu_fore\fP sets the foreground attribute of +\fImenu\fP. This is the highlight used for selected menu items. +\fBmenu_fore\fP returns the foreground attribute. +The default +is \fBA_REVERSE\fP. +.PP +The function \fBset_menu_back\fP sets the background attribute of +\fImenu\fP. This is the highlight used for selectable (but not currently +selected) menu items. +The function \fBmenu_back\fP returns the background +attribute. +The default is \fBA_NORMAL\fP. +.PP +The function \fBset_menu_grey\fP sets the grey attribute of \fImenu\fP. This is +the highlight used for un-selectable menu items in menus that permit more than +one selection. +The function \fBmenu_grey\fP returns the grey attribute. +The default is \fBA_UNDERLINE\fP. +.PP +The function \fBset_menu_pad\fP sets the character used to fill the space +between the name and description parts of a menu item. +\fBmenu_pad\fP returns +the given menu's pad character. +The default is a blank. +.SH RETURN VALUE +These routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.SH SEE ALSO +\fBcurses\fP(3) and related pages whose names begin \*(``menu_\*('' for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_cursor.3 b/static/openbsd/man3/menu_cursor.3 new file mode 100644 index 00000000..f9a394e2 --- /dev/null +++ b/static/openbsd/man3/menu_cursor.3 @@ -0,0 +1,71 @@ +'\" t +.\" $OpenBSD: menu_cursor.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_cursor.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH menu_cursor 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBpos_menu_cursor\fP \- position a menu's cursor +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint pos_menu_cursor(const MENU *\fImenu\fB);\fR +.SH DESCRIPTION +The function \fBpos_menu_cursor\fP restores the cursor to the current position +associated with the menu's selected item. +This is useful after \fBcurses\fP +routines have been called to do screen-painting in response to a menu select. +.SH RETURN VALUE +This routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_NOT_POSTED +The menu has not been posted. +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_driver.3 b/static/openbsd/man3/menu_driver.3 new file mode 100644 index 00000000..ccf22cf3 --- /dev/null +++ b/static/openbsd/man3/menu_driver.3 @@ -0,0 +1,207 @@ +.\" $OpenBSD: menu_driver.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_driver.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.TH menu_driver 3 2023-07-01 "ncurses 6.4" "Library calls" +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBmenu_driver\fP \- command-processing loop of the menu system +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint menu_driver(MENU *\fImenu\fB, int \fIc\fB);\fR +.SH DESCRIPTION +Once a menu has been posted (displayed), you should funnel input events to it +through \fBmenu_driver\fP. This routine has three major input cases: +.bP +The input is a form navigation request. +Navigation request codes are constants defined in \fB\fP, +which are distinct from the key- and character codes +returned by \fBwgetch\fP(3). +.bP +The input is a printable character. +Printable characters (which must be positive, less than 256) are +checked according to the program's locale settings. +.bP +The input is the KEY_MOUSE special key associated with an mouse event. +.PP +The menu driver requests are as follows: +.TP 5 +REQ_LEFT_ITEM +Move left to an item. +.TP 5 +REQ_RIGHT_ITEM +Move right to an item. +.TP 5 +REQ_UP_ITEM +Move up to an item. +.TP 5 +REQ_DOWN_ITEM +Move down to an item. +.TP 5 +REQ_SCR_ULINE +Scroll up a line. +.TP 5 +REQ_SCR_DLINE +Scroll down a line. +.TP 5 +REQ_SCR_DPAGE +Scroll down a page. +.TP 5 +REQ_SCR_UPAGE +Scroll up a page. +.TP 5 +REQ_FIRST_ITEM +Move to the first item. +.TP 5 +REQ_LAST_ITEM +Move to the last item. +.TP 5 +REQ_NEXT_ITEM +Move to the next item. +.TP 5 +REQ_PREV_ITEM +Move to the previous item. +.TP 5 +REQ_TOGGLE_ITEM +Select/deselect an item. +.TP 5 +REQ_CLEAR_PATTERN +Clear the menu pattern buffer. +.TP 5 +REQ_BACK_PATTERN +Delete the previous character from the pattern buffer. +.TP 5 +REQ_NEXT_MATCH +Move to the next item matching the pattern match. +.TP 5 +REQ_PREV_MATCH +Move to the previous item matching the pattern match. +.PP +If the second argument is a printable character, the code appends +it to the pattern buffer and attempts to move to the next item matching +the new pattern. +If there is no such match, \fBmenu_driver\fP returns +\fBE_NO_MATCH\fP and deletes the appended character from the buffer. +.PP +If the second argument is one of the above pre-defined requests, the +corresponding action is performed. +.SS MOUSE HANDLING +If the second argument is the KEY_MOUSE special key, the associated +mouse event is translated into one of the above pre-defined requests. +Currently only clicks in the user window (e.g., inside the menu display +area or the decoration window) are handled. +.PP +If you click above the display region of the menu: +.bP +a REQ_SCR_ULINE is generated for a single click, +.bP +a REQ_SCR_UPAGE is generated for a double-click and +.bP +a REQ_FIRST_ITEM is generated for a triple-click. +.PP +If you click below the display region of the menu: +.bP +a REQ_SCR_DLINE is generated for a single click, +.bP +a REQ_SCR_DPAGE is generated for a double-click and +.bP +a REQ_LAST_ITEM is generated for a triple-click. +.PP +If you click at an item inside the display area of the menu: +.bP +the menu cursor is positioned to that item. +.bP +If you double-click an item a REQ_TOGGLE_ITEM +is generated and \fBE_UNKNOWN_COMMAND\fP is returned. +This return value makes sense, +because a double click usually means that an item-specific action should +be returned. +It is exactly the purpose of this return value to signal that an +application specific command should be executed. +.bP +If a translation +into a request was done, \fBmenu_driver\fP returns the result of this request. +.PP +If you clicked outside the user window +or the mouse event could not be translated +into a menu request an \fBE_REQUEST_DENIED\fP is returned. +.SS APPLICATION-DEFINED COMMANDS +If the second argument is neither printable nor one of the above +pre-defined menu requests or KEY_MOUSE, +the drive assumes it is an application-specific +command and returns \fBE_UNKNOWN_COMMAND\fP. Application-defined commands +should be defined relative to \fBMAX_COMMAND\fP, the maximum value of these +pre-defined requests. +.SH RETURN VALUE +\fBmenu_driver\fP return one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NOT_POSTED +The menu has not been posted. +.TP 5 +.B E_UNKNOWN_COMMAND +The menu driver code saw an unknown request code. +.TP 5 +.B E_NO_MATCH +Character failed to match. +.TP 5 +.B E_REQUEST_DENIED +The menu driver could not process the request. +.SH SEE ALSO +\fBcurses\fP(3), +\fBgetch\fP(3), +\fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header files +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +The support for mouse events is ncurses specific. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_format.3 b/static/openbsd/man3/menu_format.3 new file mode 100644 index 00000000..3b078450 --- /dev/null +++ b/static/openbsd/man3/menu_format.3 @@ -0,0 +1,89 @@ +'\" t +.\" $OpenBSD: menu_format.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2016 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_format.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH menu_format 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_menu_format\fP, +\fBmenu_format\fP \- set and get menu sizes +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_menu_format(MENU *\fImenu\fB, int \fIrows\fB, int \fIcols\fB);\fR +.br +\fBvoid menu_format(const MENU *\fImenu\fB, int *\fIrows\fB, int *\fIcols\fB);\fR +.SH DESCRIPTION +The function \fBset_menu_format\fP sets the maximum display size of the given +menu. +If this size is too small to display all menu items, the menu will be +made scrollable. +If this size is larger than the menus subwindow and the +subwindow is too small to display all menu items, \fBpost_menu\fP will fail. +.PP +The default format is 16 rows, 1 column. +Calling \fBset_menu_format\fP with a +null menu pointer will change this default. +A zero row or column argument to +\fBset_menu_format\fP is interpreted as a request not to change the current +value. +.PP +The function \fBmenu_format\fP returns the maximum-size constraints for the +given menu into the storage addressed by \fBrows\fP and \fBcols\fP. +.SH RETURN VALUE +These routines returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The menu is already posted. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_hook.3 b/static/openbsd/man3/menu_hook.3 new file mode 100644 index 00000000..83453edb --- /dev/null +++ b/static/openbsd/man3/menu_hook.3 @@ -0,0 +1,103 @@ +'\" t +.\" $OpenBSD: menu_hook.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2007,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_hook.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH menu_hook 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBmenu_hook\fP \- set hooks for automatic invocation by applications +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_item_init(MENU *\fImenu\fB, Menu_Hook \fIfunc);\fR +.br +\fBMenu_Hook item_init(const MENU *\fImenu);\fR +.sp +\fBint set_item_term(MENU *\fImenu\fB, Menu_Hook \fIfunc);\fR +.br +\fBMenu_Hook item_term(const MENU *\fImenu);\fR +.sp +\fBint set_menu_init(MENU *\fImenu\fB, Menu_Hook \fIfunc);\fR +.br +\fBMenu_Hook menu_init(const MENU *\fImenu);\fR +.sp +\fBint set_menu_term(MENU *\fImenu\fB, Menu_Hook \fIfunc);\fR +.br +\fBMenu_Hook menu_term(const MENU *\fImenu);\fR +.SH DESCRIPTION +These functions make it possible to set hook functions to be called at various +points in the automatic processing of input event codes by \fBmenu_driver\fP. +.PP +The function \fBset_item_init\fP sets a hook to be called at menu-post time and +each time the selected item changes (after the change). +\fBitem_init\fP +returns the current item init hook, if any (\fBNULL\fP if there is no such +hook). +.PP +The function \fBset_item_term\fP sets a hook to be called at menu-unpost time +and each time the selected item changes (before the change). +\fBitem_term\fP +returns the current item term hook, if any (\fBNULL\fP if there is no such +hook). +.PP +The function \fBset_menu_init\fP sets a hook to be called at menu-post time and +just after the top row on the menu changes once it is posted. +\fBmenu_init\fP +returns the current menu init hook, if any (\fBNULL\fP if there is no such +hook). +.PP +The function \fBset_menu_term\fP sets a hook to be called at menu-unpost time +and just before the top row on the menu changes once it is posted. +\fBmenu_term\fP returns the current menu term hook, if any (\fBNULL\fP if there +is no such hook). +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fP on error. +Other routines +return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric +S. Raymond. diff --git a/static/openbsd/man3/menu_items.3 b/static/openbsd/man3/menu_items.3 new file mode 100644 index 00000000..62b4d22f --- /dev/null +++ b/static/openbsd/man3/menu_items.3 @@ -0,0 +1,92 @@ +'\" t +.\" $OpenBSD: menu_items.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2012,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_items.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH menu_items 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_menu_items\fP, +\fBmenu_items\fP, +\fBitem_count\fP \- make and break connections between items and menus +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_menu_items(MENU *\fImenu\fB, ITEM **\fIitems\fB);\fR +.br +\fBITEM **menu_items(const MENU *\fImenu\fB);\fR +.br +\fBint item_count(const MENU *\fImenu\fB);\fR +.SH DESCRIPTION +The function \fBset_menu_items\fP changes the item pointer array of the given +\fImenu\fP. The array must be terminated by a \fBNULL\fP. +.PP +The function \fBmenu_items\fP returns the item array of the given menu. +.PP +The function \fBitem_count\fP returns the count of items in \fImenu\fP. +.SH RETURN VALUE +The function \fBmenu_items\fP returns a pointer (which may be \fBNULL\fP). +It does not set \fBerrno\fP. +.PP +The function \fBitem_count\fP returns \fBERR\fP (the general \fBcurses\fP error +return value) if its \fImenu\fP parameter is \fBNULL\fP. +.PP +The function \fBset_menu_items\fP returns one of the following codes on error: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.TP 5 +.B E_POSTED +The menu is already posted. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +. +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.PP +The SVr4 menu library documentation specifies the \fBitem_count\fP error value +as \-1 (which is the value of \fBERR\fP). +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_mark.3 b/static/openbsd/man3/menu_mark.3 new file mode 100644 index 00000000..7496a0d1 --- /dev/null +++ b/static/openbsd/man3/menu_mark.3 @@ -0,0 +1,85 @@ +'\" t +.\" $OpenBSD: menu_mark.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_mark.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH menu_mark 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_menu_mark\fP, +\fBmenu_mark\fP \- get and set the menu mark string +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_menu_mark(MENU *\fImenu\fB, const char *\fImark\fB);\fR +.br +\fBconst char *menu_mark(const MENU *\fImenu\fB);\fR +.SH DESCRIPTION +In order to make menu selections visible on older terminals without +highlighting or color capability, the menu library marks selected items +in a menu with a prefix string. +.PP +The function \fBset_menu_mark\fP sets the mark string for the given menu. +Calling \fBset_menu_mark\fP with a null menu item will abolish the mark string. +Note that changing the length of the mark string for a menu while the +menu is posted is likely to produce unhelpful behavior. +.PP +The default string is "\-" (a dash). +Calling \fBset_menu_mark\fP with +a non-\fBNULL\fP menu argument will change this default. +.PP +The function \fBmenu_mark\fP returns the menu's mark string (or \fBNULL\fP if +there is none). +.SH RETURN VALUE +The function \fBmenu_mark\fP returns a pointer (which may be \fBNULL\fP). +It does not set \fBerrno\fP. +.PP +The function \fBset_menu_mark\fP may return the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_new.3 b/static/openbsd/man3/menu_new.3 new file mode 100644 index 00000000..73f5f3aa --- /dev/null +++ b/static/openbsd/man3/menu_new.3 @@ -0,0 +1,84 @@ +'\" t +.\" $OpenBSD: menu_new.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_new.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH menu_new 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBnew_menu\fP, +\fBfree_menu\fP \- create and destroy menus +.SH SYNOPSIS +\fB#include \fP +.sp +\fBMENU *new_menu(ITEM **\fIitems\fB);\fR +.br +\fBint free_menu(MENU *\fImenu\fB);\fR +.SH DESCRIPTION +The function \fBnew_menu\fP creates a new menu connected to a specified item +pointer array (which must be \fBNULL\fP-terminated). +.PP +The function \fBfree_menu\fP disconnects \fImenu\fP from its item array +and frees the storage allocated for the menu. +.SH RETURN VALUE +The function \fBnew_menu\fP returns \fBNULL\fP on error. +It sets \fBerrno\fP according to the function's failure: +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred, e.g., malloc failure. +.PP +The function \fBfree_menu\fP returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The menu has already been posted. +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_opts.3 b/static/openbsd/man3/menu_opts.3 new file mode 100644 index 00000000..c46779f2 --- /dev/null +++ b/static/openbsd/man3/menu_opts.3 @@ -0,0 +1,110 @@ +'\" t +.\" $OpenBSD: menu_opts.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2016 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_opts.3,v 1.10 2023/10/17 09:52:10 nicm Exp $ +.TH menu_opts 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_menu_opts\fP, +\fBmenu_opts_on\fP, +\fBmenu_opts_off\fP, +\fBmenu_opts\fP \- set and get menu options +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_menu_opts(MENU *\fImenu\fB, Menu_Options \fIopts\fB);\fR +.br +\fBMenu_Options menu_opts(const MENU *\fImenu\fB);\fR +.sp +\fBint menu_opts_on(MENU *\fImenu\fB, Menu_Options \fIopts\fB);\fR +.br +\fBint menu_opts_off(MENU *\fImenu\fB, Menu_Options \fIopts\fB);\fR +.SH DESCRIPTION +The function \fBset_menu_opts\fP sets all the given menu's option bits (menu +option bits may be logically-OR'ed together). +.PP +The function \fBmenu_opts_on\fP turns on the given option bits, and leaves +others alone. +.PP +The function \fBmenu_opts_off\fP turns off the given option bits, and leaves +others alone. +.PP +The function \fBmenu_opts\fP returns the menu's current option bits. +.PP +The following options are defined (all are on by default): +.TP 5 +O_ONEVALUE +Only one item can be selected for this menu. +.TP 5 +O_SHOWDESC +Display the item descriptions when the menu is posted. +.TP 5 +O_ROWMAJOR +Display the menu in row-major order. +.TP 5 +O_IGNORECASE +Ignore the case when pattern-matching. +.TP 5 +O_SHOWMATCH +Move the cursor to within the item name while pattern-matching. +.TP 5 +O_NONCYCLIC +Don't wrap around next-item and previous-item, +requests to the other end of the menu. +.TP 5 +O_MOUSE_MENU +If user clicks with the mouse +and it does not fall on the currently active menu, +push \fBKEY_MOUSE\fP and the \fBMEVENT\fP data +back on the queue to allow processing in another part of the calling program. +.SH RETURN VALUE +Except for \fBmenu_opts\fP, each routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_POSTED +The menu is already posted. +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_pattern.3 b/static/openbsd/man3/menu_pattern.3 new file mode 100644 index 00000000..6c7cda3b --- /dev/null +++ b/static/openbsd/man3/menu_pattern.3 @@ -0,0 +1,93 @@ +.\" $OpenBSD: menu_pattern.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_pattern.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.TH menu_pattern 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_menu_pattern\fP, +\fBmenu_pattern\fP \- set and get a menu's pattern buffer +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_menu_pattern(MENU *\fImenu\fB, const char *\fIpattern\fB);\fR +.br +\fBchar *menu_pattern(const MENU *\fImenu\fB);\fR +.SH DESCRIPTION +Every menu has an associated pattern match buffer. +As input events that are +printable characters come in, they are appended to this match buffer +and tested for a match, as described in \fBmenu_driver\fP(3). +.PP +The function \fBset_menu_pattern\fP sets the pattern buffer for the given menu +and tries to find the first matching item. +If it succeeds, that item becomes +current; if not, the current item does not change. +.PP +The function \fBmenu_pattern\fP returns the pattern buffer of the given +\fImenu\fP. +.SH RETURN VALUE +The function \fBmenu_pattern\fP returns a pointer, +which is \fBNULL\fP if the \fImenu\fP parameter is \fBNULL\fP. +Otherwise, it is a pointer to a string which is empty +if no pattern has been set. +It does not set \fBerrno\fP. +.PP +The function \fBset_menu_pattern\fP may return the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to menu. +.TP 5 +.B E_NO_MATCH +Character failed to match. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_post.3 b/static/openbsd/man3/menu_post.3 new file mode 100644 index 00000000..b697d52f --- /dev/null +++ b/static/openbsd/man3/menu_post.3 @@ -0,0 +1,92 @@ +'\" t +.\" $OpenBSD: menu_post.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_post.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH menu_post 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBpost_menu\fP, +\fBunpost_menu\fP \- write or erase menus from associated subwindows +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint post_menu(MENU *\fImenu\fB);\fR +.br +\fBint unpost_menu(MENU *\fImenu\fB);\fR +.SH DESCRIPTION +The function \fBpost_menu\fP displays a menu to its associated subwindow. +To +trigger physical display of the subwindow, +use \fBrefresh\fP(3) or some equivalent +\fBcurses\fP routine (the implicit \fBdoupdate\fP triggered by an \fBcurses\fP +input request will do). +\fBpost_menu\fP resets the selection status of all items. +.PP +The function \fBunpost_menu\fP erases menu from its associated subwindow. +.SH RETURN VALUE +These routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The menu has already been posted. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NO_ROOM +Menu is too large for its window. +You should consider using \fBset_menu_format\fP to solve the problem. +.TP 5 +.B E_NOT_POSTED +The menu has not been posted. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_requestname.3 b/static/openbsd/man3/menu_requestname.3 new file mode 100644 index 00000000..f54d6976 --- /dev/null +++ b/static/openbsd/man3/menu_requestname.3 @@ -0,0 +1,70 @@ +'\" t +.\" $OpenBSD: menu_requestname.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_requestname.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.TH menu_requestname 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBmenu_request_by_name\fP, +\fBmenu_request_name\fP \- handle printable menu request names +.SH SYNOPSIS +\fB#include \fP +.sp +\fBconst char *menu_request_name(int \fIrequest\fB);\fR +.br +\fBint menu_request_by_name(const char *\fIname\fB);\fR +.SH DESCRIPTION +The function \fBmenu_request_name\fP returns the printable name of a menu +request code. +.br +The function \fBmenu_request_by_name\fP searches in the name-table for a request +with the given name and returns its request code. +Otherwise E_NO_MATCH is returned. +.SH RETURN VALUE +\fBmenu_request_name\fP returns \fBNULL\fP on error +and sets \fBerrno\fP to \fBE_BAD_ARGUMENT\fP. +.br +\fBmenu_request_by_name\fP returns \fBE_NO_MATCH\fP on error. +It does not set \fBerrno\fP. +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on +Version 7, BSD or System V implementations. +It is recommended that +any code depending on them be conditioned using NCURSES_VERSION. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_spacing.3 b/static/openbsd/man3/menu_spacing.3 new file mode 100644 index 00000000..233582ce --- /dev/null +++ b/static/openbsd/man3/menu_spacing.3 @@ -0,0 +1,93 @@ +'\" t +.\" $OpenBSD: menu_spacing.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_spacing.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.TH menu_spacing 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_menu_spacing\fP, +\fBmenu_spacing\fP \- set and get spacing between menu items. +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_menu_spacing(MENU *\fImenu\fB,\fR + \fBint \fIspc_description\fB,\fR + \fBint \fIspc_rows\fB,\fR + \fBint \fIspc_columns\fB);\fR +.br +\fBint menu_spacing(const MENU *\fImenu\fB,\fR + \fBint* \fIspc_description\fB,\fR + \fBint* \fIspc_rows\fB,\fR + \fBint* \fIspc_columns\fB);\fR +.SH DESCRIPTION +The function \fBset_menu_spacing\fP sets the spacing information for the menu. +Its parameter \fBspc_description\fP controls the number of spaces +between an item name and an item description. +It must not be larger than \fBTABSIZE\fP. +The menu system puts in the +middle of this spacing area the pad character. +The remaining parts are filled with +spaces. +The \fBspc_rows\fP parameter controls the number of rows +that are used for an item. +It must not be larger than 3. +The menu system inserts the blank lines between item rows, these lines +will contain the pad character in the appropriate positions. +The \fBspc_columns\fP parameter controls +the number of blanks between columns of items. +It must not be larger than \fBTABSIZE\fP. +A value of 0 for all the spacing values resets them to the default, +which is 1 for all of them. +.br +The function \fBmenu_spacing\fP passes back the spacing info for the menu. +If a +pointer is NULL, this specific info is simply not returned. +.SH RETURN VALUE +Both routines return \fBE_OK\fP on success. +\fBset_menu_spacing\fP may return +\fBE_POSTED\fP if the menu is posted, or \fBE_BAD_ARGUMENT\fP if one of the +spacing values is out of range. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_variables\fP(3), +\fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on +Version 7, BSD or System V implementations. +It is recommended that +any code depending on them be conditioned using NCURSES_VERSION. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_userptr.3 b/static/openbsd/man3/menu_userptr.3 new file mode 100644 index 00000000..814406f8 --- /dev/null +++ b/static/openbsd/man3/menu_userptr.3 @@ -0,0 +1,67 @@ +'\" t +.\" $OpenBSD: menu_userptr.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_userptr.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH menu_userptr 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_menu_userptr\fP, +\fBmenu_userptr\fP \- associate application data with a menu item +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_menu_userptr(MENU *\fImenu\fB, void *\fIuserptr\fB);\fR +.br +\fBvoid *menu_userptr(const MENU *\fImenu\fB);\fR +.SH DESCRIPTION +Every menu and every menu item has a field that can be used to hold +application-specific data (that is, the menu-driver code leaves it alone). +These functions get and set the menu user pointer field. +.SH RETURN VALUE +\fBmenu_userptr\fP returns a pointer (which may be \fBNULL\fP). +It does not set \fBerrno\fP. +.PP +\fBset_menu_userptr\fP returns \fBE_OK\fP (success). +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.PP +The user pointer is a void pointer. +We chose not to leave it as a char pointer for SVr4 compatibility. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/menu_win.3 b/static/openbsd/man3/menu_win.3 new file mode 100644 index 00000000..4b439a22 --- /dev/null +++ b/static/openbsd/man3/menu_win.3 @@ -0,0 +1,97 @@ +'\" t +.\" $OpenBSD: menu_win.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2006,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_win.3,v 1.9 2023/10/17 09:52:10 nicm Exp $ +.TH menu_win 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBmenu_win\fP \- make and break menu window and subwindow associations +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_menu_win(MENU *\fImenu\fB, WINDOW *\fIwin\fB);\fR +.br +\fBWINDOW *menu_win(const MENU *\fImenu\fB);\fR +.sp +\fBint set_menu_sub(MENU *\fImenu\fB, WINDOW *\fIsub\fB);\fR +.br +\fBWINDOW *menu_sub(const MENU *\fImenu\fB);\fR +.sp +\fBint scale_menu(const MENU *\fImenu, int *\fIrows\fB, int *\fIcolumns);\fR +.SH DESCRIPTION +Every menu has an associated pair of \fBcurses\fP windows. +The menu window +displays any title and border associated with the window; the menu subwindow +displays the items of the menu that are currently available for selection. +.PP +The first four functions get and set those windows. +It is not necessary to set +either window; by default, the driver code uses \fBstdscr\fP for both. +.PP +In the \fBset_\fP functions, window argument of \fBNULL\fP is treated as though +it were \fBstsdcr\fP. A menu argument of \fBNULL\fP is treated as a request +to change the system default menu window or subwindow. +.PP +The function \fBscale_menu\fP returns the minimum size required for the +subwindow of \fImenu\fP. +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fP on error. +Routines that return +an integer return one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The menu has already been posted. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_variables\fP(3), +\fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/mio_open.3 b/static/openbsd/man3/mio_open.3 new file mode 100644 index 00000000..b80779f2 --- /dev/null +++ b/static/openbsd/man3/mio_open.3 @@ -0,0 +1,255 @@ +.\" $OpenBSD: mio_open.3,v 1.20 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2007 Alexandre Ratchov +.\" +.\" 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: June 13 2025 $ +.Dt MIO_OPEN 3 +.Os +.Sh NAME +.Nm mio_open , +.Nm mio_close , +.Nm mio_read , +.Nm mio_write , +.Nm mio_nfds , +.Nm mio_pollfd , +.Nm mio_revents , +.Nm mio_eof +.Nd sndio interface to MIDI streams +.Sh SYNOPSIS +.Lb libsndio +.In sndio.h +.Ft struct mio_hdl * +.Fn mio_open "const char *name" "unsigned int mode" "int nbio_flag" +.Ft void +.Fn mio_close "struct mio_hdl *hdl" +.Ft size_t +.Fn mio_read "struct mio_hdl *hdl" "void *addr" "size_t nbytes" +.Ft size_t +.Fn mio_write "struct mio_hdl *hdl" "const void *addr" "size_t nbytes" +.Ft int +.Fn mio_nfds "struct mio_hdl *hdl" +.Ft int +.Fn mio_pollfd "struct mio_hdl *hdl" "struct pollfd *pfd" "int events" +.Ft int +.Fn mio_revents "struct mio_hdl *hdl" "struct pollfd *pfd" +.Ft int +.Fn mio_eof "struct mio_hdl *hdl" +.Sh DESCRIPTION +The +.Nm sndio +library allows user processes to access +.Xr midi 4 +hardware and +.Xr sndiod 8 +MIDI thru boxes and control ports in a uniform way. +.Ss Opening and closing a MIDI stream +First the application must call the +.Fn mio_open +function to obtain a handle representing the newly created stream; +later it will be passed as the +.Ar hdl +argument of most other functions. +The +.Ar name +parameter gives the device string discussed in +.Xr sndio 7 . +If the program is using a single device and is providing no device chooser, +it should be set to MIO_PORTANY to allow the user to select it using the +.Ev MIDIDEVICE +environment variable. +.Pp +The +.Ar mode +parameter gives the direction of the stream. +The following are supported: +.Bl -tag -width "MIO_OUT | MIO_IN" +.It MIO_OUT +The stream is output-only; data written to the stream will be sent +to the hardware or other programs. +.It MIO_IN +The stream is input-only; received data from the hardware or +other programs must be read from the stream. +.It MIO_IN | MIO_OUT +The stream sends and receives data. +This mode should be used rather than calling +.Fn mio_open +twice. +.El +.Pp +If the +.Ar nbio_flag +argument is true (i.e. non-zero), then the +.Fn mio_read +and +.Fn mio_write +functions (see below) will be non-blocking. +.Pp +The +.Fn mio_close +function closes the stream and frees all allocated resources +associated with the +.Nm libsndio +handle. +.Ss Sending and receiving data +When input mode is selected, the +.Fn mio_read +function must be called to retrieve received data; it must be called +often enough to ensure that internal buffers will not overrun. +It will store at most +.Ar nbytes +bytes at the +.Ar addr +location. +Unless the +.Ar nbio_flag +flag is set, it will block until data becomes available and +will return zero only on error. +.Pp +When output mode is selected, the +.Fn mio_write +function can be called to provide data to transmit. +Unless the +.Ar nbio_flag +is set, +.Fn mio_write +will block until the requested amount of data is written. +.Ss Non-blocking mode operation +If the +.Ar nbio_flag +is set on +.Fn mio_open , +then the +.Fn mio_read +and +.Fn mio_write +functions will never block; if no data is available, they will +return zero immediately. +.Pp +To avoid busy loops when non-blocking mode is used, the +.Xr poll 2 +system call can be used to check if data can be +read from or written to the stream. +The +.Fn mio_pollfd +function prepares the array +.Ar pfd +of +.Va pollfd +structures for use with +.Xr poll 2 . +The optimal size of the +.Ar pfd +array, which the caller must pre-allocate, is provided by the +.Fn mio_nfds +function. +.Pp +.Xr poll 2 +will sleep until any of the +.Ar events +requested with +.Fn mio_pollfd +have occurred. +Events are represented as a bit-mask of +.Va POLLIN +and +.Va POLLOUT +constants. +The events which woke up +.Xr poll 2 +can be obtained with the +.Fn mio_revents +function. +If +.Va POLLIN +is set, +.Fn mio_read +can be called without blocking. +If +.Va POLLOUT +is set, +.Fn mio_write +can be called without blocking. +POLLHUP may be set if an error occurs, even if +it is not requested with +.Fn mio_pollfd . +.Ss Error handling +Errors related to the MIDI subsystem +(like hardware errors or dropped connections) and +programming errors (such as a call to +.Fn mio_read +on a play-only stream) are considered fatal. +Once an error occurs, all functions which take a +.Va mio_hdl +argument, except +.Fn mio_close +and +.Fn mio_eof , +stop working (i.e. always return 0). +.Sh RETURN VALUES +The +.Fn mio_open +function returns the newly created handle on success or NULL +on failure. +.Pp +The +.Fn mio_pollfd +function returns the number of +.Va pollfd +structures filled. +The +.Fn mio_nfds +function returns the number of +.Va pollfd +structures the caller must preallocate in order to be sure +that +.Fn mio_pollfd +will never overrun. +.Pp +The +.Fn mio_revents +function returns the bit-mask set by +.Xr poll 2 +in the +.Va pfd +array of +.Va pollfd +structures. +.Pp +The +.Fn mio_read +and +.Fn mio_write +functions return the number of bytes transferred. +.Pp +The +.Fn mio_eof +function returns 0 if there's no pending error, and a non-zero +value if there's an error. +.Sh ENVIRONMENT +.Bl -tag -width "SNDIO_DEBUGXXX" -compact +.It Ev SNDIO_DEBUG +The debug level: +may be a value between 0 and 2. +.El +.Sh SEE ALSO +.Xr poll 2 , +.Xr midi 4 , +.Xr sndio 7 , +.Xr sndiod 8 +.Sh HISTORY +These functions first appeared in +.Ox 4.7 . +.Sh AUTHORS +.An Alexandre Ratchov Aq Mt ratchov@openbsd.org diff --git a/static/openbsd/man3/mitem_current.3 b/static/openbsd/man3/mitem_current.3 new file mode 100644 index 00000000..91f15e9c --- /dev/null +++ b/static/openbsd/man3/mitem_current.3 @@ -0,0 +1,102 @@ +'\" t +.\" $OpenBSD: mitem_current.3,v 1.7 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2006,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_current.3,v 1.7 2023/10/17 09:52:10 nicm Exp $ +.TH mitem_current 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBmitem_current\fP \- set and get current_menu_item +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_current_item(MENU *\fImenu\fB, ITEM *\fIitem\fB);\fR +.br +\fBITEM *current_item(const MENU *\fImenu\fB);\fR +.sp +\fBint set_top_row(MENU *\fImenu\fB, int \fIrow\fB);\fR +.br +\fBint top_row(const MENU *\fImenu\fB);\fR +.sp +\fBint item_index(const ITEM *\fIitem\fB);\fR +.SH DESCRIPTION +The function \fBset_current_item\fP sets the current item (the item on which +the menu cursor is positioned). +\fBcurrent_item\fP returns a pointer to the +current item in the given menu. +.PP +The function \fBset_top_row\fP sets the top row of the menu to show the given +row (the top row is initially 0, and is reset to this value whenever the +\fBO_ROWMAJOR\fP option is toggled). +The item leftmost on the given row +becomes current. +The function \fBtop_row\fP returns the number of the top menu +row being displayed. +.PP +The function \fBitem_index\fP returns the (zero-origin) index of \fIitem\fP in +the menu's item pointer list. +.SH RETURN VALUE +\fBcurrent_item\fP returns a pointer (which may be \fBNULL\fP). +It does not set \fBerrno\fP. +.PP +\fBtop_row\fP and \fBitem_index\fP return \fBERR\fP (the general \fBcurses\fP +error value) if their \fImenu\fP parameter is \fBNULL\fP. +.PP +\fBset_current_item\fP and \fBset_top_row\fP return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.PP +The SVr4 menu library documentation specifies the \fBtop_row\fP and +\fBindex_item\fP error value as \-1 (which is the value of \fBERR\fP). +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/mitem_name.3 b/static/openbsd/man3/mitem_name.3 new file mode 100644 index 00000000..d9177431 --- /dev/null +++ b/static/openbsd/man3/mitem_name.3 @@ -0,0 +1,62 @@ +'\" t +.\" $OpenBSD: mitem_name.3,v 1.7 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_name.3,v 1.7 2023/10/17 09:52:10 nicm Exp $ +.TH mitem_name 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBitem_name\fP, +\fBitem_description\fP \- get menu item name and description fields +.SH SYNOPSIS +\fB#include \fP +.sp +\fBconst char *item_name(const ITEM *\fIitem\fB);\fR +.br +\fBconst char *item_description(const ITEM *\fIitem\fB);\fR +.SH DESCRIPTION +The function \fBitem_name\fP returns the name part of the given item. +.br +The function \fBitem_description\fP returns the description part of the given +item. +.SH RETURN VALUE +These routines return a pointer (which may be \fBNULL\fP). +They do not set \fBerrno\fP. +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/mitem_new.3 b/static/openbsd/man3/mitem_new.3 new file mode 100644 index 00000000..cb7898e5 --- /dev/null +++ b/static/openbsd/man3/mitem_new.3 @@ -0,0 +1,92 @@ +'\" t +.\" $OpenBSD: mitem_new.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_new.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.TH mitem_new 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBnew_item\fP, +\fBfree_item\fP \- create and destroy menu items +.SH SYNOPSIS +\fB#include \fP +.sp +\fBITEM *new_item(const char *\fIname\fB, const char *\fIdescription\fB);\fR +.br +\fBint free_item(ITEM *\fIitem\fB);\fR +.SH DESCRIPTION +The function \fBnew_item\fP allocates a new item and initializes it from the +\fBname\fP and \fBdescription\fP pointers. +Please notice that the item stores +only the pointers to the name and description. +Those pointers must be valid +during the lifetime of the item. +So you should be very careful with names +or descriptions allocated on the stack of some routines. +.br +The function \fBfree_item\fP de-allocates an item. +Please notice that it +is the responsibility of the application to release the memory for the +name or the description of the item. +.SH RETURN VALUE +The function \fBnew_item\fP returns \fBNULL\fP on error. +It sets \fBerrno\fP according to the function's failure: +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred, e.g., malloc failure. +.PP +The function \fBfree_item\fP returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CONNECTED +Item is connected to a menu. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/mitem_opts.3 b/static/openbsd/man3/mitem_opts.3 new file mode 100644 index 00000000..9d4ff6b8 --- /dev/null +++ b/static/openbsd/man3/mitem_opts.3 @@ -0,0 +1,85 @@ +'\" t +.\" $OpenBSD: mitem_opts.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_opts.3,v 1.8 2023/10/17 09:52:10 nicm Exp $ +.TH mitem_opts 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_item_opts\fP, +\fBitem_opts_on\fP, +\fBitem_opts_off\fP, +\fBitem_opts\fP \- set and get menu item options +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_item_opts(ITEM *\fIitem\fB, Item_Options \fIopts\fB);\fR +.br +\fBItem_Options item_opts(const ITEM *\fIitem\fB);\fR +.sp +\fBint item_opts_on(ITEM *\fIitem\fB, Item_Options \fIopts\fB);\fR +.br +\fBint item_opts_off(ITEM *\fIitem\fB, Item_Options \fIopts\fB);\fR +.SH DESCRIPTION +The function \fBset_item_opts\fP sets all the given item's option bits (menu +option bits may be logically-OR'ed together). +.PP +The function \fBitem_opts_on\fP turns on the given option bits, and leaves +others alone. +.PP +The function \fBitem_opts_off\fP turns off the given option bits, and leaves +others alone. +.PP +The function \fBitem_opts\fP returns the item's current option bits. +.PP +There is only one defined option bit mask, \fBO_SELECTABLE\fP. When this is +on, the item may be selected during menu processing. +This option defaults +to on. +.SH RETURN VALUE +Except for \fBitem_opts\fP, each routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/mitem_userptr.3 b/static/openbsd/man3/mitem_userptr.3 new file mode 100644 index 00000000..6a8a59fd --- /dev/null +++ b/static/openbsd/man3/mitem_userptr.3 @@ -0,0 +1,69 @@ +'\" t +.\" $OpenBSD: mitem_userptr.3,v 1.7 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_userptr.3,v 1.7 2023/10/17 09:52:10 nicm Exp $ +.TH mitem_userptr 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_item_userptr\fP, +\fBitem_userptr\fP \- associate application data with a menu item +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_item_userptr(ITEM *\fIitem\fB, void *\fIuserptr\fB);\fR +.br +\fBvoid *item_userptr(const ITEM *\fIitem\fB);\fR +.SH DESCRIPTION +Every menu item has a field that can be used to hold application-specific data +(that is, the menu-driver code leaves it alone). +These functions get and set +that field. +.SH RETURN VALUE +The function \fBitem_userptr\fP returns a pointer (possibly \fBNULL\fP). +It does not set \fBerrno\fP. +.PP +The \fBset_item_userptr\fP always returns \fBE_OK\fP (success). +. +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.PP +The user pointer is a void pointer. +We chose not to leave it as a char pointer for SVr4 compatibility. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/mitem_value.3 b/static/openbsd/man3/mitem_value.3 new file mode 100644 index 00000000..61896d9d --- /dev/null +++ b/static/openbsd/man3/mitem_value.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: mitem_value.3,v 1.5 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_value.3,v 1.5 2023/10/17 09:52:10 nicm Exp $ +.TH mitem_value 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBset_item_value\fP, +\fBitem_value\fP \- set and get menu item values +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint set_item_value(ITEM *\fIitem\fB, bool \fIvalue\fB);\fR +.br +\fBbool item_value(const ITEM *\fIitem\fB);\fR +.SH DESCRIPTION +If you turn off the menu option \fBO_ONEVALUE\fP (e.g., with +\fBset_menu_opts\fP or \fBmenu_opts_off\fP; see \fBmenu_opts\fP(3)), the menu +becomes multi-valued; that is, more than one item may simultaneously be +selected. +.PP +In a multi_valued menu, you can used \fBset_item_value\fP to select the +given menu item (second argument \fBTRUE\fP) or deselect it (second argument +\fBFALSE\fP). +.SH RETURN VALUE +The function \fBset_item_value\fP returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fP(3)). +.TP 5 +.B E_REQUEST_DENIED +The menu driver could not process the request. +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/mitem_visible.3 b/static/openbsd/man3/mitem_visible.3 new file mode 100644 index 00000000..5779d9bd --- /dev/null +++ b/static/openbsd/man3/mitem_visible.3 @@ -0,0 +1,56 @@ +'\" t +.\" $OpenBSD: mitem_visible.3,v 1.7 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998,2010 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_visible.3,v 1.7 2023/10/17 09:52:10 nicm Exp $ +.TH mitem_visible 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBmitem_visible\fP \- check visibility of a menu item +.SH SYNOPSIS +\fB#include \fP +.sp +\fBbool item_visible(const ITEM *\fIitem\fB);\fR +.SH DESCRIPTION +A menu item is visible when it is in the portion of a posted menu that +is mapped onto the screen (if the menu is scrollable, in particular, this +portion will be smaller than the whole menu). +.SH SEE ALSO +\fBcurses\fP(3), \fBmenu\fP(3). +.SH NOTES +The header file \fB\fP automatically includes the header file +\fB\fP. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. +Manual pages and adaptation for new curses by Eric S. Raymond. diff --git a/static/openbsd/man3/mktemp.3 b/static/openbsd/man3/mktemp.3 new file mode 100644 index 00000000..a9673581 --- /dev/null +++ b/static/openbsd/man3/mktemp.3 @@ -0,0 +1,431 @@ +.\" $OpenBSD: mktemp.3,v 1.4 2025/08/04 14:11:37 schwarze 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. +.\" +.Dd $Mdocdate: August 4 2025 $ +.Dt MKTEMP 3 +.Os +.Sh NAME +.Nm mktemp , +.Nm mkstemp , +.Nm mkstemps , +.Nm mkdtemp , +.Nm mkdtemps , +.Nm mkostemp , +.Nm mkostemps +.Nd make temporary file name (unique) +.Sh SYNOPSIS +.In stdlib.h +.Ft char * +.Fn mktemp "char *template" +.Ft int +.Fn mkstemp "char *template" +.Ft int +.Fn mkstemps "char *template" "int suffixlen" +.Ft char * +.Fn mkdtemp "char *template" +.Ft char * +.Fn mkdtemps "char *template" "int suffixlen" +.In stdlib.h +.In fcntl.h +.Ft int +.Fn mkostemp "char *template" "int flags" +.Ft int +.Fn mkostemps "char *template" "int suffixlen" "int flags" +.Sh DESCRIPTION +The +.Fn mktemp +family of functions take the given file name template and overwrite +a portion of it to create a new file name. +This file name is unique and suitable for use by the application. +The template may be any file name with at least six trailing +.Em X Ns s , +for example +.Pa /tmp/temp.XXXXXXXX . +The trailing +.Em X Ns s +are replaced with a unique digit and letter combination. +The number of unique file names that can be returned +depends on the number of +.Em X Ns s +provided; +.Fn mktemp +will try at least 2 ** 31 combinations before giving up. +At least six +.Em X Ns s +must be used, though 10 is much better. +.Pp +The +.Fn mktemp +function generates a temporary file name based on a template as +described above. +Because +.Fn mktemp +does not actually create the temporary file, there is a window of +opportunity during which another process can open the file instead. +Because of this race condition, +.Fn mktemp +should not be used where +.Fn mkstemp +can be used instead. +.Fn mktemp +was marked as a legacy interface in +.St -p1003.1-2001 . +.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. +.Pp +The +.Fn mkostemp +function acts the same as +.Fn mkstemp , +except that the +.Fa flags +argument may contain zero or more of the following flags for the underlying +.Xr open 2 +system call: +.Pp +.Bl -tag -width "O_CLOEXECXX" -offset indent -compact +.It Dv O_APPEND +Append on each write. +.It Dv O_CLOEXEC +Set the close-on-exec flag on the new file descriptor. +.It Dv O_CLOFORK +Set the close-on-fork flag on the new file descriptor. +.It Dv O_SYNC +Perform synchronous I/O operations. +.El +.Pp +The +.Fn mkstemps +and +.Fn mkostemps +functions act the same as +.Fn mkstemp +and +.Fn mkostemp , +except they permit a suffix to exist in the template. +The template should be of the form +.Pa /tmp/tmpXXXXXXXXXXsuffix . +.Fn mkstemps +and +.Fn mkostemps +are told the length of the suffix string, i.e., +.Li strlen("suffix") . +.Pp +The +.Fn mkdtemp +function makes the same replacement to the template as in +.Fn mktemp +and creates the template directory, mode 0700. +The +.Fn mkdtemps +function acts the same as +.Fn mkdtemp , +except that it permits a suffix to exist in the template, +similar to +.Fn mkstemps . +.Sh RETURN VALUES +The +.Fn mktemp , +.Fn mkdtemp , +and +.Fn mkdtemps +functions return a pointer to the template on success and +.Dv NULL +on failure. +The +.Fn mkstemp , +.Fn mkstemps , +.Fn mkostemp , +and +.Fn mkostemps +functions return \-1 if no suitable file could be created. +If any 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[19]; +FILE *sfp; + +strlcpy(sfn, "/tmp/ed.XXXXXXXXXX", sizeof(sfn)); +if (mktemp(sfn) == NULL || (sfp = fopen(sfn, "w+")) == NULL) { + warn("%s", sfn); + return (NULL); +} +return (sfp); +.Ed +.Pp +should be rewritten like this: +.Bd -literal -offset indent +char sfn[19]; +FILE *sfp; +int fd; + +strlcpy(sfn, "/tmp/ed.XXXXXXXXXX", sizeof(sfn)); +if ((fd = mkstemp(sfn)) == -1 || + (sfp = fdopen(fd, "w+")) == NULL) { + if (fd != -1) { + unlink(sfn); + close(fd); + } + warn("%s", sfn); + 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 file name 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 mktemp , +.Fn mkstemp , +.Fn mkdtemp , +and +.Fn mkostemp +functions may set +.Va errno +to one of the following values: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Ar template +argument has fewer than six trailing +.Em X Ns s . +.It Bq Er EEXIST +All file names tried are already in use. +Consider appending more +.Em X Ns s to the +.Ar template . +.El +.Pp +The +.Fn mkstemps +and +.Fn mkostemps +functions may set +.Va errno +to +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Ar template +argument length is less than +.Ar suffixlen +or it has fewer than six +.Em X Ns s +before the suffix. +.It Bq Er EEXIST +All file names tried are already in use. +Consider appending more +.Em X Ns s to the +.Ar template . +.El +.Pp +In addition, the +.Fn mkostemp +and +.Fn mkostemps +functions may also set +.Va errno +to +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa flags +is invalid. +.El +.Pp +The +.Fn mktemp +function may also set +.Va errno +to any value specified by the +.Xr lstat 2 +function. +.Pp +The +.Fn mkstemp , +.Fn mkstemps , +.Fn mkostemp , +and +.Fn mkostemps +functions 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 lstat 2 , +.Xr mkdir 2 , +.Xr open 2 , +.Xr tempnam 3 , +.Xr tmpfile 3 , +.Xr tmpnam 3 +.Sh STANDARDS +The +.Fn mkstemp , +.Fn mkdtemp , +and +.Fn mkostemp +functions conform to the +.St -p1003.1-2024 +specification. +The ability to specify more than six +.Em X Ns s +is an extension to that standard. +.Pp +The +.Fn mktemp +function conforms to +.St -p1003.1-2001 ; +as of +.St -p1003.1-2008 +it is no longer a part of the standard. +.Pp +The +.Fn mkstemps , +.Fn mkdtemps , +and +.Fn mkostemps +functions are non-standard and should not be used if portability is required. +.Sh HISTORY +A +.Fn mktemp +function appeared in +.At v7 . +The +.Fn mkstemp +function appeared in +.Bx 4.3 . +The +.Fn mkdtemp +function appeared in +.Ox 2.2 . +The +.Fn mkstemps +function appeared in +.Ox 2.3 . +The +.Fn mkostemp +and +.Fn mkostemps +functions appeared in +.Ox 5.7 . +The +.Fn mkdtemps +function appeared in +.Ox 7.5 . +.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 file names 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 . diff --git a/static/openbsd/man3/modf.3 b/static/openbsd/man3/modf.3 new file mode 100644 index 00000000..bca1662c --- /dev/null +++ b/static/openbsd/man3/modf.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: modf.3,v 1.14 2025/06/06 21:50:10 schwarze 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. +.\" +.Dd $Mdocdate: June 6 2025 $ +.Dt MODF 3 +.Os +.Sh NAME +.Nm modf , +.Nm modff , +.Nm modfl +.Nd extract signed integral and fractional values from floating-point number +.Sh SYNOPSIS +.Lb libm +.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 +.Vt double +in the object pointed to by +.Fa iptr . +The +.Fn modff +function is a single precision version of +.Fn modf . +The +.Fn modfl +function is an extended precision version of +.Fn modf . +.Sh RETURN VALUES +The +.Fn modf , +.Fn modff +and +.Fn modfl +functions return the signed fractional part of +.Fa value . +.Sh SEE ALSO +.Xr frexp 3 , +.Xr ldexp 3 +.Sh STANDARDS +The +.Fn modf +function conforms to +.St -ansiC . diff --git a/static/openbsd/man3/moncontrol.3 b/static/openbsd/man3/moncontrol.3 new file mode 100644 index 00000000..fdf99596 --- /dev/null +++ b/static/openbsd/man3/moncontrol.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: moncontrol.3,v 1.11 2025/09/02 00:27:38 yasuoka 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. +.\" +.Dd $Mdocdate: September 2 2025 $ +.Dt MONCONTROL 3 +.Os +.Sh NAME +.Nm moncontrol +.Nd control execution profile +.Sh SYNOPSIS +.In sys/gmon.h +.Ft void +.Fn moncontrol "int mode" +.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. +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.progname.pid.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 . +.Sh FILES +.Bl -tag -width gmon.progname.pid.out -compact +.It Pa gmon.progname.pid.out +execution data file +.El +.Sh SEE ALSO +.Xr cc 1 , +.Xr gprof 1 , +.Xr profil 2 +.Sh CAVEATS +Do not call +.Fn moncontrol 0 +if +.Xr pthread_create 3 +will be called subsequently. +While profiling is stopped, +.Xr pthread_create 3 +does not allocate the collection buffer for the new thread. +This cannot be recovered by +.Fn moncontrol 1 , +resulting in failure to collect the statistics for those threads. diff --git a/static/openbsd/man3/nan.3 b/static/openbsd/man3/nan.3 new file mode 100644 index 00000000..f5d58da2 --- /dev/null +++ b/static/openbsd/man3/nan.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: nan.3,v 1.7 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2007 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/nan.3,v 1.1 2007/12/16 21:19:28 das Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt NAN 3 +.Os +.Sh NAME +.Nm nan , +.Nm nanf , +.Nm nanl +.Nd quiet NaNs +.Sh SYNOPSIS +.Lb libm +.In math.h +.Ft double +.Fn nan "const char *s" +.Ft float +.Fn nanf "const char *s" +.Ft long double +.Fn nanl "const char *s" +.Sh DESCRIPTION +The +.Dv NAN +macro expands to a quiet NaN (Not A Number). +Similarly both the +.Fn nan , +.Fn nanf +and +.Fn nanl +functions generate a quiet NaN value without raising an invalid exception. +The argument +.Fa s +should point to either an empty string or a hexadecimal representation +of a non-negative integer (e.g. 0x1234). +In the latter case, the integer is encoded in some free bits in the +representation of the NaN, which sometimes stores +machine-specific information about why a particular NaN was generated. +There are 22 such bits available for +.Vt float +variables, 51 bits for +.Vt double +variables, and at least 51 bits for a +.Vt long double . +If +.Fa s +is improperly formatted or represents an integer that is too large, +then the particular encoding of the quiet NaN that is returned +is indeterminate. +.Sh COMPATIBILITY +Calling these functions with a non-empty string isn't portable. +Another operating system may translate the string into a different +NaN encoding, and furthermore, the meaning of a given NaN encoding +varies across machine architectures. +If you understood the innards of a particular platform well enough to +know what string to use, then you would have no need for these functions +anyway, so don't use them. +Use the +.Dv NAN +macro instead. +.Sh SEE ALSO +.Xr isnan 3 , +.Xr strtod 3 +.Sh STANDARDS +The +.Fn nan , +.Fn nanf +and +.Fn nanl +functions and the +.Dv NAN +macro conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/ndbm.3 b/static/openbsd/man3/ndbm.3 new file mode 100644 index 00000000..85c94507 --- /dev/null +++ b/static/openbsd/man3/ndbm.3 @@ -0,0 +1,209 @@ +.\" David Leonard, 1998. Placed in the public domain. +.\" $OpenBSD: ndbm.3,v 1.21 2025/06/13 18:48:05 schwarze Exp $ +.Dd $Mdocdate: June 13 2025 $ +.Dt DBM_OPEN 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_pagfno , +.Nm dbm_rdonly , +.Nm dbm_store +.Nd database access methods +.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 flags" "mode_t mode" +.Ft int +.Fn dbm_pagfno "DBM *db" +.Ft int +.Fn dbm_rdonly "DBM *db" +.Ft int +.Fn dbm_store "DBM *db" "datum key" "datum content" "int store_mode" +.Sh DESCRIPTION +These functions provide a ndbm-compatible interface to the +database access methods described in +.Xr dbopen 3 . +Each unique record in the database is a key/content pair, +the components of which may be any arbitrary binary data. +The key and the content data are described by the +.Vt datum +data structure: +.Bd -literal -offset indent +typedef struct { + void *dptr; + size_t dsize; +} datum; +.Ed +.Pp +The +.Fn dbm_open +function is used to open a database in the file named by +.Fa file , +suffixed with +.Dv DBM_SUFFIX +.Pq Sq Pa .db . +If necessary, the file is created with mode +.Ar mode . +Access to this file depends on the +.Fa flags +parameter (see +.Xr open 2 ) . +Read-only access may be indicated by specifying +.Dv DBM_RDONLY . +The +.Fn dbm_rdonly +function may be used to determine if a database is opened for read-only +access. +.Pp +Once the database is open, +.Fn dbm_fetch +is used to retrieve the data content associated with the key +.Fa key . +Similarly, +.Fn dbm_store +is used to store the +.Fa content +data with the key +.Fa key . +When storing, the +.Fa store_mode +parameter must be one of: +.Bl -tag -width DBM_REPLACE -offset indent +.It Dv DBM_INSERT +Only insert new keys into the database. +Existing key/content pairs are untouched. +.It Dv DBM_REPLACE +Replace any existing entry with the same key. +Any previously stored records with the same key are lost. +.El +.Pp +The +.Fn dbm_delete +function removes the key +.Fa key +and its associated content from the database. +.Pp +The functions +.Fn dbm_firstkey +and +.Fn dbm_nextkey +are used to iterate over all of the records in the database. +Each record will be reached exactly once, but in no particular order. +The +.Fn dbm_firstkey +function returns the first record of the database, and thereafter +.Fn dbm_nextkey +returns the following records. +The following code traverses the entire database: +.Bd -literal -offset indent +for (key = dbm_firstkey(db); key.dptr != NULL; + key = dbm_nextkey(db)) +.Ed +.Pp +The behaviour of +.Fn dbm_nextkey +is undefined if the database is modified after a call to +.Fn dbm_firstkey . +.Pp +The +.Fn dbm_error +function returns the last error condition of the database, +or 0 if no error had occurred or had been cleared. +The +.Fn dbm_clearerr +function clears the error condition of the database. +.Pp +The +.Fn dbm_dirfno +function is used to find the file descriptor associated with the +directory file of an open database. +Since a directory bitmap file is not used in this implementation, +this function returns the file descriptor of the database file opened with +.Fn dbm_open . +.Pp +The +.Fn dbm_pagfno +function is used to find the file descriptor associated with the +page file of an open database. +Since a page file is not used in this implementation, this function +is implemented as a macro that always returns the (undefined) value +.Dv DBM_PAGFNO_NOT_AVAILABLE . +.Pp +The database is closed with the +.Fn dbm_close +function. +Thereafter, the +.Fa db +handle is invalid. +.Ss Implementation notes +The underlying database is a +.Xr hash 3 +database with a +bucket size of 4096, +a filling factor of 40, +default hashing function and cache size, +and uses the host's native byte order. +.Sh RETURN VALUES +Upon successful completion, all functions that return +.Ft int +return a value of 0, otherwise a negative value is returned. +.Pp +Routines that return a +.Ft datum +indicate errors by setting the +.Va dptr +field to +.Dv NULL . +.Pp +The +.Fn dbm_open +function returns +.Dv NULL +on error, and sets +.Va errno +appropriately. +On success, it returns a handle to the database that should be +used as the +.Fa db +argument in the other functions. +.Pp +The +.Fn dbm_store +function returns 1 when it is called with a +.Fa flags +value of +.Dv DBM_INSERT +and a record with the specified key already exists. +.Sh ERRORS +If an error occurs, the error can be retrieved with +.Fn dbm_error +and corresponds to those errors described in +.Xr dbopen 3 . +.Sh SEE ALSO +.Xr open 2 , +.Xr dbopen 3 , +.Xr hash 3 diff --git a/static/openbsd/man3/new_pair.3 b/static/openbsd/man3/new_pair.3 new file mode 100644 index 00000000..ab8ab462 --- /dev/null +++ b/static/openbsd/man3/new_pair.3 @@ -0,0 +1,165 @@ +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey +.\" +.\" $Id: new_pair.3,v 1.1 2023/10/17 09:52:08 nicm Exp $ +.TH new_pair 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.de NS +.ie n .sp +.el .sp .5 +.ie n .in +4 +.el .in +2 +.nf +.ft CR \" Courier +.. +.de NE +.fi +.ft R +.ie n .in -4 +.el .in -2 +.. +.SH NAME +\fBalloc_pair\fP, +\fBfind_pair\fP, +\fBfree_pair\fP \- new curses color-pair functions +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint alloc_pair(int \fIfg\fB, int \fIbg\fB);\fR +.br +\fBint find_pair(int \fIfg\fB, int \fIbg\fB);\fR +.br +\fBint free_pair(int \fIpair\fB);\fR +.SH DESCRIPTION +These functions are an extension to the curses library. +They permit an application to dynamically allocate a color pair using +the foreground/background colors rather than assign a fixed color pair number, +and return an unused pair to the pool. +.PP +The number of colors may be related to the number of possible color +pairs for a given terminal, or it may not: +.bP +While almost all terminals allow setting the color \fIattributes\fP +independently, +it is unlikely that your terminal allows you to modify the attributes +of a given character cell without rewriting it. +That is, the foreground and background colors are applied as a pair. +.bP +Color pairs are the curses library's way of managing a color palette +on a terminal. +If the library does not keep track of the \fIcombinations\fP of +colors which are displayed, it will be inefficient. +.bP +For simple terminal emulators +with only a few dozen color combinations, +it is convenient to use the maximum number of combinations +as the limit on color pairs: +.NS +\fBCOLORS\fI * \fBCOLORS\fR +.NE +.bP +Terminals which support \fIdefault colors\fP distinct +from \*(``ANSI colors\*('' +add to the possible combinations, producing this total: +.NS +\fI( \fBCOLORS\fI + 1 ) * ( \fBCOLORS\fI + 1 )\fR +.NE +.bP +An application might use up to a few dozen color pairs to +implement a predefined color scheme. +.IP +Beyond that lies in the realm of programs using the foreground +and background colors for \*(``ASCII art\*('' +(or some other non-textual application). +.IP +Also beyond those few dozen pairs, the required size for a table +to represent the combinations grows rapidly with an increasing number of colors. +.IP +These functions allow a developer to let the screen library +manage color pairs. +.SS alloc_pair +The \fBalloc_pair\fP function accepts parameters for +foreground and background color, and +checks if that color combination is already associated with a color pair. +.bP +If the combination already exists, +\fBalloc_pair\fP returns the existing pair. +.bP +If the combination does not exist, +\fBalloc_pair\fP allocates a new color pair and returns that. +.bP +If the table fills up, \fBalloc_pair\fP discards the least-recently +allocated entry using \fBfree_pair\fP and allocates a new color pair. +.PP +All of the color pairs are allocated from a table of possible color pairs. +The size of the table is determined by the terminfo \fBpairs\fP capability. +The table is shared with \fBinit_pair\fP; +in fact \fBalloc_pair\fP calls \fBinit_pair\fP after +updating the ncurses library's fast index to the colors versus color pairs. +.SS find_pair +The \fBfind_pair\fP function accepts parameters for +foreground and background color, and +checks if that color combination is already associated with a color pair, +returning the pair number if it has been allocated. +Otherwise it returns \-1. +.SS free_pair +Marks the given color pair as unused, +i.e., like color pair 0. +.SH RETURN VALUE +The \fBalloc_pair\fP function returns a color pair number in the range +1 through \fBCOLOR_PAIRS\fP\-1, unless it encounters an error updating +its fast index to the color pair values, preventing it from allocating +a color pair. +In that case, it returns \-1. +.PP +The \fBfind_pair\fP function returns a color pair number if the +given color combination has been associated with a color pair, +or \-1 if not. +.PP +Likewise, \fBfree_pair\fP returns \fBOK\fP unless it encounters an +error updating the fast index or if no such color pair is in use. +.SH PORTABILITY +These routines are specific to ncurses. +They were not supported on +Version 7, BSD or System V implementations. +It is recommended that +any code depending on them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBcurs_color\fP(3). +.SH AUTHOR +Thomas Dickey. diff --git a/static/openbsd/man3/newlocale.3 b/static/openbsd/man3/newlocale.3 new file mode 100644 index 00000000..2f2574b6 --- /dev/null +++ b/static/openbsd/man3/newlocale.3 @@ -0,0 +1,175 @@ +.\" $OpenBSD: newlocale.3,v 1.3 2019/06/25 17:40:24 schwarze Exp $ +.\" +.\" Copyright (c) 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 $Mdocdate: June 25 2019 $ +.Dt NEWLOCALE 3 +.Os +.Sh NAME +.Nm newlocale , +.Nm duplocale , +.Nm freelocale +.Nd create and destroy locale objects +.Sh SYNOPSIS +.In locale.h +.Ft locale_t +.Fo newlocale +.Fa "int mask" +.Fa "const char *locname" +.Fa "locale_t oldloc" +.Fc +.Ft locale_t +.Fo duplocale +.Fa "locale_t oldloc" +.Fc +.Ft void +.Fo freelocale +.Fa "locale_t oldloc" +.Fc +.Sh DESCRIPTION +The function +.Fn newlocale +creates a new locale object for use with +.Xr uselocale 3 +and with many functions that accept +.Vt locale_t +arguments. +Locale categories not contained in the +.Fa mask +are copied from +.Fa oldloc +to the new locale object, or from the +.Qq C +locale if +.Fa oldloc +is +.Po Vt locale_t Pc Ns 0 . +.Pp +On +.Ox , +.Fa locname +only affects the return value if +.Fa mask +includes +.Dv LC_CTYPE_MASK , +and +.Fa locname +is only meaningful if it is +.Qq C +or +.Qq POSIX , +if it ends with +.Qq .UTF-8 , +or if it is an empty string. +Other +.Fa locname +arguments have the same effect as +.Qq C . +.Pp +The function +.Fn duplocale +copies +.Fa oldloc , +or the global locale if given the special argument +.Dv LC_GLOBAL_LOCALE . +.Pp +For portability, when an object returned from +.Fn newlocale +or +.Fn duplocale +is no longer needed, pass it to +.Fn freelocale , +even though the latter has no effect on +.Ox . +The +.Fa oldloc +objects passed to +.Fn newlocale +or +.Fn freelocale +become invalid, and using them or passing them once again to +.Fn freelocale +results in undefined behaviour, whereas objects passed to +.Fn duplocale +remain valid and can be passed to +.Fn freelocale +later on. +.Sh RETURN VALUES +The functions +.Fn newlocale +and +.Fn duplocale +return the new locale object on success or +.Po Vt locale_t Pc Ns 0 +on failure. +.Sh ENVIRONMENT +If +.Fa locname +is an empty string, +.Fa newlocale +inspects +.Ev LC_ALL , +.Ev LC_CTYPE , +and +.Ev LANG +as described in +.Xr locale 1 . +.Sh ERRORS +The function +.Fn newlocale +fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +An invalid bit is set in +.Fa mask , +or +.Fa locname +is +.Dv NULL . +.It Bq Er ENOENT +Locale data is not available for +.Fa locname . +.El +.Pp +On other operating systems, +.Fn newlocale +and +.Fn duplocale +may also fail with +.Er ENOMEM . +.Sh SEE ALSO +.Xr iswalnum 3 , +.Xr iswctype 3 , +.Xr towctrans 3 , +.Xr towlower 3 , +.Xr uselocale 3 , +.Xr wcscasecmp 3 , +.Xr wctrans 3 , +.Xr wctype 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2008 +including Technical Corrigendum 3. +.Sh HISTORY +These functions have been available since +.Ox 6.2 . +.Sh CAVEATS +Calling +.Fn newlocale +with an +.Fa oldloc +argument of +.Dv LC_GLOBAL_LOCALE +results in undefined behaviour. diff --git a/static/openbsd/man3/nextafter.3 b/static/openbsd/man3/nextafter.3 new file mode 100644 index 00000000..2a3a046a --- /dev/null +++ b/static/openbsd/man3/nextafter.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: nextafter.3,v 1.9 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt NEXTAFTER 3 +.Os +.Sh NAME +.Nm nextafter , +.Nm nextafterf , +.Nm nextafterl , +.Nm nexttoward , +.Nm nexttowardf , +.Nm nexttowardl +.Nd next representable value +.Sh SYNOPSIS +.Lb libm +.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 +These functions +return the next machine representable number from +.Fa x +in direction +.Fa y . +If +.Fa x +equals +.Fa y , +these functions return +.Fa y . +.Sh SEE ALSO +.Xr nearbyint 3 +.Sh STANDARDS +.St -ieee754 +.Sh HISTORY +The +.Nm nextafter +and +.Nm nextafterf +functions appeared in +.Bx 4.3 +and +.Nx 1.1 , +respectively. diff --git a/static/openbsd/man3/nice.3 b/static/openbsd/man3/nice.3 new file mode 100644 index 00000000..61398787 --- /dev/null +++ b/static/openbsd/man3/nice.3 @@ -0,0 +1,92 @@ +.\" $OpenBSD: nice.3,v 1.18 2013/07/18 10:14:48 schwarze 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. +.\" +.Dd $Mdocdate: July 18 2013 $ +.Dt NICE 3 +.Os +.Sh NAME +.Nm nice +.Nd change process scheduling priority +.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 adds the value specified in +.Fa incr +to the scheduling priority of the invoking process. +.Pp +.Fa incr +is an integer such that the resulting scheduling priority +is within the range \-20 to 20. +Priority values outside this range are truncated to the appropriate limit. +The default priority is 0; lower priorities cause more favorable scheduling. +Only the superuser may lower priorities. +.Pp +Children inherit the priority of their parent processes via +.Xr fork 2 . +.Sh RETURN VALUES +On success, +.Fn nice +returns the new priority. +On error, it returns -1. +.Pp +Since +.Fn nice +can legitimately return the value -1, it is necessary +to clear the external variable +.Va errno +prior to the +call, then check it afterward to determine +if a -1 is an error or a legitimate value. +.Sh ERRORS +.Fn nice +has the same failure conditions as +.Xr setpriority 2 . +.Sh SEE ALSO +.Xr nice 1 , +.Xr fork 2 , +.Xr setpriority 2 , +.Xr renice 8 +.Sh HISTORY +A +.Fn nice +system call first appeared in +.At v3 . +It has accepted an +.Fa incr +argument since +.At v4 . diff --git a/static/openbsd/man3/nl_langinfo.3 b/static/openbsd/man3/nl_langinfo.3 new file mode 100644 index 00000000..b91da2de --- /dev/null +++ b/static/openbsd/man3/nl_langinfo.3 @@ -0,0 +1,78 @@ +.\" $OpenBSD: nl_langinfo.3,v 1.13 2017/10/04 17:59:24 schwarze Exp $ +.\" +.\" Copyright (c) 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 $Mdocdate: October 4 2017 $ +.Dt NL_LANGINFO 3 +.Os +.Sh NAME +.Nm nl_langinfo , +.Nm nl_langinfo_l +.Nd get locale information +.Sh SYNOPSIS +.In langinfo.h +.Ft char * +.Fn nl_langinfo "nl_item item" +.Ft char * +.Fn nl_langinfo_l "nl_item item" "locale_t locale" +.Sh DESCRIPTION +The +.Fn nl_langinfo +function returns information about the global +.Xr locale 1 , +and +.Fn nl_langinfo_l +about the +.Fa locale +passed as an argument. +.Sh RETURN VALUES +On +.Ox , +if +.Fa item +is +.Dv CODESET , +the return value is either +.Qq US-ASCII +or +.Qq UTF-8 . +For other values of +.Fa item , +the strings that +.St -p1003.1-2008 +specifies for the C locale are returned. +.Pp +If +.Fa item +is invalid, a pointer to an empty string is returned. +.Sh SEE ALSO +.Xr setlocale 3 , +.Xr uselocale 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The function +.Fn nl_langinfo +has been available since +.Nx 1.0 , +and +.Fn nl_langinfo_l +since +.Ox 6.2 . +.Sh BUGS +The return values for +.Dv CODESET +are not standardized and vary among implementations. diff --git a/static/openbsd/man3/nlist.3 b/static/openbsd/man3/nlist.3 new file mode 100644 index 00000000..0afb82c3 --- /dev/null +++ b/static/openbsd/man3/nlist.3 @@ -0,0 +1,76 @@ +.\" $OpenBSD: nlist.3,v 1.14 2020/02/08 01:09:57 jsg 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. +.\" +.Dd $Mdocdate: February 8 2020 $ +.Dt NLIST 3 +.Os +.Sh NAME +.Nm nlist +.Nd retrieve symbol table name list from an executable file +.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 always has its +.Fa n_name +field set to +.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 an executable, the returned value is \-1. +.Sh SEE ALSO +.Xr elf 5 +.Sh HISTORY +An +.Fn nlist +function first appeared in +.At v2 . diff --git a/static/openbsd/man3/ober_add_string.3 b/static/openbsd/man3/ober_add_string.3 new file mode 100644 index 00000000..c1686db2 --- /dev/null +++ b/static/openbsd/man3/ober_add_string.3 @@ -0,0 +1,238 @@ +.\" $OpenBSD: ober_add_string.3,v 1.4 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2007, 2012 Reyk Floeter +.\" +.\" 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: June 13 2025 $ +.Dt OBER_ADD_STRING 3 +.Os +.Sh NAME +.Nm ober_get_element , +.Nm ober_add_sequence , +.Nm ober_add_set , +.Nm ober_add_null , +.Nm ober_add_eoc , +.Nm ober_add_integer , +.Nm ober_add_enumerated , +.Nm ober_add_boolean , +.Nm ober_add_string , +.Nm ober_add_nstring , +.Nm ober_add_ostring , +.Nm ober_add_bitstring , +.Nm ober_add_oid , +.Nm ober_add_noid , +.Nm ober_add_oidstring , +.Nm ober_printf_elements +.Nd create ASN.1 objects for BER encoding +.Sh SYNOPSIS +.Lb libutil +.In sys/types.h +.In ber.h +.Ft struct ber_element * +.Fn "ober_get_element" "unsigned int encoding" +.Ft struct ber_element * +.Fn "ober_add_sequence" "struct ber_element *prev" +.Ft struct ber_element * +.Fn "ober_add_set" "struct ber_element *prev" +.Ft struct ber_element * +.Fn "ober_add_null" "struct ber_element *prev" +.Ft struct ber_element * +.Fn "ober_add_eoc" "struct ber_element *prev" +.Ft struct ber_element * +.Fn "ober_add_integer" "struct ber_element *prev" "long long val" +.Ft struct ber_element * +.Fn "ober_add_enumerated" "struct ber_element *prev" "long long val" +.Ft struct ber_element * +.Fn "ober_add_boolean" "struct ber_element *prev" "int bool" +.Ft struct ber_element * +.Fn "ober_add_string" "struct ber_element *prev" "const char *string" +.Ft struct ber_element * +.Fn "ober_add_nstring" "struct ber_element *prev" "const char *string" "size_t size" +.Ft struct ber_element * +.Fo "ober_add_ostring" +.Fa "struct ber_element *prev" +.Fa "struct ber_octetstring *ostring" +.Fc +.Ft struct ber_element * +.Fo "ober_add_bitstring" +.Fa "struct ber_element *prev" +.Fa "const void *buf" +.Fa "size_t size" +.Fc +.Ft struct ber_element * +.Fn "ober_add_oid" "struct ber_element *prev" "struct ber_oid *oid" +.Ft struct ber_element * +.Fn "ober_add_noid" "struct ber_element *prev" "struct ber_oid *oid" "int n" +.Ft struct ber_element * +.Fn "ober_add_oidstring" "struct ber_element *prev" "const char *string" +.Ft struct ber_element * +.Fn "ober_printf_elements" "struct ber_element *prev" "char *format" "..." +.Sh DESCRIPTION +Intermediary storage of BER elements during encoding and decoding uses the +following structure: +.Bd -literal +struct ber_element { + struct ber_element *be_next; + unsigned int be_type; + unsigned int be_encoding; + size_t be_len; + off_t be_offs; + int be_free; + u_int8_t be_class; + void (*be_cb)(void *, size_t); + void *be_cbarg; + union { + struct ber_element *bv_sub; + void *bv_val; + long long bv_numeric; + } be_union; +#define be_sub be_union.bv_sub +#define be_val be_union.bv_val +#define be_numeric be_union.bv_numeric +}; +.Ed +.Pp +.Fn ober_get_element +creates a new +.Vt ber_element +with default values, dynamically allocates required storage, and sets +.Fa be_encoding +to +.Fa encoding . +.Pp +The +.Fn ober_add_* +functions allocate a new +.Vt ber_element +of the respective type. +If +.Fa prev +is an empty sequence or set, they put the new element into that +sequence or set. +Otherwise, unless +.Fa prev +is +.Dv NULL , +they put it behind +.Fa prev . +Those functions taking a second argument initialize the content +of the new element from the second argument. +.Pp +.Fn ober_printf_elements +creates zero or more +.Vt ber_element +structures. +For each byte in +.Fa fmt , +arguments of the types given in the following table are consumed +and passed to the listed function, creating one +.Vt ber_element +per byte. +The following bytes are valid: +.Bl -column -offset indent byte ober_add_enumerated "struct ber_element *" +.It Sy byte Ta Sy function Ta Sy arguments +.It B Ta Fn ober_add_bitstring Ta 2: Vt void * , size_t +.It b Ta Fn ober_add_boolean Ta 1: Vt int +.It d Ta Fn ober_add_integer Ta 1: Vt int +.It E Ta Fn ober_add_enumerated Ta 1: Vt long long +.It e Ta see below Ta 1: Vt struct ber_element * +.It i Ta Fn ober_add_integer Ta 1: Vt long long +.It O Ta Fn ober_add_oid Ta 1: Vt struct ber_oid * +.It o Ta Fn ober_add_oidstring Ta 1: Vt char * +.It s Ta Fn ober_add_string Ta 1: Vt char * +.It t Ta Xr ober_set_header 3 Ta 2: Vt int , unsigned int +.It x Ta Fn ober_add_nstring Ta 2: Vt char * , size_t +.It \&( Ta Fn ober_add_set Ta 0 +.It \&) Ta see below Ta 0 +.It \&. Ta Fn ober_add_eoc Ta 0 +.It 0 Ta Fn ober_add_null Ta 0 +.It { Ta Fn ober_add_sequence Ta 0 +.It } Ta see below Ta 0 +.El +.Pp +The +.Sq e +and +.Sq t +bytes are special in so far as they do not create new elements. +The +.Sq e +byte adds an element that was already created earlier into or behind +the previous element, or into and behind +.Fa ber +if the +.Sq e +is the first byte in +.Fa fmt , +just like the +.Fn ober_add_* +functions would add a new element. +The +.Sq t +byte changes the class and type of the last element, or of +.Fa ber +if +.Sq t +is the first byte in +.Fa fmt , +without changing its position relative to other elements. +.Pp +A closing brace or parenthesis closes an open sequence or set, +if any, such that the next element will be added behind rather +than into the sequence or set. +Only one sequence or set can be open at any time. +Nesting is not supported without multiple function calls. +.Sh RETURN VALUES +Upon successful completion, +these functions return a pointer to a populated +.Vt ber_element . +Otherwise +.Dv NULL +is returned and the global variable +.Va errno +is set to indicate the error. +.Pp +.Fn ober_printf_elements +returns +.Dv NULL +without setting +.Va errno +if +.Fa fmt +is an empty string and +.Fa ber +is +.Dv NULL . +.Sh SEE ALSO +.Xr ober_get_string 3 , +.Xr ober_oid_cmp 3 , +.Xr ober_read_elements 3 , +.Xr ober_set_header 3 +.Sh STANDARDS +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules. +.Sh HISTORY +These functions first appeared as internal functions in +.Xr snmpd 8 +in +.Ox 4.2 +and were moved to libutil in +.Ox 6.6 . +.Sh AUTHORS +.An -nosplit +The BER library was written by +.An Claudio Jeker Aq Mt claudio@openbsd.org , +.An Marc Balmer Aq Mt marc@openbsd.org +and +.An Reyk Floeter Aq Mt reyk@openbsd.org . diff --git a/static/openbsd/man3/ober_get_string.3 b/static/openbsd/man3/ober_get_string.3 new file mode 100644 index 00000000..30896d58 --- /dev/null +++ b/static/openbsd/man3/ober_get_string.3 @@ -0,0 +1,191 @@ +.\" $OpenBSD: ober_get_string.3,v 1.8 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2007, 2012 Reyk Floeter +.\" +.\" 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: June 13 2025 $ +.Dt OBER_GET_STRING 3 +.Os +.Sh NAME +.Nm ober_get_null , +.Nm ober_get_eoc , +.Nm ober_get_integer , +.Nm ober_get_enumerated , +.Nm ober_get_boolean , +.Nm ober_get_string , +.Nm ober_get_nstring , +.Nm ober_get_ostring , +.Nm ober_get_bitstring , +.Nm ober_get_oid , +.Nm ober_getpos , +.Nm ober_scanf_elements +.Nd access properties of ASN.1 objects decoded from BER +.Sh SYNOPSIS +.Lb libutil +.In sys/types.h +.In ber.h +.Ft int +.Fn "ober_get_null" "struct ber_element *root" +.Ft int +.Fn "ober_get_eoc" "struct ber_element *root" +.Ft int +.Fn "ober_get_integer" "struct ber_element *root" "long long *val" +.Ft int +.Fn "ober_get_enumerated" "struct ber_element *root" "long long *val" +.Ft int +.Fn "ober_get_boolean" "struct ber_element *root" "int *bool" +.Ft int +.Fn "ober_get_string" "struct ber_element *root" "char **charbuf" +.Ft int +.Fn "ober_get_nstring" "struct ber_element *root" "void **buf" "size_t *size" +.Ft int +.Fn "ober_get_ostring" "struct ber_element *root" "struct ber_octetstring *ostring" +.Ft int +.Fn "ober_get_bitstring" "struct ber_element *root" "void **buf" "size_t *size" +.Ft int +.Fn "ober_get_oid" "struct ber_element *root" "struct ber_oid *oid" +.Ft off_t +.Fn "ober_getpos" "struct ber_element *elm" +.Ft int +.Fn "ober_scanf_elements" "struct ber_element *root" "char *format" "..." +.Sh DESCRIPTION +Functions which take two arguments save the value contained in the +.Fa root +element into the storage location pointed to by the second argument. +If the storage location is +.Dv NULL +then only a type check is performed. +Additionally, +.Fn ober_get_nstring +and +.Fn ober_get_bitstring +save the number of bytes contained in the string into +.Pf * Fa size . +If +.Fa buf +is +.Dv NULL +and size is not +.Dv NULL , +size is set. +.Fa size +must not be +.Dv NULL +to return a valid +.Fa buf . +.Pp +.Fn ober_scanf_elements +retrieves the values from zero or more elements starting at +.Fa root . +For each character in +.Fa fmt , +arguments of the types given in the following table are consumed +and passed to the function listed, processing one +.Vt ber_element +per character. +The following characters are valid: +.Bl -column -offset indent\ + characte ober_get_enumerated_ "1: struct ber_element **" +.It Sy character Ta Sy function Ta Sy arguments +.It $ Ta see below Ta 0 +.It B Ta Fn ober_get_bitstring Ta 2: Vt void ** , size_t * +.It b Ta Fn ober_get_boolean Ta 1: Vt int * +.It d Ta Fn ober_get_integer Ta 1: Vt int * +.It E Ta Fn ober_get_enumerated Ta 1: Vt long long * +.It e Ta see below Ta 1: Vt struct ber_element ** +.It i Ta Fn ober_get_integer Ta 1: Vt long long * +.It o Ta Fn ober_get_oid Ta 1: Vt struct ber_oid * +.It p Ta Fn ober_getpos Ta 1: Vt off_t * +.It S Ta see below Ta 0 +.It s Ta Fn ober_get_string Ta 1: Vt char ** +.It t Ta see below Ta 2: Vt int * , unsigned int * +.It x Ta Fn ober_get_nstring Ta 2: Vt void **, size_t * +.It \&( or { Ta see below Ta 0 +.It \&) or } Ta see below Ta 0 +.It \&. Ta Fn ober_get_eoc Ta 0 +.It 0 Ta Fn ober_get_null Ta 0 +.El +.Pp +For +.Sq e , +.Sq p , +.Sq S , +and +.Sq t , +the type of the element is not checked. +For +.Sq p +and +.Sq t , +the pointer is not incremented to the next element. +For +.Sq e , +a pointer to the element is stored in the corresponding pointer variable. +For +.Sq S , +the element is skipped without extracting any information from it. +For +.Sq t , +the class and type of the element are stored in the two corresponding +variables, but if the element contains a value, that value is ignored. +A +.Sq $ +mandates the end of a sequence or set. +.Pp +For an opening parenthesis or brace, it is checked that the element +is a sequence or a set, and parsing continues with its children. +For a closing parenthesis or brace, parsing of the current sequence +or set is ended and parsing continues with the element following +the sequence or set. +.Sh RETURN VALUES +.Fn ober_getpos +returns the value of +.Vt be_offs . +.Pp +.Fn ober_scanf_elements +returns 0 for success or \-1 when encountering elements that do not +agree with the expectations of +.Fa fmt +or when +.Fa fmt +is syntactically invalid. +Even when +.Fn ober_scanf_elements +fails, some of the arguments may already have been filled in. +.Pp +The other functions return 0 if +.Va root +is of the requested type or \-1 otherwise. +.Sh SEE ALSO +.Xr ober_add_string 3 , +.Xr ober_oid_cmp 3 , +.Xr ober_read_elements 3 , +.Xr ober_set_header 3 +.Sh STANDARDS +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules. +.Sh HISTORY +These functions first appeared as internal functions in +.Xr snmpd 8 +in +.Ox 4.2 +and were moved to libutil in +.Ox 6.6 . +.Sh AUTHORS +.An -nosplit +The BER library was written by +.An Claudio Jeker Aq Mt claudio@openbsd.org , +.An Marc Balmer Aq Mt marc@openbsd.org +and +.An Reyk Floeter Aq Mt reyk@openbsd.org . diff --git a/static/openbsd/man3/ober_oid_cmp.3 b/static/openbsd/man3/ober_oid_cmp.3 new file mode 100644 index 00000000..3bd0a566 --- /dev/null +++ b/static/openbsd/man3/ober_oid_cmp.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: ober_oid_cmp.3,v 1.7 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2007, 2012 Reyk Floeter +.\" +.\" 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: June 13 2025 $ +.Dt OBER_OID_CMP 3 +.Os +.Sh NAME +.Nm ober_oid_cmp , +.Nm ober_oid2ber , +.Nm ober_string2oid +.Nd OID helper functions for the BER library +.Sh SYNOPSIS +.Lb libutil +.In sys/types.h +.In ber.h +.Ft int +.Fn "ober_oid_cmp" "struct ber_oid *a" "struct ber_oid *b" +.Ft size_t +.Fn "ober_oid2ber" "struct ber_oid *oid" "u_int8_t *buf" "size_t size" +.Ft int +.Fn "ober_string2oid" "const char *string" "struct ber_oid *oid" +.Sh DESCRIPTION +Object Identifiers are commonly used in ASN.1-based protocols. +These functions provide an interface to parse OIDs. +For internal representation of OIDs, the following structure +.Vt struct ber_oid +is being used: +.Bd -literal +#define BER_MIN_OID_LEN 2 +#define BER_MAX_OID_LEN 64 + +struct ber_oid { + u_int32_t bo_id[BER_MAX_OID_LEN + 1]; + size_t bo_n; +}; +.Ed +.Pp +The +.Fn ober_oid2ber +and +.Fn ober_string2oid +functions may be used to convert from and to +.Vt struct ber_oid . +.Pp +.Fn ober_oid_cmp +may be used to compare two +.Vt ber_oid +structures. +.Sh RETURN VALUES +.Fn ober_oid2ber +returns the number of bytes written or 0 on failure. +.Pp +.Fn ober_string2oid +returns 0 on success or -1 on failure. +.Pp +.Fn ober_oid_cmp +returns an integer greater than, equal to, or less than 0, according to whether +the oid +.Fa a +is greater than, equal to, or less than the oid +.Fa b . +If the shortest length from +.Fa a +and +.Fa b +matches +the weight of the integer is 2, else it is 1. +.Sh SEE ALSO +.Xr ober_add_string 3 , +.Xr ober_get_string 3 , +.Xr ober_read_elements 3 , +.Xr ober_set_header 3 +.Sh HISTORY +These functions first appeared as internal functions in +.Xr snmpd 8 +in +.Ox 4.2 +and were moved to libutil in +.Ox 6.6 . +.Sh AUTHORS +.An -nosplit +The BER library was written by +.An Claudio Jeker Aq Mt claudio@openbsd.org , +.An Marc Balmer Aq Mt marc@openbsd.org +and +.An Reyk Floeter Aq Mt reyk@openbsd.org . diff --git a/static/openbsd/man3/ober_read_elements.3 b/static/openbsd/man3/ober_read_elements.3 new file mode 100644 index 00000000..7e1127f7 --- /dev/null +++ b/static/openbsd/man3/ober_read_elements.3 @@ -0,0 +1,244 @@ +.\" $OpenBSD: ober_read_elements.3,v 1.5 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2007, 2012 Reyk Floeter +.\" +.\" 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: June 13 2025 $ +.Dt OBER_READ_ELEMENTS 3 +.Os +.Sh NAME +.Nm ober_set_readbuf , +.Nm ober_set_application , +.Nm ober_read_elements , +.Nm ober_get_writebuf , +.Nm ober_write_elements , +.Nm ober_free +.Nd encode and decode ASN.1 with Basic Encoding Rules +.Sh SYNOPSIS +.Lb libutil +.In sys/types.h +.In ber.h +.Ft void +.Fn "ober_set_readbuf" "struct ber *ber" "void *buf" "size_t len" +.Ft void +.Fo "ober_set_application" +.Fa "struct ber *ber" +.Fa "unsigned int (*cb)(struct ber_element *)" +.Fc +.Ft struct ber_element * +.Fn "ober_read_elements" "struct ber *ber" "struct ber_element *root" +.Ft ssize_t +.Fn "ober_get_writebuf" "struct ber *ber" "void **buf" +.Ft ssize_t +.Fn "ober_write_elements" "struct ber *ber" "struct ber_element *root" +.Ft void +.Fn "ober_free" "struct ber *ber" +.Sh DESCRIPTION +The BER API provides a mechanism to read and write ASN.1 using the +Basic Encoding Rules. +.Pp +Encoded BER is stored in the following structure: +.Bd -literal +struct ber { + off_t br_offs; + u_char *br_wbuf; + u_char *br_wptr; + u_char *br_wend; + u_char *br_rbuf; + u_char *br_rptr; + u_char *br_rend; + + unsigned int (*br_application)(struct ber_element *); +}; +.Ed +.Pp +.Fa br_rbuf +and +.Fa br_wbuf +are the read and write buffers for a BER byte stream. +These buffers are used when reading an existing byte stream (e.g. received from +a TLS connection), or when writing a new byte stream in preparation for +subsequent operations performed by the calling application (e.g. network +transmission or export to a file). +.Pp +Intermediary storage of BER elements during encoding and decoding uses the +following structure: +.Bd -literal +struct ber_element { + struct ber_element *be_next; + unsigned int be_type; + unsigned int be_encoding; + size_t be_len; + off_t be_offs; + int be_free; + u_int8_t be_class; + void (*be_cb)(void *, size_t); + void *be_cbarg; + union { + struct ber_element *bv_sub; + void *bv_val; + long long bv_numeric; + } be_union; +#define be_sub be_union.bv_sub +#define be_val be_union.bv_val +#define be_numeric be_union.bv_numeric +}; +.Ed +.Pp +.Fn ober_set_readbuf +sets +.Fa br_rbuf +to point an input buffer of BER encoded bytes in preparation for decoding. +It is assumed that +.Fa br_rbuf +is already populated and available to the +application, commonly obtained by +.Xr read 2 , +.Xr recv 2 , +or +.Xr tls_read 3 . +.Pp +.Fn ober_read_elements +may then be called to parse, validate, and store the +.Fa ber +data stream into its +constituent +.Vt ber_element +parts for subsequent processing. +The calling application must have explicit knowledge of the expected data +types in order for correct decoding. +.Pp +.Fn ober_get_writebuf +sets +.Fa br_wbuf +to point to an output buffer for writing a BER byte stream. +.Pp +.Fn ober_write_elements +encodes +.Fa root +into a compliant BER byte stream which is written to +.Fa ber +for subsequent use by the calling +functions such as +.Xr send 2 , +.Xr write 2 , +or +.Xr tls_write 3 . +.Pp +.Fn ober_free +frees any dynamically allocated storage associated with +.Fa ber . +.Sh RETURN VALUES +.Fn ober_read_elements +returns a pointer to a fully populated list of one or more +.Vt ber_element +structures. +Otherwise \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Pp +.Fn ober_get_writebuf +returns the number of bytes contained within the buffer +.Fa buf +or \-1 on failure. +.Pp +.Fn ober_write_elements +returns the number of bytes written. +Otherwise \-1 is returned and the global variable +.Va errno +is set to +.Er ENOMEM . +.Sh ERRORS +.Fn ober_read_elements +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +No memory was available to create the full +.Vt ber_element +structure list. +.It Bq Er ENOBUFS +.Fn ober_read_elements +was called before calling +.Fn ober_set_readbuf . +.It Bq Er ECANCELED +.Fa buf +does not contain enough data to complete the unpacking. +.It Bq Er EINVAL +.Fa buf +does not contain a valid BER data structure. +.It Bq Er ERANGE +One of the values in the structure is larger than the library can unpack. +.El +.Sh SEE ALSO +.Xr read 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr write 2 , +.Xr ober_add_string 3 , +.Xr ober_get_string 3 , +.Xr ober_oid_cmp 3 , +.Xr ober_set_header 3 , +.Xr tls_read 3 +.Sh STANDARDS +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules. +.Sh HISTORY +These functions first appeared as internal functions in +.Xr snmpd 8 +in +.Ox 4.2 +and were moved to libutil in +.Ox 6.6 . +.Sh AUTHORS +.An -nosplit +The BER library was written by +.An Claudio Jeker Aq Mt claudio@openbsd.org , +.An Marc Balmer Aq Mt marc@openbsd.org +and +.An Reyk Floeter Aq Mt reyk@openbsd.org . +.Sh CAVEATS +The BER +API is subject to the following restrictions which are common to the +Distinguished Encoding Rules as defined by X.690: +.Pp +.Bl -enum -compact +.It +Only the definite form of length encoding shall be used, encoded in the +minimum number of octets. +.It +For bitstring, octetstring and restricted character string types, the +constructed form of encoding shall not be used. +.It +If a boolean encoding represents the boolean value TRUE, its single contents +octet shall have all eight bits set to one. +.It +Each unused bit in the final octet of the encoding of a bit string value shall +be set to zero. +.It +If a bitstring value has no 1 bits, then an encoder shall encode the value with +a length of 1 and an initial octet set to 0. +.El +.Pp +In addition, set and sequence values are limited to a maximum of 65535 elements. +No alternative encodings are permitted. +.Pp +.Do +Whereas the basic encoding rules give the sender of an encoding various choices +as to how data values may be encoded, the canonical and distinguished encoding +rules select just one encoding from those allowed by the basic encoding rules. +.Dc +.Bq X.690 +.Pp +The restrictions placed on this API avoid the ambiguity inherent in +BER encoded ASN.1 thereby acting as a security mitigation. diff --git a/static/openbsd/man3/ober_set_header.3 b/static/openbsd/man3/ober_set_header.3 new file mode 100644 index 00000000..dc3efb76 --- /dev/null +++ b/static/openbsd/man3/ober_set_header.3 @@ -0,0 +1,160 @@ +.\" $OpenBSD: ober_set_header.3,v 1.6 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2007, 2012 Reyk Floeter +.\" +.\" 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: June 13 2025 $ +.Dt OBER_SET_HEADER 3 +.Os +.Sh NAME +.Nm ober_set_header , +.Nm ober_calc_len , +.Nm ober_set_writecallback , +.Nm ober_link_elements , +.Nm ober_replace_elements , +.Nm ober_dup , +.Nm ober_unlink_elements , +.Nm ober_free_element , +.Nm ober_free_elements +.Nd change and destroy ASN.1 objects for BER encoding +.Sh SYNOPSIS +.Lb libutil +.In sys/types.h +.In ber.h +.Ft void +.Fn "ober_set_header" "struct ber_element *elm" "int class" "unsigned int type" +.Ft size_t +.Fn "ober_calc_len" "struct ber_element *root" +.Ft void +.Fo "ober_set_writecallback" +.Fa "struct ber_element *elm" +.Fa "void (*cb)(void *arg, size_t offs)" +.Fa "void *arg" +.Fc +.Ft void +.Fn "ober_link_elements" "struct ber_element *prev" "struct ber_element *elm" +.Ft void +.Fn "ober_replace_elements" "struct ber_element *prev" "struct ber_element *elm" +.Ft struct ber_element * +.Fn "ober_dup" "struct ber_element *orig" +.Ft struct ber_element * +.Fn "ober_unlink_elements" "struct ber_element *prev" +.Ft void +.Fn "ober_free_element" "struct ber_element *root" +.Ft void +.Fn "ober_free_elements" "struct ber_element *root" +.Pp +.Fd #define BER_TYPE_BOOLEAN 1 +.Fd #define BER_TYPE_INTEGER 2 +.Fd #define BER_TYPE_BITSTRING 3 +.Fd #define BER_TYPE_OCTETSTRING 4 +.Fd #define BER_TYPE_NULL 5 +.Fd #define BER_TYPE_OBJECT 6 +.Fd #define BER_TYPE_ENUMERATED 10 +.Fd #define BER_TYPE_SEQUENCE 16 +.Fd #define BER_TYPE_SET 17 +.Pp +.Fd #define BER_TYPE_CONSTRUCTED 0x20 +.Pp +.Fd #define BER_CLASS_UNIVERSAL 0x0 +.Fd #define BER_CLASS_UNIV BER_CLASS_UNIVERSAL +.Fd #define BER_CLASS_APPLICATION 0x1 +.Fd #define BER_CLASS_APP BER_CLASS_APPLICATION +.Fd #define BER_CLASS_CONTEXT 0x2 +.Fd #define BER_CLASS_PRIVATE 0x3 +.Sh DESCRIPTION +.Fn ober_set_header +sets the +.Fa class +and +.Fa type +of +.Fa elm . +.Pp +.Fn ober_calc_len +determines the total length of +.Fa root . +.Pp +.Fn ober_set_writecallback +registers the +.Vt br_cb +callback function. +.Pp +.Fn ober_link_elements +links +.Fa prev +and +.Fa elm . +.Pp +.Fn ober_replace_elements +replaces +.Fa prev +with +.Fa new +and frees any dynamically allocated storage associated with +.Fa prev . +.Pp +.Fn ober_dup +duplicates an element and all linked elements. +.Pp +.Fn ober_unlink_elements +unlinks +.Fa prev . +.Pp +.Fn ober_free_element +and +.Fn ober_free_elements +free any dynamically allocated storage associated with +.Fa root . +.Sh RETURN VALUES +.Fn ober_calc_len +returns the total length of a fully populated +.Fa root +containing one or more +.Vt ber_element . +.Pp +.Fn ober_dup +returns a pointer to the duplicated element or +.Dv NULL +on error. +.Pp +.Fn ober_unlink_elements +returns a pointer to +.Vt ber_element . +.Sh SEE ALSO +.Xr ober_add_string 3 , +.Xr ober_get_string 3 , +.Xr ober_oid_cmp 3 , +.Xr ober_read_elements 3 +.Sh STANDARDS +ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: +Information technology - ASN.1 encoding rules. +.Sh HISTORY +.Fn ober_dup +first appeared in +.Ox 7.0 . +.Pp +The other functions first appeared as internal functions in +.Xr snmpd 8 +in +.Ox 4.2 +and were moved to libutil in +.Ox 6.6 . +.Sh AUTHORS +.An -nosplit +The BER library was written by +.An Claudio Jeker Aq Mt claudio@openbsd.org , +.An Marc Balmer Aq Mt marc@openbsd.org +and +.An Reyk Floeter Aq Mt reyk@openbsd.org . diff --git a/static/openbsd/man3/ohash_init.3 b/static/openbsd/man3/ohash_init.3 new file mode 100644 index 00000000..d1a11aaf --- /dev/null +++ b/static/openbsd/man3/ohash_init.3 @@ -0,0 +1,272 @@ +.\" $OpenBSD: ohash_init.3,v 1.5 2025/06/13 18:34:00 schwarze Exp $ +.\" Copyright (c) 1999 Marc Espie +.\" +.\" 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: June 13 2025 $ +.Dt OHASH_INIT 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 +.Lb libutil +.In stdint.h +.In stddef.h +.In 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 +is a pointer to a +.Fa struct ohash_info . +.Bd -literal -offset indent +struct ohash_info { + ptrdiff_t key_offset; + void *data; /* user data */ + void *(*calloc)(size_t, size_t, void *); + void (*free)(void *, void *); + void *(*alloc)(size_t, void *); +}; +.Ed +.Pp +The +.Va offset +field holds the position of the key in each record; +the +.Va calloc +and +.Va free +fields are pointers to +.Xr calloc 3 +and +.Xr free 3 Ns -like +functions, used for managing the table internal storage; +the +.Va alloc +field is only used by the utility function +.Xr ohash_create_entry 3 . +.Pp +Each of these functions are called similarly to their standard counterpart, +but with an extra +.Fa "void *" +parameter corresponding to the content of the field +.Fa data , +which can be used to communicate specific information to the functions. +.Pp +.Fn ohash_init +stores a copy of those fields internally, so +.Fa info +can be reclaimed after initialization. +.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: +.Bd -literal -offset indent +p = (*info->calloc)(n, sizeof_record, info->data); +/* copy data from old to p */ +(*info->free)(old, info->data); +.Ed +.Pp +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 hcreate 3 , +.Xr ohash_interval 3 +.Rs +.%A Donald E. Knuth +.%B The Art of Computer Programming +.%V Vol. 3 +.%P pp. 506\(en550 +.%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/openbsd/man3/ohash_interval.3 b/static/openbsd/man3/ohash_interval.3 new file mode 100644 index 00000000..22f736f7 --- /dev/null +++ b/static/openbsd/man3/ohash_interval.3 @@ -0,0 +1,94 @@ +.\" $OpenBSD: ohash_interval.3,v 1.3 2025/06/13 18:34:00 schwarze Exp $ +.\" Copyright (c) 2001 Marc Espie +.\" +.\" 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: June 13 2025 $ +.Dt OHASH_INTERVAL 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 +.Lb libutil +.In stdint.h +.In stddef.h +.In ohash.h +.Ft uint32_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: +.Bd -literal -offset indent +p = (*info->alloc)(sz, info->data); +.Ed +.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/openbsd/man3/open_memstream.3 b/static/openbsd/man3/open_memstream.3 new file mode 100644 index 00000000..c08fc210 --- /dev/null +++ b/static/openbsd/man3/open_memstream.3 @@ -0,0 +1,107 @@ +.\" $OpenBSD: open_memstream.3,v 1.4 2013/06/05 03:39:23 tedu Exp $ +.\" +.\" Copyright (c) 2011 Martin Pieuchot +.\" +.\" 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: June 5 2013 $ +.Dt OPEN_MEMSTREAM 3 +.Os +.Sh NAME +.Nm open_memstream , +.Nm open_wmemstream +.Nd open a memory buffer stream +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn open_memstream "char **pbuf" "size_t *psize" +.In wchar.h +.Ft FILE * +.Fn open_wmemstream "wchar_t **pbuf" "size_t *psize" +.Sh DESCRIPTION +The +.Fn open_memstream +and +.Fn open_wmemstream +functions create, respectively, a seekable byte-oriented or wide-oriented +stream for writing. +A dynamically allocated buffer, using +.Xr malloc 3 , +is then wrapped to the pointer referenced by +.Fa pbuf +and grows automatically as required. +.Pp +When the stream is either closed or flushed, the address of the buffer is +stored in the pointer referenced by +.Fa pbuf . +At the same time the smaller of the current position and the buffer length is +written in the variable pointed to by +.Fa psize . +This value represents, respectively, +the number of bytes or wide characters contained in the buffer, +not including the terminating null character. +.Pp +The buffer memory should be released after the stream is closed. +.Sh RETURN VALUES +Upon successful completion, +.Fn open_memstream +and +.Fn open_wmemstream +return 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 pbuf +or the +.Fa psize +argument is +.Dv NULL . +.El +.Pp +The +.Fn open_memstream +and +.Fn open_wmemstream +functions +may also fail and set +.Va errno +for any of the errors +specified for the routine +.Xr malloc 3 . +.Sh SEE ALSO +.Xr fmemopen 3 , +.Xr fopen 3 , +.Xr funopen 3 , +.Xr malloc 3 +.Sh STANDARDS +The functions +.Fn open_memstream +and +.Fn open_wmemstream , +conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn open_memstream +and +.Fn open_wmemstream +functions first appeared in +.Ox 5.4 . diff --git a/static/openbsd/man3/opendev.3 b/static/openbsd/man3/opendev.3 new file mode 100644 index 00000000..3c8e93ba --- /dev/null +++ b/static/openbsd/man3/opendev.3 @@ -0,0 +1,114 @@ +.\" $OpenBSD: opendev.3,v 1.25 2025/06/06 22:01:40 schwarze Exp $ +.\" +.\" Copyright (c) 2000, Todd C. Miller. All rights reserved. +.\" Copyright (c) 1996, Jason Downs. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(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 AUTHOR(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 $Mdocdate: June 6 2025 $ +.Dt OPENDEV 3 +.Os +.Sh NAME +.Nm opendev +.Nd short form device open routine +.Sh SYNOPSIS +.Lb libutil +.In util.h +.Ft int +.Fn opendev "const char *path" "int oflags" "int dflags" "char **realpath" +.Sh DESCRIPTION +The +.Fn opendev +function opens a device using a +.Dq short form +name or +.Xr disklabel 8 +UID +.Pq DUID . +For instance +.Dq sd0 +or +.Dq sd0c +will be expanded to +.Pa /dev/rsd0c +on most architectures. +.Pp +Device name lookup is done by first checking +.Fa path +for a +.Sq / +and if one is found attempting to open that file. +If not, +.Fa path +is checked to see if it is a valid DUID. +If it is, the corresponding device is obtained via +.Xr diskmap 4 . +If +.Fa path +has no +.Sq / +and is not a DUID, +.Fa /dev +is searched for a matching device. +.Pp +The +.Fa oflags +are the same as the +.Fa flags +passed to +.Xr open 2 . +.Pp +The +.Fa dflags +are specified by OR'ing the following values: +.Bd -literal -offset indent +OPENDEV_PART attempt to open the raw partition during expansion +OPENDEV_BLCK open the block device (default is character device) +.Ed +.Pp +If +.Fa realpath +is not +.Dv NULL , +it is modified to point at the fully expanded device name. +.Sh RETURN VALUES +The +.Fn opendev +return value and errors are the same as the return value and errors of +.Xr open 2 . +.Sh SEE ALSO +.Xr open 2 , +.Xr getrawpartition 3 , +.Xr diskmap 4 , +.Xr disklabel 8 +.Sh HISTORY +The +.Fn opendev +function first appeared in +.Ox 1.2 . +.Sh CAVEATS +If +.Fa realpath +is not +.Dv NULL , +on return it will point to internal +static storage space that will be overwritten by subsequent calls. diff --git a/static/openbsd/man3/opendir.3 b/static/openbsd/man3/opendir.3 new file mode 100644 index 00000000..397508f3 --- /dev/null +++ b/static/openbsd/man3/opendir.3 @@ -0,0 +1,316 @@ +.\" $OpenBSD: opendir.3,v 1.3 2024/03/23 16:30:01 guenther 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 $Mdocdate: March 23 2024 $ +.Dt OPENDIR 3 +.Os +.Sh NAME +.Nm opendir , +.Nm fdopendir , +.Nm readdir , +.Nm readdir_r , +.Nm telldir , +.Nm seekdir , +.Nm rewinddir , +.Nm closedir , +.Nm dirfd +.Nd directory operations +.Sh SYNOPSIS +.In sys/types.h +.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 +.Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result" +.Ft long +.Fn telldir "const 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 +.Fn opendir +function opens the directory named by +.Fa filename , +associates a directory stream with it, and returns a pointer to be used +to identify the directory stream in subsequent operations. +On failure, +.Dv NULL +is returned and +.Va errno +is set to indicate the error. +.Pp +The +.Fn fdopendir +function is equivalent to +.Fn opendir +except that the directory is specified by file descriptor rather than by name. +The file offset associated with the file descriptor at the time of the call +determines which entries are returned. +.Pp +Upon successful return from +.Fn fdopendir , +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 directory, +other than by means of +.Fn closedir , +.Fn readdir , +.Fn readdir_r , +or +.Fn rewinddir , +the behavior is undefined. +Upon calling +.Fn closedir +the file descriptor shall be closed. +.Pp +The +.Fn readdir +function returns a pointer to the next directory entry in the named +directory stream +.Fa dirp . +It returns +.Dv NULL +upon reaching the end of the directory or detecting an invalid +.Fn seekdir +operation. +.Pp +The +.Fn readdir_r +function is a deprecated variant of +.Fn readdir . +Like +.Fn readdir , +it initializes the +.Vt dirent +structure referenced by +.Fa entry +to represent the next directory entry in the named directory stream +.Fa dirp , +and stores a pointer to this structure at the location referenced by +.Fa result . +The storage pointed to by +.Fa entry +must be large enough for a dirent with a +.Fa d_name +array member containing at least +.Dv NAME_MAX +plus one elements. +.Fn readdir_r +returns 0 on success, or an error number if an error occurs; see +.Sx ERRORS . +On successful return, the pointer returned at +.Fa "*result" +will have the same value as the argument +.Fa entry . +Upon reaching the end of the directory stream, this pointer shall have the value +.Dv NULL . +.Pp +The +.Fn telldir +function returns the current location associated with the named +directory stream +.Fa dirp . +On failure, \-1 is returned and +.Va errno +is set to indicate the error. +.Pp +The +.Fn seekdir +function sets the position of the next +.Fn readdir +operation on the named directory stream +.Fa dirp . +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 +.Dv DIR +pointer, +.Fa dirp , +from which they are derived. +If the directory is closed and then reopened, the +.Fn telldir +value may be invalidated due to undetected directory compaction. +.Pp +The +.Fn rewinddir +function resets the position of the named directory stream +.Fa dirp +to the beginning of the directory. +.Pp +The +.Fn closedir +function closes the named directory stream and frees the structure +associated with the +.Fa dirp +pointer, returning 0 on success. +On failure, \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Pp +The +.Fn dirfd +function returns the integer file descriptor associated with the named +directory stream +.Fa dirp +(see +.Xr open 2 ) . +.Sh EXAMPLES +Sample code which searches a directory for entry +.Dq name +is: +.Bd -literal -offset indent +len = strlen(name); +dirp = opendir("."); +if (dirp) { + while ((dp = readdir(dirp)) != NULL) + if (dp->d_namlen == len && + !strcmp(dp->d_name, name)) { + closedir(dirp); + return FOUND; + } + closedir(dirp); +} +return NOT_FOUND; +.Ed +.Sh ERRORS +The +.Fn opendir +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +The supplied +.Fa filename +is not a directory. +.El +.Pp +The +.Fn opendir +function may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr fcntl 2 , +.Xr fstat 2 , +.Xr open 2 , +and +.Xr malloc 3 . +.Pp +The +.Fn fdopendir +function will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor open for reading. +.It Bq Er ENOTDIR +The descriptor +.Fa fd +is not associated with a directory. +.El +.Pp +The +.Fn readdir +and +.Fn readdir_r +functions may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr getdents 2 . +.Pp +The +.Fn telldir +function may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr realloc 3 . +.Pp +The +.Fn closedir +function may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr close 2 . +.Sh SEE ALSO +.Xr close 2 , +.Xr getdents 2 , +.Xr lseek 2 , +.Xr open 2 , +.Xr dir 5 +.Sh STANDARDS +The +.Fn opendir , +.Fn fdopendir , +.Fn readdir , +.Fn readdir_r , +.Fn telldir , +.Fn seekdir , +.Fn rewinddir , +.Fn closedir , +and +.Fn dirfd +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 +.Ox 5.0 . +.Sh CAVEATS +The +.Fn readdir_r +function was intended to provide a thread-safe version of +.Fn readdir . +However, it was later found to be both unnecessary in the typical +usage and unportable due to insufficient buffer sizing guidance. +It was therefore officially deprecated in issue 8. diff --git a/static/openbsd/man3/opendisk.3 b/static/openbsd/man3/opendisk.3 new file mode 100644 index 00000000..98b70707 --- /dev/null +++ b/static/openbsd/man3/opendisk.3 @@ -0,0 +1,160 @@ +.\" $OpenBSD: opendisk.3,v 1.10 2025/06/06 22:01:40 schwarze Exp $ +.\" $NetBSD: opendisk.3,v 1.4 1999/07/02 15:49:12 simonb 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 $Mdocdate: June 6 2025 $ +.Dt OPENDISK 3 +.Os +.Sh NAME +.Nm opendisk +.Nd open a disk's raw partition +.Sh SYNOPSIS +.Lb libutil +.In sys/types.h +.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 +.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). +If +.Fa iscooked +is non zero, the +.Dq cooked +partition (block device) is opened, rather than the +.Dq raw +partition (character device). +.Pp +.Fn opendisk +attempts to open the following variations of +.Fa path , +in order: +.Bl -tag -width "/dev/rpathX" +.It Fa path +The pathname as given. +.It Fa 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 . +.El +.Pp +If +.Fa iscooked +is zero, then the following two variations are attempted: +.Bl -tag -width "/dev/rpathX" +.It Pa /dev/r Ns Fa path +.Fa path +with a prefix of +.Dq Pa /dev/r . +.It Pa /dev/r Ns Fa path Ns Em X +.Fa path +with a prefix of +.Dq Pa /dev/r +and a suffix of +.Sq Em X +(q.v.). +.El +.Pp +Otherwise (i.e., +.Fa iscooked +is non-zero), the following variations are attempted: +.Bl -tag -width "/dev/rpathX" +.It Pa /dev/ Ns Fa path +.Fa path +with a prefix of +.Dq Pa /dev/ . +.It Pa /dev/ Ns Fa path Ns Em X +.Fa path +with a prefix of +.Dq Pa /dev/ +and a suffix of +.Sq Em X +(q.v.). +.El +.Sh RETURN VALUES +An open file descriptor, or -1 if the +.Xr open 2 +failed. +.Sh ERRORS +.Fn opendisk +may set +.Va errno +to one of the following values: +.Bl -tag -width Er +.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. +.Sh SEE ALSO +.Xr open 2 , +.Xr getrawpartition 3 +.Sh HISTORY +The +.Fn opendisk +function first appeared in +.Nx 1.3 . diff --git a/static/openbsd/man3/openpty.3 b/static/openbsd/man3/openpty.3 new file mode 100644 index 00000000..f88668fb --- /dev/null +++ b/static/openbsd/man3/openpty.3 @@ -0,0 +1,219 @@ +.\" $OpenBSD: openpty.3,v 1.21 2025/06/06 22:01:40 schwarze 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 $Mdocdate: June 6 2025 $ +.Dt OPENPTY 3 +.Os +.Sh NAME +.Nm getptmfd , +.Nm openpty , +.Nm fdopenpty , +.Nm login_tty , +.Nm forkpty , +.Nm fdforkpty +.Nd tty utility functions +.Sh SYNOPSIS +.Lb libutil +.In termios.h +.In util.h +.Ft int +.Fn getptmfd "void" +.Ft int +.Fn openpty "int *amaster" "int *aslave" "char *name" "const struct termios *termp" "const struct winsize *winp" +.Ft int +.Fn fdopenpty "int ptmfd" "int *amaster" "int *aslave" "char *name" "const struct termios *termp" "const struct winsize *winp" +.Ft int +.Fn login_tty "int fd" +.Ft pid_t +.Fn forkpty "int *amaster" "char *name" "const struct termios *termp" "const struct winsize *winp" +.Ft pid_t +.Fn fdforkpty "int ptmfd" "int *amaster" "char *name" "const struct termios *termp" "const 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 +(a string of at least 16 characters). +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 openpty +function allocates the pseudo-tty through the +.Pa /dev/ptm +device (see +.Xr pty 4 +for details) which means that its ownership is changed to the UID of +the caller, permissions are set to correct values, and all earlier +uses of that device are revoked (see +.Xr revoke 2 +for details). +.Pp +The +.Fn fdopenpty +and +.Fn fdforkpty +functions work like +.Fn openpty +and +.Fn forkpty +but expect a +.Pa /dev/ptm +file descriptor +.Fa ptmfd +obtained from the +.Fn getptmfd +function. +.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 in +.Fa amaster , +and the filename of the slave in +.Fa name +if it 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/tty[p-zP-T][0-9a-zA-Z]x -compact +.It Pa /dev/pty[p-zP-T][0-9a-zA-Z] +master pseudo terminals +.It Pa /dev/tty[p-zP-T][0-9a-zA-Z] +slave pseudo terminals +.It Pa /dev/ptm +pseudo terminal management device +.El +.Sh ERRORS +.Fn getptmfd +may fail and set +.Va errno +for any of the errors specified for the routine +.Xr open 2 . +.Pp +.Fn openpty +and +.Fn fdopenpty +will fail if: +.Bl -tag -width Er +.It Bq Er ENOENT +There are no available ttys. +.El +.Pp +.Fn fdopenpty +and +.Fn fdforkpty +will fail if +.Fn getptmfd +fails. +.Fn forkpty +and +.Fn fdforkpty +will fail if either +.Fn openpty +or +.Fn fork +fails. +.Pp +.Fn login_tty +will fail if +.Fn ioctl +fails to set +.Fa fd +to the controlling terminal of the current process. +.Sh SEE ALSO +.Xr fork 2 , +.Xr revoke 2 , +.Xr pty 4 diff --git a/static/openbsd/man3/ossaudio.3 b/static/openbsd/man3/ossaudio.3 new file mode 100644 index 00000000..68910179 --- /dev/null +++ b/static/openbsd/man3/ossaudio.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: ossaudio.3,v 1.13 2025/06/06 20:52:27 schwarze Exp $ +.\" $NetBSD: ossaudio.3,v 1.12 2001/05/19 17:23:39 jdolecek Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson, +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: June 6 2025 $ +.Dt OSSAUDIO 3 +.Os +.Sh NAME +.Nm ossaudio +.Nd OSS audio emulation +.Sh SYNOPSIS +.Lb libossaudio +.In soundcard.h +.Sh DESCRIPTION +The +.Nm +library provides an emulation of the OSS (Linux) audio +interface. +.Pp +Use the native +.Xr sioctl_open 3 +interface for new programs and the emulation +library only for porting programs. +.Sh SEE ALSO +.Xr sioctl_open 3 , +.Xr audio 4 +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 1.3 . +.Sh BUGS +The emulation uses a #define for +.Fn ioctl +so some obscure programs +can fail to compile. +.Pp +The emulation is incomplete. +.Pp +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 +.Dv EINTR +whereas +.Ox +returns +.Dv EAGAIN . diff --git a/static/openbsd/man3/panel.3 b/static/openbsd/man3/panel.3 new file mode 100644 index 00000000..9a97a71d --- /dev/null +++ b/static/openbsd/man3/panel.3 @@ -0,0 +1,278 @@ +.\" $OpenBSD: panel.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: panel.3,v 1.11 2023/10/17 09:52:10 nicm Exp $ +.TH panel 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +panel \- panel stack extension for curses +.SH SYNOPSIS +\fB#include \fP +.P +\fBcc [flags] sourcefiles \-lpanel \-lncurses\fP +.P +\fBPANEL *new_panel(WINDOW *\fIwin\fB);\fR +.sp +\fBint bottom_panel(PANEL *\fIpan\fB);\fR +.br +\fBint top_panel(PANEL *\fIpan\fB);\fR +.br +\fBint show_panel(PANEL *\fIpan\fB);\fR +.br +\fBvoid update_panels(void);\fP +.br +\fBint hide_panel(PANEL *\fIpan\fB);\fR +.sp +\fBWINDOW *panel_window(const PANEL *\fIpan\fB);\fR +.br +\fBint replace_panel(PANEL *\fIpan\fB, WINDOW *\fIwindow\fB);\fR +.br +\fBint move_panel(PANEL *\fIpan\fB, int \fIstarty\fB, int \fIstartx\fB);\fR +.br +\fBint panel_hidden(const PANEL *\fIpan\fB);\fR +.sp +\fBPANEL *panel_above(const PANEL *\fIpan\fB);\fR +.br +\fBPANEL *panel_below(const PANEL *\fIpan\fB);\fR +.sp +\fBint set_panel_userptr(PANEL *\fIpan\fB, const void *\fIptr\fB);\fR +.br +\fBconst void *panel_userptr(const PANEL *\fIpan\fB);\fR +.sp +\fBint del_panel(PANEL *\fIpan\fB);\fR +.sp +\fR/* ncurses-extensions */\fP +.br +\fBPANEL *ground_panel(SCREEN *\fIsp\fB);\fR +.br +\fBPANEL *ceiling_panel(SCREEN *\fIsp\fB);\fR +.br +.SH DESCRIPTION +Panels are \fBcurses\fP(3) windows with the added feature of +depth. +Panel functions allow the use of stacked windows and ensure +the proper portions of each window and the curses \fBstdscr\fP window are +hidden or displayed when panels are added, moved, modified or removed. +The set of currently visible panels is the stack of panels. +The +\fBstdscr\fP window is beneath all panels, and is not considered part +of the stack. +.P +A window is associated with every panel. +The panel routines enable +you to create, move, hide, and show panels, as well as position a +panel at any desired location in the stack. +.P +Panel routines are a functional layer added to \fBcurses\fP(3), make only +high-level curses calls, and work anywhere terminfo curses does. +.SH FUNCTIONS +.\" --------- +.SS bottom_panel +\fBbottom_panel(\fIpan\fB)\fR +puts panel \fIpan\fP at the bottom of all panels. +.\" --------- +.SS ceiling_panel +\fBceiling_panel(\fIsp\fB)\fR +acts like \fBpanel_below(NULL)\fP, for the given \fBSCREEN\fP \fIsp\fP. +.\" --------- +.SS del_panel +\fBdel_panel(\fIpan\fB)\fR +removes the given panel \fIpan\fP from the stack and deallocates the +\fBPANEL\fP structure (but not its associated window). +.\" --------- +.SS ground_panel +\fBground_panel(\fIsp\fB)\fR +acts like \fBpanel_above(NULL)\fP, for the given \fBSCREEN\fP \fIsp\fP. +.\" --------- +.SS hide_panel +\fBhide_panel(\fIpan\fB)\fR +removes the given panel \fIpan\fP from the panel stack +and thus hides it from view. +The \fBPANEL\fP structure is not lost, merely removed from the stack. +.\" --------- +.SS move_panel +\fBmove_panel(\fIpan\fB,\fIstarty\fB,\fIstartx\fB)\fR +moves the given panel \fIpan\fP's window so that its upper-left corner is at +\fIstarty\fP, \fIstartx\fP. +It does not change the position of the panel in the stack. +Be sure to use this function, not \fBmvwin\fP(3), to move a panel window. +.\" --------- +.SS new_panel +\fBnew_panel(\fIwin\fB)\fR allocates a \fBPANEL\fR structure, +associates it with \fIwin\fP, places the panel on the top of the stack +(causes it to be displayed above any other panel) and returns a +pointer to the new panel. +.\" --------- +.SS panel_above +\fBpanel_above(\fIpan\fB)\fR +returns a pointer to the panel above \fIpan\fP. +If the panel argument is +\fB(PANEL *)0\fP, it returns a pointer to the bottom panel in the stack. +.\" --------- +.SS panel_below +\fBpanel_below(\fIpan\fB)\fR +returns a pointer to the panel just below \fIpan\fP. +If the panel argument +is \fB(PANEL *)0\fP, it returns a pointer to the top panel in the stack. +.\" --------- +.SS panel_hidden +\fBpanel_hidden(\fIpan\fB)\fR +returns \fBFALSE\fP if the panel \fIpan\fP is in the panel stack, +\fBTRUE\fP if it is not. +If the panel is a null pointer, return \fBERR\fP. +.\" --------- +.SS panel_userptr +\fBpanel_userptr(\fIpan\fB)\fR +returns the user pointer for a given panel \fIpan\fP. +.\" --------- +.SS panel_window +\fBpanel_window(\fIpan\fB)\fR +returns a pointer to the window of the given panel \fIpan\fP. +.\" --------- +.SS replace_panel +\fBreplace_panel(\fIpan\fB,\fIwindow\fB)\fR +replaces the current window of panel \fIpan\fP with \fIwindow\fP +This is useful, for example if you want to resize a panel. +In \fBncurses\fP, you can call \fBreplace_panel\fP +to resize a panel using a window resized with \fBwresize\fP(3). +It does not change the position of the panel in the stack. +.\" --------- +.SS set_panel_userptr +\fBset_panel_userptr(\fIpan\fB,\fIptr\fB)\fR +sets the panel's user pointer. +.\" --------- +.SS show_panel +\fBshow_panel(\fIpan\fB)\fR +makes a hidden panel visible by placing it on top of the panels in the +panel stack. +See \fBCOMPATIBILITY\fP below. +.\" --------- +.SS top_panel +\fBtop_panel(\fIpan\fB)\fR +puts the given visible panel \fIpan\fP on top of all panels in the stack. +See \fBCOMPATIBILITY\fP below. +.\" --------- +.SS update_panels +\fBupdate_panels()\fR +refreshes the \fIvirtual screen\fP to reflect the relations between the +panels in the stack, but does not call \fBdoupdate\fP(3) to refresh the +\fIphysical screen\fP. +Use this function and not \fBwrefresh\fP(3) or \fBwnoutrefresh\fP(3). +.PP +\fBupdate_panels\fP may be called more than once before a call to +\fBdoupdate\fP, but \fBdoupdate\fP is the function responsible for updating +the \fIphysical screen\fP. +.SH DIAGNOSTICS +Each routine that returns a pointer returns \fBNULL\fP if an error +occurs. +Each routine that returns an int value returns \fBOK\fP if it +executes successfully and \fBERR\fP if not. +.PP +Except as noted, the \fIpan\fP and \fIwindow\fP parameters must be non-null. +If those are null, an error is returned. +.PP +The \fBmove_panel\fP function uses \fBmvwin\fP(3), +and will return an error if \fBmvwin\fP returns an error. +.SH COMPATIBILITY +Reasonable care has been taken to ensure compatibility +with the native panel facility introduced in System V (inspection of +the SVr4 manual pages suggests the programming interface is unchanged). +The \fBPANEL\fP data structures are merely similar. +The programmer +is cautioned not to directly use \fBPANEL\fP fields. +.P +The functions \fBshow_panel\fP and \fBtop_panel\fP are identical +in this implementation, and work equally well with displayed or hidden +panels. +In the native System V implementation, \fBshow_panel\fP is +intended for making a hidden panel visible (at the top of the stack) +and \fBtop_panel\fP is intended for making an already-visible panel +move to the top of the stack. +You are cautioned to use the correct +function to ensure compatibility with native panel libraries. +.SH NOTE +In your library list, libpanel.a should be before libncurses.a; that is, +you should say \*(``\-lpanel \-lncurses\*('', not the other way around +(which would give a link-error with static libraries). +.SH PORTABILITY +The panel facility was documented in SVr4.2 in +\fICharacter User Interface Programming (UNIX SVR4.2)\fP. +.PP +It is not part of X/Open Curses. +.PP +A few implementations exist: +.bP +Systems based on SVr4 source code, +e.g., Solaris, provide this library. +.bP +\fBncurses\fP (since version 0.6 in 1993) +and \fBPDCurses\fP (since version 2.2 in 1995) +provide a panel library whose common ancestor +was a public domain implementation by Warren Tucker +published in \fIu386mon\fP 2.20 (1990). +.IP +According to Tucker, the SystemV panel library +was first released in SVr3.2 (1988), +and his implementation helped with a port to SVr3.1 (1987). +.IP +Several developers have improved each of these; +they are no longer the same as Tucker's implementation. +.bP +NetBSD 8 (2018) +has a panel library begun by Valery Ushakov in 2015. +This is based on the AT&T documentation. +.SH FILES +panel.h +interface for the panels library +.P +libpanel.a +the panels library itself +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_variables\fP(3), +.PP +This describes \fBncurses\fP +version 6.4 (patch 20230826). +.SH AUTHOR +Originally written by Warren Tucker , +primarily to assist in porting \fIu386mon\fP to systems without a native +panels library. +.PP +Repackaged for ncurses by Zeyd ben-Halim. +.PP +Juergen Pfeifer and Thomas E. Dickey revised/improved the library. diff --git a/static/openbsd/man3/pause.3 b/static/openbsd/man3/pause.3 new file mode 100644 index 00000000..969f7b4e --- /dev/null +++ b/static/openbsd/man3/pause.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: pause.3,v 1.17 2022/12/30 21:21:25 cheloha 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. +.\" +.Dd $Mdocdate: December 30 2022 $ +.Dt PAUSE 3 +.Os +.Sh NAME +.Nm pause +.Nd wait for a signal +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn pause void +.Sh DESCRIPTION +.Bf -symbolic +.Fn pause +is obsoleted by +.Xr sigsuspend 2 . +.Ef +.Pp +.Fn pause +blocks the calling thread until it receives an unmasked signal. +.Sh RETURN VALUES +.Fn pause +always returns \-1. +.Sh ERRORS +.Fn pause +always sets +.Xr errno 2 +to the following value: +.Bl -tag -width Er +.It Bq Er EINTR +The call was interrupted by a signal. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr setitimer 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr signal 3 +.Sh HISTORY +A +.Fn pause +system call first appeared outside of Bell Labs in the +.Dq 50 changes +tape for +.At v6 . +It was first officially released with PWB/UNIX 1.0. +It was reimplemented as a wrapper around the +.Fn sigpause +and +.Fn sigblock +system calls in +.Bx 4.2 , +and around the +.Xr sigsuspend 2 +and +.Xr sigprocmask 2 +system calls in +.Bx 4.3 Reno . diff --git a/static/openbsd/man3/pcap_open_live.3 b/static/openbsd/man3/pcap_open_live.3 new file mode 100644 index 00000000..ff0b6215 --- /dev/null +++ b/static/openbsd/man3/pcap_open_live.3 @@ -0,0 +1,667 @@ +.\" $OpenBSD: pcap_open_live.3,v 1.7 2025/06/13 18:45:02 schwarze Exp $ +.\" +.\" Copyright (c) 1994, 1996, 1997 +.\" 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: (1) source code distributions +.\" retain the above copyright notice and this paragraph in its entirety, (2) +.\" distributions including binary code include the above copyright notice and +.\" this paragraph in its entirety in the documentation or other materials +.\" provided with the distribution, and (3) all advertising materials mentioning +.\" features or use of this software display the following acknowledgement: +.\" ``This product includes software developed by the University of California, +.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of +.\" the University nor the names of its contributors may be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED +.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt PCAP_OPEN_LIVE 3 +.Os +.Sh NAME +.Nm pcap_open_live , +.Nm pcap_open_offline , +.Nm pcap_dump_open , +.Nm pcap_dump_fopen , +.Nm pcap_lookupdev , +.Nm pcap_lookupnet , +.Nm pcap_dispatch , +.Nm pcap_loop , +.Nm pcap_dump , +.Nm pcap_inject , +.Nm pcap_sendpacket , +.Nm pcap_compile , +.Nm pcap_setfilter , +.Nm pcap_freecode , +.Nm pcap_next , +.Nm pcap_next_ex , +.Nm pcap_setdirection , +.Nm pcap_datalink , +.Nm pcap_snapshot , +.Nm pcap_is_swapped , +.Nm pcap_major_version , +.Nm pcap_minor_version , +.Nm pcap_stats , +.Nm pcap_file , +.Nm pcap_fileno , +.Nm pcap_get_selectable_fd , +.Nm pcap_perror , +.Nm pcap_geterr , +.Nm pcap_strerror , +.Nm pcap_close , +.Nm pcap_dump_file , +.Nm pcap_dump_ftell , +.Nm pcap_dump_flush , +.Nm pcap_dump_close , +.Nm pcap_breakloop , +.Nm pcap_findalldevs , +.Nm pcap_freealldevs , +.Nm pcap_getnonblock , +.Nm pcap_setnonblock , +.Nm pcap_set_datalink , +.Nm pcap_list_datalinks , +.Nm pcap_free_datalinks , +.Nm pcap_open_dead , +.Nm pcap_fopen_offline , +.Nm pcap_lib_version , +.Nm pcap_datalink_val_to_name , +.Nm pcap_datalink_val_to_description , +.Nm pcap_datalink_name_to_val , +.Nm pcap_create , +.Nm pcap_set_snaplen , +.Nm pcap_set_promisc , +.Nm pcap_can_set_rfmon , +.Nm pcap_set_rfmon , +.Nm pcap_set_timeout , +.Nm pcap_set_buffer_size , +.Nm pcap_set_immediate_mode , +.Nm pcap_activate , +.Nm pcap_statustostr , +.Nm pcap_offline_filter +.Nd Packet Capture library +.Sh SYNOPSIS +.Lb libpcap +.In pcap.h +.Ft pcap_t * +.Fn pcap_open_live "const char *source" "int snaplen" "int promisc" "int to_ms" "char *errbuf" +.Ft pcap_t * +.Fn pcap_open_offline "char *fname" "char *errbuf" +.Ft pcap_dumper_t * +.Fn pcap_dump_open "pcap_t *p" "char *fname" +.Ft pcap_dumper_t * +.Fn pcap_dump_fopen "pcap_t *p" "FILE *f" +.Ft char * +.Fn pcap_lookupdev "char *errbuf" +.Ft int +.Fn pcap_lookupnet "const char *device" "bpf_u_int32 *netp" "bpf_u_int32 *maskp" "char *errbuf" +.Ft int +.Fn pcap_dispatch "pcap_t *p" "int cnt" "pcap_handler callback" "u_char *user" +.Ft int +.Fn pcap_loop "pcap_t *p" "int cnt" "pcap_handler callback" "u_char *user" +.Ft void +.Fn pcap_dump "u_char *user" "const struct pcap_pkthdr *h" "const u_char *sp" +.Ft int +.Fn pcap_inject "pcap_t *p" "const void *buf" "size_t len" +.Ft int +.Fn pcap_sendpacket "pcap_t *p" "const u_char *buf" "int size" +.Ft int +.Fn pcap_compile "pcap_t *p" "struct bpf_program *program" "const char *buf" "int optimize" "bpf_u_int32 netmask" +.Ft int +.Fn pcap_setfilter "pcap_t *p" "struct bpf_program *fp" +.Ft void +.Fn pcap_freecode "struct bpf_program *program" +.Ft u_char * +.Fn pcap_next "pcap_t *p" "struct pcap_pkthdr *h" +.Ft int +.Fn pcap_next_ex "pcap_t *p" "struct pcap_pkthdr **pkt_header" "const u_char **pkt_data" +.Ft int +.Fn pcap_setdirection "pcap_t *p" "pcap_direction_t d" +.Ft int +.Fn pcap_datalink "pcap_t *p" +.Ft int +.Fn pcap_snapshot "pcap_t *p" +.Ft int +.Fn pcap_is_swapped "pcap_t *p" +.Ft int +.Fn pcap_major_version "pcap_t *p" +.Ft int +.Fn pcap_minor_version "pcap_t *p" +.Ft int +.Fn pcap_stats "pcap_t *p" "struct pcap_stat *ps" +.Ft FILE * +.Fn pcap_file "pcap_t *p" +.Ft int +.Fn pcap_fileno "pcap_t *p" +.Ft int +.Fn pcap_get_selectable_fd "pcap_t *p" +.Ft void +.Fn pcap_perror "pcap_t *p" "const char *prefix" +.Ft char * +.Fn pcap_geterr "pcap_t *p" +.Ft const char * +.Fn pcap_strerror "int errnum" +.Ft void +.Fn pcap_close "pcap_t *p" +.Ft FILE * +.Fn pcap_dump_file "pcap_dumper_t *p" +.Ft long +.Fn pcap_dump_ftell "pcap_dumper_t *p" +.Ft int +.Fn pcap_dump_flush "pcap_dumper_t *p" +.Ft void +.Fn pcap_dump_close "pcap_dumper_t *p" +.Ft void +.Fn pcap_breakloop "pcap_t *p" +.Ft int +.Fn pcap_findalldevs "pcap_if_t **alldevsp" "char *errbuf" +.Ft void +.Fn pcap_freealldevs "pcap_if_t *alldevs" +.Ft int +.Fn pcap_getnonblock "pcap_t *p" "char *errbuf" +.Ft int +.Fn pcap_setnonblock "pcap_t *p" "int nonblock" "char *errbuf" +.Ft int +.Fn pcap_set_datalink "pcap_t *p" "int dlt" +.Ft int +.Fn pcap_list_datalinks "pcap_t *p" "int **dlt_buffer" +.Ft void +.Fn pcap_free_datalinks "int *dlt_list" +.Ft pcap_t * +.Fn pcap_open_dead "int linktype" "int snaplen" +.Ft pcap_t * +.Fn pcap_fopen_offline "FILE *fp" "char *errbuf" +.Ft const char * +.Fn pcap_lib_version "void" +.Ft const char * +.Fn pcap_datalink_val_to_name "int dlt" +.Ft const char * +.Fn pcap_datalink_val_to_description "int dlt" +.Ft int +.Fn pcap_datalink_name_to_val "const char *name" +.Ft pcap_t * +.Fn pcap_create "const char *device" "char *errbuf" +.Ft int +.Fn pcap_set_snaplen "pcap_t *p" "int snaplen" +.Ft int +.Fn pcap_set_promisc "pcap_t *p" "int promisc" +.Ft int +.Fn pcap_can_set_rfmon "pcap_t *p" +.Ft int +.Fn pcap_set_rfmon "pcap_t *p" "int rfmon" +.Ft int +.Fn pcap_set_timeout "pcap_t *p" "int timeout_ms" +.Ft int +.Fn pcap_set_buffer_size "pcap_t *p" "int buffer_size" +.Ft int +.Fn pcap_set_immediate_mode "pcap_t *p" "int immediate" +.Ft int +.Fn pcap_activate "pcap_t *p" +.Ft const char * +.Fn pcap_statustostr "int errnum" +.Ft int +.Fn pcap_offline_filter "const struct bpf_program *fp" "const struct pcap_pkthdr *h" "const u_char *pkt" +.Sh DESCRIPTION +.Nm +provides a high level interface to packet capture systems. +All packets +on the network, even those destined for other hosts, are accessible +through this mechanism. +.Pp +Note that +.Fa errbuf +in +.Fn pcap_open_live , +.Fn pcap_open_offline , +.Fn pcap_findalldevs , +.Fn pcap_lookupdev , +.Fn pcap_lookupnet , +.Fn pcap_getnonblock , +.Fn pcap_setnonblock , +.Fn pcap_fopen_offline , +and +.Fn pcap_create +is assumed to be able to hold at least +.Dv PCAP_ERRBUF_SIZE +chars. +.Pp +.Fn pcap_open_live +is used to obtain a packet capture descriptor to look +at packets on the network. +.Fa source +is a string that specifies the network device to open. +.Fa snaplen +specifies the maximum number of bytes to capture from one packet. +.Fa promisc +specifies if the interface is to be put into promiscuous mode. +(Note that even if this parameter is false, the interface +could well be in promiscuous mode for some other reason.) +.Fa to_ms +specifies the read timeout in milliseconds. +.Fa errbuf +is used to return error text and is only set when +.Fn pcap_open_live +fails and returns +.Dv NULL . +.Pp +.Fn pcap_open_offline +is called to open a +.Dq savefile +for reading. +.Fa fname +specifies the name of the file to open. +The file has the same format as those used by +.Xr tcpdump 8 . +.\" and +.\" .BR tcpslice(1) . +The name +.Ql - +is a synonym for +.Dv stdin . +.Fa errbuf +is used to return error text and is only set when +.Fn pcap_open_offline +fails and returns +.Dv NULL . +.Pp +.Fn pcap_dump_open +is called to open a +.Dq savefile +for writing. +The name +.Ql - +is a synonym for +.Dv stdout . +.Dv NULL +is returned on failure. +.Fa p +is a +.Fa pcap +struct as returned by +.Fn pcap_open_offline +or +.Fn pcap_open_live . +.Fa fname +specifies the name of the file to open. +If +.Dv NULL +is returned, +.Fn pcap_geterr +can be used to get the error text. +.Pp +.Fn pcap_dump_fopen +allows the use of savefile functions on the already-opened stream +.Fa f . +.Pp +.Fn pcap_lookupdev +returns a pointer to a network device suitable for use with +.Fn pcap_open_live +and +.Fn pcap_lookupnet . +If there is an error, +.Dv NULL +is returned and +.Fa errbuf +is filled in with an appropriate error message. +.Pp +.Fn pcap_lookupnet +is used to determine the network number and mask +associated with the network device +.Fa device . +Both +.Fa netp +and +.Fa maskp +are +.Fa bpf_u_int32 +pointers. +A return of \-1 indicates an error in which case +.Fa errbuf +is filled in with an appropriate error message. +.Pp +.Fn pcap_dispatch +is used to collect and process packets. +.Fa cnt +specifies the maximum number of packets to process before returning. +A +.Fa cnt +of \-1 processes all the packets received in one buffer. +A +.Fa cnt +of 0 processes all packets until an error occurs, EOF is reached, +or the read times out (when doing live reads and a non-zero +read timeout is specified). +.Fa callback +specifies a routine to be called with three arguments: a +.Fa u_char +pointer which is passed in from +.Fn pcap_dispatch , +a pointer to the +.Fa pcap_pkthdr +struct (which precedes the actual network headers and data), +and a +.Fa u_char +pointer to the packet data. +The number of packets read is returned. +Zero is returned when EOF is reached in a savefile. +A return of \-1 indicates an error in which case +.Fn pcap_perror +or +.Fn pcap_geterr +may be used to display the error text. +.Pp +.Fn pcap_dump +outputs a packet to a save file previously opened using +.Fn pcap_dump_open +or +.Fn pcap_dump_fopen . +Note that the +.Fa user +argument contains the handle to the save file and should be of type +.Vt pcap_dumper_t * . +This makes +.Fn pcap_dump +a suitable callback function for use as an argument to +.Fn pcap_dispatch . +.Pp +.Fn pcap_inject +uses +.Xr write 2 +to inject a raw packet through the network interface. +It returns the number of bytes written or \-1 on failure. +.Pp +.Fn pcap_sendpacket +is an alternate interface for packet injection (provided for compatibility). +It returns 0 on success or \-1 on failure. +.Pp +.Fn pcap_compile +is used to compile the string +.Fa buf +into a filter program. +.Fa program +is a pointer to a +.Fa bpf_program +struct and is filled in by +.Fn pcap_compile . +.Fa optimize +controls whether optimization on the resulting code is performed. +.Fa netmask +specifies the netmask of the local net. +.Pp +.Fn pcap_setfilter +is used to specify a filter program. +.Fa fp +is a pointer to an array of +.Fa bpf_program +struct, usually the result of a call to +.Fn pcap_compile . +\-1 +is returned on failure; +0 +is returned on success. +.Pp +.Fn pcap_freecode +is used to free up allocated memory pointed to by a +.Fa bpf_program +struct generated by +.Fn pcap_compile +when that BPF program is no longer needed, for example after it has +been made the filter program for a pcap structure by a call to +.Fn pcap_setfilter . +.Pp +.Fn pcap_loop +is similar to +.Fn pcap_dispatch +except it keeps reading packets until +.Fa cnt +packets are processed or an error occurs. +It does +.Em not +return when live read timeouts occur. +Rather, specifying a non-zero read timeout to +.Fn pcap_open_live +and then calling +.Fn pcap_loop +allows the reception and processing of any packets that arrive when the +timeout occurs. +A negative +.Fa cnt +causes +.Fn pcap_loop +to loop forever (or at least until an error occurs). +.Fn pcap_loop +may be terminated early through an explicit call to +.Fn pcap_breakloop . +In this case, the return value of +.Fn pcap_loop +will be \-2. +.Pp +.Fn pcap_next +returns a +.Fa u_char +pointer to the next packet. +.Pp +.Fn pcap_next_ex +reads the next packet and returns a success/failure indication: a +return value of 1 indicates success, 0 means that the timeout was exceeded +on a live capture, \-1 indicates that an error occurred whilst reading +the packet and \-2 is returned when there are no more packets to read in a +savefile. +.Pp +.Fn pcap_datalink +returns the link layer type, e.g., DLT_EN10MB. +.Pp +.Fn pcap_snapshot +returns the snapshot length specified when +.Fn pcap_open_live +was called. +.Pp +.Fn pcap_is_swapped +returns true if the current savefile +uses a different byte order than the current system. +.Pp +.Fn pcap_major_version +returns the major number of the version of the pcap used to write the savefile. +.Pp +.Fn pcap_minor_version +returns the minor number of the version of the pcap used to write the savefile. +.Pp +.Fn pcap_file +returns the stream associated with the savefile. +.Pp +.Fn pcap_stats +returns 0 and fills in a +.Fa pcap_stat +struct. +The values represent packet statistics from the start of the +run to the time of the call. +If there is an error or the underlying +packet capture doesn't support packet statistics, \-1 is returned and +the error text can be obtained with +.Fn pcap_perror +or +.Fn pcap_geterr . +.Pp +.Fn pcap_fileno +and +.Fn pcap_get_selectable_fd +return the file descriptor number of the savefile. +.Pp +.Fn pcap_perror +prints the text of the last pcap library error on +.Dv stderr , +prefixed by +.Fa prefix . +.Pp +.Fn pcap_geterr +returns the error text pertaining to the last pcap library error. +.Pp +.Fn pcap_strerror +is provided in case +.Xr strerror 3 +isn't available. +.Pp +.Fn pcap_close +closes the files associated with +.Fa p +and deallocates resources. +.Pp +.Fn pcap_dump_file +returns the stream associated with a savefile. +.Pp +.Fn pcap_dump_ftell +returns the current file offset within a savefile. +.Pp +.Fn pcap_dump_flush +ensures that any buffered data has been written to a savefile. +.Pp +.Fn pcap_dump_close +closes the savefile. +.Pp +.Fn pcap_findalldevs +constructs a linked list of network devices that are suitable for +opening with +.Fn pcap_open_live . +.Pp +.Fn pcap_freealldevs +frees a list of interfaces built by +.Fn pcap_findalldevs . +.Pp +.Fn pcap_getnonblock +returns 1 if the capture file descriptor is in non-blocking mode, 0 +if it is in blocking mode, or \-1 on error. +.Pp +.Fn pcap_setnonblock +sets or resets non-blocking mode on a capture file descriptor. +.Pp +.Fn pcap_set_datalink +sets the datalink type on a live capture device that supports multiple +datalink types. +.Pp +.Fn pcap_setdirection +is used to limit the direction that packets must be flowing in order +to be captured. +The direction is either +.Dv PCAP_D_INOUT , +.Dv PCAP_D_IN +or +.Dv PCAP_D_OUT . +Direction is only relevant to live captures. +When reading from a dump file, +.Fn pcap_setdirection +has no effect. +.Pp +.Fn pcap_list_datalinks +returns an array of the supported datalink types for an opened live capture +device as a \-1 terminated array. +It is the caller's responsibility to free this list with +.Fn pcap_free_datalinks , +which frees the list of link-layer header types pointed to by +.Dv dlt_list . +.Pp +.Fn pcap_breakloop +safely breaks out of a +.Fn pcap_loop . +This function sets an internal flag and is safe to be called from inside a +signal handler. +.Pp +.Fn pcap_open_dead +is used for creating a pcap_t structure to use when calling the +other functions in libpcap. +It is typically used when just using libpcap for compiling BPF code. +.Pp +.Fn pcap_fopen_offline +may be used to read dumped data from an existing open stream +.Fa fp . +.Pp +.Fn pcap_lib_version +returns a string describing the version of libpcap. +.Pp +.Fn pcap_datalink_val_to_name +and +.Fn pcap_datalink_val_to_description +look up the name or description of a datalink type by number. +These functions return +.Dv NULL +if the specified datalink type is not known. +.Fn pcap_datalink_name_to_val +finds the datalink number for a given datalink name. +Returns \-1 if the name is not known. +.Pp +.Fn pcap_create +is used to create a packet capture handle to look at +packets on the network. +The returned handle must be activated with +.Fn pcap_activate +before packets can be captured with it; options for the +capture, such as promiscuous mode, can be set on the handle +before activating it. +.Pp +.Fn pcap_set_snaplen +sets the snapshot length to be used on a capture handle when the +handle is activated to +.Fa snaplen . +.Pp +.Fn pcap_set_promisc +sets whether promiscuous mode should be set on a capture handle +when the handle is activated. +If +.Fa promisc +is non-zero, promiscuous mode will be set, otherwise it will not be set. +.Pp +.Fn pcap_can_set_rfmon +checks whether monitor mode could be set on a capture handle when the +handle is activated. +.Pp +.Fn pcap_set_rfmon +sets whether monitor mode should be set on a capture handle +when the handle is activated. +If +.Fa rfmon +is non-zero, monitor mode will be set, otherwise it will not be set. +.Pp +.Fn pcap_set_timeout +sets the read timeout that will be used on a capture handle when the +handle is activated to +.Fa to_ms , +which is in units of milliseconds. +.Pp +.Fn pcap_set_buffer_size +sets the buffer size that will be used on a capture handle when the +handle is activated to +.Fa buffer_size , +which is in units of bytes. +.Pp +.Fn pcap_set_immediate_mode +sets whether immediate mode should be set on a capture handle when +the handle is activated. +If +.Fa immediate +is non-zero, immediate mode will be set, otherwise it will not be set. +.Pp +.Fn pcap_activate +is used to activate a packet capture handle to look at +packets on the network, with the options that were set on the handle +being in effect. +.Pp +.Fn pcap_statustostr +converts a PCAP_ERROR_ or PCAP_WARNING_ value returned by a libpcap +routine to an error string. +.Pp +.Fn pcap_offline_filter +checks whether a filter matches a packet. +.Sh SEE ALSO +.Xr pcap-filter 5 , +.Xr tcpdump 8 +.\" , tcpslice(1) +.Sh AUTHORS +.An -nosplit +.An Van Jacobson , +.An Craig Leres , +and +.An Steven McCanne , +all of the +Lawrence Berkeley National Laboratory, University of California, Berkeley, CA. diff --git a/static/openbsd/man3/perror.3 b/static/openbsd/man3/perror.3 new file mode 100644 index 00000000..bed232d2 --- /dev/null +++ b/static/openbsd/man3/perror.3 @@ -0,0 +1,88 @@ +.\" $OpenBSD: perror.3,v 1.11 2019/05/16 13:35:16 schwarze Exp $ +.\" +.\" 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. +.\" +.Dd $Mdocdate: May 16 2019 $ +.Dt PERROR 3 +.Os +.Sh NAME +.Nm perror +.Nd write error messages to standard error +.Sh SYNOPSIS +.In stdio.h +.Ft void +.Fn perror "const char *string" +.Sh DESCRIPTION +The +.Fn perror +function looks up the error message string affiliated +with an error number and writes it, followed by a new-line, to the +standard error stream. +.Pp +If the argument +.Fa string +is not the +.Dv NULL +pointer and is not zero length, it is prepended to the message string and +separated from it by a colon and a space +.Pq Ql \&:\ \& . +Otherwise, only the error message string is printed. +.Pp +The contents of the error message string are the same as those returned by +.Fn strerror +with argument +.Fa errno . +.Sh SEE ALSO +.Xr intro 2 , +.Xr psignal 3 , +.Xr setlocale 3 , +.Xr strerror 3 +.Sh STANDARDS +The +.Fn perror +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn perror +function first appeared in +.At v4 . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_MESSAGES +.Xr locale 1 +category can cause different strings to be printed instead of the +normal error messages; see CAVEATS in +.Xr setlocale 3 +for details. diff --git a/static/openbsd/man3/pidfile.3 b/static/openbsd/man3/pidfile.3 new file mode 100644 index 00000000..a9de83ce --- /dev/null +++ b/static/openbsd/man3/pidfile.3 @@ -0,0 +1,83 @@ +.\" $OpenBSD: pidfile.3,v 1.8 2025/06/06 22:01:40 schwarze Exp $ +.\" $NetBSD: pidfile.3,v 1.2 2001/04/12 22:34:31 sommerfeld Exp $ +.\" +.\" Copyright (c) 1999 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 $Mdocdate: June 6 2025 $ +.Dt PIDFILE 3 +.Os +.Sh NAME +.Nm pidfile +.Nd write a daemon pid file +.Sh SYNOPSIS +.Lb libutil +.In util.h +.Ft int +.Fn pidfile "const char *basename" +.Sh DESCRIPTION +.Fn pidfile +writes a file containing the process ID of the program to the +.Pa /var/run +directory. +The file name has the form +.Pa /var/run/basename.pid . +If the +.Ar basename +argument is NULL, +.Nm +will determine the program name and use that instead. +.Pp +The pid file can be used as a quick reference if +the process needs to be sent a signal. +When the program exits, the pid file will be removed automatically, +unless the program receives a fatal signal. +.Sh RETURN VALUES +.Fn pidfile +returns 0 on success and -1 on failure. +.Sh SEE ALSO +.Xr atexit 3 +.Sh HISTORY +The +.Nm +function call appeared in +.Ox 3.0 . +.Sh CAVEATS +If +.Fn pidfile +is called multiple times with different +.Ar basename , +only the last pidfile will be removed upon exit. +.Pp +.Fn pidfile +uses +.Fn atexit +to ensure the pidfile is unlinked at program exit. +However, programs that use the +.Fn _exit +function (for example, in signal handlers) +will not trigger this behaviour. diff --git a/static/openbsd/man3/pkcs5_pbkdf2.3 b/static/openbsd/man3/pkcs5_pbkdf2.3 new file mode 100644 index 00000000..0f429cfc --- /dev/null +++ b/static/openbsd/man3/pkcs5_pbkdf2.3 @@ -0,0 +1,64 @@ +.\" $OpenBSD: pkcs5_pbkdf2.3,v 1.6 2025/06/06 22:01:40 schwarze Exp $ +.\" +.\" Copyright (c) 2012 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 $Mdocdate: June 6 2025 $ +.Dt PKCS5_PBKDF2 3 +.Os +.Sh NAME +.Nm pkcs5_pbkdf2 +.Nd password-based key derivation function +.Sh SYNOPSIS +.Lb libutil +.In util.h +.Ft int +.Fn pkcs5_pbkdf2 "const char *pass" "size_t pass_len" "const char *salt" \ + "size_t salt_len" "u_int8_t *key" "size_t key_len" "u_int rounds" +.Sh DESCRIPTION +The +.Nm +function converts a password into a byte array suitable for use as +an encryption key. +The password and salt values are combined and repeatedly hashed +.Ar rounds +times. +The salt value should be randomly generated beforehand. +The repeated hashing is designed to thwart discovery of the key via +password guessing attacks. +The higher the number of rounds, the slower each attempt will be. +A minimum value of at least 1000 is recommended. +.Sh RETURN VALUES +The +.Fn pkcs5_pbkdf2 +function returns 0 to indicate success and -1 for failure. +.\" .Sh EXAMPLES +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr sha1 1 , +.Xr bcrypt_pbkdf 3 +.Sh STANDARDS +.Rs +.%A B. Kaliski +.%D September 2000 +.%R RFC 2898 +.%T PKCS #5: Password-Based Cryptography Specification Version 2.0 +.Re +.\" .Sh HISTORY +.\" .Sh AUTHORS +.Sh CAVEATS +The standard allows for different hash functions to be used. +This implementation only uses +.Xr sha1 1 . +.\" .Sh BUGS diff --git a/static/openbsd/man3/popen.3 b/static/openbsd/man3/popen.3 new file mode 100644 index 00000000..7cda6a14 --- /dev/null +++ b/static/openbsd/man3/popen.3 @@ -0,0 +1,195 @@ +.\" $OpenBSD: popen.3,v 1.20 2016/02/05 18:09:20 espie 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. +.\" +.Dd $Mdocdate: February 5 2016 $ +.Dt POPEN 3 +.Os +.Sh NAME +.Nm popen , +.Nm pclose +.Nd process I/O +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn popen "const char *command" "const char *type" +.Ft int +.Fn pclose "FILE *stream" +.Sh DESCRIPTION +The +.Fn popen +function +.Dq opens +a process by creating a pipe, forking, and invoking the shell. +Since a pipe is by definition unidirectional, the +.Fa type +argument may specify only reading or writing, not both; +the resulting stream is correspondingly read-only or write-only. +.Pp +The +.Fa command +argument is a pointer to a NUL-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. +The +.Fa type +argument is a pointer to a NUL-terminated +string which must be either +.Qq r +or +.Qq re +for reading +or +.Qq w +or +.Qq we +for writing. +If the letter +.Qq e +is present in the string then the close-on-exec flag shall be set on the +file descriptor underlying the +.Vt FILE +that is returned. +.Pp +The return value from +.Fn popen +is a normal standard I/O stream in all respects +except that it must be closed with +.Fn pclose +rather than +.Xr fclose 3 . +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 +.Fn popen +output streams are fully buffered by default. +In addition, fork handlers established using +.Xr pthread_atfork 3 +are not called when a multithreaded program calls +.Fn popen . +.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 fork 2 +or +.Xr pipe 2 +calls fail, +or if it cannot allocate memory. +.Pp +The +.Fn pclose +function returns \-1 if +.Fa stream +is not associated with a +.Dq popened +command, if +.Fa stream +already +.Dq pclosed , +or if +.Xr wait4 2 +returns an error. +.Sh ERRORS +The +.Fn popen +function does not reliably set +.Va errno . +.Sh SEE ALSO +.Xr sh 1 , +.Xr fork 2 , +.Xr pipe 2 , +.Xr wait4 2 , +.Xr fclose 3 , +.Xr fflush 3 , +.Xr fopen 3 , +.Xr stdio 3 , +.Xr system 3 +.Sh HISTORY +A +.Fn popen +and a +.Fn pclose +function appeared in +.At v7 . +.Sh CAVEATS +Never supply the +.Fn popen +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. +.Pp +It is often simpler to bypass the shell entirely and use +.Xr pipe 2 , +.Xr fork 2 , +.Xr dup2 2 , +.Xr execlp 3 , +and +.Xr fdopen 3 +directly instead of having to sanitize a string for shell consumption. +.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 +.Fa command , +or an immediate exit of the command. +The only hint is an exit status of 127. diff --git a/static/openbsd/man3/posix_memalign.3 b/static/openbsd/man3/posix_memalign.3 new file mode 100644 index 00000000..fcd0a4cb --- /dev/null +++ b/static/openbsd/man3/posix_memalign.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: posix_memalign.3,v 1.4 2017/05/13 07:11:29 otto Exp $ +.\" Copyright (C) 2006 Jason Evans . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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 $Mdocdate: May 13 2017 $ +.Dt POSIX_MEMALIGN 3 +.Os +.Sh NAME +.Nm posix_memalign +.Nd aligned memory allocation +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn posix_memalign "void **ptr" "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 a multiple of +.Fa alignment , +and returns the allocation in the value pointed to by +.Fa ptr . +.Pp +The requested +.Fa alignment +must be a power of 2 at least as large as +.Fn sizeof "void *" . +.Pp +Memory that is allocated via +.Fn posix_memalign +can be used as an argument in subsequent calls to +.Xr realloc 3 , +.Xr reallocarray 3 +and +.Xr free 3 , +but not +.Xr recallocarray 3 +and +.Xr freezero 3 . +.Sh RETURN VALUES +The +.Fn posix_memalign +function returns the value 0 if successful; otherwise it returns an error value. +.Sh ERRORS +The +.Fn posix_memalign +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa alignment +parameter is not a power of 2 at least as large as +.Fn sizeof "void *" . +.It Bq Er ENOMEM +Memory allocation error. +.El +.Sh SEE ALSO +.Xr free 3 , +.Xr malloc 3 , +.Xr realloc 3 +.Sh STANDARDS +The +.Fn posix_memalign +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_memalign +function first appeared in +.Ox 4.8 . diff --git a/static/openbsd/man3/posix_openpt.3 b/static/openbsd/man3/posix_openpt.3 new file mode 100644 index 00000000..b55e1be7 --- /dev/null +++ b/static/openbsd/man3/posix_openpt.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: posix_openpt.3,v 1.4 2019/01/25 00:19:25 millert Exp $ +.\" +.\" Copyright (c) 2012 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. +.\" +.Dd $Mdocdate: January 25 2019 $ +.Dt POSIX_OPENPT 3 +.Os +.Sh NAME +.Nm posix_openpt +.Nd open a pseudo-terminal device +.Sh SYNOPSIS +.In stdlib.h +.In fcntl.h +.Ft int +.Fn posix_openpt "int oflag" +.Sh DESCRIPTION +The +.Fn posix_openpt +function finds the next available pseudo-terminal and returns an open +file descriptor for its master device. +The path name of the slave device may be determined via the +.Fn ptsname +function. +Note that the +.Fn unlockpt +and +.Fn grantpt +functions should be called before opening the slave device. +.Pp +The +.Ar oflag +argument is formed by bitwise-inclusive +.Tn OR Ns 'ing +the following values defined in +.In fcntl.h : +.Bl -tag -width O_NOCTTY -offset indent +.It Dv O_RDWR +Open for reading and writing. +.It Dv O_NOCTTY +Prevent the device from being made the controlling terminal for the session. +This flag has no effect on +.Ox +and is included for compatibility with other systems. +.El +.Pp +The +.Dv O_RDWR +flag must be specified in +.Fa oflag . +If +.Fa oflag +contains values other than those listed above, +.Fn posix_openpt +will return an error. +.Sh RETURN VALUES +If successful, +.Fn posix_openpt +returns a non-negative integer, the file descriptor for the +pseudo-terminal master device. +Otherwise, a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn posix_openpt +function will fail if: +.Bl -tag -width Er +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er EINVAL +The value of +.Fa oflag +is not valid. +.El +.Sh SEE ALSO +.Xr ptsname 3 , +.Xr pty 4 , +.Xr tty 4 +.Sh STANDARDS +The +.Fn posix_openpt +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_openpt +function appeared in +.Ox 5.3 . diff --git a/static/openbsd/man3/posix_spawn.3 b/static/openbsd/man3/posix_spawn.3 new file mode 100644 index 00000000..f386c346 --- /dev/null +++ b/static/openbsd/man3/posix_spawn.3 @@ -0,0 +1,135 @@ +.\" $OpenBSD: posix_spawn.3,v 1.11 2023/06/26 15:28:52 tb Exp $ +.\" +.\" Copyright (c) 2012 Marc Espie +.\" +.\" 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: June 26 2023 $ +.Dt POSIX_SPAWN 3 +.Os +.Sh NAME +.Nm posix_spawn , posix_spawnp +.Nd launch external command +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawn "pid_t *restrict pidp" "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 pidp" "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 +function forks a new process and starts an external program from +pathname +.Fa path . +.Pp +The +.Fn posix_spawnp +function is similar, except it constructs the pathname from +.Fa file +following the usual +.Ev PATH +handling rules: +if file contains a slash, then it is directly used as a path. +Otherwise, +.Fn posix_spawnp +searches every directory mentioned in +.Ev PATH +until it finds an executable. +If +.Ev PATH +is not set, the default is +.Dq /usr/bin:/bin . +.Pp +Arguments to the new process are passed to +.Xr execve 2 +as +.Fa argv +and +.Fa envp . +If +.Fa envp +is NULL, the environment is passed unchanged from the parent process. +.Pp +If +.Fa file_actions +is a null pointer, file descriptors open in the parent process +follow the usual rules: they remain open in the child process unless they've +been marked +.Dv FD_CLOEXEC +with +.Xr fcntl 2 . +.Pp +Otherwise, file descriptors in the child process +are altered according to +.Xr posix_spawn_file_actions_init 3 , +.Xr posix_spawn_file_actions_addclose 3 , +.Xr posix_spawn_file_actions_adddup2 3 , +and +.Xr posix_spawn_file_actions_addopen 3 . +.Pp +The +.Fa attrp +argument can be used to control signal, UID and GID handling in the +child process. +.Pp +If +.Fa attrp +is NULL, default values are used: caught signals in the parent +process are set to the default value in the child process, and ignored signals +stay ignored. +.Pp +See +.Xr posix_spawnattr_setflags 3 +for attribute details. +.Sh RETURN VALUES +Upon successful completion, both functions return 0. +If +.Fa pidp +is not a NULL pointer, +.Li *pidp +gets set to the PID of the newly created child process. +.Pp +In case of an error, both functions may return +.Fn fork +or +.Fn exec +return values and set +.Va errno +accordingly. +.Pp +Note, however, that after the new process is started, the child +process has no way to return an error value. +In case of a problem, the child process will instead exit +with exit status 127. +.Sh SEE ALSO +.Xr execve 2 , +.Xr fork 2 , +.Xr posix_spawn_file_actions_addclose 3 , +.Xr posix_spawn_file_actions_init 3 , +.Xr posix_spawnattr_init 3 , +.Xr posix_spawnattr_setflags 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2001 . +.Pp +The handling of NULL +.Fa envp +is an extension to that standard. +.Sh HISTORY +These functions were ported from +.Fx +to +.Ox 5.2 . +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/openbsd/man3/posix_spawn_file_actions_addopen.3 b/static/openbsd/man3/posix_spawn_file_actions_addopen.3 new file mode 100644 index 00000000..7cfb7ef3 --- /dev/null +++ b/static/openbsd/man3/posix_spawn_file_actions_addopen.3 @@ -0,0 +1,106 @@ +.\" $OpenBSD: posix_spawn_file_actions_addopen.3,v 1.9 2022/03/29 18:15:52 naddy Exp $ +.\" +.\" Copyright (c) 2012 Marc Espie +.\" +.\" 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: March 29 2022 $ +.Dt POSIX_SPAWN_FILE_ACTIONS_ADDOPEN 3 +.Os +.Sh NAME +.Nm posix_spawn_file_actions_addclose , +.Nm posix_spawn_file_actions_adddup2 , +.Nm posix_spawn_file_actions_addopen +.Nd add action to close, dup2 or open file descriptor to file actions object +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawn_file_actions_addclose "posix_spawn_file_actions_t *file_actions" "int fildes" +.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_addopen "posix_spawn_file_actions_t *file_actions" "int fildes" "const char *restrict path" "int oflag" "mode_t mode" +.Sh DESCRIPTION +These function add an action to +.Xr close 2 , +.Xr dup2 2 , +or +.Xr open 2 +a file descriptor +to a +.Xr posix_spawn 3 +file actions object. +.Pp +Actions are executed in order in the child process: +.Bl -dash +.It +The +.Fn posix_spawn_file_actions_addclose +function adds an action that causes +.Bd -literal -offset indent +close(fildes); +.Ed +.Pp +to be called. +.It +The +.Fn posix_spawn_file_actions_adddup2 +function adds an action that causes +.Bd -literal -offset indent +dup2(fildes, newfildes); +.Ed +.Pp +to be called. +In addition, the action will cause the close-on-exec flag to be cleared on +.Fa newfildes , +even if +.Fa newfildes +equals +.Fa fildes . +.It +The +.Fn posix_spawn_file_actions_addopen +function adds an action that causes +.Bd -literal -offset indent +open(path, oflag, mode); +.Ed +.Pp +to be called and the result to be forced as +.Fa fildes +(if +.Fa fildes +was already open before this action, the old file descriptor +is closed before the action is performed). +.Pp +Note that +.Fn posix_spawn_file_actions_addopen +makes a copy of the +.Fa path +argument. +.El +.Sh RETURN VALUES +Upon successful completion, these functions return zero. +Otherwise they may return +.Er EINVAL +for negative file descriptors, or +.Er ENOMEM +if they run out of memory. +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawn_file_actions_init 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/openbsd/man3/posix_spawn_file_actions_init.3 b/static/openbsd/man3/posix_spawn_file_actions_init.3 new file mode 100644 index 00000000..ba055bfe --- /dev/null +++ b/static/openbsd/man3/posix_spawn_file_actions_init.3 @@ -0,0 +1,57 @@ +.\" $OpenBSD: posix_spawn_file_actions_init.3,v 1.8 2014/11/30 02:41:43 schwarze Exp $ +.\" +.\" Copyright (c) 2012 Marc Espie +.\" +.\" 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: November 30 2014 $ +.Dt POSIX_SPAWN_FILE_ACTIONS_INIT 3 +.Os +.Sh NAME +.Nm posix_spawn_file_actions_init , +.Nm posix_spawn_file_actions_destroy +.Nd create and destroy posix_spawn file actions objects +.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 +File actions objects can be initialized by +.Fn posix_spawn_file_actions_init +and destroyed by +.Fn posix_spawn_file_actions_destroy . +.Pp +Multiple initialization of the same object is undefined behavior +and will lead to memory leaks. +.Pp +Similarly, objects should be passed to +.Fn posix_spawn_file_actions_destroy +to reclaim memory. +The object should not be re-used after destruction. +It can however be initialized again with +.Fn posix_spawn_file_actions_init . +.Sh RETURN VALUES +These function return 0 on successful completion. +They may return +.Er ENOMEM +when running out of memory. +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawn_file_actions_addopen 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2001 . +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/openbsd/man3/posix_spawnattr_getflags.3 b/static/openbsd/man3/posix_spawnattr_getflags.3 new file mode 100644 index 00000000..a3f509f7 --- /dev/null +++ b/static/openbsd/man3/posix_spawnattr_getflags.3 @@ -0,0 +1,98 @@ +.\" $OpenBSD: posix_spawnattr_getflags.3,v 1.10 2023/02/22 06:31:51 guenther Exp $ +.\" +.\" Copyright (c) 2012 Marc Espie +.\" +.\" 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: February 22 2023 $ +.Dt POSIX_SPAWNATTR_GETFLAGS 3 +.Os +.Sh NAME +.Nm posix_spawnattr_getflags , +.Nm posix_spawnattr_setflags +.Nd get or set flags of a posix_spawn attributes object +.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 +and +.Fn posix_spawnattr_setflags +functions are used to get or set the flags part of a +.Xr posix_spawn 3 +attribute object referenced by +.Fa attr . +.Pp +Flag values are OR-ed from the following flags: +.Bl -tag -width POSIX_SPAWN +.It Dv POSIX_SPAWN_RESETIDS +Reset the effective user and group ID of the child process to the parent's +real user and group ID; +see +.Xr setegid 2 . +.Pp +If the new process is created from a set-user-ID or set-group-ID file, usual +.Xr execve 2 +semantics take precedence. +.It Dv POSIX_SPAWN_SETPGROUP +Set the process group of the child process according to the pgroup attribute +of the object; see +.Xr posix_spawnattr_getpgroup 3 +and +.Xr setpgid 2 . +.It Dv POSIX_SPAWN_SETSIGDEF +Reset signals set by +.Xr posix_spawnattr_setsigdefault 3 +to their default value in the child process. +.It Dv POSIX_SPAWN_SETSIGMASK +Set the signal mask of the child process according +to the value set by +.Xr posix_spawnattr_setsigmask 3 , +using +.Xr sigprocmask 2 . +.It Dv POSIX_SPAWN_SETSCHEDPARAM +Set the scheduling parameter of the child process +according to the value set by +.Xr posix_spawnattr_setschedparam 3 +.Po +mandated by +.St -p1003.1-2001 , +this implementation currently does nothing +.Pc . +.It Dv POSIX_SPAWN_SETSCHEDULER +Set the scheduler policy of the child process +according to the value set by +.Xr posix_spawnattr_setschedpolicy 3 +.Po +mandated by +.St -p1003.1-2001 , +this implementation currently does nothing +.Pc . +.El +.Pp +.Xr posix_spawnattr_init 3 +initializes this value to no flags set. +.Sh RETURN VALUES +Both functions return 0. +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawnattr_init 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2001 . +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/openbsd/man3/posix_spawnattr_getpgroup.3 b/static/openbsd/man3/posix_spawnattr_getpgroup.3 new file mode 100644 index 00000000..10e80795 --- /dev/null +++ b/static/openbsd/man3/posix_spawnattr_getpgroup.3 @@ -0,0 +1,80 @@ +.\" $OpenBSD: posix_spawnattr_getpgroup.3,v 1.10 2023/02/22 06:31:51 guenther Exp $ +.\" +.\" Copyright (c) 2012 Marc Espie +.\" +.\" 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: February 22 2023 $ +.Dt POSIX_SPAWNATTR_GETPGROUP 3 +.Os +.Sh NAME +.Nm posix_spawnattr_getpgroup , +.Nm posix_spawnattr_getschedparam , +.Nm posix_spawnattr_getschedpolicy , +.Nm posix_spawnattr_getsigdefault , +.Nm posix_spawnattr_getsigmask , +.Nm posix_spawnattr_setpgroup , +.Nm posix_spawnattr_setschedparam , +.Nm posix_spawnattr_setschedpolicy , +.Nm posix_spawnattr_setsigdefault , +.Nm posix_spawnattr_setsigmask +.Nd get or set misc attributes of a posix_spawn attributes object +.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_getschedparam "const posix_spawnattr_t *restrict attr" "struct sched_param *restrict schedparam" +.Ft int +.Fn posix_spawnattr_getschedpolicy "const posix_spawnattr_t *restrict attr" "int *restrict schedpolicy" +.Ft int +.Fn posix_spawnattr_getsigdefault "const posix_spawnattr_t *restrict attr" "sigset_t *restrict sigdefault" +.Ft int +.Fn posix_spawnattr_getsigmask "const posix_spawnattr_t *restrict attr" "sigset_t *restrict sigmask" +.Ft int +.Fn posix_spawnattr_setpgroup "posix_spawnattr_t *attr" "pid_t pgroup" +.Ft int +.Fn posix_spawnattr_setschedparam "posix_spawnattr_t *attr" "const struct sched_param *restrict schedparam" +.Ft int +.Fn posix_spawnattr_setschedpolicy "posix_spawnattr_t *attr" "int schedpolicy" +.Ft int +.Fn posix_spawnattr_setsigdefault "posix_spawnattr_t *attr" "const sigset_t *restrict sigdefault" +.Ft int +.Fn posix_spawnattr_setsigmask "posix_spawnattr_t *attr" "const sigset_t *restrict sigmask" +.Sh DESCRIPTION +The +.Fn posix_spawnattr_get* +functions obtain the value of the corresponding attribute from the +attributes object referenced by +.Fa attr . +.Pp +The +.Fn posix_spawnattr_set* +functions set the value of the corresponding attribute in the +attributes object referenced by +.Fa attr . +.Pp +See +.Xr posix_spawnattr_getflags 3 +for attribute details. +.Sh RETURN VALUES +Those functions return 0. +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawnattr_init 3 , +.Xr sigaddset 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/openbsd/man3/posix_spawnattr_init.3 b/static/openbsd/man3/posix_spawnattr_init.3 new file mode 100644 index 00000000..4071d711 --- /dev/null +++ b/static/openbsd/man3/posix_spawnattr_init.3 @@ -0,0 +1,75 @@ +.\" $OpenBSD: posix_spawnattr_init.3,v 1.8 2014/11/30 02:41:43 schwarze Exp $ +.\" +.\" Copyright (c) 2012 Marc Espie +.\" +.\" 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: November 30 2014 $ +.Dt POSIX_SPAWNATTR_INIT 3 +.Os +.Sh NAME +.Nm posix_spawnattr_init , +.Nm posix_spawnattr_destroy +.Nd create and destroy posix_spawn attributes object +.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 +.Xr posix_spawn 3 +attributes objects can be initialized by +.Fn posix_spawnattr_init +and destroyed by +.Fn posix_spawnattr_destroy . +.Pp +Initialization fills an attributes object pointed by +.Fa attr +with the default values for all the attributes. +.Pp +Multiple initialization of the same object is undefined behavior +and will lead to memory leaks. +.Pp +Similarly, objects should be passed to +.Fn posix_spawnattr_destroy +to reclaim memory. +The object should not be re-used after destruction. +It can however be initialized again with +.Fn posix_spawnattr_init . +.Pp +An attributes object, possibly modified by +.Fn posix_spawn_set* , +is used to specify what process attributes +will be passed across a spawn operation as implemented by +.Fn posix_spawn +or +.Fn posix_spawnp . +.Pp +Attribute details are described in +.Xr posix_spawnattr_setflags 3 . +.Pp +Modifying or destroying attributes object +will not affect processes that have already been spawned. +.Sh RETURN VALUES +These function return 0 on successful completion. +They may return +.Er ENOMEM +when running out of memory. +.Sh SEE ALSO +.Xr posix_spawn 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2001 . +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/openbsd/man3/printf.3 b/static/openbsd/man3/printf.3 new file mode 100644 index 00000000..7984acbc --- /dev/null +++ b/static/openbsd/man3/printf.3 @@ -0,0 +1,1033 @@ +.\" $OpenBSD: printf.3,v 1.94 2024/08/07 05:15:28 guenther 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 $Mdocdate: August 7 2024 $ +.Dt PRINTF 3 +.Os +.Sh NAME +.Nm printf , +.Nm fprintf , +.Nm sprintf , +.Nm snprintf , +.Nm asprintf , +.Nm dprintf , +.Nm vprintf , +.Nm vfprintf , +.Nm vsprintf , +.Nm vsnprintf , +.Nm vasprintf , +.Nm vdprintf +.Nd formatted output conversion +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn printf "const char * restrict format" ... +.Ft int +.Fn fprintf "FILE *stream" "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 asprintf "char ** restrict ret" "const char * restrict format" ... +.Ft int +.Fn dprintf "int fd" "const char * restrict format" ... +.In stdarg.h +.In stdio.h +.Ft int +.Fn vprintf "const char * restrict format" "va_list ap" +.Ft int +.Fn vfprintf "FILE *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 vsnprintf "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" +.Ft int +.Fn vdprintf "int fd" "const char * restrict format" "va_list ap" +.Sh DESCRIPTION +The +.Fn printf +family of functions produce output according to the given +.Fa format +as described below. +This format may contain +.Dq conversion specifiers ; +the results of such conversions, if any, depend on the arguments +following the +.Fa format +string. +.Pp +The +.Fn printf +and +.Fn vprintf +functions write output to the standard output stream, +.Em stdout ; +.Fn fprintf +and +.Fn vfprintf +write output to the supplied stream pointer +.Fa stream ; +.Fn dprintf +and +.Fn vdprintf +write output to the given file descriptor; +.Fn sprintf , +.Fn snprintf , +.Fn vsprintf , +and +.Fn vsnprintf +write to the character string +.Fa str ; +.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 va_start 3 ) +are converted for output. +.Pp +.Fn snprintf +and +.Fn vsnprintf +write at most +.Fa size Ns \-1 +characters to +.Fa str , +followed by a terminating +.Ql \e0 . +If +.Fa size +is zero, +no characters are written and +.Fa str +may be a +.Dv NULL +pointer. +.Pp +.Fn sprintf +and +.Fn vsprintf +effectively assume an infinite +.Fa size ; +their use is not recommended. +.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. +The arguments must correspond properly (after type promotion) +with the conversion specifiers. +.Pp +The overall syntax of a conversion specification is: +.Bd -filled -offset indent +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Ar flags +.Op Ar width +.Op . Ar precision +.Op Ar size +.Ar conversion +.Sm on +.Ed +.Pp +Not all combinations of these parts are meaningful; +see the description of the individual +.Ar conversion +specifiers for details. +.Pp +The parts of a conversion specification are as follows: +.Bl -tag -width Ds +.It Cm % +A literal percent character begins a conversion specification. +.It Ar argno Ns Cm $ +An unsigned decimal digit string followed by a dollar character +specifies the index of the next argument to access. +By default, the argument following the last argument accessed is used. +Arguments are numbered starting at 1. +.It Ar flags +Zero or more of the following flag characters can be given: +.Bl -tag -width 11n +.It Cm # Pq hash +Use an alternate form for the output. +The effect differs depending on the conversion specifier. +.It So \~ Sc Pq space +For signed conversions, print a space character before a positive number. +.It Cm + Pq plus +For signed conversions, always print a sign before the number, +even if it is positive. +This overrides the space flag if both are specified. +.It Cm 0 Pq zero +Pad numbers with leading zeros instead of space characters +to fill the field +.Ar width . +This flag is ignored if the +.Ar precision +modifier is also given, which in this case specifies +.Ar mindigits . +.It Cm \- Pq minus +Left adjust: pad to the field +.Ar width +with space characters on the right rather than on the left. +This overrides the +.Sq Cm 0 +flag if both are specified. +.El +.It Ar width +An unsigned decimal digit string specifies a minimum field width in bytes. +Unless the +.Sq Cm 0 +or +.Sq Cm \- +flag is given, the value is right adjusted in the field and +padded with space characters on the left. +By default, no padding is added. +In no case does a non-existent or small field +.Ar width +cause truncation of a field; if the result of a conversion is wider +than the field width, the field is expanded to contain the conversion +result. +.It Pf . Ar precision +The meaning of an unsigned decimal digit string prefixed with a +period character depends on the conversion specifier: +it provides the minimum number of digits for integer conversions, +of decimals for some floating point conversions and of significant +digits for others, or the maximum number of bytes to print for +string conversions. +.Pp +A field +.Ar width +or +.Ar precision , +or both, may alternatively be indicated as +.Cm * Ns Op Ar argno Ns Cm $ , +i.e. as an asterisk optionally followed +by an unsigned decimal digit string and a dollar sign. +In this case, an additional +.Vt int +argument supplies the field width or precision. +If a single conversion specification tries to use arguments +both with and without +.Ar argno Ns Cm $ +modifiers, the result is undefined. +.It Ar size +An argument size modifier. +The syntax, the precise meaning, and the default size of the argument +depend on the following +.Ar conversion +character. +.It Ar conversion +Each conversion specification ends with a conversion specifier, +which is a single letter determining which argument type is expected +and how it is formatted. +.El +.Pp +The conversion specifiers are: +.Bl -tag -width Ds +.It Cm %a +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm # +.Op Cm \~ | + +.Op Cm \- | 0 +.Op Ar width +.Op . Ar hexadecimals +.Op Cm L | l +.Cm a +.Sm on +.Pp +The +.Vt double +argument is converted to the hexadecimal notation +.Sm off +.Oo \- Oc Sy 0x No h.hhh Sy p No \(+-d +.Sm on +with one digit before the hexadecimal point. +If specified, the number is rounded to +.Ar hexadecimals +after the hexadecimal point; otherwise, +enough digits are printed to represent it exactly. +The hexadecimal point is only printed if at least one digit follows it +or if the +.Sq Cm # +flag is given. +.Pp +The exponent is expressed in base 2, not in base 16. +Consequently, there are multiple ways to represent a number in this format. +For example, 0x3.24p+0, 0x6.48p-1, and 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 +mantissa is minimized. +Zeroes are always represented with a mantissa of +.Ql 0 +(preceded by a sign if appropriate) and an exponent of +.Ql +0 . +.Pp +If the argument is infinity, it is converted to +.Ql [-]inf . +If the argument is not-a-number (NaN), it is converted to +.Ql [-]nan . +.Pp +.Cm %La +is similar to +.Cm %a +except that it takes an argument of +.Vt long double . +.Cm %la Pq ell a +is an alias for +.Cm %a . +.It Cm \&%A +Identical to +.Cm %a +except that upper case is used, i.e.\& +.Ql 0X +for the prefix, +.Ql 0123456789ABCDEF +for the digits, +.Ql P +to introduce the exponent, +and +.Ql [-]INF +and +.Ql [-]NAN +for infinity and not-a-number, respectively. +.It Cm %c +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm \- +.Op Ar width +.Cm c +.Sm on +.Pp +The +.Vt int +argument is converted to an +.Vt unsigned char , +and the resulting single-byte character is written, with optional padding. +.It Cm %lc +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm \- +.Op Ar width +.Cm lc +.Sm on +.Pp +The +.Vt wint_t +argument is converted to a multibyte character according to the current +.Dv LC_CTYPE +.Xr locale 1 , +and that character is written. +For example, under a UTF-8 locale on +.Ox , +.Ql printf("%lc", 0x03c0) +writes the greek letter pi, whereas the same call fails +under the default POSIX locale. +Padding assures at least +.Ar width +bytes are printed; the number of characters printed may be smaller, +and the number of display columns occupied may be smaller or larger. +.It Cm %d +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm \~ | + +.Op Cm \- | 0 +.Op Ar width +.Op . Ar mindigits +.Op Ar size +.Cm d +.Sm on +.Pp +The +.Vt int +argument is converted to signed decimal notation. +If specified, at least +.Ar mindigits +are printed, padding with leading zeros if needed. +The following are similar to +.Cm %d +except that they take an argument of a different size: +.Bl -column %hhd +.It Cm %hhd Ta Vt signed char +.It Cm %hd Ta Vt signed short +.It Cm %d Ta Vt signed int +.It Cm %ld Ta Vt signed long Pq percent ell dee +.It Cm %lld Ta Vt signed long long Pq percent ell ell dee +.It Cm %jd Ta Vt intmax_t +.It Cm %td Ta Vt ptrdiff_t +.It Cm %zd Ta Vt ssize_t +.It Cm %qd Ta Vt quad_t Pq deprecated +.El +.It Cm \&%D +A deprecated alias for +.Cm %ld . +.It Cm %e +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm # +.Op Cm \~ | + +.Op Cm \- | 0 +.Op Ar width +.Op . Ar decimals +.Op Cm L | l +.Cm e +.Sm on +.Pp +The +.Vt double +argument is rounded and converted to the scientific notation +.Pf [\-]d.dddddd Sy e Ns \(+-dd +with one digit before the decimal point and +.Ar decimals , +or six digits by default, after it. +If +.Ar decimals +is zero and the +.Sq Cm # +flag is not given, the decimal point is omitted. +The exponent always contains at least two digits; if the value is zero, +the exponent is +.Ql +00 . +If the argument is infinity, it is converted to +.Ql [-]inf . +If the argument is not-a-number (NaN), it is converted to +.Ql [-]nan . +.Pp +.Cm %Le +is similar to +.Cm %e +except that it takes an argument of +.Vt long double . +.Cm %le Pq ell e +is an alias for +.Cm %e . +.It Cm \&%E +Identical to +.Cm %e +except that upper case is used, i.e.\& +.Ql E +instead of +.Ql e +to introduce the exponent and +.Ql [-]INF +and +.Ql [-]NAN +for infinity and not-a-number, respectively. +.It Cm %f +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm # +.Op Cm \~ | + +.Op Cm \- | 0 +.Op Ar width +.Op . Ar decimals +.Op Cm L | l +.Cm f +.Sm on +.Pp +The +.Vt double +argument is rounded and converted to the decimal notation [\-]ddd.dddddd with +.Ar decimals , +or six digits by default, after the decimal point. +If +.Ar decimals +is zero and the +.Sq Cm # +flag is not given, the decimal point is omitted. +If a decimal point appears, at least one digit appears before it. +If the argument is infinity, it is converted to +.Ql [-]inf . +If the argument is not-a-number (NaN), it is converted to +.Ql [-]nan . +.Pp +.Cm %Lf +is similar to +.Cm %f +except that it takes an argument of +.Vt long double . +.Cm %lf Pq ell eff +is an alias for +.Cm %f . +.It Cm \&%F +Identical to +.Cm %f +except that upper case is used, i.e.\& +.Ql [-]INF +and +.Ql [-]NAN +for infinity and not-a-number, respectively. +.It Cm %g +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm # +.Op Cm \~ | + +.Op Cm \- | 0 +.Op Ar width +.Op . Ar significant +.Op Cm L | l +.Cm g +.Sm on +.Pp +The +.Vt double +argument is converted in style +.Cm %f +or +.Cm %e +.Pq general floating point notation +with +.Ar significant +digits, or six significant digits by default. +If +.Ar significant +is zero, one is used instead. +Style +.Cm %e +is used if the exponent from its conversion is less than \-4 +or greater than or equal to +.Ar significant . +Unless the +.Sq Cm # +flag is given, trailing zeros are removed from the fractional +part of the result, and the decimal point only appears if it is +followed by at least one digit. +.Pp +.Cm %Lg +is similar to +.Cm %g +except that it takes an argument of +.Vt long double . +.Cm %lg Pq ell gee +is an alias for +.Cm %g . +.It Cm \&%G +Identical to +.Cm %g +except that upper case is used, i.e.\& +.Ql E +instead of +.Ql e +to introduce the exponent and +.Ql [-]INF +and +.Ql [-]NAN +for infinity and not-a-number, respectively. +.It Cm %i +An alias for +.Cm %d , +supporting the same modifiers. +.It Cm %n +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Ar size +.Cm n +.Sm on +.Pp +The +.Cm %n +conversion specifier has serious security implications, so it was changed to +no longer store the number of bytes written so far into the variable indicated +by the pointer argument. +Instead a +.Xr syslog 3 +message will be generated, after which the program is aborted with +.Dv SIGABRT . +.It Cm %o +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm # +.Op Cm \- | 0 +.Op Ar width +.Op . Ar mindigits +.Op Ar size +.Cm o +.Sm on +.Pp +Similar to +.Cm %u +except that the +.Vt unsigned int +argument is converted to unsigned octal notation. +If the +.Sq Cm # +flag is given, +.Ar mindigits +is increased such that the first digit printed is a zero, +except if a zero value is printed with an explicit +.Ar mindigits +of zero. +.It Cm \&%O +A deprecated alias for +.Cm %lo . +.It Cm %p +The +.Vt void * +pointer argument is printed in hexadecimal, similar to +.Cm %#x +or +.Cm %#lx +depending on the size of pointers. +.It Cm %s +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm \- +.Op Ar width +.Op . Ar maxbytes +.Cm s +.Sm on +.Pp +Characters from the +.Vt char * Pq string +argument are written up to (but not including) a terminating NUL character. +If +.Ar maxbytes +is specified, at most +.Ar maxbytes +bytes are written; in that case, no NUL character needs to be present. +.It Cm %ls +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm \- +.Op Ar width +.Op . Ar maxbytes +.Cm ls +.Sm on +.Pp +The +.Vt wchar_t * Pq wide character string +argument is converted to a multibyte character string +according to the current +.Dv LC_CTYPE +.Xr locale 1 +up to (but not including) a terminating NUL character, +and that multibyte character string is written. +If +.Ar maxbytes +is specified, at most +.Ar maxbytes +bytes are written; in that case, no NUL character needs to be present. +If a multibyte character does not fit into the rest of +.Ar maxbytes , +it is omitted together with the rest of the argument string; +partial characters are not written. +Locale dependency and padding work in the same way as for +.Cm %lc . +.It Cm %u +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm \- | 0 +.Op Ar width +.Op . Ar mindigits +.Op Ar size +.Cm u +.Sm on +.Pp +The +.Vt unsigned int +argument is converted to unsigned decimal notation. +If specified, at least +.Ar mindigits +are printed, padding with leading zeros if needed. +The following are similar to +.Cm %u +except that they take an argument of a different size: +.Bl -column %hhu +.It Cm %hhu Ta Vt unsigned char +.It Cm %hu Ta Vt unsigned short +.It Cm %u Ta Vt unsigned int +.It Cm %lu Ta Vt unsigned long Pq percent ell u +.It Cm %llu Ta Vt unsigned long long Pq percent ell ell u +.It Cm %ju Ta Vt uintmax_t +.It Cm %tu Ta unsigned type of same size as Vt ptrdiff_t +.It Cm %zu Ta Vt size_t +.It Cm %qu Ta Vt u_quad_t Pq deprecated +.El +.It Cm \&%U +A deprecated alias for +.Cm %lu . +.It Cm %x +.Sm off +.Cm % +.Op Ar argno Cm $ +.Op Cm # +.Op Cm \- | 0 +.Op Ar width +.Op . Ar mindigits +.Op Ar size +.Cm x +.Sm on +.Pp +Similar to +.Cm %u +except that the +.Vt unsigned int +argument is converted to unsigned hexadecimal notation using the digits +.Ql 0123456789abcdef . +If the +.Sq Cm # +flag is given, the string +.Ql 0x +is prepended unless the value is zero. +.It Cm \&%X +Identical to +.Cm %x +except that upper case is used, i.e.\& +.Ql 0X +for the optional prefix and +.Ql 0123456789ABCDEF +for the digits. +.It Cm %% +A single percent sign +.Pq Ql % +is written. +No argument is converted. +The complete conversion specification is +.Ql %% ; +no modifiers can be inserted between the two percent signs. +.El +.Sh RETURN VALUES +For all these functions if an output or encoding error occurs, a value +less than 0 is returned. +.Pp +The +.Fn printf , +.Fn dprintf , +.Fn fprintf , +.Fn sprintf , +.Fn vprintf , +.Fn vdprintf , +.Fn vfprintf , +.Fn vsprintf , +.Fn asprintf , +and +.Fn vasprintf +functions +return the number of bytes printed +(not including the trailing +.Ql \e0 +used to end output to strings). +.Pp +The +.Fn snprintf +and +.Fn vsnprintf +functions return the number of bytes that would have +been output if the +.Fa size +were unlimited +.Po +again, not including the final +.Ql \e0 +.Pc . +A return value greater than or equal to the +.Fa size +argument indicates that the string was too small and some characters +were discarded. +.Pp +The +.Fn asprintf +and +.Fn vasprintf +functions return the number of bytes that were output +to the newly allocated string +(excluding the final +.Ql \e0 ) . +A pointer to the newly allocated string is returned in +.Fa ret ; +it should be passed to +.Xr free 3 +to release the allocated storage +when it is no longer needed. +If sufficient space cannot be allocated or some other error occurs, +these functions return \-1. +The value of +.Fa ret +in this situation is implementation-dependent. +On +.Ox , +.Fa ret +is set to the +.Dv NULL +pointer, but other implementations may leave +.Fa ret +unchanged. +.Sh ENVIRONMENT +.Bl -tag -width LC_CTYPE +.It Ev LC_CTYPE +The character encoding +.Xr locale 1 . +It decides which +.Vt wchar_t +values represent valid wide characters for the +.Cm %lc +and +.Cm %ls +conversion specifiers and how they are encoded into multibyte characters. +If unset or set to +.Qq C , +.Qq POSIX , +or an unsupported value, +.Cm %lc +and +.Cm %ls +only work correctly for ASCII characters +and fail for arguments greater than 255. +.El +.Sh EXAMPLES +To print a date and time in the form `Sunday, July 3, 10:02', +where +.Va weekday +and +.Va month +are pointers to strings: +.Bd -literal -offset indent +#include + +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 +#include + +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 +#include +#include + +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 return value would be too large to be represented by an +.Vt int . +.El +.Sh SEE ALSO +.Xr printf 1 , +.Xr scanf 3 , +.Xr wprintf 3 +.Sh STANDARDS +The +.Fn fprintf , +.Fn printf , +.Fn snprintf , +.Fn sprintf , +.Fn vfprintf , +.Fn vprintf , +.Fn vsnprintf , +and +.Fn vsprintf +functions conform to +.St -isoC-99 . +The +.Fn dprintf , +.Fn vdprintf , +.Fn asprintf , +and +.Fn vasprintf +functions conform to +.St -p1003.1-2024 . +.Sh HISTORY +The predecessors +.Fn ftoa +and +.Fn itoa +first appeared in +.At v1 . +The function +.Fn printf +first appeared in +.At v2 , +and +.Fn fprintf +and +.Fn sprintf +in +.At v7 . +.Pp +The functions +.Fn snprintf +and +.Fn vsnprintf +first appeared in +.Bx 4.3 Net/2 . +.Pp +The functions +.Fn asprintf +and +.Fn vasprintf +first appeared in the GNU C library. +This implementation first appeared in +.Ox 2.3 . +.Pp +The functions +.Fn dprintf +and +.Fn vdprintf +first appeared in +.Ox 5.3 . +.Sh CAVEATS +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 +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 asprintf +interface is not available on all systems as it is not part of +.St -isoC-99 . +.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 the stack, +leading to a possible security hole. +This holds true even if the string has been built +.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 +int ret = snprintf(buffer, sizeof(buffer), "%s", string); +if (ret < 0 || (size_t)ret >= sizeof(buffer)) + goto toolong; +.Ed +.Pp +There is no way for +.Fn printf +to know the size of each argument passed. +If positional arguments are used, care must be taken to 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 the code is non-portable and liable to fail. +.Pp +On systems other than +.Ox , +the +.Dv LC_NUMERIC +.Xr locale 1 +category can cause erratic output; see CAVEATS in +.Xr setlocale 3 +for details. diff --git a/static/openbsd/man3/psignal.3 b/static/openbsd/man3/psignal.3 new file mode 100644 index 00000000..64dd573f --- /dev/null +++ b/static/openbsd/man3/psignal.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: psignal.3,v 1.15 2026/03/23 21:33:43 daniel 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 $Mdocdate: March 23 2026 $ +.Dt PSIGNAL 3 +.Os +.Sh NAME +.Nm psignal , +.Nm sys_siglist , +.Nm sys_signame +.Nd system signal messages +.Sh SYNOPSIS +.In signal.h +.Ft void +.Fn psignal "int sig" "const char *s" +.Vt extern char *sys_siglist[]; +.Vt extern char *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 not +.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 +(see +.Xr sigaction 2 +for a list), +the string +.Dq Unknown signal +is produced. +.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 value +.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 . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_MESSAGES +.Xr locale 1 +category can cause different strings to be printed instead of the +normal signal descriptions; see CAVEATS in +.Xr setlocale 3 +for details. diff --git a/static/openbsd/man3/pthread_atfork.3 b/static/openbsd/man3/pthread_atfork.3 new file mode 100644 index 00000000..a3394c5e --- /dev/null +++ b/static/openbsd/man3/pthread_atfork.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: pthread_atfork.3,v 1.13 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" David Leonard , 1999. Public domain. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_ATFORK 3 +.Os +.Sh NAME +.Nm pthread_atfork +.Nd specify handler functions to call when the process forks +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_atfork "void (*prepare)(void)" "void (*parent)(void)" "void (*child)(void)" +.Sh DESCRIPTION +The +.Fn pthread_atfork +function declares fork handlers to be called before and after +.Xr fork 2 , +in the context of the thread that called +.Xr fork 2 . +The +.Fa prepare +fork handler will be called before +.Xr fork 2 +processing commences. +The +.Fa parent +fork handler will be called after +.Xr fork 2 +processing completes in the parent process. +The +.Fa child +fork handler will be called after +.Xr fork 2 +processing completes in the child process. +If no handling is desired at +one or more of these three points, +the corresponding fork handler +address(es) may be set to +.Dv NULL . +.Pp +The order of calls to +.Fn pthread_atfork +is significant. +The +.Fa parent +and +.Fa child +fork handlers will be called in the order in which they were established +by calls to +.Fn pthread_atfork . +The +.Fa prepare +fork handlers will be called in the opposite order. +.Pp +If a shared object is unloaded from process memory using +.Xr dlclose 3 , +then any functions registered by calling +.Fn pthread_atfork +from that shared object will be unregistered without being invoked. +Note that it is the source of the call to +.Fn pthread_atfork +that matters, not the source of the functions that were registered. +.Sh RETURN VALUES +Upon successful completion, +.Fn pthread_atfork +will return a value of zero. +Otherwise, an error number will be +returned to indicate the error. +.Sh ERRORS +.Fn pthread_atfork +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient table space exists to record the fork handler addresses. +None of the handler lists are modified. +.El +.Sh SEE ALSO +.Xr fork 2 , +.Xr atexit 3 , +.Xr dlclose 3 +.Sh STANDARDS +.Fn pthread_atfork +conforms to +.St -p1003.1-2004 . +.Pp +The behavior when a shared object is unloaded is an extension to +that standard. diff --git a/static/openbsd/man3/pthread_attr_init.3 b/static/openbsd/man3/pthread_attr_init.3 new file mode 100644 index 00000000..6c26ef5c --- /dev/null +++ b/static/openbsd/man3/pthread_attr_init.3 @@ -0,0 +1,81 @@ +.\" $OpenBSD: pthread_attr_init.3,v 1.12 2025/06/07 00:16:52 schwarze Exp $ +.\" Manual page derived from TOG's UNIX98 documentation. +.\" +.\" David Leonard, 2000. Public Domain. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_ATTR_INIT 3 +.Os +.Sh NAME +.Nm pthread_attr_init , +.Nm pthread_attr_destroy +.Nd initialise and destroy threads attribute object +.Sh SYNOPSIS +.Lb libpthread +.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 +The function +.Fn pthread_attr_init +initialises a thread attributes +object +.Fa attr +with the default value for all of the individual +attributes used by a given implementation. +.Pp +The resulting attribute object (possibly modified by setting +individual attribute values), when used by +.Xr pthread_create 3 , +defines the attributes of the thread created. +A single attributes object can be used in multiple simultaneous calls to +.Xr pthread_create 3 . +.Pp +The +.Fn pthread_attr_destroy +function is used to destroy a thread +attributes object. +An implementation may cause +.Fn pthread_attr_destroy +to set +.Fa attr +to an implementation-dependent +invalid value. +The behaviour of using the attribute after it has +been destroyed is undefined. +.Sh RETURN VALUES +Upon successful completion, +.Fn pthread_attr_init +and +.Fn pthread_attr_destroy +return a value of 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_attr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to initialise the thread attributes +object. +.El +.Pp +These functions will not return an error code of +.Bq Er EINTR . +.Sh SEE ALSO +.Xr pthread_attr_setdetachstate 3 , +.Xr pthread_attr_setguardsize 3 , +.Xr pthread_attr_setstack 3 , +.Xr pthread_attr_setstackaddr 3 , +.Xr pthread_attr_setstacksize 3 , +.Xr pthread_create 3 , +.Xr pthreads 3 +.Sh STANDARDS +.Fn pthread_attr_destroy +and +.Fn pthread_attr_init +conform to ISO/IEC 9945-1 ANSI/IEEE +.Pq Dq Tn POSIX +Std 1003.1 Second Edition 1996-07-12. diff --git a/static/openbsd/man3/pthread_attr_setdetachstate.3 b/static/openbsd/man3/pthread_attr_setdetachstate.3 new file mode 100644 index 00000000..8a479fc0 --- /dev/null +++ b/static/openbsd/man3/pthread_attr_setdetachstate.3 @@ -0,0 +1,106 @@ +.\" $OpenBSD: pthread_attr_setdetachstate.3,v 1.11 2025/06/07 00:16:52 schwarze Exp $ +.\" Manual page derived from TOG's UNIX98 documentation. +.\" +.\" David Leonard, 2000. Public Domain. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_ATTR_SETDETACHSTATE 3 +.Os +.Sh NAME +.Nm pthread_attr_setdetachstate , +.Nm pthread_attr_getdetachstate +.Nd set and get detachstate attribute +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" +.Ft int +.Fn pthread_attr_getdetachstate "pthread_attr_t *attr" "int *detachstate" +.Sh DESCRIPTION +The +.Va detachstate +attribute controls whether the thread is created in +a detached state. +If the thread is created detached, then use of +the ID of the newly created thread by the +.Xr pthread_detach 3 +or +.Xr pthread_join 3 +function is an error. +.Pp +The +.Fn pthread_attr_setdetachstate +and +.Fn pthread_attr_getdetachstate +functions, respectively, set and get the +.Va detachstate +attribute in the +.Fa attr +object. +.Pp +The +.Fa detachstate +can be set to either +.Dv PTHREAD_CREATE_DETACHED +or +.Dv PTHREAD_CREATE_JOINABLE . +A value of +.Dv PTHREAD_CREATE_DETACHED +causes +all threads created with +.Fa attr +to be in the detached state, whereas +using a value of +.Dv PTHREAD_CREATE_JOINABLE +causes all threads created +with +.Fa attr +to be in the joinable state. +The default value of the +.Va detachstate +attribute is +.Dv PTHREAD_CREATE_JOINABLE . +.Sh RETURN VALUES +Upon successful completion, +.Fn pthread_attr_setdetachstate +and +.Fn pthread_attr_getdetachstate +return a value of 0. +Otherwise, an error number is returned to indicate the error. +.Pp +The +.Fn pthread_attr_getdetachstate +function stores the value of the +.Va detachstate +attribute in +.Fa detachstate +if successful. +.Sh ERRORS +The +.Fn pthread_attr_setdetachstate +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of +.Fa detachstate +was not valid. +.El +.Pp +These functions will not return an error code of +.Bq Er EINTR . +.Sh SEE ALSO +.Xr pthread_attr_init 3 , +.Xr pthread_attr_setguardsize 3 , +.Xr pthread_attr_setstack 3 , +.Xr pthread_attr_setstackaddr 3 , +.Xr pthread_attr_setstacksize 3 , +.Xr pthread_create 3 , +.Xr pthreads 3 +.Sh STANDARDS +.Fn pthread_attr_setdetachstate +and +.Fn pthread_attr_getdetachstate +conform to ISO/IEC 9945-1 ANSI/IEEE +.Pq Dq Tn POSIX +Std 1003.1 Second Edition 1996-07-12. diff --git a/static/openbsd/man3/pthread_attr_setguardsize.3 b/static/openbsd/man3/pthread_attr_setguardsize.3 new file mode 100644 index 00000000..1d95e4c6 --- /dev/null +++ b/static/openbsd/man3/pthread_attr_setguardsize.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: pthread_attr_setguardsize.3,v 1.4 2025/06/07 00:16:52 schwarze Exp $ +.\" Manual page derived from TOG's XPG6 documentation. +.\" +.\" David Leonard, 2000. Public Domain. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_ATTR_SETGUARDSIZE 3 +.Os +.Sh NAME +.Nm pthread_attr_setguardsize , +.Nm pthread_attr_getguardsize +.Nd set and get guardsize attribute +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_attr_setguardsize "pthread_attr_t *attr" "size_t guardsize" +.Ft int +.Fn pthread_attr_getguardsize "const pthread_attr_t *attr" "size_t *guardsize" +.Sh DESCRIPTION +The functions +.Fn pthread_attr_setguardsize +and +.Fn pthread_attr_getguardsize , +respectively, set and get the thread +creation +.Va guardsize +attribute in the +.Fa attr +object. +If +.Va guardsize +is zero, +a guard area shall not be provided for threads created with +.Fa attr . +If +.Va guardsize +is greater than zero, +a guard area of at least size +.Va guardsize +bytes shall be provided for each thread created with +.Fa attr . +.Pp +The +.Va guardsize +attribute controls the size of the guard area for the created +thread's stack. +The +.Va guardsize +attribute provides protection against overflow of the stack pointer. +If a thread's stack is created with guard protection, +the implementation allocates extra memory at the overflow end of +the stack as a buffer against stack overflow of the stack pointer. +If an application overflows into this buffer, an error shall result +(possibly in a SIGSEGV signal being delivered to the thread). +.Sh RETURN VALUES +Upon successful completion, +.Fn pthread_attr_setguardsize +and +.Fn pthread_attr_getguardsize +return a value of 0. +Otherwise, an error number is returned to indicate the error. +.Pp +The +.Fn pthread_attr_getguardsize +function stores the +.Va guardsize +attribute value in +.Fa guardsize +if successful. +.Sh ERRORS +No errors are defined. +.Pp +These functions will not return an error code of +.Bq Er EINTR . +.Sh SEE ALSO +.Xr pthread_attr_init 3 , +.Xr pthread_attr_setdetachstate 3 , +.Xr pthread_attr_setstack 3 , +.Xr pthread_attr_setstackaddr 3 , +.Xr pthread_attr_setstacksize 3 , +.Xr pthread_create 3 , +.Xr pthreads 3 +.Sh STANDARDS +.Fn pthread_attr_setguardsize +and +.Fn pthread_attr_getguardsize +conform to ISO/IEC 9945-1 ANSI/IEEE +.Pq Dq Tn POSIX +Std 1003.1, 2004 Edition. diff --git a/static/openbsd/man3/pthread_attr_setstack.3 b/static/openbsd/man3/pthread_attr_setstack.3 new file mode 100644 index 00000000..a40a77be --- /dev/null +++ b/static/openbsd/man3/pthread_attr_setstack.3 @@ -0,0 +1,107 @@ +.\" $OpenBSD: pthread_attr_setstack.3,v 1.7 2025/06/07 00:16:52 schwarze Exp $ +.\" Manual page derived from TOG's UNIX98 documentation. +.\" +.\" David Leonard, 2000. Public Domain. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_ATTR_SETSTACK 3 +.Os +.Sh NAME +.Nm pthread_attr_setstack , +.Nm pthread_attr_getstack +.Nd set and get stack attributes +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_attr_setstack "pthread_attr_t *attr" "void *stackaddr" "size_t stacksize" +.Ft int +.Fn pthread_attr_getstack "const pthread_attr_t *attr" "void **stackaddr" "size_t *stacksize" +.Sh DESCRIPTION +The functions +.Fn pthread_attr_setstack +and +.Fn pthread_attr_getstack , +respectively, set and get the thread +creation +.Va stackaddr +and +.Va stacksize +attributes in the +.Fa attr +object. +.Pp +The stack attributes specify the area of storage to be used for the +created thread's stack. +The base (lowest addressable byte) of the storage shall be +.Va stackaddr , +and the size of the storage shall be +.Va stacksize +bytes. +The stacksize shall be at least +.Dv PTHREAD_STACK_MIN . +.Pp +On +.Ox +the provided stack must be page-aligned. +It will be replaced (meaning zeroed) with a new +.Ar MAP_ANON | Ar MAP_STACK +mapping. +The passed memory object should not be deallocated or reused, +even when the thread using it has terminated. +If there is no need for a specific memory object as stack, +the +.Xr pthread_attr_setstacksize 3 +function should be used. +.Sh RETURN VALUES +Upon successful completion, +.Fn pthread_attr_setstack +and +.Fn pthread_attr_getstack +return a value of 0. +Otherwise, an error number is returned to indicate the error. +.Pp +The +.Fn pthread_attr_getstack +function stores the +.Va stackaddr +attribute value in +.Fa stackaddr +and the +.Va stacksize +attribute value in +.Fa stacksize +if successful. +.Sh ERRORS +The +.Fn pthread_attr_setstack +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of +.Fa stacksize +is less than +.Dv PTHREAD_STACK_MIN +or exceeds a system-imposed limit or the value of +.Fa stackaddr +is +.Dv NULL . +.El +.Pp +These functions will not return an error code of +.Bq Er EINTR . +.Sh SEE ALSO +.Xr pthread_attr_init 3 , +.Xr pthread_attr_setdetachstate 3 , +.Xr pthread_attr_setguardsize 3 , +.Xr pthread_attr_setstackaddr 3 , +.Xr pthread_attr_setstacksize 3 , +.Xr pthread_create 3 , +.Xr pthreads 3 +.Sh STANDARDS +.Fn pthread_attr_setstack +and +.Fn pthread_attr_getstack +conform to ISO/IEC 9945-1 ANSI/IEEE +.Pq Dq Tn POSIX +Std 1003.1, 2004 Edition. diff --git a/static/openbsd/man3/pthread_attr_setstackaddr.3 b/static/openbsd/man3/pthread_attr_setstackaddr.3 new file mode 100644 index 00000000..060b41a0 --- /dev/null +++ b/static/openbsd/man3/pthread_attr_setstackaddr.3 @@ -0,0 +1,83 @@ +.\" $OpenBSD: pthread_attr_setstackaddr.3,v 1.14 2025/06/07 00:16:52 schwarze Exp $ +.\" Manual page derived from TOG's UNIX98 documentation. +.\" +.\" David Leonard, 2000. Public Domain. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_ATTR_SETSTACKADDR 3 +.Os +.Sh NAME +.Nm pthread_attr_setstackaddr , +.Nm pthread_attr_getstackaddr +.Nd set and get stackaddr attribute +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr" +.Ft int +.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr" +.Sh DESCRIPTION +The functions +.Fn pthread_attr_setstackaddr +and +.Fn pthread_attr_getstackaddr , +respectively, set and get the thread +creation +.Va stackaddr +attribute in the +.Fa attr +object. +.Pp +The +.Va stackaddr +attribute specifies the location of storage to be +used for the created thread's stack. +The size of the storage is at least +.Dv PTHREAD_STACK_MIN . +.Pp +On +.Ox +the stack must have been allocated using +.Xr mmap 2 +with the +.Va MAP_STACK +attribute. +Otherwise, use of the stack will cause SIGABRT faults. +.Xr pthread_attr_setstack 3 +can avoid this problem because it knows the size of the stack to remap. +.Sh RETURN VALUES +Upon successful completion, +.Fn pthread_attr_setstackaddr +and +.Fn pthread_attr_getstackaddr +return a value of 0. +Otherwise, an error number is returned to indicate the error. +.Pp +The +.Fn pthread_attr_getstackaddr +function stores the +.Va stackaddr +attribute value in +.Fa stackaddr +if successful. +.Sh ERRORS +No errors are defined. +.Pp +These functions will not return an error code of +.Bq Er EINTR . +.Sh SEE ALSO +.Xr pthread_attr_init 3 , +.Xr pthread_attr_setdetachstate 3 , +.Xr pthread_attr_setguardsize 3 , +.Xr pthread_attr_setstack 3 , +.Xr pthread_attr_setstacksize 3 , +.Xr pthread_create 3 , +.Xr pthreads 3 +.Sh STANDARDS +.Fn pthread_attr_setstackaddr +and +.Fn pthread_attr_getstackaddr +conform to ISO/IEC 9945-1 ANSI/IEEE +.Pq Dq Tn POSIX +Std 1003.1 Second Edition 1996-07-12. diff --git a/static/openbsd/man3/pthread_attr_setstacksize.3 b/static/openbsd/man3/pthread_attr_setstacksize.3 new file mode 100644 index 00000000..3bb34737 --- /dev/null +++ b/static/openbsd/man3/pthread_attr_setstacksize.3 @@ -0,0 +1,80 @@ +.\" $OpenBSD: pthread_attr_setstacksize.3,v 1.11 2025/06/07 00:16:52 schwarze Exp $ +.\" Manual page derived from TOG's UNIX98 documentation. +.\" +.\" David Leonard, 2000. Public Domain. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_ATTR_SETSTACKSIZE 3 +.Os +.Sh NAME +.Nm pthread_attr_setstacksize , +.Nm pthread_attr_getstacksize +.Nd set and get stacksize attribute +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize" +.Ft int +.Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize" +.Sh DESCRIPTION +The functions +.Fn pthread_attr_setstacksize +and +.Fn pthread_attr_getstacksize , +respectively, set and get the thread +creation +.Va stacksize +attribute in the +.Fa attr +object. +.Pp +The +.Va stacksize +attribute defines the minimum stack size (in bytes) +allocated for the created thread's stack. +.Sh RETURN VALUES +Upon successful completion, +.Fn pthread_attr_setstacksize +and +.Fn pthread_attr_getstacksize +return a value of 0. +Otherwise, an error number is returned to indicate the error. +.Pp +The +.Fn pthread_attr_getstacksize +function stores the +.Va stacksize +attribute value in +.Fa stacksize +if successful. +.Sh ERRORS +The +.Fn pthread_attr_setstacksize +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of +.Fa stacksize +is less than +.Dv PTHREAD_STACK_MIN +or exceeds a system-imposed limit. +.El +.Pp +These functions will not return an error code of +.Bq Er EINTR . +.Sh SEE ALSO +.Xr pthread_attr_init 3 , +.Xr pthread_attr_setdetachstate 3 , +.Xr pthread_attr_setguardsize 3 , +.Xr pthread_attr_setstack 3 , +.Xr pthread_attr_setstackaddr 3 , +.Xr pthread_create 3 , +.Xr pthreads 3 +.Sh STANDARDS +.Fn pthread_attr_setstacksize +and +.Fn pthread_attr_getstacksize +conform to ISO/IEC 9945-1 ANSI/IEEE +.Pq Dq Tn POSIX +Std 1003.1 Second Edition 1996-07-12. diff --git a/static/openbsd/man3/pthread_barrier_init.3 b/static/openbsd/man3/pthread_barrier_init.3 new file mode 100644 index 00000000..9404c2b6 --- /dev/null +++ b/static/openbsd/man3/pthread_barrier_init.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: pthread_barrier_init.3,v 1.6 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2012 Paul Irofti +.\" +.\" 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: June 7 2025 $ +.Dt PTHREAD_BARRIER_INIT 3 +.Os +.Sh NAME +.Nm pthread_barrier_init , +.Nm pthread_barrier_destroy +.Nd initialize and destroy a barrier object +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_barrier_init "pthread_barrier_t *barrier" "pthread_barrierattr_t *attr" "unsigned int count" +.Ft int +.Fn pthread_barrier_destroy "pthread_barrier_t *barrier" +.Sh DESCRIPTION +The +.Fn pthread_barrier_init +function creates a new barrier object, with attributes specified with +.Fa attr +and with a threshold specified with +.Fa count . +If +.Fa attr +is +.Dv NULL , +the default attributes are used. +The +.Fa count +argument is later used by the +.Fn pthread_barrier_wait +function to check if the required number of threads reached the barrier. +.Pp +The +.Fn pthread_barrier_destroy +function frees the resources allocated for +.Fa barrier . +.Sh RETURN VALUES +If successful, +.Fn pthread_barrier_init +and +.Fn pthread_barrier_destroy +return zero; +otherwise an error number is returned to indicate the error. +.Sh ERRORS +.Fn pthread_barrier_init +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa barrier +or +.Fa attr +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to create another barrier object. +.It Bq Er ENOTSUP +The attributes specified by +.Fa attr +are not supported by the current implementation. +.El +.Pp +.Fn pthread_barrier_destroy +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa barrier +is invalid. +.It Bq Er EBUSY +There are still threads waiting on the barrier. +.El +.Sh SEE ALSO +.Xr pthread_barrier_wait 3 , +.Xr pthread_barrierattr_getpshared 3 , +.Xr pthread_barrierattr_init 3 +.Sh STANDARDS +.Fn pthread_barrier_init +and +.Fn pthread_barrier_destroy +conform to +.St -p1003.1-2008 . +.Sh BUGS +Currently only private barriers are supported and the pshared attribute is +always set that way. +Any attempts to change that value will trigger +.Er ENOTSUP . diff --git a/static/openbsd/man3/pthread_barrier_wait.3 b/static/openbsd/man3/pthread_barrier_wait.3 new file mode 100644 index 00000000..d467d1f6 --- /dev/null +++ b/static/openbsd/man3/pthread_barrier_wait.3 @@ -0,0 +1,59 @@ +.\" $OpenBSD: pthread_barrier_wait.3,v 1.6 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2012 Paul Irofti +.\" +.\" 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: June 7 2025 $ +.Dt PTHREAD_BARRIER_WAIT 3 +.Os +.Sh NAME +.Nm pthread_barrier_wait +.Nd synchronize at a barrier +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_barrier_wait "pthread_barrier_t *barrier" +.Sh DESCRIPTION +The +.Fn pthread_barrier_wait +function blocks the calling thread until the required number of threads +call +.Fn pthread_barrier_wait , +as specified at the object's initialization. +.Sh RETURN VALUES +If successful, +.Fn pthread_barrier_wait +returns +.Dv PTHREAD_BARRIER_SERIAL_THREAD +for a single arbitrary thread and zero for each of the other threads; +otherwise an error number is returned to indicate the error. +.Sh ERRORS +.Fn pthread_barrier_wait +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa barrier +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_barrier_init 3 , +.Xr pthread_barrierattr_getpshared 3 , +.Xr pthread_barrierattr_init 3 +.Sh STANDARDS +.Fn pthread_barrier_wait +conforms to +.St -p1003.1-2008 . diff --git a/static/openbsd/man3/pthread_barrierattr_getpshared.3 b/static/openbsd/man3/pthread_barrierattr_getpshared.3 new file mode 100644 index 00000000..0fc7685e --- /dev/null +++ b/static/openbsd/man3/pthread_barrierattr_getpshared.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: pthread_barrierattr_getpshared.3,v 1.6 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2012 Paul Irofti +.\" +.\" 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: June 7 2025 $ +.Dt PTHREAD_BARRIERATTR_GETPSHARED 3 +.Os +.Sh NAME +.Nm pthread_barrierattr_getpshared , +.Nm pthread_barrierattr_setpshared +.Nd get or set the process-shared attribute of the barrier attribute's object +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_barrierattr_getpshared "pthread_barrierattr_t *attr" "int *pshared" +.Ft int +.Fn pthread_barrierattr_setpshared "pthread_barrierattr_t *attr" "int pshared" +.Sh DESCRIPTION +The +.Fn pthread_barrierattr_getpshared +function writes in +.Fa pshared +the current process-shared attribute value. +.Pp +The +.Fn pthread_barrierattr_setpshared +function sets the process-shared attribute as indicated in +.Fa pshared . +.Sh RETURN VALUES +If successful, +.Fn pthread_barrierattr_getpshared +and +.Fn pthread_barrierattr_setpshared +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_barrierattr_getpshared +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +.Fn pthread_barrierattr_setpshared +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOTSUP +The value specified by +.Fa pshared +is not PTHREAD_PROCESS_PRIVATE. +.El +.Sh SEE ALSO +.Xr pthread_barrier_init 3 , +.Xr pthread_barrier_wait 3 , +.Xr pthread_barrierattr_init 3 +.Sh STANDARDS +.Fn pthread_barrierattr_getpshared +and +.Fn pthread_barrierattr_setpshared +conform to +.St -p1003.1-2008 . +.Sh BUGS +Currently only private barriers are supported and the pshared attribute is +always set that way. +Any attempts to change that value will trigger +.Er ENOTSUP . diff --git a/static/openbsd/man3/pthread_barrierattr_init.3 b/static/openbsd/man3/pthread_barrierattr_init.3 new file mode 100644 index 00000000..817712e7 --- /dev/null +++ b/static/openbsd/man3/pthread_barrierattr_init.3 @@ -0,0 +1,78 @@ +.\" $OpenBSD: pthread_barrierattr_init.3,v 1.5 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2012 Paul Irofti +.\" +.\" 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: June 7 2025 $ +.Dt PTHREAD_BARRIERATTR_INIT 3 +.Os +.Sh NAME +.Nm pthread_barrierattr_init , +.Nm pthread_barrierattr_destroy +.Nd initialize and destroy a barrier attribute object +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_barrierattr_init "pthread_barrierattr_t *attr" +.Ft int +.Fn pthread_barrierattr_destroy "pthread_barrierattr_t *attr" +.Sh DESCRIPTION +The +.Fn pthread_barrierattr_init +function creates a new barrier attribute object. +.Pp +The +.Fn pthread_barrierattr_destroy +function frees the resources allocated for +.Fa attr . +.Sh RETURN VALUES +If successful, +.Fn pthread_barrierattr_init +and +.Fn pthread_barrierattr_destroy +return zero; +otherwise an error number is returned to indicate the error. +.Sh ERRORS +.Fn pthread_barrierattr_init +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to create another barrier attribute +object. +.El +.Pp +.Fn pthread_barrierattr_destroy +will 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 , +.Xr pthread_barrier_wait 3 , +.Xr pthread_barrierattr_getpshared 3 +.Sh STANDARDS +.Fn pthread_barrierattr_init +and +.Fn pthread_barrierattr_destroy +conform to +.St -p1003.1-2008 . diff --git a/static/openbsd/man3/pthread_cancel.3 b/static/openbsd/man3/pthread_cancel.3 new file mode 100644 index 00000000..a18ec98c --- /dev/null +++ b/static/openbsd/man3/pthread_cancel.3 @@ -0,0 +1,72 @@ +.\" $OpenBSD: pthread_cancel.3,v 1.15 2025/06/13 18:48:06 schwarze Exp $ +.\" +.\" +.\" David Leonard, 1999. Public Domain. +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt PTHREAD_CANCEL 3 +.Os +.Sh NAME +.Nm pthread_cancel +.Nd cancel execution of a thread +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_cancel "pthread_t thread" +.Sh DESCRIPTION +The +.Fn pthread_cancel +function requests that +.Fa thread +be cancelled. +The target thread's cancelability state and type determines +when the cancellation takes effect. +When the cancellation is acted on, the cancellation cleanup handlers for +.Fa thread +are called. +When the last cancellation cleanup handler returns, +the thread-specific data destructor functions will be called for +.Fa thread . +When the last destructor function returns, +.Fa thread +will be terminated. +.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 +.Pq Vt 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 +.Fn pthread_cancel +will 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_cleanup_push 3 , +.Xr pthread_exit 3 , +.Xr pthread_join 3 , +.Xr pthread_setcancelstate 3 , +.Xr pthread_setcanceltype 3 , +.Xr pthread_testcancel 3 +.Sh STANDARDS +.Fn pthread_cancel +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_cleanup_pop.3 b/static/openbsd/man3/pthread_cleanup_pop.3 new file mode 100644 index 00000000..e16e4def --- /dev/null +++ b/static/openbsd/man3/pthread_cleanup_pop.3 @@ -0,0 +1,64 @@ +.\" $OpenBSD: pthread_cleanup_pop.3,v 1.11 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1997 Brian Cully +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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: pthread_cleanup_pop.3,v 1.4 1999/08/28 00:03:02 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_CLEANUP_POP 3 +.Os +.Sh NAME +.Nm pthread_cleanup_pop +.Nd call the first cleanup routine +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft void +.Fn pthread_cleanup_pop "int execute" +.Sh DESCRIPTION +The +.Fn pthread_cleanup_pop +function pops the top cleanup routine off of the current thread's cleanup +routine stack and, if +.Fa execute +is non-zero, it will execute the function. +If there is no cleanup routine then +.Fn pthread_cleanup_pop +does nothing. +.Sh RETURN VALUES +.Fn pthread_cleanup_pop +does not return any value. +.Sh ERRORS +None +.Sh SEE ALSO +.Xr pthread_cleanup_push 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +.Fn pthread_cleanup_pop +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_cleanup_push.3 b/static/openbsd/man3/pthread_cleanup_push.3 new file mode 100644 index 00000000..412a0cfd --- /dev/null +++ b/static/openbsd/man3/pthread_cleanup_push.3 @@ -0,0 +1,67 @@ +.\" $OpenBSD: pthread_cleanup_push.3,v 1.8 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1997 Brian Cully +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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: pthread_cleanup_push.3,v 1.5 1999/08/28 00:03:02 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_CLEANUP_PUSH 3 +.Os +.Sh NAME +.Nm pthread_cleanup_push +.Nd add a cleanup function for thread exit +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft void +.Fn pthread_cleanup_push "void (*cleanup_routine)(void *)" "void *arg" +.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 +When +.Fa cleanup_routine +is called, it is passed +.Fa arg +as its only argument. +.Sh RETURN VALUES +.Fn pthread_cleanup_push +does not return any value. +.Sh ERRORS +None +.Sh SEE ALSO +.Xr pthread_cleanup_pop 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +.Fn pthread_cleanup_push +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_cond_init.3 b/static/openbsd/man3/pthread_cond_init.3 new file mode 100644 index 00000000..5d80f79f --- /dev/null +++ b/static/openbsd/man3/pthread_cond_init.3 @@ -0,0 +1,174 @@ +.\" $OpenBSD: pthread_cond_init.3,v 1.14 2025/07/03 18:01:38 tedu Exp $ +.\" +.\" Copyright (c) 1997 Brian Cully +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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: pthread_cond_init.3,v 1.6 1999/08/28 00:03:03 peter Exp $ +.\" $FreeBSD: pthread_cond_destroy.3,v 1.5 1999/08/28 00:03:03 peter Exp $ +.\" $FreeBSD: pthread_cond_wait.3,v 1.6 1999/08/28 00:03:04 peter Exp $ +.\" $FreeBSD: pthread_cond_timedwait.3,v 1.6 1999/08/28 00:03:04 peter Exp $ +.\" $FreeBSD: pthread_cond_broadcast.3,v 1.5 1999/08/28 00:03:03 peter Exp $ +.\" $FreeBSD: pthread_cond_signal.3,v 1.5 1999/08/28 00:03:04 peter Exp $ +.\" +.Dd $Mdocdate: July 3 2025 $ +.Dt PTHREAD_COND_INIT 3 +.Os +.Sh NAME +.Nm pthread_cond_init , +.Nm pthread_cond_destroy , +.Nm pthread_cond_wait , +.Nm pthread_cond_timedwait , +.Nm pthread_cond_broadcast , +.Nm pthread_cond_signal +.Nd block and unblock threads with condition variables +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fo pthread_cond_init +.Fa "pthread_cond_t *cond" +.Fa "const pthread_condattr_t *attr" +.Fc +.Ft int +.Fo pthread_cond_destroy +.Fa "pthread_cond_t *cond" +.Fc +.Ft int +.Fo pthread_cond_wait +.Fa "pthread_cond_t *cond" +.Fa "pthread_mutex_t *mutex" +.Fc +.Ft int +.Fo pthread_cond_timedwait +.Fa "pthread_cond_t *cond" +.Fa "pthread_mutex_t *mutex" +.Fa "const struct timespec *abstime" +.Fc +.Ft int +.Fo pthread_cond_broadcast +.Fa "pthread_cond_t *cond" +.Fc +.Ft int +.Fo pthread_cond_signal +.Fa "pthread_cond_t *cond" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_cond_init +function creates a new condition variable with attributes specified by +.Fa attr . +If +.Fa attr +is +.Dv NULL , +the default attributes are used. +.Pp +The +.Fn pthread_cond_destroy +function frees the resources associated with the condition variable +.Fa cond . +.Pp +The +.Fn pthread_cond_wait +function atomically blocks the current thread by waiting on the condition +variable +.Fa cond , +and unlocks the mutex specified by +.Fa mutex . +The waiting thread unblocks only after another thread calls +.Fn pthread_cond_broadcast +or +.Fn pthread_cond_signal +with the same condition variable. +The +.Fn pthread_cond_timedwait +function does the same, but returns after the system time reaches +.Fa abstime . +In all cases, both functions then reacquire the lock on +.Fa mutex +before returning. +.Pp +The +.Fn pthread_cond_broadcast +function unblocks all threads waiting for the condition variable +.Fa cond . +The +.Fn pthread_cond_signal +function unblocks at least one thread waiting for the condition variable +.Fa cond . +.Sh RETURN VALUES +These functions return zero for success and positive error numbers +for failure. +.Sh ERRORS +.Fn pthread_cond_init +fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to create another condition +variable. +.It Bq Er EAGAIN +The system temporarily lacks the resources to create another condition +variable. +.El +.Pp +The other functions fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond , +.Fa mutex , +or +.Fa abstime +is invalid. +.El +.Pp +.Fn pthread_cond_destroy +additionally fails if: +.Bl -tag -width Er +.It Bq Er EBUSY +The variable +.Fa cond +is locked by another thread. +.El +.Pp +.Fn pthread_cond_timedwait +additionally fails 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_condattr_init 3 , +.Xr pthread_mutex_init 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_condattr_init.3 b/static/openbsd/man3/pthread_condattr_init.3 new file mode 100644 index 00000000..20be1090 --- /dev/null +++ b/static/openbsd/man3/pthread_condattr_init.3 @@ -0,0 +1,120 @@ +.\" $OpenBSD: pthread_condattr_init.3,v 1.3 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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: pthread_mutexattr.3,v 1.5 2001/07/15 07:53:26 dd Exp $ +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_CONDATTR_INIT 3 +.Os +.Sh NAME +.Nm pthread_condattr_init , +.Nm pthread_condattr_destroy , +.Nm pthread_condattr_setclock , +.Nm pthread_condattr_getclock +.Nd condition variable attribute operations +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_condattr_init "pthread_condattr_t *attr" +.Ft int +.Fn pthread_condattr_destroy "pthread_condattr_t *attr" +.Ft int +.Fn pthread_condattr_setclock "pthread_condattr_t *attr" "clockid_t clock_id" +.Ft int +.Fn pthread_condattr_getclock "pthread_condattr_t *attr" "clockid_t *clock_id" +.Sh DESCRIPTION +Condition variable attributes are used to specify parameters to +.Fn pthread_cond_init . +One attribute object can be used in multiple calls to +.Fn pthread_cond_init , +with or without modifications between calls. +.Pp +The +.Fn pthread_condattr_init +function initializes +.Fa attr +with all the default condition variable attributes. +.Pp +The +.Fn pthread_condattr_destroy +function destroys +.Fa attr . +.Pp +The +.Fn pthread_condattr_setclock +function sets the clock attribute of +.Fa attr +to the value of the +.Fa clock_id +parameter. +The +.Fn pthread_condattr_getclock +function copies the value of the clock attribute from +.Fa attr +to the location pointed to by the +.Fa clock_id +parameter. +The clock attribute is the ID of the clock against which the timeout of +.Fn pthread_cond_timedwait +is compared; +the default value of the clock attribute is +.Dv CLOCK_REALTIME . +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +.Fn pthread_condattr_init +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Out of memory. +.El +.Pp +.Fn pthread_condattr_setclock +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of +.Fa clock_id +is neither +.Dv CLOCK_REALTIME +nor +.Dv CLOCK_MONOTONIC . +.El +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr pthread_cond_init 3 +.Sh STANDARDS +.Fn pthread_condattr_init , +.Fn pthread_condattr_destroy , +.Fn pthread_condattr_setclock , +and +.Fn pthread_condattr_getclock +conform to +.St -p1003.1-2008 diff --git a/static/openbsd/man3/pthread_create.3 b/static/openbsd/man3/pthread_create.3 new file mode 100644 index 00000000..06a379cd --- /dev/null +++ b/static/openbsd/man3/pthread_create.3 @@ -0,0 +1,126 @@ +.\" $OpenBSD: pthread_create.3,v 1.17 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_create.3,v 1.8 1999/08/28 00:03:04 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_CREATE 3 +.Os +.Sh NAME +.Nm pthread_create +.Nd create a new thread +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg" +.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 NULL, the default attributes are used. +If the attributes specified by +.Fa attr +are modified later, the thread's attributes are not affected. +Upon successful completion +.Fn pthread_create +will store the ID of the created thread in the location specified by +.Fa thread . +.Pp +The thread is created executing +.Fa start_routine +with +.Fa arg +as its sole argument. +If the +.Fa start_routine +returns, the effect is as if there was an implicit call to +.Fn pthread_exit +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 +.Fn exit +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 +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources to create another thread, or +the system-imposed limit on the total number of threads in a process +[PTHREAD_THREADS_MAX] would be exceeded. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr __tfork 3 , +.Xr pthread_attr_init 3 , +.Xr pthread_attr_setdetachstate 3 , +.Xr pthread_attr_setguardsize 3 , +.Xr pthread_attr_setstack 3 , +.Xr pthread_attr_setstackaddr 3 , +.Xr pthread_attr_setstacksize 3 , +.Xr pthread_cleanup_pop 3 , +.Xr pthread_cleanup_push 3 , +.Xr pthread_exit 3 , +.Xr pthread_join 3 +.Sh STANDARDS +.Fn pthread_create +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_detach.3 b/static/openbsd/man3/pthread_detach.3 new file mode 100644 index 00000000..e49f2ba3 --- /dev/null +++ b/static/openbsd/man3/pthread_detach.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: pthread_detach.3,v 1.13 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996-1998 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_detach.3,v 1.5 1999/08/28 00:03:05 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_DETACH 3 +.Os +.Sh NAME +.Nm pthread_detach +.Nd detach a thread +.Sh SYNOPSIS +.Lb libpthread +.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. +Note that the function does not change the value +of +.Va errno +as it did for some drafts of the standard. +These early drafts also passed a pointer to pthread_t as the argument. +Beware! +.Sh ERRORS +.Fn pthread_detach +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The implementation has detected that 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 +.Fn pthread_detach +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_equal.3 b/static/openbsd/man3/pthread_equal.3 new file mode 100644 index 00000000..d725c74a --- /dev/null +++ b/static/openbsd/man3/pthread_equal.3 @@ -0,0 +1,69 @@ +.\" $OpenBSD: pthread_equal.3,v 1.11 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_equal.3,v 1.4 1999/08/28 00:03:05 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_EQUAL 3 +.Os +.Sh NAME +.Nm pthread_equal +.Nd compare thread IDs +.Sh SYNOPSIS +.Lb libpthread +.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 +.Fn pthread_equal +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_exit.3 b/static/openbsd/man3/pthread_exit.3 new file mode 100644 index 00000000..74b7f283 --- /dev/null +++ b/static/openbsd/man3/pthread_exit.3 @@ -0,0 +1,106 @@ +.\" $OpenBSD: pthread_exit.3,v 1.14 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_exit.3,v 1.7 1999/08/28 00:03:06 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_EXIT 3 +.Os +.Sh NAME +.Nm pthread_exit +.Nd terminate the calling thread +.Sh SYNOPSIS +.Lb libpthread +.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 +.Fn pthread_exit +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_getconcurrency.3 b/static/openbsd/man3/pthread_getconcurrency.3 new file mode 100644 index 00000000..22432ffa --- /dev/null +++ b/static/openbsd/man3/pthread_getconcurrency.3 @@ -0,0 +1,115 @@ +.\" $OpenBSD: pthread_getconcurrency.3,v 1.5 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2003 Sergey Osokin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (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_r/man/pthread_getconcurrency.3,v 1.2 2003/05/24 19:50:43 ru Exp $ +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_GETCONCURRENCY 3 +.Os +.Sh NAME +.Nm pthread_getconcurrency , +.Nm pthread_setconcurrency +.Nd get or set level of concurrency +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_getconcurrency void +.Ft int +.Fn pthread_setconcurrency "int new_level" +.Sh DESCRIPTION +The +.Fn pthread_setconcurrency +function allows an application to inform the threads implementation +of its desired concurrency level, +.Fa new_level . +The actual level of concurrency provided by the implementation +as a result of this function call is unspecified. +If +.Fa new_level +is zero, it causes the implementation to maintain the concurrency +level at its discretion as if +.Fn pthread_setconcurrency +was never called. +The +.Fn pthread_getconcurrency +function returns the value set by a previous call to the +.Fn pthread_setconcurrency +function. +If the +.Fn pthread_setconcurrency +function was not previously called, this function returns zero to +indicate that the implementation is maintaining the concurrency +level. +When an application calls +.Fn pthread_setconcurrency , +it is informing the implementation of its desired concurrency +level. +The implementation uses this as a hint, not a requirement. +.Sh RETURN VALUES +If successful, the +.Fn pthread_setconcurrency +function returns zero. +Otherwise, an error number is returned +to indicate the error. +The +.Fn pthread_getconcurrency +function always returns the concurrency level set by a previous +call to +.Fn pthread_setconcurrency . +If the +.Fn pthread_setconcurrency +function has never been called, +.Fn pthread_getconcurrency +returns zero. +.Sh ERRORS +.Fn pthread_setconcurrency +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa new_level +is negative. +.It Bq Er EAGAIN +The value specified by +.Fa new_level +would cause a system resource to be exceeded. +.El +.Sh APPLICATION USAGE +Use of these functions changes the state of the underlying +concurrency upon which the application depends. +Library developers are advised to not use the +.Fn pthread_getconcurrency +and +.Fn pthread_setconcurrency +functions since their use may conflict with an application's +use of these functions. +.Sh STANDARDS +The +.Fn pthread_getconcurrency +and +.Fn pthread_setconcurrency +functions conform to +.St -susv2 . diff --git a/static/openbsd/man3/pthread_getcpuclockid.3 b/static/openbsd/man3/pthread_getcpuclockid.3 new file mode 100644 index 00000000..a4519d36 --- /dev/null +++ b/static/openbsd/man3/pthread_getcpuclockid.3 @@ -0,0 +1,62 @@ +.\" $OpenBSD: pthread_getcpuclockid.3,v 1.4 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2013 Philip Guenther +.\" +.\" 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: June 7 2025 $ +.Dt PTHREAD_GETCPUCLOCKID 3 +.Os +.Sh NAME +.Nm pthread_getcpuclockid +.Nd get a clock measuring thread CPU time +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_getcpuclockid "pthread_t thread" "clockid_t *clock_id" +.Sh DESCRIPTION +The +.Fn pthread_getcpuclockid +function allows the calling thread to get a +.Vt clockid_t +value that measures the time spent by CPUs running in user or kernel mode +on behalf of the thread specified by +.Fa thread . +.Sh RETURN VALUES +If successful, +.Fn pthread_getcpuclockid +will return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_getcpuclockid +will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +thread is an invalid thread ID. +.El +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr clock_getcpuclockid 3 +.Sh STANDARDS +The +.Fn pthread_getcpuclockid +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn pthread_getcpuclockid +function first appeared in IEEE Std 1003.1d-1999 +.Pq Dq POSIX.1d +and has been available since +.Ox 5.4 . diff --git a/static/openbsd/man3/pthread_getspecific.3 b/static/openbsd/man3/pthread_getspecific.3 new file mode 100644 index 00000000..a5c06fc7 --- /dev/null +++ b/static/openbsd/man3/pthread_getspecific.3 @@ -0,0 +1,84 @@ +.\" $OpenBSD: pthread_getspecific.3,v 1.8 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_getspecific.3,v 1.6 1999/08/28 00:03:06 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_GETSPECIFIC 3 +.Os +.Sh NAME +.Nm pthread_getspecific +.Nd get a thread-specific data value +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft void * +.Fn pthread_getspecific "pthread_key_t key" +.Sh DESCRIPTION +The +.Fn pthread_getspecific +function returns the value currently bound to the specified +.Fa key +on behalf of the calling thread. +.Pp +The effect of calling +.Fn pthread_getspecific +with a +.Fa key +value not obtained from +.Fn pthread_key_create +or after +.Fa key +has been deleted with +.Fn pthread_key_delete +is undefined. +.Pp +.Fn pthread_getspecific +may be called from a thread-specific data destructor function. +.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 NULL is returned. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +.Fn pthread_getspecific +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_join.3 b/static/openbsd/man3/pthread_join.3 new file mode 100644 index 00000000..f30c835f --- /dev/null +++ b/static/openbsd/man3/pthread_join.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: pthread_join.3,v 1.11 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996-1998 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_join.3,v 1.6 1999/08/28 00:03:06 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_JOIN 3 +.Os +.Sh NAME +.Nm pthread_join +.Nd wait for thread termination +.Sh SYNOPSIS +.Lb libpthread +.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 non-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 +[_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 +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The implementation has detected that 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 . +.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 +.Fn pthread_join +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_key_create.3 b/static/openbsd/man3/pthread_key_create.3 new file mode 100644 index 00000000..9e1f1b3a --- /dev/null +++ b/static/openbsd/man3/pthread_key_create.3 @@ -0,0 +1,105 @@ +.\" $OpenBSD: pthread_key_create.3,v 1.10 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_key_create.3,v 1.5 1999/08/28 00:03:06 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_KEY_CREATE 3 +.Os +.Sh NAME +.Nm pthread_key_create +.Nd thread-specific data key creation +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)" +.Sh DESCRIPTION +The +.Fn pthread_key_create +function creates a thread-specific data key visible to all threads in the +process. +Key values provided by +.Fn pthread_key_create +are opaque objects used to locate thread-specific data. +Although the same +key value may be used by different threads, 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 NULL is associated with the new key in all +active threads. +Upon thread creation, the value 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 non-NULL destructor pointer, and the +thread has a non-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 non-NULL values +with associated destructors, there are still some non-NULL values with +associated destructors, then the process is repeated. +If, after at least +[PTHREAD_DESTRUCTOR_ITERATIONS] iterations of destructor calls for +outstanding non-NULL values, there are still some non-NULL values with +associated destructors, the implementation stops calling destructors. +.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. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_key_create +will 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 +[PTHREAD_KEYS_MAX] would be exceeded. +.It Bq Er ENOMEM +Insufficient memory exists to create the key. +.El +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +.Fn pthread_key_create +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_key_delete.3 b/static/openbsd/man3/pthread_key_delete.3 new file mode 100644 index 00000000..7f34421c --- /dev/null +++ b/static/openbsd/man3/pthread_key_delete.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: pthread_key_delete.3,v 1.11 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_key_delete.3,v 1.5 1999/08/28 00:03:06 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_KEY_DELETE 3 +.Os +.Sh NAME +.Nm pthread_key_delete +.Nd delete a thread-specific data key +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_key_delete "pthread_key_t key" +.Sh DESCRIPTION +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 NULL at the time that +.Fn pthread_key_delete +is called. +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 is callable from within destructor functions. +Destructor functions are not invoked by +.Fn pthread_key_delete . +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_delete +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_key_delete +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_key_create 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +.Fn pthread_key_delete +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_kill.3 b/static/openbsd/man3/pthread_kill.3 new file mode 100644 index 00000000..2ecd683a --- /dev/null +++ b/static/openbsd/man3/pthread_kill.3 @@ -0,0 +1,76 @@ +.\" $OpenBSD: pthread_kill.3,v 1.4 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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_r/man/pthread_kill.3,v 1.8 2001/10/01 16:09:09 ru Exp $ +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_KILL 3 +.Os +.Sh NAME +.Nm pthread_kill +.Nd send a signal to a specified thread +.Sh SYNOPSIS +.Lb libpthread +.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 . +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 +will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +.Fa thread +is an invalid thread ID. +.It Bq Er EINVAL +.Fa sig +is an invalid or unsupported signal number. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr pthread_self 3 , +.Xr raise 3 +.Sh STANDARDS +.Fn pthread_kill +conforms to +.St -p1003.1-96 diff --git a/static/openbsd/man3/pthread_main_np.3 b/static/openbsd/man3/pthread_main_np.3 new file mode 100644 index 00000000..21addc5a --- /dev/null +++ b/static/openbsd/man3/pthread_main_np.3 @@ -0,0 +1,40 @@ +.\" $OpenBSD: pthread_main_np.3,v 1.7 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Peter Valchev Public Domain, 2001 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_MAIN_NP 3 +.Os +.Sh NAME +.Nm pthread_main_np +.Nd identify the main thread +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.In pthread_np.h +.Ft int +.Fn pthread_main_np "void" +.Sh DESCRIPTION +The +.Fn pthread_main_np +function identifies the main thread. +.Sh RETURN VALUES +The +.Fn pthread_main_np +function returns: +.Bl -tag -width hrmf +.It 1 +if the calling thread is the main thread +.It 0 +if the calling thread is not the main thread +.It -1 +if the thread initialization has not completed +.El +.Sh SEE ALSO +.Xr pthread_self 3 , +.Xr pthreads 3 +.Sh STANDARDS +The +.Fn pthread_main_np +function is non-portable and may not be supported with the above +semantics on other POSIX systems. diff --git a/static/openbsd/man3/pthread_mutex_init.3 b/static/openbsd/man3/pthread_mutex_init.3 new file mode 100644 index 00000000..22bf16e4 --- /dev/null +++ b/static/openbsd/man3/pthread_mutex_init.3 @@ -0,0 +1,235 @@ +.\" $OpenBSD: pthread_mutex_init.3,v 1.16 2025/07/25 20:01:28 tedu Exp $ +.\" +.\" Copyright (c) 1997 Brian Cully +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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: pthread_mutex_init.3,v 1.6 1999/08/28 00:03:07 peter Exp $ +.\" $FreeBSD: pthread_mutex_destroy.3,v 1.5 1999/08/28 00:03:07 peter Exp $ +.\" $FreeBSD: pthread_mutex_lock.3,v 1.5 1999/08/28 00:03:07 peter Exp $ +.\" $FreeBSD: pthread_mutex_unlock.3,v 1.5 1999/08/28 00:03:08 peter Exp $ +.\" +.Dd $Mdocdate: July 25 2025 $ +.Dt PTHREAD_MUTEX_INIT 3 +.Os +.Sh NAME +.Nm pthread_mutex_init , +.Nm pthread_mutex_destroy , +.Nm pthread_mutex_lock , +.Nm pthread_mutex_timedlock , +.Nm pthread_mutex_trylock , +.Nm pthread_mutex_unlock +.Nd operations on mutex variables +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fo pthread_mutex_init +.Fa "pthread_mutex_t *mutex" +.Fa "const pthread_mutexattr_t *attr" +.Fc +.Ft int +.Fo pthread_mutex_destroy +.Fa "pthread_mutex_t *mutex" +.Fc +.Ft int +.Fo pthread_mutex_lock +.Fa "pthread_mutex_t *mutex" +.Fc +.Ft int +.Fo pthread_mutex_timedlock +.Fa "pthread_mutex_t *mutex" +.Fa "const struct timespec *abstime" +.Fc +.Ft int +.Fo pthread_mutex_trylock +.Fa "pthread_mutex_t *mutex" +.Fc +.Ft int +.Fo pthread_mutex_unlock +.Fa "pthread_mutex_t *mutex" +.Fc +.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, otherwise +.Fa attr +should be initialized by calling +.Xr pthread_mutexattr_init 3 . +.Pp +A mutex may also be initialized by assignment with the macro +PTHREAD_MUTEX_INITIALIZER. +.Pp +The +.Fn pthread_mutex_destroy +function frees the resources allocated for +.Fa mutex . +.Pp +The +.Fn pthread_mutex_lock +function locks +.Fa mutex . +If the mutex is currently locked by another thread, +the calling thread will block until the +mutex becomes available. +.Pp +If the mutex is currently locked by the calling thread, +then the behavior depends on the type of the mutex. +If +.Fa mutex +is of type +.Dv PTHREAD_MUTEX_NORMAL , +then the calling thread will deadlock and never return from +.Fn pthread_mutex_lock . +If +.Fa mutex +is of type +.Dv PTHREAD_MUTEX_ERRORCHECK , +then +.Er EDEADLK +is immediately returned. +If +.Fa mutex +is of type +.Dv PTHREAD_MUTEX_RECURSIVE , +then the recursion count on the mutex is incremented. +.Pp +The +.Fn pthread_mutex_timedlock +function locks +.Fa mutex +like +.Fn pthread_mutex_lock +except that it will not block or deadlock past the system time +specified in +.Fa abstime . +.Pp +The +.Fn pthread_mutex_trylock +function locks +.Fa mutex +like +.Fn pthread_mutex_lock +except that if +.Fa mutex +is locked by another thread, +or is locked by the calling thread and is not of type +.Dv PTHREAD_MUTEX_RECURSIVE , +then it will immediately return +.Er EBUSY . +.Pp +The +.Fn pthread_mutex_unlock +function unlocks the previously locked +.Fa mutex . +.Sh RETURN VALUES +These functions return zero for success and positive error numbers +for failure. +.Sh ERRORS +.Fn pthread_mutex_init +fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to create another mutex. +.El +.Pp +The other functions fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.El +.Pp +.Fn pthread_mutex_destroy +fails if: +.Bl -tag -width Er +.It Bq Er EBUSY +.Fa mutex +is locked or referenced by another thread. +.El +.Pp +.Fn pthread_mutex_lock , +.Fn pthread_mutex_timedlock , +and +.Fn pthread_mutex_trylock +fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The mutex is of type +.Dv PTHREAD_MUTEX_RECURSIVE +and the maximum recursion count has been reached. +.El +.Pp +.Fn pthread_mutex_lock +and +.Fn pthread_mutex_timedlock +fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The mutex is of type +.Dv PTHREAD_MUTEX_ERRORCHECK +and is already locked by the calling thread. +.El +.Pp +.Fn pthread_mutex_timedlock +fails if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The mutex could not be locked and the specified time was reached. +.El +.Pp +.Fn pthread_mutex_trylock +fails if: +.Bl -tag -width Er +.It Bq Er EBUSY +The mutex could not be locked because it was already locked. +.El +.Pp +.Fn pthread_mutex_unlock +fails if: +.Bl -tag -width Er +.It Bq Er EPERM +The current thread does not hold a lock on +.Fa mutex . +.El +.Sh SEE ALSO +.Xr pthread_mutexattr_init 3 , +.Xr pthreads 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2024 . +Raising an error for invalid arguments is an extension. diff --git a/static/openbsd/man3/pthread_mutexattr.3 b/static/openbsd/man3/pthread_mutexattr.3 new file mode 100644 index 00000000..d1d08cfa --- /dev/null +++ b/static/openbsd/man3/pthread_mutexattr.3 @@ -0,0 +1,178 @@ +.\" $OpenBSD: pthread_mutexattr.3,v 1.7 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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: pthread_mutexattr.3,v 1.5 2001/07/15 07:53:26 dd Exp $ +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_MUTEXATTR_INIT 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 +.Nd mutex attribute operations +.Sh SYNOPSIS +.Lb libpthread +.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 *attr" "int *type" +.Sh DESCRIPTION +Mutex attributes are used to specify parameters to +.Fn pthread_mutex_init . +One attribute object can be used in multiple calls to +.Fn pthread_mutex_init , +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_set* +functions set the attribute that corresponds to each function name. +.Pp +The +.Fn pthread_mutexattr_get* +functions copy the value of the attribute that corresponds to each function name +to the location pointed to by the second function parameter. +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +.Fn pthread_mutexattr_init +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Out of memory. +.El +.Pp +.Fn pthread_mutexattr_destroy +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +.Fn pthread_mutexattr_setprioceiling +will 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 +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +.Fn pthread_mutexattr_setprotocol +will 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 +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +.Fn pthread_mutexattr_settype +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa type . +.El +.Pp +.Fn pthread_mutexattr_gettype +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Sh SEE ALSO +.Xr pthread_mutex_init 3 +.Sh STANDARDS +.Fn pthread_mutexattr_init +and +.Fn pthread_mutexattr_destroy +conform to +.St -p1003.1-96 +.Pp +.Fn pthread_mutexattr_setprioceiling , +.Fn pthread_mutexattr_getprioceiling , +.Fn pthread_mutexattr_setprotocol , +.Fn pthread_mutexattr_getprotocol , +.Fn pthread_mutexattr_settype , +and +.Fn pthread_mutexattr_gettype +conform to +.St -susv2 diff --git a/static/openbsd/man3/pthread_once.3 b/static/openbsd/man3/pthread_once.3 new file mode 100644 index 00000000..2dfc2c4a --- /dev/null +++ b/static/openbsd/man3/pthread_once.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: pthread_once.3,v 1.16 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_once.3,v 1.5 1999/08/28 00:03:09 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_ONCE 3 +.Os +.Sh NAME +.Nm pthread_once +.Nd dynamic package initialization +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Vt pthread_once_t once_control No = Dv PTHREAD_ONCE_INIT ; +.Ft int +.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)" +.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 +.Va once_control +is as if +.Fn pthread_once +was never called. +.Pp +The constant +.Dv PTHREAD_ONCE_INIT +is defined in the header file +.In pthread.h . +.Pp +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 +.Fn pthread_once +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_rwlock_init.3 b/static/openbsd/man3/pthread_rwlock_init.3 new file mode 100644 index 00000000..bb309cf9 --- /dev/null +++ b/static/openbsd/man3/pthread_rwlock_init.3 @@ -0,0 +1,273 @@ +.\" $OpenBSD: pthread_rwlock_init.3,v 1.12 2025/07/08 02:23:49 jsg Exp $ +.\" 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: pthread_rwlock_init.3,v 1.2 1999/08/28 00:03:09 peter Exp $ +.\" $FreeBSD: pthread_rwlock_destroy.3,v 1.3 1999/08/28 00:03:09 peter Exp $ +.\" $FreeBSD: pthread_rwlock_rdlock.3,v 1.2 1999/08/28 00:03:09 peter Exp $ +.\" $FreeBSD: pthread_rwlock_wrlock.3,v 1.2 1999/08/28 00:03:10 peter Exp $ +.\" $FreeBSD: pthread_rwlock_unlock.3,v 1.2 1999/08/28 00:03:10 peter Exp $ +.\" +.Dd $Mdocdate: July 8 2025 $ +.Dt PTHREAD_RWLOCK_INIT 3 +.Os +.Sh NAME +.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 operations on read/write locks +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fo pthread_rwlock_init +.Fa "pthread_rwlock_t *lock" +.Fa "const pthread_rwlockattr_t *attr" +.Fc +.Ft int +.Fo pthread_rwlock_destroy +.Fa "pthread_rwlock_t *lock" +.Fc +.Ft int +.Fo pthread_rwlock_rdlock +.Fa "pthread_rwlock_t *lock" +.Fc +.Ft int +.Fo pthread_rwlock_timedrdlock +.Fa "pthread_rwlock_t *lock" +.Fa "const struct timespec *abstime" +.Fc +.Ft int +.Fo pthread_rwlock_tryrdlock +.Fa "pthread_rwlock_t *lock" +.Fc +.Ft int +.Fo pthread_rwlock_wrlock +.Fa "pthread_rwlock_t *lock" +.Fc +.Ft int +.Fo pthread_rwlock_timedwrlock +.Fa "pthread_rwlock_t *lock" +.Fa "const struct timespec *abstime" +.Fc +.Ft int +.Fo pthread_rwlock_trywrlock +.Fa "pthread_rwlock_t *lock" +.Fc +.Ft int +.Fo pthread_rwlock_unlock +.Fa "pthread_rwlock_t *lock" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_rwlock_init +function initializes a read/write lock, with attributes +specified by +.Fa attr . +If +.Fa attr +is NULL, the default read/write lock attributes are used. +The results of calling +.Fn pthread_rwlock_init +with an already initialized lock are undefined. +.Pp +The +.Fn pthread_rwlock_destroy +function destroys 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_wrlock +function blocks until a write lock can be acquired against +.Fa lock . +.Pp +The +.Fn pthread_rwlock_timedrdlock +and +.Fn pthread_rwlock_timedwrlock +functions perform the same action, +but will not wait beyond +.Fa abstime +to obtain the lock before returning. +.Pp +The +.Fn pthread_rwlock_tryrdlock +and +.Fn pthread_rwlock_trywrlock +functions perform the same action +but do not block if the lock cannot be immediately obtained. +.Pp +The +.Fn pthread_rwlock_unlock +function releases the read/write lock previously obtained. +.Pp +A thread may hold multiple concurrent read locks. +If so, +.Fn pthread_rwlock_unlock +must be called once for each lock obtained. +.Sh RETURN VALUES +If successful, these functions return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_rwlock_init +fails if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources (other than memory) to +initialize the lock. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock. +.It Bq Er EPERM +The caller does not have sufficient privilege to perform the +operation. +.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. +.El +.Pp +Other functions fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock (applies to +statically initialized locks only). +.El +.Pp +.Fn pthread_rwlock_destroy +fails 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. +.El +.Pp +.Fn pthread_rwlock_tryrdlock +and +.Fn pthread_rwlock_trywrlock +fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The lock could not be acquired without blocking. +.El +.Pp +.Fn pthread_rwlock_timedrdlock +and +.Fn pthread_rwlock_timedwrlock +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 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. +.El +.Pp +The +.Fn pthread_rwlock_wrlock , +.Fn pthread_rwlock_timedwrlock , +and +.Fn pthread_rwlock_trywrlock +functions fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The calling thread already owns the read/write lock (for reading +or writing). +.El +.Pp +The +.Fn pthread_rwlock_unlock +fails if: +.Bl -tag -width Er +.It Bq Er EPERM +The current thread does not own the read/write lock. +.El +.Sh SEE ALSO +.Xr pthread_rwlockattr_init 3 , +.Xr pthreads 3 +.Sh STANDARDS +These functions are expected to conform to +.St -susv2 . +.Sh HISTORY +.Fn pthread_rwlock_init , +.Fn pthread_rwlock_destroy , +.Fn pthread_rwlock_rdlock , +.Fn pthread_rwlock_tryrdlock , +.Fn pthread_rwlock_wrlock , +.Fn pthread_rwlock_trywrlock , +and +.Fn pthread_rwlock_unlock +have been available since +.Ox 2.5 , +and +.Fn pthread_rwlock_timedrdlock +and +.Fn pthread_rwlock_timedwrlock +since +.Ox 4.8 . +.Sh BUGS +The PTHREAD_PROCESS_SHARED attribute is not supported. diff --git a/static/openbsd/man3/pthread_rwlockattr_destroy.3 b/static/openbsd/man3/pthread_rwlockattr_destroy.3 new file mode 100644 index 00000000..88718bbe --- /dev/null +++ b/static/openbsd/man3/pthread_rwlockattr_destroy.3 @@ -0,0 +1,72 @@ +.\" $OpenBSD: pthread_rwlockattr_destroy.3,v 1.12 2025/06/20 12:57:56 job Exp $ +.\" 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: pthread_rwlockattr_destroy.3,v 1.3 1999/08/28 00:03:10 peter Exp $ +.\" +.Dd $Mdocdate: June 20 2025 $ +.Dt PTHREAD_RWLOCKATTR_DESTROY 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_destroy +.Nd destroy a read/write lock attributes object +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_destroy +function is used to destroy a read/write lock attributes object +previously created with +.Fn pthread_rwlockattr_init . +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_destroy +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_rwlockattr_destroy +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_rwlockattr_init 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_destroy +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_destroy +function first appeared in +.Fx 3.0 +and +.Ox 2.5 . diff --git a/static/openbsd/man3/pthread_rwlockattr_getpshared.3 b/static/openbsd/man3/pthread_rwlockattr_getpshared.3 new file mode 100644 index 00000000..e06a3bb7 --- /dev/null +++ b/static/openbsd/man3/pthread_rwlockattr_getpshared.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: pthread_rwlockattr_getpshared.3,v 1.11 2025/06/07 00:16:52 schwarze Exp $ +.\" 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: pthread_rwlockattr_getpshared.3,v 1.4 1999/08/28 00:03:10 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_RWLOCKATTR_GETPSHARED 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_getpshared +.Nd get the process shared attribute +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_getpshared "const pthread_rwlockattr_t *attr" "int *pshared" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_getpshared +function is used to get the process shared setting of a read/write +lock attribute object. +The setting is returned via +.Fa pshared , +and may be one of two values: +.Bl -hang -offset flag -width 123456789012345678901234 +.It Ar PTHREAD_PROCESS_SHARED +Any thread of any process that has access to the memory where the +read/write lock resides can manipulate the lock. +.It Ar PTHREAD_PROCESS_PRIVATE +Only threads created within the same process as the thread that +initialized the read/write lock can manipulate the lock. +This is the default value. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_getpshared +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_rwlockattr_getpshared +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 , +.Xr pthread_rwlockattr_init 3 , +.Xr pthread_rwlockattr_setpshared 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_getpshared +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_getpshared +function first appeared in +.Fx 3.0 +and +.Ox 2.5 . diff --git a/static/openbsd/man3/pthread_rwlockattr_init.3 b/static/openbsd/man3/pthread_rwlockattr_init.3 new file mode 100644 index 00000000..410af108 --- /dev/null +++ b/static/openbsd/man3/pthread_rwlockattr_init.3 @@ -0,0 +1,71 @@ +.\" $OpenBSD: pthread_rwlockattr_init.3,v 1.11 2025/06/20 12:51:51 job Exp $ +.\" 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: pthread_rwlockattr_init.3,v 1.3 1999/08/28 00:03:10 peter Exp $ +.\" +.Dd $Mdocdate: June 20 2025 $ +.Dt PTHREAD_RWLOCKATTR_INIT 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_init +.Nd initialize a read/write lock attributes object +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_init +function is used to initialize a read/write lock attributes object. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_init +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_rwlockattr_init +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to initialize the attribute object. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlockattr_destroy 3 , +.Xr pthread_rwlockattr_getpshared 3 , +.Xr pthread_rwlockattr_setpshared 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_init +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_init +function first appeared in +.Fx 3.0 +and +.Ox 2.5 . diff --git a/static/openbsd/man3/pthread_rwlockattr_setpshared.3 b/static/openbsd/man3/pthread_rwlockattr_setpshared.3 new file mode 100644 index 00000000..8d3dab32 --- /dev/null +++ b/static/openbsd/man3/pthread_rwlockattr_setpshared.3 @@ -0,0 +1,89 @@ +.\" $OpenBSD: pthread_rwlockattr_setpshared.3,v 1.11 2025/06/07 00:16:52 schwarze Exp $ +.\" 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: pthread_rwlockattr_setpshared.3,v 1.2 1999/08/28 00:03:11 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_RWLOCKATTR_SETPSHARED 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_setpshared +.Nd set the process shared attribute +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_setpshared +function sets the process shared attribute of +.Fa attr +to the value referenced by +.Fa pshared . +.Fa pshared +may be one of two values: +.Bl -hang -offset flag -width 123456789012345678901234 +.It Ar PTHREAD_PROCESS_SHARED +Any thread of any process that has access to the memory where the +read/write lock resides can manipulate the lock. +.It Ar PTHREAD_PROCESS_PRIVATE +Only threads created within the same process as the thread that +initialized the read/write lock can manipulate the lock. +This is the default value. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_setpshared +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_rwlockattr_setpshared +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +or +.Fa pshared +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlockattr_init 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_setpshared +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_setpshared +function first appeared in +.Fx 3.0 +and +.Ox 2.5 . +.Sh BUGS +The PTHREAD_PROCESS_SHARED attribute is not supported. diff --git a/static/openbsd/man3/pthread_schedparam.3 b/static/openbsd/man3/pthread_schedparam.3 new file mode 100644 index 00000000..87e9870f --- /dev/null +++ b/static/openbsd/man3/pthread_schedparam.3 @@ -0,0 +1,93 @@ +.\" $OpenBSD: pthread_schedparam.3,v 1.7 2025/06/07 00:16:52 schwarze Exp $ +.\" Copyright (C) 2000 Jason Evans . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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_r/man/pthread_schedparam.3,v 1.4 2001/07/15 07:53:27 dd Exp $ +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_SETSCHEDPARAM 3 +.Os +.Sh NAME +.Nm pthread_setschedparam , +.Nm pthread_getschedparam +.Nd thread scheduling parameter manipulation +.Sh SYNOPSIS +.Lb libpthread +.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 *policy" "struct sched_param *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 either be +.Dv SCHED_FIFO +(first in, first out) or +.Dv SCHED_RR +(round-robin). +The thread priority (accessed via +.Va param->sched_priority ) +must be within the range returned by the +.Fn sched_get_priority_min +and +.Fn sched_get_priority_max +functions. +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +.Fn pthread_setschedparam +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Va policy . +.It Bq Er ENOTSUP +Invalid value for scheduling parameters. +.It Bq Er ESRCH +Non-existent thread +.Va thread . +.El +.Pp +.Fn pthread_getschedparam +will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +Non-existent thread +.Va thread . +.El +.Sh SEE ALSO +.Xr sched_get_priority_max 3 +.Sh STANDARDS +.Fn pthread_setschedparam +and +.Fn pthread_getschedparam +conform to +.St -susv2 diff --git a/static/openbsd/man3/pthread_self.3 b/static/openbsd/man3/pthread_self.3 new file mode 100644 index 00000000..a96d7848 --- /dev/null +++ b/static/openbsd/man3/pthread_self.3 @@ -0,0 +1,62 @@ +.\" $OpenBSD: pthread_self.3,v 1.9 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_self.3,v 1.4 1999/08/28 00:03:11 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_SELF 3 +.Os +.Sh NAME +.Nm pthread_self +.Nd get the calling thread's ID +.Sh SYNOPSIS +.Lb libpthread +.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 +.Fn pthread_self +function returns the thread ID of the calling thread. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_equal 3 +.Sh STANDARDS +.Fn pthread_self +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_set_name_np.3 b/static/openbsd/man3/pthread_set_name_np.3 new file mode 100644 index 00000000..cae07660 --- /dev/null +++ b/static/openbsd/man3/pthread_set_name_np.3 @@ -0,0 +1,59 @@ +.\" $OpenBSD: pthread_set_name_np.3,v 1.10 2025/12/03 17:09:23 kurt Exp $ +.\" David Leonard , 1999. Public domain. +.Dd $Mdocdate: December 3 2025 $ +.Dt PTHREAD_SET_NAME_NP 3 +.Os +.Sh NAME +.Nm pthread_set_name_np , +.Nm pthread_get_name_np +.Nd set the name of a thread +.Sh SYNOPSIS +.Lb libpthread +.In pthread_np.h +.Ft void +.Fn pthread_set_name_np "pthread_t thread" "const char *name" +.Ft void +.Fn pthread_get_name_np "pthread_t thread" "char *name" "size_t len" +.Sh DESCRIPTION +The +.Fn pthread_set_name_np +function associates +.Fa name +with +.Fa thread . +This can be useful for debugging, as the name is displayed in +the thread status as displayed when the process receives the +.Dv SIGINFO +signal. +.Pp +The string pointed to by +.Fa name +is copied, and so need not be valid for the life of the thread. +A maximum of +.Dv _MAXCOMLEN +- 1 bytes of +.Fa name +will be copied. +.Pp +The +.Fn pthread_get_name_np +function retrieves +.Fa name +associated with +.Fa thread . +The +.Fa len +of buffer +.Fa name +should be at least +.Dv _MAXCOMLEN +bytes otherwise +.Fa name +will be truncated to fit in a buffer +.Fa len +bytes long. +.Sh SEE ALSO +.Xr pthreads 3 +.Sh STANDARDS +These functions are non-portable and may not be supported with the above +semantics on other POSIX systems. diff --git a/static/openbsd/man3/pthread_setspecific.3 b/static/openbsd/man3/pthread_setspecific.3 new file mode 100644 index 00000000..4678686c --- /dev/null +++ b/static/openbsd/man3/pthread_setspecific.3 @@ -0,0 +1,95 @@ +.\" $OpenBSD: pthread_setspecific.3,v 1.14 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 1996 John Birrell . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce 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: pthread_setspecific.3,v 1.5 1999/08/28 00:03:11 peter Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_SETSPECIFIC 3 +.Os +.Sh NAME +.Nm pthread_setspecific +.Nd set a thread-specific data value +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_setspecific "pthread_key_t key" "const void *value" +.Sh DESCRIPTION +The +.Fn pthread_setspecific +function associates a thread-specific value with a +.Fa key +obtained via a previous call to +.Fn pthread_key_create . +Different threads may bind different values to the same key. +These values are +typically pointers to blocks of dynamically allocated memory that have been +reserved for use by the calling thread. +.Pp +The effect of calling +.Fn pthread_setspecific +with a key value not obtained from +.Fn pthread_key_create +or after +.Fa key +has been deleted with +.Fn pthread_key_delete +is undefined. +.Pp +.Fn pthread_setspecific +may be called from a thread-specific data destructor function; however, this +may result in lost storage or infinite loops. +.Sh RETURN VALUES +If successful, the +.Fn pthread_setspecific +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_setspecific +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to associate the value with the +.Fa key . +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 +.Sh STANDARDS +.Fn pthread_setspecific +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_sigmask.3 b/static/openbsd/man3/pthread_sigmask.3 new file mode 100644 index 00000000..852ae106 --- /dev/null +++ b/static/openbsd/man3/pthread_sigmask.3 @@ -0,0 +1,72 @@ +.\" $OpenBSD: pthread_sigmask.3,v 1.12 2025/06/07 00:30:54 schwarze Exp $ +.\" +.\" +.\" David Leonard, 1999. Public Domain. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_SIGMASK 3 +.Os +.Sh NAME +.Nm pthread_sigmask +.Nd examine and/or change a thread's signal mask +.Sh SYNOPSIS +.Lb libpthread +.In signal.h +.Ft int +.Fn pthread_sigmask "int how" "const sigset_t *set" "sigset_t *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 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 +will 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 pthreads 3 , +.Xr sigaddset 3 +.Sh STANDARDS +.Fn pthread_sigmask +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/pthread_spin_init.3 b/static/openbsd/man3/pthread_spin_init.3 new file mode 100644 index 00000000..4b040f45 --- /dev/null +++ b/static/openbsd/man3/pthread_spin_init.3 @@ -0,0 +1,89 @@ +.\" $OpenBSD: pthread_spin_init.3,v 1.4 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2012 Paul Irofti +.\" +.\" 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: June 7 2025 $ +.Dt PTHREAD_SPIN_INIT 3 +.Os +.Sh NAME +.Nm pthread_spin_init , +.Nm pthread_spin_destroy +.Nd initialize and destroy a spinlock object +.Sh SYNOPSIS +.Lb libpthread +.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" +.Sh DESCRIPTION +The +.Fn pthread_spin_init +function creates a new spinlock object, with sharing attributes specified by +.Fa pshared . +.Pp +The +.Fn pthread_spin_destroy +function frees the resources allocated for the +.Fa lock . +.Sh RETURN VALUES +If successful, +.Fn pthread_spin_init +and +.Fn pthread_spin_destroy +return zero; otherwise an error number is returned to indicate the error. +.Sh ERRORS +.Fn pthread_spin_init +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to create another spinlock object. +.It Bq Er ENOTSUP +The shared attributes specified by +.Fa pshared +are not supported by the current implementation. +.El +.Pp +.Fn pthread_spin_destroy +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er EBUSY +The lock is still in use. +.El +.Sh SEE ALSO +.Xr pthread_spin_lock 3 , +.Xr pthread_spin_unlock 3 +.Sh STANDARDS +.Fn pthread_spin_init +and +.Fn pthread_spin_destroy +conform to +.St -p1003.1-2008 . +.Sh BUGS +Currently only +.Dv PTHREAD_PROCESS_PRIVATE +spinlocks are supported and the pshared attribute is +always set that way. +Any attempts to initialize it to a different value will trigger +.Er ENOTSUP . diff --git a/static/openbsd/man3/pthread_spin_lock.3 b/static/openbsd/man3/pthread_spin_lock.3 new file mode 100644 index 00000000..b62a26aa --- /dev/null +++ b/static/openbsd/man3/pthread_spin_lock.3 @@ -0,0 +1,84 @@ +.\" $OpenBSD: pthread_spin_lock.3,v 1.4 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2012 Paul Irofti +.\" +.\" 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: June 7 2025 $ +.Dt PTHREAD_SPIN_LOCK 3 +.Os +.Sh NAME +.Nm pthread_spin_lock , +.Nm pthread_spin_trylock +.Nd lock a spinlock object +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_spin_lock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_trylock "pthread_spinlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_spin_lock +function locks the spinlock referenced by +.Fa lock . +The calling thread will acquire the lock if it's not owned by another thread. +Otherwise it will spin until the lock becomes available. +.Pp +The +.Fn pthread_spin_trylock +function will acquire the lock if the +.Fa lock +is not owned by another thread. +Otherwise it will fail. +.Sh RETURN VALUES +If successful, +.Fn pthread_spin_lock +and +.Fn pthread_spin_trylock +return zero; otherwise an error number is returned to indicate the error. +.Sh ERRORS +.Fn pthread_spin_lock +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er EDEADLK +A deadlock condition was detected. +.El +.Pp +.Fn pthread_spin_trylock +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er EBUSY +The lock is still in use. +.It Bq Er EDEADLK +A deadlock condition was detected. +.El +.Sh SEE ALSO +.Xr pthread_spin_init 3 , +.Xr pthread_spin_unlock 3 +.Sh STANDARDS +.Fn pthread_spin_lock +and +.Fn pthread_spin_trylock +conform to +.St -p1003.1-2008 . diff --git a/static/openbsd/man3/pthread_spin_unlock.3 b/static/openbsd/man3/pthread_spin_unlock.3 new file mode 100644 index 00000000..37040906 --- /dev/null +++ b/static/openbsd/man3/pthread_spin_unlock.3 @@ -0,0 +1,60 @@ +.\" $OpenBSD: pthread_spin_unlock.3,v 1.4 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2012 Paul Irofti +.\" +.\" 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: June 7 2025 $ +.Dt PTHREAD_SPIN_UNLOCK 3 +.Os +.Sh NAME +.Nm pthread_spin_unlock +.Nd unlock a spinlock object +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft int +.Fn pthread_spin_unlock "pthread_spinlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_spin_unlock +function releases the spin lock referenced by +.Fa lock +which was locked via the +.Fn pthread_spin_lock +or +.Fn pthread_spin_trylock +functions. +.Sh RETURN VALUES +If successful, +.Fn pthread_spin_unlock +returns zero; otherwise an error number is returned to indicate the error. +.Sh ERRORS +.Fn pthread_spin_unlock +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er EPERM +The lock is not owned by the calling thread. +.El +.Sh SEE ALSO +.Xr pthread_spin_init 3 , +.Xr pthread_spin_lock 3 +.Sh STANDARDS +.Fn pthread_spin_unlock +conforms to +.St -p1003.1-2008 . diff --git a/static/openbsd/man3/pthread_stackseg_np.3 b/static/openbsd/man3/pthread_stackseg_np.3 new file mode 100644 index 00000000..cbdf51de --- /dev/null +++ b/static/openbsd/man3/pthread_stackseg_np.3 @@ -0,0 +1,50 @@ +.\" $OpenBSD: pthread_stackseg_np.3,v 1.8 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" PUBLIC DOMAIN: No Rights Reserved. Marco S Hyman +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_STACKSEG_NP 3 +.Os +.Sh NAME +.Nm pthread_stackseg_np +.Nd return stack size and location +.Sh SYNOPSIS +.Lb libpthread +.In pthread_np.h +.Ft int +.Fn pthread_stackseg_np "pthread_t thread" "stack_t *sinfo" +.Sh DESCRIPTION +The +.Fn pthread_stackseg_np +function returns information about the given thread's stack. +A +.Fa stack_t +is the same as a +.Fa struct sigaltstack +(see +.Xr sigaltstack 2 ) +except the +.Fa ss_sp +variable points to the top of the stack instead of the base. +.Sh RETURN VALUES +If successful, the +.Fn pthread_stackseg_np +function will return 0. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_stackseg_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +Stack information for the given thread is not currently available. +There is no guarantee that the given thread's stack information will ever +become available. +.El +.Sh SEE ALSO +.Xr sigaltstack 2 , +.Xr pthreads 3 +.Sh STANDARDS +.Fn pthread_stackseg_np +is a non-portable extension to +.St -p1003.1-2001 . diff --git a/static/openbsd/man3/pthread_testcancel.3 b/static/openbsd/man3/pthread_testcancel.3 new file mode 100644 index 00000000..6cee18ce --- /dev/null +++ b/static/openbsd/man3/pthread_testcancel.3 @@ -0,0 +1,236 @@ +.\" $OpenBSD: pthread_testcancel.3,v 1.18 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" +.\" David Leonard, 1999. Public Domain. +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_TESTCANCEL 3 +.Os +.Sh NAME +.Nm pthread_setcancelstate , +.Nm pthread_setcanceltype , +.Nm pthread_testcancel +.Nd set cancelability state +.Sh SYNOPSIS +.Lb libpthread +.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 +base interfaces: +.Fn accept , +.Fn close , +.Fn connect , +.Fn creat , +.Fn fcntl "F_SETLKW" , +.Fn fdatasync , +.Fn fsync , +.Fn lockf , +.Fn msgrcv , +.Fn msgsnd , +.Fn msync , +.Fn nanosleep , +.Fn open , +.Fn openat , +.Fn pause , +.Fn poll , +.Fn pread , +.Fn pselect , +.Fn pthread_cond_timedwait , +.Fn pthread_cond_wait , +.Fn pthread_join , +.Fn pthread_testcancel , +.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 sigsuspend , +.Fn sigwait , +.Fn sleep , +.Fn system , +.Fn tcdrain , +.Fn wait , +.Fn waitid , +.Fn waitpid , +.Fn write , +.Fn writev . +.Pp +In addition, +cancellation points will occur when a thread is executing the following +extension interfaces: +.Fn accept4 , +.Fn closefrom , +.Fn ppoll , +.Fn preadv , +.Fn pwritev , +.Fn recvmmsg , +.Fn sendmmsg , +.Fn wait3 , +.Fn wait4 . +.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 cancelled. +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 cancelled 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 cancelled, +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 +.Fn pthread_testcancel +conforms to +.St -p1003.1-96 diff --git a/static/openbsd/man3/pthread_yield.3 b/static/openbsd/man3/pthread_yield.3 new file mode 100644 index 00000000..66ee0988 --- /dev/null +++ b/static/openbsd/man3/pthread_yield.3 @@ -0,0 +1,28 @@ +.\" $OpenBSD: pthread_yield.3,v 1.6 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" PUBLIC DOMAIN: No Rights Reserved. Marco S Hyman +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt PTHREAD_YIELD 3 +.Os +.Sh NAME +.Nm pthread_yield +.Nd yield control of the current thread +.Sh SYNOPSIS +.Lb libpthread +.In pthread.h +.Ft void +.Fn pthread_yield "void" +.Sh DESCRIPTION +The +.Fn pthread_yield +function resets the accumulated time slice of the current thread and then +enters the thread scheduler, which resumes execution of the next thread ready +to run. +If no other thread is ready to run, control returns to the current thread. +.Sh SEE ALSO +.Xr pthreads 3 +.Sh STANDARDS +.Fn pthread_yield +is a non-portable (but quite common) extension to +.St -p1003.1-2001 . diff --git a/static/openbsd/man3/pthreads.3 b/static/openbsd/man3/pthreads.3 new file mode 100644 index 00000000..7b0b0b89 --- /dev/null +++ b/static/openbsd/man3/pthreads.3 @@ -0,0 +1,481 @@ +.\" $OpenBSD: pthreads.3,v 1.46 2025/07/03 18:01:38 tedu Exp $ +.\" David Leonard , 1998. Public domain. +.Dd $Mdocdate: July 3 2025 $ +.Dt PTHREADS 3 +.Os +.Sh NAME +.Nm pthreads +.Nd POSIX 1003.1c thread interface +.Sh DESCRIPTION +A thread is a flow of control within a process. +Each thread represents a minimal amount of state: +normally just the CPU state and a signal mask. +All other process state (such as memory, file descriptors) +is shared among all of the threads in the process. +.Pp +In +.Ox , +threads use a 1-to-1 implementation, +where every thread is independently scheduled by the kernel. +.Pp +For the purpose of this document, +the functions available are grouped in the following categories. +For further information, see the individual man page for each function. +.Pp +.Bl -dash -offset indent -compact +.It +Attribute Object Routines +.It +Barrier Routines +.It +Cleanup Routines +.It +Condition Variable Routines +.It +Mutex Routines +.It +Non Portable Extensions +.It +Per-Thread Context Routines +.It +Read/Write Lock Routines +.It +Spinlock Routines +.It +Thread Routines +.El +.Ss Attribute Object Routines +The functions available are as follows: +.Pp +.Bl -tag -width "pthread_attr_getdetachstate()" -compact +.It Fn pthread_attr_init +Initialise a threads attribute object. +.It Fn pthread_attr_destroy +Destroy a threads attribute object. +.It Fn pthread_attr_getdetachstate +Get detachstate attribute. +.It Fn pthread_attr_setdetachstate +Set detachstate attribute. +.It Fn pthread_attr_getstack +Get stackaddr and stacksize attributes. +.It Fn pthread_attr_setstack +Set stackaddr and stacksize attributes. +.It Fn pthread_attr_getstackaddr +Get stackaddr attribute. +.It Fn pthread_attr_setstackaddr +Set stackaddr attribute. +.It Fn pthread_attr_getstacksize +Get stacksize attribute. +.It Fn pthread_attr_setstacksize +Set stacksize attribute. +.It Fn pthread_attr_getguardsize +Get guardsize attribute. +.It Fn pthread_attr_setguardsize +Set guardsize attribute. +.El +.Ss Barrier Routines +The functions available are as follows: +.Pp +.Bl -tag -width "pthread_barrierattr_getpshared()" -compact +.It Fn pthread_barrier_init +Initialize a barrier object. +.It Fn pthread_barrier_destroy +Destroy a barrier object. +.It Fn pthread_barrier_wait +Synchronize at a barrier. +.It Fn pthread_barrierattr_init +Initialize a barrier's attribute object. +.It Fn pthread_barrierattr_destroy +Destroy a barrier's attribute object. +.It Fn pthread_barrierattr_getpshared +Get the process-shared attribute of the barrier attribute's object. +.It Fn pthread_barrierattr_setpshared +Set the process-shared attribute of the barrier attribute's object. +.El +.Ss Cleanup Routines +The functions available are as follows: +.Pp +.Bl -tag -width "pthread_cleanup_push()" -compact +.It Fn pthread_atfork +Register fork handlers. +.It Fn pthread_cleanup_pop +Call the first cleanup routine. +.It Fn pthread_cleanup_push +Add a cleanup function for thread exit. +.El +.Ss Condition Variable Routines +The functions available are as follows: +.Pp +.Bl -tag -width "pthread_condattr_setclock()" -compact +.It Fn pthread_cond_init +Create a condition variable. +.It Fn pthread_cond_destroy +Destroy a condition variable. +.It Fn pthread_cond_broadcast +Unblock all threads waiting for a condition variable. +.It Fn pthread_cond_signal +Unblock a thread waiting for a condition variable. +.It Fn pthread_cond_timedwait +Wait on a condition variable until a specific point in time. +.It Fn pthread_cond_wait +Wait on a condition variable. +.It Fn pthread_condattr_init +Initialise a condition variable attribute object. +.It Fn pthread_condattr_destroy +Destroy a condition variable attribute object. +.It Fn pthread_condattr_getclock +Get clock attribute. +.It Fn pthread_condattr_setclock +Set clock attribute. +.El +.Ss Mutex Routines +The functions available are as follows: +.Pp +.Bl -tag -width "pthread_mutexattr_getprioceiling()" -compact +.It Fn pthread_mutex_init +Create a mutex. +.It Fn pthread_mutex_destroy +Free resources allocated for a mutex. +.It Fn pthread_mutex_lock +Lock a mutex. +.It Fn pthread_mutex_timedlock +Attempt to lock a mutex before a specific point in time. +.It Fn pthread_mutex_trylock +Attempt to lock a mutex without blocking. +.It Fn pthread_mutex_unlock +Unlock a mutex. +.It Fn pthread_mutexattr_init +Mutex attribute operations. +.It Fn pthread_mutexattr_destroy +Mutex attribute operations. +.It Fn pthread_mutexattr_getprioceiling +Mutex attribute operations. +.It Fn pthread_mutexattr_setprioceiling +Mutex attribute operations. +.It Fn pthread_mutexattr_getprotocol +Mutex attribute operations. +.It Fn pthread_mutexattr_setprotocol +Mutex attribute operations. +.It Fn pthread_mutexattr_gettype +Mutex attribute operations. +.It Fn pthread_mutexattr_settype +Mutex attribute operations. +.El +.Ss Non Portable Extensions +The functions available are as follows: +.Pp +.Bl -tag -width "pthread_set_name_np()" -compact +.It Fn pthread_main_np +Identify the main thread. +.It Fn pthread_set_name_np +Set the name of a thread. +.It Fn pthread_get_name_np +Get the name of a thread. +.It Fn pthread_stackseg_np +Return stack size and location. +.It Fn pthread_yield +Yield control of the current thread. +.El +.Ss Per-Thread Context Routines +The functions available are as follows: +.Pp +.Bl -tag -width "pthread_getspecific()" -compact +.It Fn pthread_key_create +Thread-specific data key creation. +.It Fn pthread_key_delete +Delete a thread-specific data key. +.It Fn pthread_getspecific +Get a thread-specific data value. +.It Fn pthread_setspecific +Set a thread-specific data value. +.El +.Ss Read/Write Lock Routines +The functions available are as follows: +.Pp +.Bl -tag -width "pthread_rwlockattr_getpshared()" -compact +.It Fn pthread_rwlock_init +Initialise a read/write lock. +.It Fn pthread_rwlock_destroy +Destroy a read/write lock. +.It Fn pthread_rwlock_rdlock +Acquire a read/write lock for reading. +.It Fn pthread_rwlock_timedrdlock +Attempt to acquire a read/write lock for reading before a specific +point in time. +.It Fn pthread_rwlock_tryrdlock +Attempt to acquire a read/write lock for reading without blocking. +.It Fn pthread_rwlock_wrlock +Acquire a read/write lock for writing. +.It Fn pthread_rwlock_timedwrlock +Attempt to acquire a read/write lock for writing before a specific +point in time. +.It Fn pthread_rwlock_trywrlock +Attempt to acquire a read/write lock for writing without blocking. +.It Fn pthread_rwlock_unlock +Release a read/write lock. +.It Fn pthread_rwlockattr_init +Initialise a read/write lock attributes object. +.It Fn pthread_rwlockattr_destroy +Destroy a read/write lock attributes object. +.It Fn pthread_rwlockattr_getpshared +Get the process shared attribute. +.It Fn pthread_rwlockattr_setpshared +Set the process shared attribute. +.El +.Ss Spinlock Routines +The functions available are as follows: +.Pp +.Bl -tag -width "pthread_spin_trylock()" -compact +.It Fn pthread_spin_init +Initialize a spinlock object. +.It Fn pthread_spin_destroy +Destroy a spinlock object. +.It Fn pthread_spin_lock +Lock a spinlock object. +.It Fn pthread_spin_trylock +Attempt to lock a spinlock without blocking. +.It Fn pthread_spin_unlock +Unlock a spinlock object. +.El +.Ss Thread Routines +The functions available are as follows: +.Pp +.Bl -tag -width "pthread_getconcurrency()" -compact +.It Fn pthread_create +Create a new thread. +.It Fn pthread_cancel +Cancel execution of a thread. +.It Fn pthread_detach +Detach a thread. +.It Fn pthread_equal +Compare thread IDs. +.It Fn pthread_exit +Terminate the calling thread. +.It Fn pthread_getconcurrency +Get level of concurrency. +.It Fn pthread_setconcurrency +Set level of concurrency. +.It Fn pthread_join +Wait for thread termination. +.It Fn pthread_kill +Send a signal to a specific thread. +.It Fn pthread_once +Dynamic package initialisation. +.It Fn pthread_self +Get the calling thread's ID. +.It Fn pthread_setcancelstate +Set cancelability state. +.It Fn pthread_setcanceltype +Set cancelability state. +.It Fn pthread_testcancel +Set cancelability state. +.It Fn pthread_sigmask +Examine/change a thread's signal mask. +.It Fn pthread_getcpuclockid +Get a CPU time clock for a thread. +.El +.Ss Thread stacks +Each thread has a different stack, whether it be provided by a +user attribute, or provided automatically by the system. +If a thread overflows its stack, unpredictable results may occur. +System-allocated stacks (including that of the initial thread) +are typically allocated in such a way that a +.Dv SIGSEGV +signal is delivered to the process when a stack overflows. +.Pp +Signals handlers are normally run on the stack of the currently executing +thread. +Hence, if you want to handle the +.Dv SIGSEGV +signal from stack overflow for a thread, you should use +.Xr sigaltstack 2 +in that thread. +.Ss Thread safety +The following functions are not thread-safe: +.Bd -filled +asctime(), +basename(), +catgets(), +crypt(), +ctime(), +dbm_clearerr(), +dbm_close(), +dbm_delete(), +dbm_error(), +dbm_fetch(), +dbm_firstkey(), +dbm_nextkey(), +dbm_open(), +dbm_store(), +dirname(), +dlerror(), +drand48(), +ecvt(), +encrypt(), +endgrent(), +endpwent(), +fcvt(), +ftw(), +gcvt(), +getc_unlocked(), +getchar_unlocked(), +.\" getdate(), +getenv(), +getgrent(), +getgrgid(), +getgrnam(), +gethostbyaddr(), +gethostbyname(), +gethostent(), +getlogin(), +getnetbyaddr(), +getnetbyname(), +getnetent(), +getopt(), +getprotobyname(), +getprotobynumber(), +getprotoent(), +getpwent(), +getpwnam(), +getpwuid(), +getservbyname(), +getservbyport(), +getservent(), +gmtime(), +hcreate(), +hdestroy(), +hsearch(), +inet_ntoa(), +l64a(), +lgamma(), +lgammaf(), +lgammal(), +localeconv(), +localtime(), +lrand48(), +mrand48(), +nftw(), +nl_langinfo(), +putc_unlocked(), +putchar_unlocked(), +putenv(), +rand(), +readdir(), +setenv(), +setgrent(), +setkey(), +setpwent(), +strerror(), +strsignal(), +strtok(), +ttyname(), +unsetenv(), +wcstombs(), +wctomb() +.Ed +.Pp +The +.Fn ctermid +and +.Fn tmpnam +functions are not thread-safe when passed a +.Dv NULL +argument. +The +.Fn wcrtomb , +.Fn wcsrtombs , +and +.Fn wcsnrtombs +functions are not thread-safe when passed a +.Dv NULL +.Fa ps +argument. +.Sh ENVIRONMENT +.Bl -tag -width "RTHREAD_DEBUG" +.It Ev RTHREAD_DEBUG +Enables debugging output when set to a positive number, +with larger numbers generating more verbose output. +.El +.Sh SEE ALSO +.Xr intro 3 , +.Xr pthread_atfork 3 , +.Xr pthread_attr_init 3 , +.Xr pthread_attr_setdetachstate 3 , +.Xr pthread_attr_setguardsize 3 , +.Xr pthread_attr_setstack 3 , +.Xr pthread_attr_setstackaddr 3 , +.Xr pthread_attr_setstacksize 3 , +.Xr pthread_barrier_init 3 , +.Xr pthread_barrier_wait 3 , +.Xr pthread_barrierattr_getpshared 3 , +.Xr pthread_barrierattr_init 3 , +.Xr pthread_cancel 3 , +.Xr pthread_cleanup_pop 3 , +.Xr pthread_cleanup_push 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_condattr_init 3 , +.Xr pthread_create 3 , +.Xr pthread_detach 3 , +.Xr pthread_equal 3 , +.Xr pthread_exit 3 , +.Xr pthread_get_name_np 3 , +.Xr pthread_getcpuclockid 3 , +.Xr pthread_getspecific 3 , +.Xr pthread_join 3 , +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_kill 3 , +.Xr pthread_main_np 3 , +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_unlock 3 , +.Xr pthread_mutexattr 3 , +.Xr pthread_once 3 , +.Xr pthread_rwlock_destroy 3 , +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_rdlock 3 , +.Xr pthread_rwlock_unlock 3 , +.Xr pthread_rwlock_wrlock 3 , +.Xr pthread_rwlockattr_destroy 3 , +.Xr pthread_rwlockattr_getpshared 3 , +.Xr pthread_rwlockattr_init 3 , +.Xr pthread_rwlockattr_setpshared 3 , +.Xr pthread_schedparam 3 , +.Xr pthread_self 3 , +.Xr pthread_set_name_np 3 , +.Xr pthread_setspecific 3 , +.Xr pthread_sigmask 3 , +.Xr pthread_spin_init 3 , +.Xr pthread_spin_lock 3 , +.Xr pthread_spin_unlock 3 , +.Xr pthread_stackseg_np 3 , +.Xr pthread_testcancel 3 , +.Xr pthread_yield 3 +.Sh STANDARDS +The thread library provides functions that +conform to +.St -p1003.1-96 +and various later versions of +.Pq Dq Tn POSIX . +Consult the manpages for the individual functions for details. +.Sh HISTORY +This 1-to-1 implementation of the +.Nm +API initially appeared in +.Ox 3.9 +under the name +.Dq librthread +as an alternative to the pure-userspace (N-to-1) implementation. +In +.Ox 5.2 +it became the default implementation and was renamed to +.Dq libpthread . +.Sh AUTHORS +.An -nosplit +.An Ted Unangst Aq Mt tedu@openbsd.org , +.An Kurt Miller Aq Mt kurt@openbsd.org , +.An Marco S Hyman Aq Mt marc@openbsd.org , +.An Otto Moerbeek Aq Mt otto@openbsd.org , +and +.An Philip Guenther Aq Mt guenther@openbsd.org . diff --git a/static/openbsd/man3/ptsname.3 b/static/openbsd/man3/ptsname.3 new file mode 100644 index 00000000..eea36a5a --- /dev/null +++ b/static/openbsd/man3/ptsname.3 @@ -0,0 +1,160 @@ +.\" $OpenBSD: ptsname.3,v 1.3 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2002 The FreeBSD Project, Inc. +.\" All rights reserved. +.\" +.\" This software includes code contributed to the FreeBSD Project +.\" by Ryan Younce of North Carolina State University. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the FreeBSD 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 FREEBSD 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 FREEBSD PROJECT +.\" OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED +.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (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/stdlib/ptsname.3 240412 2012-09-12 17:54:09Z emaste $ +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt PTSNAME 3 +.Os +.Sh NAME +.Nm grantpt , +.Nm ptsname , +.Nm unlockpt +.Nd pseudo-terminal access functions +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn grantpt "int fildes" +.Ft char * +.Fn ptsname "int fildes" +.Ft int +.Fn unlockpt "int fildes" +.Sh DESCRIPTION +The +.Fn grantpt , +.Fn ptsname , +and +.Fn unlockpt +functions allow access to pseudo-terminal devices. +These three functions accept a file descriptor that references the +master half of a pseudo-terminal pair. +This file descriptor is created with +.Xr posix_openpt 3 . +.Pp +The +.Fn grantpt +function is used to establish ownership and permissions +of the slave device counterpart to the master device +specified with +.Fa fildes . +The slave device's ownership is set to the real user ID +of the calling process, and the permissions are set to +user readable-writable and group writable. +The group owner of the slave device is also set to the +group +.Dq Li tty . +.Pp +The +.Fn ptsname +function returns the full path name of the slave device +counterpart to the master device specified with +.Fa fildes . +This value can be used +to subsequently open the appropriate slave after +.Xr posix_openpt 3 +and +.Fn grantpt +have been called. +.Pp +The +.Fn unlockpt +function clears the lock held on the pseudo-terminal pair +for the master device specified with +.Fa fildes . +.Sh RETURN VALUES +.Rv -std grantpt unlockpt +.Pp +The +.Fn ptsname +function returns a pointer to the name +of the slave device on success; otherwise a +.Dv NULL +pointer is returned. +.Sh ERRORS +The +.Fn grantpt , +.Fn ptsname +and +.Fn unlockpt +functions may fail and set +.Va errno +to: +.Bl -tag -width Er +.It Bq Er EBADF +.Fa fildes +is not a valid open file descriptor. +.It Bq Er EINVAL +.Fa fildes +is not a master pseudo-terminal device. +.El +.Pp +In addition, the +.Fn grantpt +function may set +.Va errno +to: +.Bl -tag -width Er +.It Bq Er EACCES +The slave pseudo-terminal device could not be accessed. +.El +.Sh SEE ALSO +.Xr posix_openpt 3 , +.Xr pty 4 , +.Xr tty 4 +.Sh STANDARDS +The +.Fn ptsname +function conforms to +.St -p1003.1-2008 . +.Pp +This implementation of +.Fn grantpt +and +.Fn unlockpt +does not conform to +.St -p1003.1-2008 , +because it depends on +.Xr posix_openpt 3 +to create the pseudo-terminal device with proper permissions in place. +It only validates whether +.Fa fildes +is a valid pseudo-terminal master device. +Future revisions of the specification will likely allow this behaviour, +as stated by the Austin Group. +.Sh HISTORY +The +.Fn grantpt , +.Fn ptsname +and +.Fn unlockpt +functions appeared in +.Ox 5.3 . diff --git a/static/openbsd/man3/putc.3 b/static/openbsd/man3/putc.3 new file mode 100644 index 00000000..a5729e22 --- /dev/null +++ b/static/openbsd/man3/putc.3 @@ -0,0 +1,177 @@ +.\" $OpenBSD: putc.3,v 1.15 2025/07/25 18:27:57 tedu 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. +.\" +.Dd $Mdocdate: July 25 2025 $ +.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 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 +.Vt 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 perform the same action, but do not obtain the stream lock. +They require that the stream first be locked with +.Xr flockfile 3 +for thread safe operation. +.Pp +The +.Fn putw +function writes the specified +.Vt int +.Fa w +to the named output +.Fa stream . +.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 and the global variable +.Va errno +is set to indicate the error. +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. +The global variable +.Va errno +may be set to indicate the error. +.Sh ERRORS +The function +.Fn putw +may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr write 2 +or +.Xr realloc 3 . +.Sh SEE ALSO +.Xr ferror 3 , +.Xr flockfile 3 , +.Xr fopen 3 , +.Xr getc 3 , +.Xr putwc 3 , +.Xr stdio 3 +.Sh STANDARDS +The functions +.Fn fputc , +.Fn putc , +and +.Fn putchar , +conform to +.St -ansiC . +The +.Fn putc_unlocked +and +.Fn putchar_unlocked +functions conform to +.St -p1003.1-2024 . +.Sh HISTORY +The +.Fn putc +and +.Fn putw +functions first appeared in +.At v1 ; +.Fn putchar +in +.At v2 ; +and +.Fn fputc +in +.At v7 . +The +.Fn putc_unlocked +and +.Fn putchar_unlocked +functions have been available since +.Ox 2.5 . +.Sh BUGS +Since the size and byte order of an +.Vt int +may vary from one machine to another, +.Fn putw +is not recommended for portable applications. diff --git a/static/openbsd/man3/putwc.3 b/static/openbsd/man3/putwc.3 new file mode 100644 index 00000000..4a59d631 --- /dev/null +++ b/static/openbsd/man3/putwc.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: putwc.3,v 1.5 2017/12/01 11:18:40 schwarze Exp $ +.\" +.\" $NetBSD: putwc.3,v 1.7 2003/09/08 17:54:32 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 $Mdocdate: December 1 2017 $ +.Dt PUTWC 3 +.Os +.Sh NAME +.Nm fputwc , +.Nm putwc , +.Nm putwchar +.Nd output a wide character to a stream +.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 putc 3 , +.Xr stdio 3 +.Sh STANDARDS +The functions +.Fn fputwc , +.Fn putwc , +and +.Fn putwchar , +conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/pw_dup.3 b/static/openbsd/man3/pw_dup.3 new file mode 100644 index 00000000..9b7c3385 --- /dev/null +++ b/static/openbsd/man3/pw_dup.3 @@ -0,0 +1,80 @@ +.\" $OpenBSD: pw_dup.3,v 1.10 2019/01/25 00:19:25 millert Exp $ +.\" +.\" Copyright (c) 2000 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. +.\" +.Dd $Mdocdate: January 25 2019 $ +.Dt PW_DUP 3 +.Os +.Sh NAME +.Nm pw_dup +.Nd make a copy of a struct passwd +.Sh SYNOPSIS +.In pwd.h +.Ft struct passwd * +.Fn pw_dup "const struct passwd *pw" +.Sh DESCRIPTION +The +.Fn pw_dup +function allocates sufficient memory for a copy of the struct passwd +.Fa pw , +does the copy, and returns a pointer to it. +This is useful as subsequent calls to +.Fn getpwent , +.Fn getpwnam , +and +.Fn getpwuid +will overwrite the data they returned from previous calls. +.Pp +The returned pointer should be deallocated by a single call to +.Xr free 3 . +Since +.Fn pw_dup +allocates space for the copy in one chunk, it is not necessary to free +the individual strings contained in the returned struct passwd. +.Pp +If insufficient memory is available, +.Dv NULL +is returned. +.Sh EXAMPLES +The following will make a copy of the struct passwd for root and +store it in +.Qq pw_save : +.Bd -literal -offset indent +struct passwd *pw, *pw_save; + +if ((pw = getpwnam("root")) == NULL) { + fprintf(stderr, "Cannot find root in the password file.\en"); + exit(1); +} +if ((pw_save = pw_dup(pw)) == NULL) { + fprintf(stderr, "Out of memory.\en"); + exit(1); +} +.Ed +.Sh ERRORS +.Fn pw_dup +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 getpwent 3 , +.Xr malloc 3 +.Sh HISTORY +The +.Fn pw_dup +function first appeared in +.Ox 2.9 . diff --git a/static/openbsd/man3/pw_init.3 b/static/openbsd/man3/pw_init.3 new file mode 100644 index 00000000..d74ff6b0 --- /dev/null +++ b/static/openbsd/man3/pw_init.3 @@ -0,0 +1,219 @@ +.\" $OpenBSD: pw_init.3,v 1.16 2025/06/06 22:01:40 schwarze 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 $Mdocdate: June 6 2025 $ +.Dt PW_INIT 3 +.Os +.Sh NAME +.Nm pw_init , +.Nm pw_setdir , +.Nm pw_file , +.Nm pw_edit , +.Nm pw_prompt , +.Nm pw_copy , +.Nm pw_scan , +.Nm pw_error +.Nd utility functions for interactive passwd file updates +.Sh SYNOPSIS +.Lb libutil +.In pwd.h +.In util.h +.Ft void +.Fn pw_init void +.Ft void +.Fn pw_setdir "const char *directory" +.Ft char * +.Fn pw_file "const char *filename" +.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" "const struct passwd *pw" "const struct passwd *opw" +.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_setdir +function sets an alternative directory where the rest of the functions look +for password-related files. +Use this if you are writing utilities that should +be able to handle password files outside of +.Pa /etc . +.Pp +The +.Fn pw_file +function transforms filenames so that they end up in the directory specified +to the latest +.Fn pw_setdir +call. +The rule is that all directories are stripped of the given name and +only the filename is appended to the directory. +.Pp +The +.Fn pw_edit +function runs an editor (named by the environment variable EDITOR, or +.Pa /usr/bin/vi +if EDITOR is not set) on the file +.Fa filename +(or +.Pa /etc/ptmp +if +.Fa filename +is 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 they want 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-\*(Gtpw_name +with the information in +.Fa pw . +If +.Fa opw +is not NULL, opw-\*(Gtpw_name will be used for matching instead. +Additionally, if the existing entry does not match +.Fa opw , +the operation is aborted. +The use of +.Fa opw +allows the caller to change the user name in an entry as well as +guarantee that the entry being replaced has not changed in the +meantime. +.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 is filled in with the following flags: +.Bl -tag -width _PASSWORD_NOGIDxxx +.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 _PASSWD_NOCHG +The change field of +.Fa bp +is empty. +.It Dv _PASSWD_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_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.passwdXXX" -compact +.It Pa /etc/master.passwd +Current password file. +.It Pa /etc/passwd +Legacy password file. +.It Pa /etc/ptmp +Password lock file. +.It Pa /etc/pwd.db +Insecure password database file. +.It Pa /etc/spwd.db +Secure password database file. +.El +.Sh SEE ALSO +.Xr pw_lock 3 , +.Xr passwd 5 diff --git a/static/openbsd/man3/pw_lock.3 b/static/openbsd/man3/pw_lock.3 new file mode 100644 index 00000000..c600017e --- /dev/null +++ b/static/openbsd/man3/pw_lock.3 @@ -0,0 +1,159 @@ +.\" $OpenBSD: pw_lock.3,v 1.21 2025/06/06 22:01:40 schwarze 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 $Mdocdate: June 6 2025 $ +.Dt PW_LOCK 3 +.Os +.Sh NAME +.Nm pw_lock , +.Nm pw_mkdb , +.Nm pw_abort +.Nd passwd file update functions +.Sh SYNOPSIS +.Lb libutil +.In util.h +.Ft int +.Fn pw_lock "int retries" +.Ft int +.Fn pw_mkdb "char *username" "int pwflags" +.Ft void +.Fn pw_abort 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. +A different lock file can be specified with +.Xr pw_file 3 . +.Pp +.Xr pw_init 3 +must be called before +.Fn pw_lock . +.Pp +The +.Fn pw_mkdb +function updates the passwd file from the contents of +.Pa /etc/ptmp +via +.Xr pwd_mkdb 8 . +If a +.Fa username +is specified, only the record for the specified user will be updated. +The +.Fa pwflags +are specified by OR'ing the following values: +.Pp +.Bl -tag -width _PASSWORD_SECUREONLY -offset "xxxx" -compact +.It Dv _PASSWORD_SECUREONLY +only update the secure database file +.Pq Pa /etc/spwd.db . +.It Dv _PASSWORD_OMITV7 +do not update the legacy password file +.Pq Pa /etc/passwd . +.El +.Pp +By default the secure and insecure password databases and +the legacy password file +.Pa /etc/passwd +are updated. +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. +.Pp +The +.Fn pw_abort +function aborts a passwd file update by deleting +.Pa /etc/ptmp . +The passwd database remains unchanged. +.Sh RETURN VALUES +The +.Fn pw_lock +function returns \-1 on error and sets +.Va errno . +The +.Fn pw_mkdb +function returns \-1 if it is unable to complete properly. +.Sh FILES +.Bl -tag -width "/etc/master.passwdXXX" -compact +.It Pa /etc/master.passwd +Current password file. +.It Pa /etc/passwd +Legacy password file. +.It Pa /etc/ptmp +Password lock file. +.It Pa /etc/pwd.db +Insecure password database file. +.It Pa /etc/spwd.db +Secure password database file. +.El +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +.Fn pw_lock +was called before +.Xr pw_init 3 . +.El +.Pp +.Fn pw_lock +may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr open 2 . +.Sh SEE ALSO +.Xr pw_file 3 , +.Xr pw_init 3 , +.Xr pwd_mkdb 8 diff --git a/static/openbsd/man3/qsort.3 b/static/openbsd/man3/qsort.3 new file mode 100644 index 00000000..4c0cddac --- /dev/null +++ b/static/openbsd/man3/qsort.3 @@ -0,0 +1,276 @@ +.\" 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. +.\" +.\" $OpenBSD: qsort.3,v 1.27 2020/02/08 01:09:57 jsg Exp $ +.\" +.Dd $Mdocdate: February 8 2020 $ +.Dt QSORT 3 +.Os +.Sh NAME +.Nm qsort , +.Nm heapsort , +.Nm mergesort +.Nd sort functions +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn qsort "void *base" "size_t nmemb" "size_t size" "int (*compar)(const void *, const void *)" +.Ft int +.Fn heapsort "void *base" "size_t nmemb" "size_t size" "int (*compar)(const void *, const void *)" +.Ft int +.Fn mergesort "void *base" "size_t nmemb" "size_t size" "int (*compar)(const void *, const void *)" +.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 int 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 +function is an implementation of C.A.R. Hoare's +.Dq 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 and will fall back to +.Fn heapsort +if the recursion depth exceeds 2 lg N. +.Pp +The +.Fn heapsort +function is an implementation of J.W.J. William's +.Dq 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. +This implementation of +.Fn heapsort +is implemented without recursive function calls. +.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 , +which is faster than +.Fn heapsort . +Memory availability and pre-existing order in the data can make this untrue. +.Sh RETURN VALUES +.Rv -std heapsort mergesort +.Sh EXAMPLES +.Bd -literal +#include +#include +#include + +char *array[] = { "XX", "YYY", "Z" }; +#define N (sizeof(array) / sizeof(array[0])) + +int +cmp(const void *a, const void *b) +{ + /* + * a and b point to elements of the array. + * Cast and dereference to obtain the actual elements, + * which are also pointers in this case. + */ + size_t lena = strlen(*(const char **)a); + size_t lenb = strlen(*(const char **)b); + /* + * Do not subtract the lengths. The difference between values + * cannot be represented by an int. + */ + return lena < lenb ? -1 : lena > lenb; +} + +int +main() +{ + size_t i; + + qsort(array, N, sizeof(array[0]), cmp); + for (i = 0; i < N; i++) + printf("%s\en", array[i]); +} +.Ed +.Pp +It is almost always an error to use subtraction to compute the return value +of the comparison function. +.Sh ERRORS +The +.Fn heapsort +and +.Fn mergesort +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 +is less than +.Dq "sizeof(void *) / 2" . +.It Bq Er ENOMEM +.Fn heapsort +or +.Fn mergesort +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. +.%T "Optimistic Sorting and Information Theoretic Complexity" +.%J "Fourth Annual ACM-SIAM Symposium on Discrete Algorithms" +.%P pp. 467\-464 +.%D January 1993 +.Re +.Rs +.%A Bentley, J.L. +.%A McIlroy, M.D. +.%T "Engineering a Sort Function" +.%J "Software \- Practice and Experience" +.%V Vol. 23(11) +.%P pp. 1249\-1265 +.%D November 1993 +.Re +.Rs +.%A Musser, D. +.%T "Introspective Sorting and Selection Algorithms" +.%J "Software \- Practice and Experience" +.%V Vol. 27(8) +.%P pp. 983\-993 +.%D August 1997 +.Re +.Sh STANDARDS +Previous versions of +.Fn qsort +did not permit the comparison routine itself to call +.Fn qsort . +This is no longer true. +.Pp +The +.Fn qsort +function conforms to +.St -ansiC . +.Sh HISTORY +A +.Fn qsort +function first appeared in +.At v2 . diff --git a/static/openbsd/man3/radius_new_request_packet.3 b/static/openbsd/man3/radius_new_request_packet.3 new file mode 100644 index 00000000..de9ef266 --- /dev/null +++ b/static/openbsd/man3/radius_new_request_packet.3 @@ -0,0 +1,387 @@ +.\" $OpenBSD: radius_new_request_packet.3,v 1.8 2025/06/09 02:07:30 schwarze Exp $ +.\" +.\" Copyright (c) 2009 Internet Initiative Japan 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 $Mdocdate: June 9 2025 $ +.Dt RADIUS_NEW_REQUEST_PACKET 3 +.Os +.Sh NAME +.Nm radius_new_request_packet , +.Nm radius_new_response_packet , +.Nm radius_convert_packet , +.Nm radius_delete_packet , +.Nm radius_get_id , +.Nm radius_get_code , +.Nm radius_get_authenticator , +.Nm radius_get_authenticator_retval , +.Nm radius_get_length , +.Nm radius_update_id , +.Nm radius_set_id , +.Nm radius_set_request_packet , +.Nm radius_get_request_packet , +.Nm radius_set_response_authenticator , +.Nm radius_check_response_authenticator , +.Nm radius_set_accounting_request_authenticator , +.Nm radius_check_accounting_request_authenticator , +.Nm radius_get_request_authenticator_retval , +.Nm radius_get_data , +.Nm radius_get_raw_attr , +.Nm radius_put_raw_attr , +.Nm radius_get_raw_attr_cat , +.Nm radius_put_raw_attr_cat , +.Nm radius_get_raw_attr_ptr , +.Nm radius_set_raw_attr , +.Nm radius_del_attr_all , +.Nm radius_has_attr , +.Nm radius_get_vs_raw_attr , +.Nm radius_put_vs_raw_attr , +.Nm radius_get_vs_raw_attr_cat , +.Nm radius_put_vs_raw_attr_cat , +.Nm radius_get_vs_raw_attr_ptr , +.Nm radius_set_vs_raw_attr , +.Nm radius_del_vs_attr_all , +.Nm radius_has_vs_attr , +.Nm radius_get_uint16_attr , +.Nm radius_get_uint32_attr , +.Nm radius_get_uint64_attr , +.Nm radius_get_ipv4_attr , +.Nm radius_get_ipv6_attr , +.Nm radius_put_uint16_attr , +.Nm radius_put_uint32_attr , +.Nm radius_put_uint64_attr , +.Nm radius_put_ipv4_attr , +.Nm radius_put_ipv6_attr , +.Nm radius_set_uint16_attr , +.Nm radius_set_uint32_attr , +.Nm radius_set_uint64_attr , +.Nm radius_set_ipv4_attr , +.Nm radius_set_ipv6_attr , +.Nm radius_get_string_attr , +.Nm radius_put_string_attr , +.Nm radius_get_vs_uint16_attr , +.Nm radius_get_vs_uint32_attr , +.Nm radius_get_vs_uint64_attr , +.Nm radius_get_vs_ipv4_attr , +.Nm radius_get_vs_ipv6_attr , +.Nm radius_put_vs_uint16_attr , +.Nm radius_put_vs_uint32_attr , +.Nm radius_put_vs_uint64_attr , +.Nm radius_put_vs_ipv4_attr , +.Nm radius_put_vs_ipv6_attr , +.Nm radius_set_vs_uint16_attr , +.Nm radius_set_vs_uint32_attr , +.Nm radius_set_vs_uint64_attr , +.Nm radius_set_vs_ipv4_attr , +.Nm radius_set_vs_ipv6_attr , +.Nm radius_get_vs_string_attr , +.Nm radius_put_vs_string_attr , +.Nm radius_put_message_authenticator , +.Nm radius_set_message_authenticator , +.Nm radius_check_message_authenticator , +.Nm radius_encrypt_user_password_attr , +.Nm radius_decrypt_user_password_attr , +.Nm radius_encrypt_mppe_key_attr , +.Nm radius_decrypt_mppe_key_attr , +.Nm radius_get_user_password_attr , +.Nm radius_put_user_password_attr , +.Nm radius_get_mppe_send_key_attr , +.Nm radius_put_mppe_send_key_attr , +.Nm radius_get_mppe_recv_key_attr , +.Nm radius_put_mppe_recv_key_attr , +.Nm radius_get_eap_msk , +.Nm radius_send , +.Nm radius_sendmsg , +.Nm radius_sendto , +.Nm radius_recv , +.Nm radius_recvfrom , +.Nm radius_recvmsg , +.Nm radius +.Nd manipulate RADIUS packets for RADIUS clients/servers +.Sh SYNOPSIS +.Lb libradius +.In sys/types.h +.In sys/socket.h +.In netinet/in.h +.In stdbool.h +.In radius.h +.Sh DESCRIPTION +.Nm radius +provides a facility to manipulate RADIUS packets and some helper functions. +.Sh CREATING AND DESTROYING PACKETS +RADIUS packet objects are created by +.Fn radius_new_request_packet , +.Fn radius_new_response_packet +or +.Fn radius_convert_packet . +The authenticator field of the packet that is returned by +.Fn radius_new_request_packet +and +.Fn radius_new_response_packet +is filled with random bytes. +.Pp +You must call +.Fn radius_delete_packet +to free memory associated with the packet object. +.Sh HEADER ACCESSOR +.Fn radius_get_id , +.Fn radius_get_code , +.Fn radius_get_authenticator , +.Fn radius_get_authenticator_retval +and +.Fn radius_get_length +retrieves the specified property of the packet. +.Fn radius_update_id +updates a packet's ID field with an internal ID counter. +.Fn radius_set_id +sets a packet's ID field. +.Pp +.Fn radius_set_request_packet +associates a request packet to a response packet. +The associated request packet can be retrieved by +.Fn radius_get_request_packet . +.Pp +.Fn radius_set_response_authenticator +sets a response authenticator to a response packet. +.Fn radius_check_response_authenticator +checks the response authenticator of a response packet. +The request packet must be associated with a response packet by +.Fn radius_new_response_packet +or +.Fn radius_set_request_packet . +.Pp +.Fn radius_set_accounting_request_authenticator +sets a request authenticator to an accounting request packet. +.Fn radius_check_accounting_request_authenticator +checks a request authenticator of an accounting request packet. +.Pp +.Fn radius_get_request_authenticator_retval +returns the authenticator field of the packet if the argument is +a request packet, and returns that of the associated request packet +if the argument is a response packet. +.Pp +.Fn radius_get_data +returns packet data itself. +.Sh RAW ATTRIBUTE ACCESSOR +.Fn radius_get_raw_attr +retrieves an attribute value. +.Fa length +is a value-result parameter, initially containing the size of the buffer +and modified on return to indicate the size of the value returned. +If the buffer size is not sufficient, the returned value is truncated. +.Pp +.Fn radius_put_raw_attr +appends attribute data to the end of the packet. +If buffer size is larger than the maximum size of a single attribute, +the function returns an error. +.Pp +.Fn radius_get_raw_attr_cat +retrieves an attribute value. +Unlike +.Fn radius_get_raw_attr , +.Fn radius_get_raw_attr_cat +retrieves ALL attribute values that have the specified attribute type +concatenated. +If the buffer size is not sufficient, the function returns an error. +If +.Fa buf +is +.Dv NULL , +the initial value of +.Fa length +is ignored and the actual size of concatenated values is returned. +.Pp +.Fn radius_put_raw_attr_cat +appends attribute data to the last of the packet. +Unlike +.Fn radius_put_raw_attr , +.Fn radius_put_raw_attr_cat +divides data into multiple attributes and appends them if the buffer size is +larger than the maximum size of a single attribute. +Note that packet objects may be broken (but can be deleted normally by +.Fn radius_delete_packet ) +if this function has returned an error. +.Pp +.Fn radius_get_raw_attr_ptr +retrieves a pointer and length of specified attribute. +The returned buffer must not be modified. +.Pp +.Fn radius_set_raw_attr +overwrites existing an attribute value. +If the specified attribute does not exist, this function returns an error. +If +.Fa length +is different from the length of the specified attribute, +the function returns an error. +.Pp +.Fn radius_del_attr_all +deletes all attributes matching its arguments. +.Pp +.Fn radius_has_attr +returns whether packet has a specified attribute. +.Pp +.Fn radius_get_vs_raw_attr , +.Fn radius_put_vs_raw_attr , +.Fn radius_get_vs_raw_attr_cat , +.Fn radius_put_vs_raw_attr_cat , +.Fn radius_get_vs_raw_attr_ptr , +.Fn radius_set_vs_raw_attr , +.Fn radius_del_vs_attr_all +and +.Fn radius_has_vs_attr +are vendor-specific versions of raw attribute accessors. +.Sh TYPED ATTRIBUTE ACCESSOR +To make code simple, there are many typed attribute accessors. +.Nm radius +provides typed accessors for +.Vt uint16_t , +.Vt uint32_t , +.Vt uint64_t , +.Vt struct in_addr +and +.Vt struct in6_addr . +Byte endian may be appropriately swapped for +.Vt uint16_t , +.Vt uint32_t +and +.Vt uint64_t . +.Pp +These typed accessors do not requires +.Fa length +parameters because length is implied by the type. +For "get" functions, if the actual attribute size is different from the size of +the type, the functions return an error. +.Pp +There are also typed accessors for string +.Pq Li char * . +For "get" functions for strings, the returned string is always NUL-terminated +even if buffer size is smaller than actual attribute size. +This behavior is similar to +.Fn strlcpy . +.Sh MESSAGE AUTHENTICATOR +There are helper functions for Message-Authenticator attributes. +.Pp +.Fn radius_put_message_authenticator +and +.Fn radius_set_message_authenticator +calculate a Message-Authenticator and put or set it to packet, respectively. +When +.Fn radius_put_message_authenticator +is used, +the Message-Authenticator attribute is placed at the first in the attributes. +.Pp +.Fn radius_check_message_authenticator +checks a Message-Authenticator. +.Pp +The request packet must be associated with a response packet by +.Fn radius_new_response_packet +or +.Fn radius_set_request_packet , +otherwise the packet is treated as a request packet. +.Sh ENCRYPTED ATTRIBUTE +There are helper functions for encrypted attributes. +.Pp +.Fn radius_encrypt_user_password_attr , +.Fn radius_decrypt_user_password_attr , +.Fn radius_encrypt_mppe_key_attr +and +.Fn radius_decrypt_mppe_key_attr +encrypt or decrypt User-Password attribute or MS-MPPE-{Send,Recv}-Key +attributes respectively. +.Pp +.Fn radius_get_user_password_attr , +.Fn radius_put_user_password_attr , +.Fn radius_get_mppe_send_key_attr , +.Fn radius_put_mppe_send_key_attr , +.Fn radius_get_mppe_recv_key_attr +and +.Fn radius_put_mppe_recv_key_attr +are shortcuts of combination of encrypt/decrypt functions +and get/put functions. +.Pp +.Fn radius_get_eap_msk +retrieves a Master Session Key (MSK) for Extensible Authentication Protocol +(EAP). +Currently retrieving an MSK from MS-MPPE key attributes is supported. +.Sh SENDING AND RECEIVING PACKETS +There are helper functions for sending and receiving packets. +.Pp +.Fn radius_send , +.Fn radius_sendto , +.Fn radius_sendmsg , +.Fn radius_recv , +.Fn radius_recvfrom +and +.Fn radius_recvmsg +are helper version of +.Fn send , +.Fn sendto , +.Fn sendmsg , +.Fn recv , +.Fn recvfrom +and +.Fn recvmsg , +respectively. +.Pp +.Fn radius_send , +.Fn radius_sendto +and +.Fn radius_sendmsg +return 0 on success and nonzero on failure. +.Pp +.Fn radius_recv +.Fn radius_recvfrom +and +.Fn radius_recvmsg +return the received packet on success and return NULL on failure. +.Pp +Note that +.Li msg_iov +must be +.Li NULL +and +.Li msg_iovlen +must be zero in case of +.Fn radius_sendmsg +and +.Fn radius_recvmsg . +.Sh RETURN VALUES +Functions that return int return 0 on success and nonzero on failure. +Functions that return pointer return non-NULL pointer on success and +NULL on failure. +.Sh HISTORY +The +.Nm radius+ +library was first written by UMEZAWA Takeshi in 2002 for the ID Gateway service +of Internet Initiative Japan Inc. +YASUOKA Masahiko added support for Message-Authenticator attributes in 2008. +.Ox +project rewrote C++ code to pure C code in 2010. +The +.Nm radius+ +library was renamed +.Nm radius +and moved to +.Pa lib/ +in 2013. diff --git a/static/openbsd/man3/radixsort.3 b/static/openbsd/man3/radixsort.3 new file mode 100644 index 00000000..7290142a --- /dev/null +++ b/static/openbsd/man3/radixsort.3 @@ -0,0 +1,151 @@ +.\" 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. +.\" +.\" $OpenBSD: radixsort.3,v 1.14 2022/08/04 06:20:24 jsg Exp $ +.\" +.Dd $Mdocdate: August 4 2022 $ +.Dt RADIXSORT 3 +.Os +.Sh NAME +.Nm radixsort , +.Nm sradixsort +.Nd radix sort +.Sh SYNOPSIS +.In limits.h +.In stdlib.h +.Ft int +.Fn radixsort "const u_char **base" "int nmemb" "const u_char *table" "u_int endbyte" +.Ft int +.Fn sradixsort "const u_char **base" "int nmemb" "const 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 array of +.Fa nmemb +pointers to byte strings. +The initial member is referenced by +.Fa base . +The byte strings may contain any values; the end of each string +is denoted by the user-specified value +.Fa endbyte . +.Pp +Applications may specify a sort order by providing the +.Fa table +argument. +If non-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 +.Dv NULL , +the contents of the array are sorted in ascending order according to the +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 +.Rv -std +.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 +.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.3 Net/2 . diff --git a/static/openbsd/man3/raise.3 b/static/openbsd/man3/raise.3 new file mode 100644 index 00000000..1aa2c259 --- /dev/null +++ b/static/openbsd/man3/raise.3 @@ -0,0 +1,68 @@ +.\" $OpenBSD: raise.3,v 1.11 2015/01/29 01:46:30 schwarze 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. +.\" +.Dd $Mdocdate: January 29 2015 $ +.Dt RAISE 3 +.Os +.Sh NAME +.Nm raise +.Nd send a signal to the current thread +.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 +.Rv -std +.Sh ERRORS +.Fn raise +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. +.El +.Sh SEE ALSO +.Xr kill 2 +.Sh STANDARDS +The +.Fn raise +function conforms to +.St -ansiC +and +.St -p1003.1-2008 . diff --git a/static/openbsd/man3/rand.3 b/static/openbsd/man3/rand.3 new file mode 100644 index 00000000..cf7dde85 --- /dev/null +++ b/static/openbsd/man3/rand.3 @@ -0,0 +1,135 @@ +.\" 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. +.\" +.\" $OpenBSD: rand.3,v 1.21 2022/03/29 18:15:52 naddy Exp $ +.\" +.Dd $Mdocdate: March 29 2022 $ +.Dt RAND 3 +.Os +.Sh NAME +.Nm rand , +.Nm rand_r , +.Nm srand , +.Nm srand_deterministic +.Nd bad pseudo-random number generator +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn srand "unsigned int seed" +.Ft void +.Fn srand_deterministic "unsigned int seed" +.Ft int +.Fn rand void +.Ft int +.Fn rand_r "unsigned int *seed" +.Sh DESCRIPTION +.Bf -symbolic +Standards insist that this interface return deterministic results. +Unsafe usage is very common, so +.Ox +changed the subsystem to return non-deterministic results by default. +.Ef +.Pp +To satisfy portable code, +.Fn srand +may be called to initialize the subsystem. +In +.Ox +the +.Ar seed +variable is ignored, and strong random number results will be provided from +.Xr arc4random 3 . +In other systems, the +.Ar seed +variable primes a simplistic deterministic algorithm. +.Pp +If the standardized behavior is required +.Fn srand_deterministic +can be substituted for +.Fn srand , +then subsequent +.Fn rand +calls will return results using the deterministic algorithm. +The deterministic sequence algorithm changed a number of times since +original development, is underspecified, and should not be relied upon to +remain consistent between platforms and over time. +.Pp +The +.Fn rand +function returns a result in the range of 0 to +.Dv RAND_MAX . +By default, this result comes from +.Xr arc4random 3 . +If +.Fn srand_deterministic +was called, the result will be computed using the deterministic algorithm. +.Pp +The +.Fn rand_r +function is a thread-safe version of +.Fn rand . +Storage for the seed must be provided through the +.Fa seed +argument, and needs to have been initialized by the caller. +It always operates using the deterministic algorithm. +.Sh SEE ALSO +.Xr arc4random 3 , +.Xr rand48 3 , +.Xr random 3 +.Sh STANDARDS +The +.Fn rand +function conforms to +.St -ansiC . +.Pp +The +.Fn rand_r +function conforms to +.St -p1003.1-2008 . +.Pp +The +.Fn srand +function does not conform to +.St -ansiC , +intentionally. +.Pp +The +.Fn srand_deterministic +function is an +.Ox +extension. +.Sh HISTORY +The functions +.Fn rand +and +.Fn srand +first appeared in +.At v3 . diff --git a/static/openbsd/man3/rand48.3 b/static/openbsd/man3/rand48.3 new file mode 100644 index 00000000..02e1999d --- /dev/null +++ b/static/openbsd/man3/rand48.3 @@ -0,0 +1,240 @@ +.\" 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. +.\" +.\" $OpenBSD: rand48.3,v 1.22 2025/06/13 18:34:00 schwarze Exp $ +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt DRAND48 3 +.Os +.Sh NAME +.Nm drand48 , +.Nm erand48 , +.Nm lrand48 , +.Nm nrand48 , +.Nm mrand48 , +.Nm jrand48 , +.Nm srand48 , +.Nm srand48_deterministic , +.Nm seed48 , +.Nm seed48_deterministic , +.Nm lcong48 , +.Nm lcong48_deterministic +.Nd pseudo-random number generators and initialization routines +.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 void +.Fn srand48_deterministic "long seed" +.Ft unsigned short * +.Fn seed48 "unsigned short xseed[3]" +.Ft unsigned short * +.Fn seed48_deterministic "unsigned short xseed[3]" +.Ft void +.Fn lcong48 "unsigned short p[7]" +.Ft void +.Fn lcong48_deterministic "unsigned short p[7]" +.Sh DESCRIPTION +.Bf -symbolic +Standards insist that this interface return deterministic results. +Unsafe usage is very common, so +.Ox +changed the subsystem to return non-deterministic results by default. +.Ef +.Pp +To satisfy portable code, +.Fn srand48 , +.Fn seed48 , +or +.Fn lcong48 +should be called to initialize the subsystem. +In +.Ox +the +seeding parameters are ignored, and strong random number results will be +provided from +.Xr arc4random 3 . +In other systems, the +parameters prime a simplistic deterministic algorithm. +.Pp +If the standardized behavior is required then +.Fn srand48_deterministic , +.Fn seed48_deterministic , +and +.Fn lcong48_deterministic +can be substituted for +.Fn srand48 , +.Fn seed48 , +and +.Fn lcong48 . +That will cause subsequent +calls to +.Fn drand48 , +.Fn lrand48 , +and +.Fn jrand48 +to return results using the deterministic algorithm. +.Pp +.Fn drand48 +and +.Fn erand48 +return values of type double. +The full 48 bits of r(n+1) are +loaded into the mantissa 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 +In the deterministic mode, the +.Fn rand48 +family of functions generates 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 = 0xfdeece66d = 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 , +.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 shorts, where the zeroth member +holds the least significant bits. +.Pp +All functions share the same multiplicand and addend. +.Pp +.Fn srand48_deterministic +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_deterministic +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 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_deterministic +returns a pointer to an array of 3 shorts which contains the old seed. +This array is statically allocated, so its contents are lost after +each new call to +.Fn seed48_deterministic . +.Pp +Finally, +.Fn lcong48_deterministic +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 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. +.Sh SEE ALSO +.Xr arc4random 3 , +.Xr rand 3 , +.Xr random 3 +.Sh STANDARDS +The +.Fn drand48 , +.Fn erand48 , +.Fn jrand48 , +.Fn lrand48 , +.Fn mrand48 , +and +.Fn nrand48 , +functions conform to +.St -p1003.1-2008 . +.Pp +The +.Fn seed48 , +.Fn srand48 , +and +.Fn lcong48 +function do not conform to +.St -ansiC , +intentionally. +.Pp +The +.Fn seed48_deterministic , +.Fn srand48_deterministic , +and +.Fn lcong48_deterministic +functions are +.Ox +extensions. +.Sh AUTHORS +.An Martin Birgmeier diff --git a/static/openbsd/man3/random.3 b/static/openbsd/man3/random.3 new file mode 100644 index 00000000..0770d20f --- /dev/null +++ b/static/openbsd/man3/random.3 @@ -0,0 +1,197 @@ +.\" Copyright (c) 1983, 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. +.\" +.\" $OpenBSD: random.3,v 1.29 2021/02/12 17:03:51 deraadt Exp $ +.\" +.Dd $Mdocdate: February 12 2021 $ +.Dt RANDOM 3 +.Os +.Sh NAME +.Nm random , +.Nm srandom , +.Nm srandom_deterministic , +.Nm srandomdev , +.Nm initstate , +.Nm setstate +.Nd pseudo-random number generator; routines for changing generators +.Sh SYNOPSIS +.In stdlib.h +.Ft long +.Fn random void +.Ft void +.Fn srandom "unsigned int seed" +.Ft void +.Fn srandom_deterministic "unsigned int seed" +.Ft void +.Fn srandomdev void +.Ft char * +.Fn initstate "unsigned int seed" "char *state" "size_t n" +.Ft char * +.Fn setstate "char *state" +.Sh DESCRIPTION +.Bf -symbolic +Standards insist that this interface return deterministic results. +Unsafe usage is very common, so +.Ox +changed the subsystem to return non-deterministic results by default. +.Ef +.Pp +To satisfy portable code, +.Fn srandom +or +.Fn srandomdev +may be called to initialize the subsystem. +In +.Ox +the +.Ar seed +variable is ignored, and strong random number results will be provided from +.Xr arc4random 3 . +In other systems, the +.Ar seed +variable primes a simplistic deterministic algorithm. +.Pp +If the standardized behavior is required +.Fn srandom_deterministic +can be substituted for +.Fn srandom , +then subsequent +.Fn random +calls will return results using the deterministic algorithm. +.Pp +In non-deterministic (default) mode, the +.Fn random +function returns results from +.Xr arc4random 3 +in the range from 0 to (2**31)\-1. +.Pp +In deterministic mode, 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 (2**31)\-1. +The period of this random number generator is very large, approximately +16*((2**31)\-1), but the results are a deterministic sequence from the seed. +The deterministic sequence algorithm changed a number of times since +original development, is underspecified, and should not be relied upon to +remain consistent between platforms and over time. +.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 less 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 +.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 +Use of +.Fn srandom_deterministic , +.Fn initstate , +or +.Fn setstate +forces the subsystem into deterministic mode. +.Sh DIAGNOSTICS +If +.Fn initstate +is called with less 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 arc4random 3 , +.Xr drand48 3 , +.Xr rand 3 , +.Xr random 4 +.Sh STANDARDS +The +.Fn random , +.Fn initstate , +and +.Fn setstate +functions conform to +.St -xpg4.2 . +.Pp +The +.Fn srandom +function does not conform to +.St -xpg4.2 , +intentionally. +.Pp +The +.Fn srandomdev +function is an extension. +.Pp +The +.Fn srandom_deterministic +function is an +.Ox +extension. +.Sh HISTORY +These +functions appeared in +.Bx 4.2 . +.Sh AUTHORS +.An Earl T. Cohen diff --git a/static/openbsd/man3/rcmd.3 b/static/openbsd/man3/rcmd.3 new file mode 100644 index 00000000..b2a5cdea --- /dev/null +++ b/static/openbsd/man3/rcmd.3 @@ -0,0 +1,232 @@ +.\" $OpenBSD: rcmd.3,v 1.34 2016/05/28 15:48:30 millert 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 $Mdocdate: May 28 2016 $ +.Dt RCMD 3 +.Os +.Sh NAME +.Nm rcmd , +.Nm rcmd_af , +.Nm rresvport , +.Nm rresvport_af , +.Nm ruserok +.Nd routines for returning a stream to a remote command +.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 rcmd_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 af" +.Ft int +.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" +.Sh DESCRIPTION +The +.Fn rcmd +function is used by the superuser to execute a command on a remote +machine using an authentication scheme based on reserved +port numbers. +If the calling process is not setuid, the +.Ev RSH +environment variable is set, and +.Fa inport +is +.Dq shell/tcp , +.Xr rcmdsh 3 +is called instead with the value of +.Ev RSH . +Alternately, if the user is not the superuser, +.Fn rcmd +will invoke +.Xr rcmdsh 3 +to run the command via +.Xr ssh 1 . +While +.Fn rcmd +can handle IPv4 cases only, +the +.Fn rcmd_af +function can handle other cases as well. +.Pp +The +.Fn rresvport +and +.Fn rresvport_af +functions return a descriptor to a socket +with an address in the privileged port space. +The +.Fn ruserok +function is used by servers +to authenticate clients requesting service with +.Fn rcmd . +.Pp +The +.Fn rcmd +function looks up the host +.Fa *ahost +using +.Xr getaddrinfo 3 +and, if the host exists, +.Fa *ahost +is set to the canonical name of the host. +A connection is then established to a server +residing at the well-known Internet port +.Fa inport . +If the user is not the superuser, the only valid port is +.Dq shell/tcp +(usually port 514). +.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 stdin and 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 +.Tn UNIX +signal numbers, to be +forwarded to the process group of the command. +If +.Fa fd2p +is +.Va NULL , +then the standard error (unit 2 of the remote command) will be made +the same as the standard output 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. +Note that if the user is not the superuser, +.Fa fd2p +must be +.Va NULL . +.Pp +.Fn rcmd_af +takes address family in the last argument. +If the last argument is +.Dv AF_UNSPEC , +interpretation of +.Fa *ahost +will obey the underlying address resolution like DNS. +.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 +.Va IPPORT_RESERVED - 1 , +which happens to be 1023. +Only the superuser is allowed to bind an address of this sort to a socket. +.Fn rresvport +and +.Fn rresvport_af +need to be seeded with a port number; if that port +is not available these functions will find another. +.Pp +The +.Fn ruserok +function takes a remote host's name, two user names, +and a flag indicating whether the local user's +name is that of the superuser. +Then, if the user is +.Em not +the superuser, 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 superuser, or is writeable by anyone other +than the owner, the check automatically fails. +Zero is returned if the machine name is listed in the +.Pa hosts.equiv +file, or the host and remote user name are found in the +.Pa .rhosts +file; otherwise +.Fn ruserok +returns \-1. +If the local domain (as obtained from +.Xr getaddrinfo 3 ) +is the same as the remote domain, only the machine name need be specified. +.Pp +.Fn ruserok +implicitly requires trusting the DNS server for the remote host's domain. +.Sh DIAGNOSTICS +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 +functions return a valid, bound socket descriptor on success. +It returns \-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 +.Dq all network ports in use . +.Sh SEE ALSO +.Xr ssh 1 , +.Xr intro 2 , +.Xr bindresvport 3 , +.Xr bindresvport_sa 3 , +.Xr rcmdsh 3 +.Sh HISTORY +These +functions appeared in +.Bx 4.2 . +.Pp +The +.Fn iruserok +and +.Fn iruserok_sa +functions, IP address based versions of +.Fn ruserok , +were removed in +.Ox 6.0 . diff --git a/static/openbsd/man3/rcmdsh.3 b/static/openbsd/man3/rcmdsh.3 new file mode 100644 index 00000000..9092d19f --- /dev/null +++ b/static/openbsd/man3/rcmdsh.3 @@ -0,0 +1,95 @@ +.\" $OpenBSD: rcmdsh.3,v 1.18 2016/05/28 15:48:30 millert 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 $Mdocdate: May 28 2016 $ +.Dt RCMDSH 3 +.Os +.Sh NAME +.Nm rcmdsh +.Nd return a stream to a remote command without superuser +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn rcmdsh "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "char *rshprog" +.Sh DESCRIPTION +The +.Fn rcmdsh +function is used by normal users to execute a command on a remote machine +using an authentication scheme based on reserved port numbers using +.Xr ssh 1 +or the value of +.Fa rshprog +(if non-null). +.Fa rshprog +may be a fully-qualified path, a non-qualified command, or a command containing +space-separated command line arguments. +.Pp +The +.Fn rcmdsh +function looks up the host +.Fa *ahost +using +.Xr getaddrinfo 3 +and, if the host exists, +.Fa *ahost +is set to the canonical name of the host. +A connection is then established to +a server residing at the well-known Internet port +.Li shell/tcp +(or whatever port is used by +.Fa rshprog ) . +The parameter +.Fa inport +is ignored; it is only included to provide an interface similar to +.Xr rcmd 3 . +.Pp +If the connection succeeds, a socket in the +.Ux Ns -domain +of type +.Dv SOCK_STREAM +is returned to the caller, and given to the remote +command as stdin and stdout, and stderr. +.Sh DIAGNOSTICS +The +.Fn rcmdsh +function returns a valid socket descriptor on success. +It returns \-1 on error and prints a diagnostic message on the standard error. +.Sh SEE ALSO +.Xr ssh 1 , +.Xr socketpair 2 , +.Xr rcmd 3 +.Sh HISTORY +The +.Fn rcmdsh +function first appeared in +.Ox 2.0 . +.Sh BUGS +If +.Xr ssh 1 +encounters an error, a file descriptor is still returned instead of \-1. diff --git a/static/openbsd/man3/readlabelfs.3 b/static/openbsd/man3/readlabelfs.3 new file mode 100644 index 00000000..0306feba --- /dev/null +++ b/static/openbsd/man3/readlabelfs.3 @@ -0,0 +1,62 @@ +.\" $OpenBSD: readlabelfs.3,v 1.9 2025/06/06 22:01:40 schwarze Exp $ +.\" +.\" Copyright (c) 1996, Jason Downs. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(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 AUTHOR(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 $Mdocdate: June 6 2025 $ +.Dt READLABELFS 3 +.Os +.Sh NAME +.Nm readlabelfs +.Nd read disklabel filesystem type +.Sh SYNOPSIS +.Lb libutil +.In util.h +.Ft char * +.Fn readlabelfs "char *device" "int verbose" +.Sh DESCRIPTION +The +.Fn readlabelfs +function attempts to determine the filesystem type of the disk +partition specified by +.Fa device +and returns it in a short form that can be easily used to construct +arguments within +.Xr mount 8 +and similar high-level filesystem utilities. +.Pp +If the +.Fa verbose +argument is not 0, +.Fn readlabelfs +will print appropriate error messages before returning. +Otherwise, it produces no output on the terminal. +.Sh RETURN VALUES +.Fn readlabelfs +returns +.Dv NULL +upon error, or a valid filesystem type upon success. +.Sh HISTORY +.Fn readlabelfs +first appeared in +.Ox 2.0 . diff --git a/static/openbsd/man3/readline.3 b/static/openbsd/man3/readline.3 new file mode 100644 index 00000000..59d03bcd --- /dev/null +++ b/static/openbsd/man3/readline.3 @@ -0,0 +1,1272 @@ +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Information Network Services +.\" Case Western Reserve University +.\" chet@ins.CWRU.Edu +.\" +.\" Last Change: Tue Jan 22 09:18:25 EST 2002 +.\" +.TH READLINE 3 "2002 January 22" "GNU Readline 4.3" +.\" +.\" 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 +#include +#include +.ft +.fi +.LP +.nf +\fIchar *\fP +.br +\fBreadline\fP (\fIconst char *prompt\fP); +.fi +.SH COPYRIGHT +.if n Readline is Copyright (C) 1989\-2002 by the Free Software Foundation, Inc. +.if t Readline is Copyright \(co 1989\-2002 by the 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. +.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 . +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 +.PP +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. +.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 +.PP +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). +The variables and their default values are: +.PP +.PD 0 +.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 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\-ignore\-case (Off) +If set to \fBOn\fP, readline performs filename matching and completion +in a case\-insensitive fashion. +.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, the user is asked whether +or not he wishes to view them; otherwise they are simply listed +on the terminal. +.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). +.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 editing\-mode (emacs) +Controls whether readline begins with a set of key bindings similar +to emacs or vi. +.B editing\-mode +can be set to either +.B emacs +or +.BR vi . +.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 expand\-tilde (Off) +If set to \fBon\fP, tilde expansion is performed when readline +attempts word completion. +.TP +.B history-preserve-point +If set to \fBon\fP, the history code attempts to place point at the +same location on each history line retrived with \fBprevious-history\fP +or \fBnext-history\fP. +.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. +.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. +.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 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, unless the leading `.' is +supplied by the user in the filename to be completed. +.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. +.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 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 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 +.PP +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 extends to the end of the line; +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 \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 Bash: +.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 +.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 +.PP +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 +.PP +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 +.PP +.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 clear\-screen (C\-l) +Clear the screen 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 +.PP +.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 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\-forward +Search forward through the history for the string of characters +between the start of the current line and the current cursor +position (the \fIpoint\fP). +This is a non-incremental search. +.TP +.B history\-search\-backward +Search backward through the history for the string of characters +between the start of the current line and the point. +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. +.TP +.B +yank\-last\-arg (M\-.\^, M\-_\^) +Insert the last argument to the previous command (the last word of +the previous history entry). With an argument, +behave exactly like \fByank\-nth\-arg\fP. +Successive calls to \fByank\-last\-arg\fP move back through the history +list, inserting the last argument of each line in turn. +.PD +.SS Commands for Changing Text +.PP +.PD 0 +.TP +.B delete\-char (C\-d) +Delete the character at point. If point is at the +beginning of the line, there are no characters in the line, and +the last character typed was not bound to \fBdelete\-char\fP, then return +.SM +.BR EOF . +.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 +.PP +.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 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 +.PP +.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 +.PP +.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. +.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 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 +.PP +.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. +.PD +.SS Miscellaneous +.PP +.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\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...) +If the metafied character \fIx\fP is lowercase, run the command +that is bound to the corresponding uppercase character. +.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\-) +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 count 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 count searches for subsequent occurrences. +.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 ouput. 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\-, 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-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@ins.CWRU.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@ins.CWRU.Edu . +.SH BUGS +.PP +It's too big and too slow. diff --git a/static/openbsd/man3/readpassphrase.3 b/static/openbsd/man3/readpassphrase.3 new file mode 100644 index 00000000..eb35952e --- /dev/null +++ b/static/openbsd/man3/readpassphrase.3 @@ -0,0 +1,167 @@ +.\" $OpenBSD: readpassphrase.3,v 1.21 2019/01/25 00:19:25 millert Exp $ +.\" +.\" Copyright (c) 2000, 2002 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 $Mdocdate: January 25 2019 $ +.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 +The +.Fa flags +argument is the bitwise +.Tn OR +of zero or more of the following values: +.Bd -literal -offset indent +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 +RPP_STDIN read passphrase from stdin; ignore prompt +.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 +Upon successful completion, +.Fn readpassphrase +returns a pointer to the NUL-terminated passphrase. +If an error is encountered, the terminal state is restored and +a null pointer is returned. +.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"); + +\&... + +explicit_bzero(passbuf, sizeof(passbuf)); +.Ed +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINTR +The +.Fn readpassphrase +function was interrupted by a signal. +.It Bq Er EINVAL +The +.Ar bufsiz +argument was zero. +.It Bq Er EIO +The process is a member of a background process attempting to read +from its controlling terminal, the process is ignoring or blocking +the +.Dv SIGTTIN +signal, or the process group is orphaned. +.It Bq Er EMFILE +The process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOTTY +There is no controlling terminal and the +.Dv RPP_REQUIRE_TTY +flag was specified. +.El +.Sh SIGNALS +.Fn readpassphrase +will catch the following signals: +.Bd -literal -offset indent +SIGALRM SIGHUP SIGINT +SIGPIPE SIGQUIT SIGTERM +SIGTSTP SIGTTIN SIGTTOU +.Ed +.Pp +When one of the above signals is intercepted, terminal echo will +be restored if it had previously been turned off. +If a signal handler was installed for the signal when +.Fn readpassphrase +was called, that handler is then executed. +If no handler was previously installed for the signal then the +default action is taken as per +.Xr sigaction 2 . +.Pp +The +.Dv SIGTSTP , +.Dv SIGTTIN , +and +.Dv SIGTTOU +signals (stop signals generated from keyboard or due to terminal I/O +from a background process) are treated specially. +When the process is resumed after it has been stopped, +.Fn readpassphrase +will reprint the prompt and the user may then enter a passphrase. +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr getpass 3 +.Sh STANDARDS +The +.Fn readpassphrase +function is an +.Ox +extension and should not be used if portability is desired. +.Sh HISTORY +The +.Fn readpassphrase +function first appeared in +.Ox 2.9 . diff --git a/static/openbsd/man3/realpath.3 b/static/openbsd/man3/realpath.3 new file mode 100644 index 00000000..1f932e3b --- /dev/null +++ b/static/openbsd/man3/realpath.3 @@ -0,0 +1,165 @@ +.\" 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. +.\" +.\" $OpenBSD: realpath.3,v 1.27 2025/06/13 18:34:00 schwarze Exp $ +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt REALPATH 3 +.Os +.Sh NAME +.Nm realpath +.Nd returns the canonicalized absolute pathname +.Sh SYNOPSIS +.In limits.h +.In stdlib.h +.Ft char * +.Fn realpath "const char *pathname" "char *resolved" +.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 resolved . +The +.Fa resolved +argument +.Em must +refer to a buffer capable of storing at least +.Dv PATH_MAX +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 . +All components of +.Fa pathname +must exist when +.Fn realpath +is called. +.Sh RETURN VALUES +The +.Fn realpath +function returns +.Fa resolved +on success. +If +.Fa resolved +is +.Dv NULL +and no error occurred, then +.Fn realpath +returns a NUL-terminated string in a newly allocated buffer. +If an error occurs, +.Fn realpath +returns +.Dv NULL +and the contents of +.Fa resolved +are undefined. +.Sh ERRORS +The function +.Fn realpath +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Read or search permission was denied for a component of +.Ar pathname . +.It Bq Er EINVAL +The +.Ar pathname +argument is a null pointer. +.It Bq Er EIO +An error occurred while reading from the file system. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating +.Ar pathname . +.It Bq Er ENAMETOOLONG +A component of +.Ar pathname +exceeded +.Dv NAME_MAX +characters, or the entire +.Ar pathname +(including the terminating NUL) exceeded +.Dv PATH_MAX . +.It Bq Er ENAMETOOLONG +Pathname resolution of a symbolic link produced an intermediate +result whose length exceeds +.Dv PATH_MAX . +.It Bq Er ENOENT +A component of +.Ar pathname +does not name an existing file or +.Ar pathname +points to an empty string. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENOMEM +Sufficient storage space is unavailable for allocation. +.El +.Sh SEE ALSO +.Xr readlink 1 , +.Xr realpath 1 , +.Xr getcwd 3 +.Sh STANDARDS +The +.Fn realpath +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn realpath +function call first appeared in +.Bx 4.4 . +.Pp +In +.Ox 6.6 , +it was reimplemented on top of the +.Fn __realpath +system call. +Its calling convention differs from the standard +function by requiring +.Ar resolved +to not be +.Dv NULL +and by returning an integer, +zero on success, and -1 with corresponding errno on failure. +This is visible in the output of +.Xr kdump 1 . diff --git a/static/openbsd/man3/recno.3 b/static/openbsd/man3/recno.3 new file mode 100644 index 00000000..ba7e656a --- /dev/null +++ b/static/openbsd/man3/recno.3 @@ -0,0 +1,221 @@ +.\" $OpenBSD: recno.3,v 1.21 2022/03/31 17:27:15 naddy Exp $ +.\" $NetBSD: recno.3,v 1.6 1996/05/03 21:26:51 cgd Exp $ +.\" +.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. +.\" +.\" 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 $Mdocdate: March 31 2022 $ +.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 +.Fn dbopen +routine 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 +.Nm +access method specific data structure provided to +.Fn dbopen +is defined in the +.In db.h +include file as follows: +.Bd -literal -offset indent +typedef struct { + unsigned long flags; + unsigned int cachesize; + unsigned int psize; + int lorder; + size_t reclen; + unsigned char bval; + char *bfname; +} RECNOINFO; +.Ed +.Pp +The elements of this structure are defined as follows: +.Bl -tag -width XXXXXX +.It Fa flags +The flag value is specified by +.Tn OR Ns 'ing +any of the following values: +.Bl -tag -width R_FIXEDLEN +.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 R_NOKEY flag is specified, the +.Fa 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 Ql \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 +.Fa bfname +is non-NULL, it specifies the name of the +.Xr btree 3 +file, as if specified as the file name for a +.Xr dbopen 3 +of a +.Xr btree 3 +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 +.Vt 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 +.Fa recno +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 XEINVALX +.It Bq 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 +.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/openbsd/man3/regex.3 b/static/openbsd/man3/regex.3 new file mode 100644 index 00000000..1ad08de1 --- /dev/null +++ b/static/openbsd/man3/regex.3 @@ -0,0 +1,746 @@ +.\" $OpenBSD: regex.3,v 1.30 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. +.\" +.\" 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. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (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.4 (Berkeley) 3/20/94 +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt REGEXEC 3 +.Os +.Sh NAME +.Nm regcomp , +.Nm regexec , +.Nm regerror , +.Nm regfree +.Nd regular expression routines +.Sh SYNOPSIS +.In sys/types.h +.In regex.h +.Ft int +.Fn regcomp "regex_t *preg" "const char *pattern" "int cflags" +.Pp +.Ft int +.Fn regexec "const regex_t *preg" "const char *string" "size_t nmatch" \ + "regmatch_t pmatch[]" "int eflags" +.Pp +.Ft size_t +.Fn regerror "int errcode" "const regex_t *preg" "char *errbuf" \ + "size_t errbuf_size" +.Pp +.Ft void +.Fn regfree "regex_t *preg" +.Sh DESCRIPTION +These routines implement +.St -p1003.2 +regular expressions +.Pq Dq REs ; +see +.Xr re_format 7 . +.Fn regcomp +compiles an RE written as a string into an internal form, +.Fn regexec +matches that internal form against a string and reports results, +.Fn regerror +transforms error codes from either into human-readable messages, and +.Fn regfree +frees any dynamically allocated storage used by the internal form +of an RE. +.Pp +The header +.In regex.h +declares two structure types, +.Vt regex_t +and +.Vt regmatch_t , +the former for compiled internal forms and the latter for match reporting. +It also declares the four functions, +a type +.Vt regoff_t , +and a number of constants with names starting with +.Dv REG_ . +.Pp +.Fn regcomp +compiles the regular expression contained in the +.Fa pattern +string, +subject to the flags in +.Fa cflags , +and places the results in the +.Vt regex_t +structure pointed to by +.Fa preg . +The +.Fa cflags +argument is the bitwise OR of zero or more of the following values: +.Bl -tag -width XREG_EXTENDEDX +.It Dv REG_EXTENDED +Compile modern +.Pq Dq extended +REs, +rather than the obsolete +.Pq Dq basic +REs that are the default. +.It Dv REG_BASIC +This is a synonym for 0, +provided as a counterpart to +.Dv REG_EXTENDED +to improve readability. +.It Dv 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 +.St -p1003.2 , +and should be used with +caution in software intended to be portable to other systems. +.Dv REG_EXTENDED +and +.Dv REG_NOSPEC +may not be used in the same call to +.Fn regcomp . +.It Dv REG_ICASE +Compile for matching that ignores upper/lower case distinctions. +See +.Xr re_format 7 . +.It Dv REG_NOSUB +Compile for matching that need only report success or failure, +not what was matched. +.It Dv 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, +.Ql \&[^ +bracket expressions and +.Ql \&. +never match newline, +a +.Ql ^ +anchor matches the null string after any newline in the string +in addition to its normal function, +and the +.Ql $ +anchor matches the null string before any newline in the +string in addition to its normal function. +.It Dv REG_PEND +The regular expression ends, +not at the first NUL, +but just before the character pointed to by the +.Fa re_endp +member of the structure pointed to by +.Fa preg . +The +.Fa re_endp +member is of type +.Fa 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 +.St -p1003.2 , +and should be used with +caution in software intended to be portable to other systems. +.El +.Pp +When successful, +.Fn regcomp +returns 0 and fills in the structure pointed to by +.Fa preg . +One member of that structure +(other than +.Fa re_endp ) +is publicized: +.Fa re_nsub , +of type +.Fa size_t , +contains the number of parenthesized subexpressions within the RE +(except that the value of this member is undefined if the +.Dv REG_NOSUB +flag was used). +If +.Fn regcomp +fails, it returns a non-zero error code; +see DIAGNOSTICS. +.Pp +.Fn regexec +matches the compiled RE pointed to by +.Fa preg +against the +.Fa string , +subject to the flags in +.Fa eflags , +and reports results using +.Fa nmatch , +.Fa pmatch , +and the returned value. +The RE must have been compiled by a previous invocation of +.Fn regcomp . +The compiled form is not altered during execution of +.Fn regexec , +so a single compiled RE can be used simultaneously by multiple threads. +.Pp +By default, +the NUL-terminated string pointed to by +.Fa string +is considered to be the text of an entire line, minus any terminating +newline. +The +.Fa eflags +argument is the bitwise OR of zero or more of the following values: +.Bl -tag -width XREG_STARTENDX +.It Dv REG_NOTBOL +The first character of the string is treated as the continuation +of a line. +This means that the anchors +.Ql ^ , +.Ql [[:<:]] , +and +.Ql \e< +do not match before it; but see +.Dv REG_STARTEND +below. +This does not affect the behavior of newlines under +.Dv REG_NEWLINE . +.It Dv REG_NOTEOL +The NUL terminating +the string +does not end a line, so the +.Ql $ +anchor does not match before it. +This does not affect the behavior of newlines under +.Dv REG_NEWLINE . +.It Dv REG_STARTEND +The string is considered to start at +.Fa string No + +.Fa pmatch Ns [0]. Ns Fa rm_so +and to end before the byte located at +.Fa string No + +.Fa pmatch Ns [0]. Ns Fa rm_eo , +regardless of the value of +.Fa nmatch . +See below for the definition of +.Fa pmatch +and +.Fa nmatch . +This is an extension, +compatible with but not specified by +.St -p1003.2 , +and should be used with +caution in software intended to be portable to other systems. +.Pp +Without +.Dv REG_NOTBOL , +the position +.Fa rm_so +is considered the beginning of a line, such that +.Ql ^ +matches before it, and the beginning of a word if there is a word +character at this position, such that +.Ql [[:<:]] +and +.Ql \e< +match before it. +.Pp +With +.Dv REG_NOTBOL , +the character at position +.Fa rm_so +is treated as the continuation of a line, and if +.Fa rm_so +is greater than 0, the preceding character is taken into consideration. +If the preceding character is a newline and the regular expression was compiled +with +.Dv REG_NEWLINE , +.Ql ^ +matches before the string; if the preceding character is not a word character +but the string starts with a word character, +.Ql [[:<:]] +and +.Ql \e< +match before the string. +.El +.Pp +See +.Xr re_format 7 +for a discussion of what is matched in situations where an RE or a +portion thereof could match any of several substrings of +.Fa string . +.Pp +Normally, +.Fn regexec +returns 0 for success and the non-zero code +.Dv REG_NOMATCH +for failure. +Other non-zero error codes may be returned in exceptional situations; +see DIAGNOSTICS. +.Pp +If +.Dv REG_NOSUB +was specified in the compilation of the RE, +or if +.Fa nmatch +is 0, +.Fn regexec +ignores the +.Fa pmatch +argument (but see below for the case where +.Dv REG_STARTEND +is specified). +Otherwise, +.Fa pmatch +points to an array of +.Fa nmatch +structures of type +.Vt regmatch_t . +Such a structure has at least the members +.Fa rm_so +and +.Fa rm_eo , +both of type +.Fa regoff_t +(a signed arithmetic type at least as large as an +.Vt off_t +and a +.Vt 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 +.Fa string +argument given to +.Fn regexec . +An empty substring is denoted by equal offsets, +both indicating the character following the empty substring. +.Pp +The 0th member of the +.Fa pmatch +array is filled in to indicate what substring of +.Fa string +was matched by the entire RE. +Remaining members report what substring was matched by parenthesized +subexpressions within the RE; +member +.Va i +reports subexpression +.Va 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 +.Fa rm_so +and +.Fa 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 +.Dq (b*)+ +matches +.Dq bbb , +the parenthesized subexpression matches each of the three +.Sq b Ns s +and then +an infinite number of empty strings following the last +.Sq b , +so the reported substring is one of the empties.) +.Pp +If +.Dv REG_STARTEND +is specified, +.Fa pmatch +must point to at least one +.Vt regmatch_t +(even if +.Fa nmatch +is 0 or +.Dv REG_NOSUB +was specified), +to hold the input offsets for +.Dv REG_STARTEND . +Use for output is still entirely controlled by +.Fa nmatch ; +if +.Fa nmatch +is 0 or +.Dv REG_NOSUB +was specified, +the value of +.Fa pmatch[0] +will not be changed by a successful +.Fn regexec . +.Pp +.Fn regerror +maps a non-zero +.Va errcode +from either +.Fn regcomp +or +.Fn regexec +to a human-readable, printable message. +If +.Fa preg +is non-NULL, +the error code should have arisen from use of +the +.Vt regex_t +pointed to by +.Fa preg , +and if the error code came from +.Fn regcomp , +it should have been the result from the most recent +.Fn regcomp +using that +.Vt regex_t . +.Pf ( Fn regerror +may be able to supply a more detailed message using information +from the +.Vt regex_t . ) +.Fn regerror +places the NUL-terminated message into the buffer pointed to by +.Fa errbuf , +limiting the length (including the NUL) to at most +.Fa 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 the terminating NUL). +If +.Fa errbuf_size +is 0, +.Fa errbuf +is ignored but the return value is still correct. +.Pp +If the +.Fa errcode +given to +.Fn regerror +is first OR'ed with +.Dv REG_ITOA , +the +.Dq message +that results is the printable name of the error code, +e.g., +.Dq REG_NOMATCH , +rather than an explanation thereof. +If +.Fa errcode +is +.Dv REG_ATOI , +then +.Fa preg +shall be non-null and the +.Fa 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 +.Fa errbuf +is the decimal digits of +the numeric value of the error code +(0 if the name is not recognized). +.Dv REG_ITOA +and +.Dv REG_ATOI +are intended primarily as debugging facilities; +they are extensions, +compatible with but not specified by +.St -p1003.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 +.Fn regfree +frees any dynamically allocated storage associated with the compiled RE +pointed to by +.Fa preg . +The remaining +.Vt regex_t +is no longer a valid compiled RE +and the effect of supplying it to +.Fn regexec +or +.Fn 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 +.St -p1003.2 +leaves up to the implementor, +either by explicitly saying +.Dq undefined +or by virtue of them being +forbidden by the RE grammar. +This implementation treats them as follows. +.Pp +See +.Xr re_format 7 +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 +.Sx 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 +.St -p1003.2 +(such magic meanings occur only in obsolete REs) +is taken as an ordinary character. +.Pp +Any unmatched +.Ql \&[ +is a +.Dv 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 +.Ql ^ +or +.Ql | . +.Pp +A +.Ql | +cannot appear first or last in a (sub)expression, or after another +.Ql | , +i.e., an operand of +.Ql | +cannot be an empty subexpression. +An empty parenthesized subexpression, +.Ql \&(\&) , +is legal and matches an +empty (sub)string. +An empty string is not a legal RE. +.Pp +A +.Ql { +followed by a digit is considered the beginning of bounds for a +bounded repetition, which must then follow the syntax for bounds. +A +.Ql { +.Em not +followed by a digit is considered an ordinary character. +.Pp +.Ql ^ +and +.Ql $ +beginning and ending subexpressions in obsolete +.Pq Dq basic +REs are anchors, not ordinary characters. +.Sh DIAGNOSTICS +Non-zero error codes from +.Fn regcomp +and +.Fn regexec +include the following: +.Pp +.Bl -tag -compact -width XREG_ECOLLATEX +.It Er REG_NOMATCH +.Fn regexec +failed to match +.It Er REG_BADPAT +invalid regular expression +.It Er REG_ECOLLATE +invalid collating element +.It Er REG_ECTYPE +invalid character class +.It Er REG_EESCAPE +\e applied to unescapable character +.It Er REG_ESUBREG +invalid backreference number +.It Er REG_EBRACK +brackets [ ] not balanced +.It Er REG_EPAREN +parentheses ( ) not balanced +.It Er REG_EBRACE +braces { } not balanced +.It Er REG_BADBR +invalid repetition count(s) in { } +.It Er REG_ERANGE +invalid character range in [ ] +.It Er REG_ESPACE +ran out of memory +.It Er REG_BADRPT +?, *, or + operand invalid +.It Er REG_EMPTY +empty (sub)expression +.It Er REG_ASSERT +.Dq can't happen +\(emyou found a bug +.It Er REG_INVARG +invalid argument, e.g., negative-length string +.El +.Sh SEE ALSO +.Xr grep 1 , +.Xr re_format 7 +.Pp +.St -p1003.2 , +sections 2.8 (Regular Expression Notation) +and +B.5 (C Binding for Regular Expression Matching). +.Sh HISTORY +Predecessors called +.Fn regcmp +and +.Fn regex +first appeared in PWB/UNIX 1.0. +.Pp +Predecessors +.Fn re_comp +and +.Fn re_exec +first appeared in +.Bx 4.0 , +became part of +.In unistd.h +in +.Bx 4.4 , +and were deleted after +.Ox 5.4 . +.Pp +Functions called +.Fn regcomp , +.Fn regexec , +.Fn regerror , +and +.Fn regsub +first appeared in Version\~8 +.At , +were reimplemented and declared in +.In regexp.h +for +.Bx 4.3 Tahoe , +and were also deleted after +.Ox 5.4 . +.Pp +Taking different arguments, the POSIX +.In regex.h +functions +.Fn regcomp , +.Fn regexec , +.Fn regerror , +and +.Fn regfree +appeared in +.Bx 4.4 . +.Sh AUTHORS +.An -nosplit +The +Version\~8 +.At +code was implemented by +.An Rob Pike +and extracted into a library by +.An Dave Presotto . +The +.Bx 4.3 Tahoe +and +.Bx 4.4 +versions were both written by +.An Henry Spencer . +.Sh BUGS +The implementation of internationalization is incomplete: +the locale is always assumed to be the default one of +.St -p1003.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 +.Fn regexec +performance is poor. +This will improve with later releases. +.Fa nmatch +exceeding 0 is expensive; +.Fa nmatch +exceeding 1 is worse. +.Fn regexec +is largely insensitive to RE complexity +.Em except +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 +.Fn regcomp +implements bounded repetitions by macro expansion, +which is costly in time and space if counts are large +or bounded repetitions are nested. +A RE like, say, +.Dq ((((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 +.St -p1003.2 , +things like +.Ql a)b +are legal REs because +.Ql \&) +is +a special character only in the presence of a previous unmatched +.Ql \&( . +This can't be fixed until the spec is fixed. +.Pp +The standard's definition of back references is vague. +For example, does +.Dq a\e(\e(b\e)*\e2\e)*d +match +.Dq 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/openbsd/man3/remainder.3 b/static/openbsd/man3/remainder.3 new file mode 100644 index 00000000..fdb207a7 --- /dev/null +++ b/static/openbsd/man3/remainder.3 @@ -0,0 +1,148 @@ +.\" $OpenBSD: remainder.3,v 1.9 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" 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. +.\" 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. +.\" +.\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91 +.\" $FreeBSD: src/lib/msun/man/remainder.3,v 1.6 2008/03/30 20:48:02 das Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt REMAINDER 3 +.Os +.Sh NAME +.Nm remainder , +.Nm remainderf , +.Nm remainderl , +.Nm remquo , +.Nm remquof , +.Nm remquol , +.Nm drem , +.Nm dremf +.Nd minimal residue functions +.Sh SYNOPSIS +.Lb libm +.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 +.Fn remainder , +.Fn remainderf , +.Fn remainderl , +.Fn remquo , +.Fn remquof , +and +.Fn remquol +return the remainder +.Fa r No := Fa x No \(mi Fa n Ns * Ns Fa y +where +.Fa n +is the integer nearest the exact value of +.Bk -words +.Fa x Ns / Ns Fa y ; +.Ek +moreover if +.Eo | Fa n No \(mi Fa x Ns / Ns Fa y Ec | = 1/2 +then +.Fa n +is even. +Consequently +the remainder is computed exactly and +.Eo | Fa r Ec | \(<= Eo | Fa y Ec | Ns /2 . +But attempting to take the remainder when +.Fa y +is 0 or +.Fa x +is \(+-infinity is an invalid operation that produces a NaN. +.Pp +The +.Fn remquo , +.Fn remquof +and +.Fn remquol +functions also store the last +.Va k +bits of +.Fa n +in the location pointed to by +.Fa quo , +provided that +.Fa n +exists. +The number of bits +.Va k +is platform-specific, but is guaranteed to be at least 3. +.Sh SEE ALSO +.Xr fmod 3 , +.Xr nextafter 3 +.Sh STANDARDS +The +.Fn remainder , +.Fn remainderf , +.Fn remainderl , +.Fn remquo , +.Fn remquof , +and +.Fn remquol +routines conform to +.St -isoC-99 . +The remainder is as defined in +.St -ieee754 . +.Pp +.Fn drem +and +.Fn dremf +are deprecated aliases for +.Fn remainder +and +.Fn remainderf , +respectively. +.Sh HISTORY +The +.Fn remainder +and +.Fn remainderf +functions appeared in +.Bx 4.3 +and +.Nx 1.2 , +respectively. +The +.Fn remquo +and +.Fn remquof +functions were added in +.Ox 4.4 . diff --git a/static/openbsd/man3/remove.3 b/static/openbsd/man3/remove.3 new file mode 100644 index 00000000..e59c1363 --- /dev/null +++ b/static/openbsd/man3/remove.3 @@ -0,0 +1,80 @@ +.\" $OpenBSD: remove.3,v 1.13 2015/01/29 01:46:30 schwarze 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 $Mdocdate: January 29 2015 $ +.Dt REMOVE 3 +.Os +.Sh NAME +.Nm remove +.Nd remove a file or directory +.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 +.Rv -std +.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 +.Sh STANDARDS +The +.Fn remove +function conforms to +.St -ansiC +and +.St -xpg4.2 . diff --git a/static/openbsd/man3/res_init.3 b/static/openbsd/man3/res_init.3 new file mode 100644 index 00000000..3e0cabc3 --- /dev/null +++ b/static/openbsd/man3/res_init.3 @@ -0,0 +1,441 @@ +.\" $OpenBSD: res_init.3,v 1.6 2021/11/24 20:06:32 jca 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. +.\" +.Dd $Mdocdate: November 24 2021 $ +.Dt RES_INIT 3 +.Os +.Sh NAME +.Nm res_query , +.Nm res_search , +.Nm res_mkquery , +.Nm res_send , +.Nm res_init , +.Nm dn_comp , +.Nm dn_expand +.Nd resolver routines +.Sh SYNOPSIS +.In sys/types.h +.In netinet/in.h +.In arpa/nameser.h +.In resolv.h +.Ft int +.Fo res_query +.Fa "const char *dname" +.Fa "int class" +.Fa "int type" +.Fa "unsigned char *answer" +.Fa "int anslen" +.Fc +.Ft int +.Fo res_search +.Fa "const char *dname" +.Fa "int class" +.Fa "int type" +.Fa "unsigned char *answer" +.Fa "int anslen" +.Fc +.Ft int +.Fo res_mkquery +.Fa "int op" +.Fa "const char *dname" +.Fa "int class" +.Fa "int type" +.Fa "const unsigned char *data" +.Fa "int datalen" +.Fa "const unsigned char *newrr" +.Fa "unsigned char *buf" +.Fa "int buflen" +.Fc +.Ft int +.Fo res_send +.Fa "const unsigned char *msg" +.Fa "int msglen" +.Fa "unsigned char *answer" +.Fa "int anslen" +.Fc +.Ft int +.Fn res_init "void" +.Ft int +.Fo dn_comp +.Fa "const char *exp_dn" +.Fa "unsigned char *comp_dn" +.Fa "int length" +.Fa "unsigned char **dnptrs" +.Fa "unsigned char **lastdnptr" +.Fc +.Ft int +.Fo dn_expand +.Fa "const unsigned char *msg" +.Fa "const unsigned char *eomorig" +.Fa "const unsigned char *comp_dn" +.Fa "char *exp_dn" +.Fa "int length" +.Fc +.Sh DESCRIPTION +These routines are used for making, sending, and interpreting +query and reply messages with Internet domain name servers. +.Pp +Global configuration and state information that is used by the +resolver routines is kept in the structure +.Va _res . +Most of the values have reasonable defaults and can be ignored. +Options stored in +.Va _res.options +are defined in +.In resolv.h +and are as follows. +Options are stored as a simple bit mask containing the bitwise OR +of the options enabled. +.Bl -tag -width RES_USE_DNSSEC +.It Dv RES_INIT +True if the initial name server address and default domain name are +initialized (i.e.\& +.Fn res_init +has been called). +.It Dv RES_DEBUG +Print debugging messages, +if libc is compiled with +.Dv DEBUG . +By default on +.Ox +this option does nothing. +.It Dv RES_AAONLY +Accept authoritative answers only. +With this option, +.Fn res_send +should continue until it finds an authoritative answer or finds an error. +On +.Ox +this option does nothing. +.It Dv RES_USEVC +Use TCP connections for queries instead of UDP datagrams. +.It Dv RES_PRIMARY +Query the primary name server only. +On +.Ox +this option does nothing. +.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. +.Pf ( Fn res_send +does not do iterative queries and expects the name server +to handle recursion.) +This option is enabled by default. +.It Dv RES_DEFNAMES +If set, +.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_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_DNSRCH +If this option is set, +.Fn res_search +will search for host names in the current domain and in parent domains; see +.Xr hostname 7 . +This is used by the standard host lookup routine +.Xr gethostbyname 3 . +This option is enabled by default. +.It Dv RES_INSECURE_1 +Do not require the IP source address on the reply packet +to be equal to the server's address. +.It Dv RES_INSECURE_2 +Do not check if the query section of the reply packet +is equal to that of the query packet. +.It Dv RES_NOALIASES +This option has no effect. +In the past, it turned off the legacy +.Ev HOSTALIASES +feature. +.It Dv RES_TRUSTAD +If set, the resolver routines will set the AD flag in DNS queries and +preserve the value of the AD flag in DNS replies. +If not set, the resolver routines will clear the AD flag in responses. +Direct use of this option to enable AD bit processing is discouraged. +Instead the use of trusted name servers should be annotated with +.Dq options trust-ad +in +.Xr resolv.conf 5 . +This option is automatically enabled if +.Xr resolv.conf 5 +only lists name servers on localhost. +.It Dv RES_USE_INET6 +With this option +.Xr gethostbyname 3 +will return IPv6 addresses if available. +This option is deprecated; software should use the +.Xr getaddrinfo 3 +interface instead of modifying the behavior of +.Xr gethostbyname 3 . +On some operating systems this option also causes IPv4 addresses to be +returned as IPv4-mapped IPv6 addresses. +For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1. +IPv4-mapped IPv6 addresses are not supported on +.Ox . +.It Dv RES_USE_EDNS0 +Attach an OPT pseudo-RR for the EDNS0 extension, +as specified in RFC 2671. +This informs DNS servers of a client's receive buffer size, +allowing them to take advantage of a non-default receive buffer size, +and thus to send larger replies. +DNS query packets with the EDNS0 extension are not compatible with +non-EDNS0 DNS servers. +.Ox +uses 4096 bytes as input buffer size. +.It Dv RES_USE_DNSSEC +Request that the resolver uses +Domain Name System Security Extensions (DNSSEC), +as defined in RFCs 4033, 4034, and 4035. +The resolver routines will use the EDNS0 extension and set the DNSSEC DO +flag in queries, asking the name server to signal validated records by +setting the AD flag in the reply and to attach additional DNSSEC +records. +The resolver routines will clear the AD flag in replies unless the name +servers are considered trusted. +Also, client applications are often only interested in the value of the +AD flag, making the additional DNSSEC records a waste of network +bandwidth. +See the description for +.Dq options trust-ad +in +.Xr resolv.conf 5 . +.It Dv RES_USE_CD +Set the Checking Disabled flag on queries. +.El +.Pp +The +.Fn res_init +routine reads the configuration file (if any; see +.Xr resolv.conf 5 ) +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 search list on a per-process basis. +This is similar to the +.Ic search +command in the configuration file. +Another environment variable +.Ev RES_OPTIONS +can be set to override certain internal resolver options which +are otherwise set by changing fields in the +.Va _res +structure or are inherited from the configuration file's +.Ic options +command. +The syntax of the +.Ev RES_OPTIONS +environment variable is explained in +.Xr resolv.conf 5 . +Initialization normally occurs on the first call +to one of the following routines. +.Pp +The +.Fn res_query +function provides an interface to the server query mechanism. +It 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. +Values for the +.Fa class +and +.Fa type +fields +are defined in +.In arpa/nameser.h . +.Pp +The +.Fn res_search +routine makes a query and awaits a response like +.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 first successful reply. +.Pp +The remaining routines are lower-level routines used by +.Fn res_query . +The +.Fn res_mkquery +function 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 +.In 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_send +routine sends a pre-formatted query and returns an answer. +It will call +.Fn res_init +if +.Dv RES_INIT +is not set, send the query to the local name server, and +handle timeouts and retries. +The length of the reply message is returned, or \-1 if there were errors. +.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 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 dnptrs +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. +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. +.Sh FILES +.Bl -tag -width "/etc/resolv.confXX" +.It Pa /etc/resolv.conf +The configuration file. +.El +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr resolv.conf 5 , +.Xr hostname 7 +.Sh STANDARDS +.Rs +.%A M. Stahl +.%D November 1987 +.%R RFC 1032 +.%T Domain Administrators Guide +.Re +.Pp +.Rs +.%A M. Lottor +.%D November 1987 +.%R RFC 1033 +.%T Domain Administrators Operations Guide +.Re +.Pp +.Rs +.%A P. Mockapetris +.%D November 1987 +.%R RFC 1034 +.%T Domain Names \(en Concepts and Facilities +.Re +.Pp +.Rs +.%A P. Mockapetris +.%D November 1987 +.%R RFC 1035 +.%T Domain Names \(en Implementation and Specification +.Re +.Pp +.Rs +.%A J. Klensin +.%D October 2008 +.%R RFC 5321 +.%T Simple Mail Transfer Protocol +.Re +.Sh HISTORY +The functions +.Fn res_mkquery , +.Fn res_send , +.Fn res_init , +.Fn dn_comp , +and +.Fn dn_expand +appeared in +.Bx 4.3 . +The functions +.Fn res_query +and +.Fn res_search +appeared in +.Bx 4.3 Tahoe . diff --git a/static/openbsd/man3/resizeterm.3 b/static/openbsd/man3/resizeterm.3 new file mode 100644 index 00000000..b40a2eca --- /dev/null +++ b/static/openbsd/man3/resizeterm.3 @@ -0,0 +1,178 @@ +.\" $OpenBSD: resizeterm.3,v 1.7 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1996-on +.\" +.\" $Id: resizeterm.3,v 1.7 2023/10/17 09:52:08 nicm Exp $ +.TH resizeterm 3 2023-07-01 "ncurses 6.4" "Library calls" +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBis_term_resized\fP, +\fBresize_term\fP, +\fBresizeterm\fP \- change the curses terminal size +.SH SYNOPSIS +\fB#include \fP +.sp +\fBbool is_term_resized(int \fIlines\fB, int \fIcolumns\fB);\fR +.br +\fBint resize_term(int \fIlines\fB, int \fIcolumns\fB);\fR +.br +\fBint resizeterm(int \fIlines\fB, int \fIcolumns\fB);\fR +.SH DESCRIPTION +This is an extension to the curses library. +It provides callers with a hook into the \fBncurses\fP data to resize windows, +primarily for use by programs running in an X Window terminal (e.g., xterm) +when the terminal's screen size is changed by the user: +.bP +Curses windows cannot extend outside the screen. +If the terminal is shrunk, curses windows must be shrunk to fit. +.bP +If the terminal is stretched, +rows and/or columns can be added to existing windows. +The added cells should match the current attributes of the windows. +.PP +If the calling program has not set up a handler for \fBSIGWINCH\fP +when it initializes \fBncurses\fP +(e.g., using \fBinitscr\fP(3) or \fBnewterm\fP(3)), +then \fBncurses\fP sets a handler for \fBSIGWINCH\fP which notifies +the library when a window-size event has occurred. +The library checks for this notification +.bP +when reading input data, +.bP +when implicitly resuming program mode +(e.g., between \fBendwin\fP(3) and \fBwrefresh\fP(3)), +and +.bP +when explicitly resuming program mode in \fBrestartterm\fP(3). +.PP +When the library has found that the terminal's window-size has +changed, it calls \fBresizeterm\fP to update its data structures. +.PP +An application which establishes its own \fBSIGWINCH\fP handler +can call \fBresizeterm\fP, but in that case, the library will not +see \fBSIGWINCH\fP, and proper layout will rely upon the application. +.SH FUNCTIONS +.SS resizeterm +The function \fBresizeterm\fP resizes the standard and current windows +(i.e., \fBstdscr\fP and \fBcurscr\fP) +to the specified dimensions, and adjusts other bookkeeping data used by +the \fBncurses\fP library that record the window dimensions +such as the \fBLINES\fP and \fBCOLS\fP variables. +.SS resize_term +Most of the work for \fBresizeterm\fP is +done by the inner function \fBresize_term\fP. +The outer function \fBresizeterm\fP adds bookkeeping +for the \fBSIGWINCH\fP handler, +as well as repainting the soft-key area (see \fBslk_touch\fP(3)). +.PP +The \fBresize_term\fP function attempts to resize all windows. +This helps with simple applications. +However: +.bP +It is not possible to automatically resize pads. +.bP +Applications which have complicated layouts should check for +\fBKEY_RESIZE\fP returned from \fBwgetch\fP, +and adjust their layout, e.g., using \fBwresize\fP and \fBmvwin\fP, +or by recreating the windows. +.PP +When resizing windows, \fBresize_term\fP recursively adjusts subwindows, +keeping them within the updated parent window's limits. +If a top-level window happens to extend to the screen's limits, +then on resizing the window, \fBresize_term\fP will keep the window +extending to the corresponding limit, regardless of whether the +screen has shrunk or grown. +.SS is_term_resized +A support function \fBis_term_resized\fP is provided so that applications +can check if the \fBresize_term\fP function would modify the window structures. +It returns \fBTRUE\fP if the windows would be modified, +and \fBFALSE\fP otherwise. +.SH RETURN VALUE +Except as noted, these functions return +the integer \fBERR\fP upon failure and \fBOK\fP on success. +They will fail if either of the dimensions are less than or equal to zero, +or if an error occurs while (re)allocating memory for the windows. +.SH NOTES +While these functions are intended to be used to support a signal handler +(i.e., for \fBSIGWINCH\fP), care should be taken to avoid invoking them in a +context where \fBmalloc\fP or \fBrealloc\fP may have been interrupted, +since it uses those functions. +.PP +If ncurses is configured to supply its own \fBSIGWINCH\fP handler, +.bP +on receipt of a \fBSIGWINCH\fP, the handler sets a flag +.bP +which is tested in +\fBwgetch\fP(3), +\fBdoupdate\fP(3) and +\fBrestartterm\fP(3), +.bP +in turn, calling the \fBresizeterm\fP function, +.bP +which \fBungetch\fP's a \fBKEY_RESIZE\fP which +will be read on the next call to \fBwgetch\fP. +.IP +The \fBKEY_RESIZE\fP alerts an application that the screen size has changed, +and that it should repaint special features such as pads that cannot +be done automatically. +.IP +Calling \fBresizeterm\fP or \fBresize_term\fP +directly from a signal handler is unsafe. +This indirect method is used to provide a safe way to resize the ncurses +data structures. +.PP +If the environment variables \fBLINES\fP or \fBCOLUMNS\fP are set, +this overrides the library's use of the window size obtained from +the operating system. +Thus, even if a \fBSIGWINCH\fP is received, +no screen size change may be recorded. +.SH PORTABILITY +It is possible to resize the screen with SVr4 curses, +by +.bP +exiting curses with \fBendwin\fP(3) and +.bP +resuming using \fBrefresh\fP(3). +.PP +Doing that clears the screen and is visually distracting. +.PP +This extension of ncurses was introduced in mid-1995. +It was adopted in NetBSD curses (2001) and PDCurses (2003). +.SH SEE ALSO +\fBcurs_getch\fP(3), +\fBcurs_variables\fP(3), +\fBwresize\fP(3). +.SH AUTHOR +Thomas Dickey (from an equivalent function written in 1988 for BSD curses). diff --git a/static/openbsd/man3/rint.3 b/static/openbsd/man3/rint.3 new file mode 100644 index 00000000..20192219 --- /dev/null +++ b/static/openbsd/man3/rint.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: rint.3,v 1.15 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 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 SYNOPSIS +.Lb libm +.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. +.Pp +The +.Fn nearbyint , +.Fn nearbyintf , +and +.Fn nearbyintl +functions do the same, +but without raising the +.Dq inexact +floating-point exception. +.Sh SEE ALSO +.Xr abs 3 , +.Xr ceil 3 , +.Xr fabs 3 , +.Xr floor 3 +.Sh HISTORY +A +.Fn rint +function appeared in +.At v6 . diff --git a/static/openbsd/man3/round.3 b/static/openbsd/man3/round.3 new file mode 100644 index 00000000..cf496f70 --- /dev/null +++ b/static/openbsd/man3/round.3 @@ -0,0 +1,68 @@ +.\" $OpenBSD: round.3,v 1.6 2025/06/07 10:33:06 schwarze 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.6 2005/06/15 19:04:04 ru Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt ROUND 3 +.Os +.Sh NAME +.Nm round , +.Nm roundf , +.Nm roundl +.Nd round to nearest integral value +.Sh SYNOPSIS +.Lb libm +.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 lrint 3 , +.Xr lround 3 , +.Xr nextafter 3 , +.Xr rint 3 , +.Xr trunc 3 +.Sh STANDARDS +These functions conform to +.St -isoC-99 . diff --git a/static/openbsd/man3/rpc.3 b/static/openbsd/man3/rpc.3 new file mode 100644 index 00000000..611910f5 --- /dev/null +++ b/static/openbsd/man3/rpc.3 @@ -0,0 +1,1231 @@ +.\" $OpenBSD: rpc.3,v 1.50 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 1998 Theo de Raadt +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list 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. +.\" +.\" Copyright (c) 2010, Oracle America, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer in the documentation and/or other materials +.\" provided with the distribution. +.\" * Neither the name of the "Oracle America, Inc." nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" 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. +.\" +.Dd $Mdocdate: June 13 2025 $ +.Dt CALLRPC 3 +.Os +.Sh NAME +.Nm callrpc , +.Nm clnt_broadcast , +.Nm clnt_call , +.Nm clnt_control , +.Nm clnt_create , +.Nm clnt_destroy , +.Nm clnt_freeres , +.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 clnt_geterr , +.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_freeargs , +.Nm svc_getargs , +.Nm svc_getcaller , +.Nm svc_getreq , +.Nm svc_getreq_common , +.Nm svc_getreq_poll , +.Nm svc_getreqset , +.Nm svc_getreqset2 , +.Nm svc_register , +.Nm svc_max_pollfd , +.Nm svc_pollfd , +.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 svctcp_create , +.Nm svcudp_create , +.Nm svcudp_bufcreate , +.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 int +.Fn callrpc "char *host" "u_long prognum" "u_long versnum" "u_long 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 "char *host" "u_long prog" "u_long vers" "char *proto" +.Ft bool_t +.Fn clnt_control "CLIENT *cl" "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 "char *s" +.Ft void +.Fn clnt_perrno "enum clnt_stat stat" +.Ft int +.Fn clnt_perror "CLIENT *clnt" "char *s" +.Ft char * +.Fn clnt_spcreateerror "char *s" +.Ft char * +.Fn clnt_sperrno "enum clnt_stat stat" +.Ft char * +.Fn clnt_sperror "CLIENT *rpch" "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_long protocol" +.Ft enum clnt_stat +.Fn pmap_rmtcall "struct sockaddr_in *" "u_long prog" "u_long vers" "u_long proc" "xdrproc_t inp" "char *in" "xdrproc_t outp" "char *out" "struct timeval tv" "u_long *portp" +.Ft int +.Fn pmap_set "u_long prognum" "u_long versnum" "u_int protocol" "int port" +.Ft int +.Fn pmap_unset "u_long prognum" "u_long versnum" +.Ft int +.Fn registerrpc "u_long prognum" "u_long versnum" "u_long procnum" "char *(*procname)() " "xdrproc_t inproc" "xdrproc_t outproc" +.Vt struct rpc_createerr rpc_createerr ; +.Ft int +.Fn svc_destroy "SVCXPRT *xprt" +.Vt struct pollfd *svc_pollfd ; +.Vt int svc_max_pollfd ; +.Vt fd_set svc_fdset ; +.Vt fd_set *__svc_fdset ; +.Vt int __svc_fdsetsize ; +.Vt 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 int +.Fn svc_getreq_common "int fd" +.Ft int +.Fn svc_getreq_poll "struct pollfd *pfds" "const int pollretval" +.Ft int +.Fn svc_getreqset "fd_set *rdfds" +.Ft int +.Fn svc_getreqset2 "fd_set *rdfds" "int width" +.Ft int +.Fn svc_getreq "int rdfds" +.Ft int +.Fn svc_register "SVCXPRT *xprt" "u_long prognum" "u_long versnum" "void (*dispatch)()" "u_long protocol" +.Ft int +.Fn svc_run "void" +.Ft int +.Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out" +.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" +.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_create "int sock" +.Ft SVCXPRT * +.Fn svcudp_bufcreate "int sock" "u_int sendsz" "u_int recvsz" +.Ft bool_t +.Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar" +.Ft bool_t +.Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp" +.Ft void +.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 void +.Fn xprt_register "SVCXPRT *xprt" +.Ft void +.Fn xprt_unregister "SVCXPRT *xprt" +.Sh DESCRIPTION +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. +.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. +.Fn callrpc +calls 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 +.Fa enum clnt_stat +cast to an integer if it fails. +The routine +.Fn clnt_perrno +is handy for translating failure statuses into messages. +.Pp +.Sy 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. +.Pp +.Fn clnt_broadcast +is like +.Fn callrpc , +except the call message is broadcast to all locally +connected broadcast nets. +Each time it receives a response, this routine calls +.Fa eachresult , +whose form is: +.Bd -literal -offset indent +.Ft int +.Fn eachresult "char *out" "struct sockaddr_in *addr" +.Ed +.Pp +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 +.Fa eachresult +returns zero, +.Fn clnt_broadcast +waits for more replies; otherwise it returns with appropriate +status. +.Pp +.Sy Warning: +broadcast sockets are limited in size to the +maximum transfer unit of the data link. +For Ethernet, this value is 1500 bytes. +.Pp +.Fn clnt_call +is 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. +.Pp +.Fn clnt_destroy +is 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. +.Pp +.Fn clnt_create +is a 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 +.Qq udp +and +.Qq tcp . +Default timeouts are set, but can be modified using +.Fn clnt_control . +This routine returns +.Dv NULL +if it fails. +.Pp +.Sy 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. +.Pp +.Fn clnt_control +is 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: +.Bd -literal -offset indent +CLSET_TIMEOUT struct timeval set total timeout +CLGET_TIMEOUT struct timeval get total timeout +.Ed +.Pp +.Sy 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. +.Bd -literal -offset indent +CLGET_SERVER_ADDR struct sockaddr_in get server's address +.Ed +.Pp +The following operations are valid for UDP only: +.Bd -literal -offset indent +CLSET_RETRY_TIMEOUT struct timeval set the retry timeout +CLGET_RETRY_TIMEOUT struct timeval get the retry timeout +.Ed +.Pp +The retry timeout is the time that UDP RPC +waits for the server to reply before +retransmitting the request. +.Pp +.Fn clnt_freeres +is 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. +.Pp +.Fn clnt_geterr +is a macro that copies the error structure out of the client +handle +to the structure at address +.Fa errp . +.Pp +.Fn clnt_pcreateerror +prints 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. +Used when a +.Fn clnt_create , +.Fn clntraw_create , +.Fn clnttcp_create , +or +.Fn clntudp_create +call fails. +.Pp +.Fn clnt_perrno +prints a message to standard error corresponding +to the condition indicated by +.Fa stat . +Used after +.Fn callrpc . +.Pp +.Fn clnt_perror +prints 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. +Used after +.Fn clnt_call . +.Pp +.Fn clnt_spcreateerror +is like +.Fn clnt_pcreateerror , +except that it returns a string +instead of printing to the standard error. +.Pp +.Sy Bugs: +returns pointer to static data that is overwritten +on each call. +.Pp +.Fn clnt_sperrno +takes the same arguments as +.Fn clnt_perrno , +but instead of sending a message to the standard error +indicating why an RPC +call failed, returns a pointer to a string which contains +the message. +Unlike +.Fn clnt_perror , +it does not append a newline character +to the end of 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 +.Fn printf , +or if a message format different than that supported by +.Fn clnt_perrno +is to be used. +.Pp +.Sy Note: +unlike +.Fn clnt_sperror +and +.Fn clnt_spcreaterror , +.Fn clnt_sperrno +returns a pointer to static data, but the +result will not get overwritten on each call. +.Pp +.Fn clnt_sperror +is like +.Fn clnt_perror , +except that (like +.Fn clnt_sperrno ) +it returns a string instead of printing to standard error. +.Pp +.Sy Bugs: +returns pointer to static data that is overwritten +on each call. +.Pp +.Fn clntraw_create +is a routine which 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. +.Pp +.Fn clnttcp_create +is a routine which 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-\*(Gtsin_port +is zero, then it is set to the actual port that the remote +program is listening on (the remote +.Xr portmap 8 +service is consulted for this information). +The parameter +.Fa sockp +is a socket; if it is +.Fa 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. +.Pp +.Fn clntudp_create +is a routine which creates an RPC client for the remote program +.Fa prognum , +on +.Fa versnum ; +the client uses use UDP/IP as a transport. +The remote program is located at Internet address +.Fa addr . +If +.Fa addr-\*(Gtsin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.Xr portmap 8 +service is consulted for this information). +The parameter +.Fa sockp +is a socket; if it is +.Fa 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 +.Fn clnt_call . +This routine returns +.Dv NULL +if it fails. +.Pp +.Fn clntudp_bufcreate +is like +.Fn clntudp_create , +except that it allows the user to specify the maximum packet size for sending +and receiving UDP-based RPC +messages instead of using the default size limit of 8800 bytes. +.Pp +.Fn get_myaddress +stuffs 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 +.Fa htons(PMAPPORT) . +Returns zero on success, non-zero on failure. +.Pp +.Fn pmap_getmaps +is a function interface to the +.Xr portmap 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 +.Qq Li rpcinfo \-p +uses this routine. +.Pp +.Fn pmap_getport +is a user interface to the +.Xr portmap 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 failed to contact the remote +.Xr portmap 8 +service. +In the latter case, the global variable +.Va rpc_createerr +contains the RPC status. +.Pp +.Fn pmap_rmtcall +is a user interface to the +.Xr portmap 8 +service, which instructs +.Xr portmap 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 +.Qq ping +and nothing else. +See also +.Fn clnt_broadcast . +.Pp +.Fn pmap_set +is a user interface to the +.Xr portmap 8 +service, which establishes a mapping between the triple +.Fa [ prognum , versnum , protocol ] +and +.Fa port +on the machine's +.Xr portmap 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 . +.Pp +.Fn pmap_unset +is a user interface to the +.Xr portmap 8 +service, which destroys all mapping between the triple +.Fa [ prognum , versnum , * ] +and +.Fa ports +on the machine's +.Xr portmap 8 +service. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn registerrpc +will register a 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 procname +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 +.Sy Warning: +remote procedures registered in this form +are accessed using the UDP/IP transport; see +.Fn svcudp_create +for restrictions. +.Pp +.Va rpc_createerr +is 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. +.Pp +.Fn svc_destroy +is 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. +.Pp +.Va svc_pollfd +is a global variable reflecting the RPC service side's +read file descriptor array. +This variable 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, and it may change after calls to +.Fn svc_getreq_poll +or any creation routines. +Do not pass it directly to +.Xr poll 2 ! +Instead, make a copy and pass that instead. +.Pp +.Va svc_max_pollfd +is a global variable containing the maximum length of the +.Va svc_pollfd +array. +.Va svc_max_pollfd +is not a hard limit; it will grow automatically as needed. +This variable is read-only, and it may change after calls to +.Fn svc_getreq_poll +or any creation routines. +The purpose of +.Va svc_max_pollfd +is to allow a service implementor to make a copy of +.Va svc_pollfd +that may in turn be passed to +.Xr poll 2 . +.Pp +.Va __svc_fdset +and +.Va __svc_fdsetsize +are global variables reflecting the RPC service side's +read file descriptor bit mask. +.Va __svc_fdsetsize +is a count of the number of checkable bits in +.Va __svc_fdset , +and can expand to the full size that +.Xr select 2 +supports, hence exceeding +.Fa FD_SETSIZE +if required. +These variables are 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, and it may change after calls to +.Fn svc_getreqset +or any creation routines. +Do not pass its address to +.Xr select 2 ! +Instead, pass the address of a copy. +These variables are considered obsolete; new programs should use +.Va svc_pollfd +and +.Va svc_max_pollfd +instead. +.Pp +.Va svc_fdset +is similar to +.Va __svc_fdset +but limited to +.Fa FD_SETSIZE +descriptors. +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, and it may change after calls to +.Fn svc_getreqset +or any creation routines. +Do not pass it directly to +.Xr select 2 ! +Instead, make a copy and pass that instead. +.Pp +Additionally, note that if the process has descriptor limits +which are extended beyond +.Fa FD_SETSIZE , +this variable will only be usable for the first +.Fa FD_SETSIZE +descriptors. +This variable is considered obsolete; new programs should use +.Va svc_pollfd +which does not have this limit. +.Pp +.Va svc_fds +is similar to +.Va svc_fdset , +but limited to 32 descriptors. +This interface is obsoleted by +.Va svc_fdset +and is included for source compatibility only. +.Pp +.Fn svc_freeargs +is 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. +.Pp +.Fn svc_getargs +is 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. +.Pp +.Fn svc_getcaller +is the approved way of getting the network address of the caller +of a procedure associated with the RPC service transport handle, +.Fa xprt . +.Pp +.Fn svc_getreq_common +is called to handle a request on the given socket. +It is used internally by +.Fn svc_getreq_poll , +.Fn svc_getreqset , +.Fn svc_getreqset2 , +and +.Fn svc_getreq . +.Pp +.Fn svc_getreq_poll +is a routine which 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 poll 2 +system call has determined that an RPC request has arrived on some RPC +.Fa socket(s) ; +.Fa pollretval +is the value returned by +.Xr poll 2 +and +.Fa pfds +is the array of +.Fa pollfd +structures passed to +.Xr poll 2 . +The routine returns when all sockets described by +.Fa pollfd +have been serviced. +.Pp +.Fn svc_getreqset +is a routine which 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 +.Fa 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. +.Pp +.Fn svc_getreqset2 +is a non-standard routine which 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 +.Fa 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. +This interface is non-portable, but provided for applications which +need to deal with large fd_set sizes. +.Pp +.Fn svc_getreq +is similar to +.Fa svc_getreqset , +but limited to 32 descriptors. +This interface is obsoleted by +.Fa svc_getreq_poll +and +.Fa svc_getreqset . +.Pp +.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 portmap 8 +service. +If +.Fa protocol +is non-zero, then a mapping of the triple +.Fa [ prognum , versnum , protocol ] +to +.Fa xprt-\*(Gtxp_port +is established with the local +.Xr portmap 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" +The +.Fn svc_register +routine returns one if it succeeds, and zero otherwise. +.Pp +.Fn svc_run +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 a +.Xr poll 2 +system call to return. +.Pp +.Fn svc_sendreply +is 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 one if it succeeds, zero otherwise. +.Pp +.Fn svc_unregister +removes all mapping of the double +.Fa [ prognum , versnum ] +to dispatch routines, and of the triple +.Fa [ prognum , versnum , * ] +to port number. +.Pp +.Fn svcerr_auth +is called by a service dispatch routine that refuses to perform +a remote procedure call due to an authentication error. +.Pp +.Fn svcerr_decode +is called by a service dispatch routine that cannot successfully +decode its parameters. +See also +.Fn svc_getargs . +.Pp +.Fn svcerr_noproc +is called by a service dispatch routine that does not implement +the procedure number that the caller requests. +.Pp +.Fn svcerr_noprog +is called when the desired program is not registered with the RPC +package. +Service implementors usually do not need this routine. +.Pp +.Fn svcerr_progvers +is called when the desired version of a program is not registered +with the RPC package. +Service implementors usually do not need this routine. +.Pp +.Fn svcerr_systemerr +is 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 +.Fn svcerr_weakauth +is called by a service dispatch routine that refuses to perform +a remote procedure call due to insufficient +authentication parameters. +The routine calls +.Fa "svcerr_auth(xprt, AUTH_TOOWEAK)" . +.Pp +.Fn svcraw_create +is a routine which 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. +.Pp +.Fn svctcp_create +is a routine which 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 +.Fa 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-\*(Gtxp_sock +is the transport's socket descriptor, and +.Fa xprt-\*(Gtxp_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. +.Pp +.Fn svcfd_create +will 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. +.Pp +.Fn svcudp_create +is a routine which 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 +.Fa 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-\*(Gtxp_sock +is the transport's socket descriptor, and +.Fa xprt-\*(Gtxp_port +is the transport's port number. +This routine returns +.Dv NULL +if it fails. +.Pp +.Fn svcudp_bufcreate +is like +.Fn svcudp_create , +except that it allows the user to specify the maximum packet size for sending +and receiving UDP-based RPC +messages instead of using the default size limit of 8800 bytes. +.Pp +.Fn xdr_accepted_reply +is used for encoding RPC reply messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.Pp +.Fn xdr_authunix_parms +is used for describing +.Ux +credentials. +This routine is useful for users +who wish to generate these credentials without using the RPC +authentication package. +.Pp +.Fn xdr_callhdr +is 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. +.Pp +.Fn xdr_callmsg +is used for describing RPC call messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.Pp +.Fn xdr_opaque_auth +is 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. +.Pp +.Fn xdr_pmap +is used for describing parameters to various +.Xr portmap 8 +procedures, externally. +This routine is useful for users who wish to generate +these parameters without using the pmap interface. +.Pp +.Fn xdr_pmaplist +is used for describing a list of port mappings, externally. +This routine is useful for users who wish to generate +these parameters without using the pmap interface. +.Pp +.Fn xdr_rejected_reply +is used for describing RPC reply messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.Pp +.Fn xdr_replymsg +is used for describing RPC reply messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.Pp +.Fn xprt_register +is used to register transport handles. +After RPC service transport handles are created, +they should register themselves with the RPC service package. +This routine modifies the global variables +.Va svc_pollfd , +.Va svc_fdset , +.Va __svc_fdset +and may modify +.Va svc_max_pollfd +and +.Va __svc_fdsetsize . +Service implementors usually do not need this routine. +.Pp +.Fn xprt_unregister +is used to unregister a transport handle. +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_pollfd , +.Va svc_fdset , +and +.Va __svc_fdset . +Service implementors usually do not need this routine. +.Sh SEE ALSO +.\"Xr rpc_secure 3 , +.Xr rpcgen 1 , +.Xr poll 2 , +.Xr select 2 , +.Xr authnone_create 3 , +.Xr getrpcent 3 , +.Xr getrpcport 3 , +.Xr xdr 3 , +.Xr rpc 5 , +.Xr portmap 8 +.Rs +.%Q Sun Microsystems, Inc. +.%T Remote Procedure Calls: Protocol Specification +.Re +.Rs +.%Q Sun Microsystems, Inc. +.%T Remote Procedure Call Programming Guide +.Re +.Rs +.%Q Sun Microsystems, Inc. +.%T rpcgen Programming Guide +.Re +.Sh STANDARDS +.Rs +.%D June 1988 +.%Q Sun Microsystems, Inc. +.%R RFC 1057 +.%T RPC: Remote Procedure Call Protocol Specification Version 2 +.Re diff --git a/static/openbsd/man3/rs256_pk_new.3 b/static/openbsd/man3/rs256_pk_new.3 new file mode 100644 index 00000000..6b848934 --- /dev/null +++ b/static/openbsd/man3/rs256_pk_new.3 @@ -0,0 +1,137 @@ +.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: July 9 2025 $ +.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 +.Lb libfido2 libcbor libcrypto libz +.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 fido_assert_verify 3 , +.Xr fido_cred_pubkey_ptr 3 diff --git a/static/openbsd/man3/s2i_ASN1_INTEGER.3 b/static/openbsd/man3/s2i_ASN1_INTEGER.3 new file mode 100644 index 00000000..16646c69 --- /dev/null +++ b/static/openbsd/man3/s2i_ASN1_INTEGER.3 @@ -0,0 +1,216 @@ +.\" $OpenBSD: s2i_ASN1_INTEGER.3,v 1.11 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: June 13 2025 $ +.Dt S2I_ASN1_INTEGER 3 +.Os +.Sh NAME +.Nm i2s_ASN1_ENUMERATED , +.Nm i2s_ASN1_ENUMERATED_TABLE , +.Nm i2s_ASN1_INTEGER , +.Nm s2i_ASN1_INTEGER , +.Nm i2s_ASN1_OCTET_STRING , +.Nm s2i_ASN1_OCTET_STRING +.Nd ASN.1 data type conversion utilities for certificate extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/asn1.h +.In openssl/x509v3.h +.Ft char * +.Fo i2s_ASN1_ENUMERATED +.Fa "X509V3_EXT_METHOD *method" +.Fa "const ASN1_ENUMERATED *a" +.Fc +.Ft char * +.Fo i2s_ASN1_INTEGER +.Fa "X509V3_EXT_METHOD *method" +.Fa "const ASN1_INTEGER *a" +.Fc +.Ft ASN1_INTEGER * +.Fo s2i_ASN1_INTEGER +.Fa "X509V3_EXT_METHOD *method" +.Fa "const char *value" +.Fc +.Ft char * +.Fo i2s_ASN1_OCTET_STRING +.Fa "X509V3_EXT_METHOD *method" +.Fa "const ASN1_OCTET_STRING *aos" +.Fc +.Ft ASN1_OCTET_STRING * +.Fo s2i_ASN1_OCTET_STRING +.Fa "X509V3_EXT_METHOD *method" +.Fa "X509V3_CTX *ctx" +.Fa "const char *value" +.Fc +.Ft char * +.Fo i2s_ASN1_ENUMERATED_TABLE +.Fa "X509V3_EXT_METHOD *method" +.Fa "const ASN1_ENUMERATED *a" +.Fc +.Sh DESCRIPTION +These functions convert to and from +.Vt ASN1_ENUMERATED , +.Vt ASN1_INTEGER , +and +.Vt ASN1_OCTET_STRING +objects. +They are primarily used internally for parsing configuration files and +displaying X.509v3 certificate extensions. +With the exception of +.Fn i2s_ASN1_ENUMERATED_TABLE , +these functions ignore the +.Fa method +argument. +Any object or string returned by these functions must be freed by the caller. +.Pp +.Fn i2s_ASN1_ENUMERATED +and +.Fn i2s_ASN1_INTEGER +first convert +.Fa a +into a +.Vt BIGNUM +object with +.Xr ASN1_ENUMERATED_to_BN 3 +or +.Xr ASN1_INTEGER_to_BN 3 +and then derive a string representation using +.Xr BN_bn2dec 3 +or +.Xr BN_bn2hex 3 . +Decimal representation is used if the number has less than 128 bits, +otherwise hexadecimal representation is used to avoid excessive conversion cost. +.Pp +.Fn s2i_ASN1_INTEGER +converts the NUL-terminated decimal or hexadecimal string representation of +an integer in +.Fa value +into an +.Vt ASN1_INTEGER +object. +A sign prefix of +.Sq - +indicates a negative number and the base prefixes +.Sq 0x +and +.Sq 0X +indicate hexadecimal representation, +otherwise decimal representation is assumed. +After skipping the sign and base prefixes, an intermediate conversion into a +.Vt BIGNUM +is performed using +.Xr BN_dec2bn 3 +or +.Xr BN_hex2bn 3 +and the +.Vt ASN1_INTEGER +is then obtained with +.Xr BN_to_ASN1_INTEGER 3 . +.Pp +.Fn i2s_ASN1_OCTET_STRING +converts the octets in +.Fa aos +into a string where the octets are colon-separated and +represented as pairs of uppercase hexadecimal digits. +.Pp +.Fn s2i_ASN1_OCTET_STRING +converts the NUL-terminated string +.Fa str +into an +.Vt ASN1_OCTET_STRING . +The +.Fa method +and +.Fa ctx +arguments are ignored. +Every pair of hexadecimal digits is converted into an octet. +Colons are ignored if they are at the start, the end or +if they separate two pairs of digits. +.Pp +.Fn i2s_ASN1_ENUMERATED_TABLE +looks up the value of +.Fa a +in the +.Fa usr_data +field of the +.Pf non- Dv NULL +.Fa method +and returns a copy of the associated long name. +If no match is found, +.Fa a +is passed to +.Fn i2s_ASN1_ENUMERATED . +The +.Fa method +argument can be provided by application programs or it can be a +default method obtained from +.Xr X509V3_EXT_get_nid 3 . +The default +.Fa methods +corresponding to the following +.Fa nid +arguments have strings configured in their usr_data field: +.Pp +.Bl -column NID_netscape_cert_type "Netscape certificate type (obsolete)" -compact +.It Dv NID_crl_reason Ta reason codes, RFC 5280, 5.3.1 +.It Dv NID_key_usage Ta key usage, RFC 5280, 4.2.1.3 +.It Dv NID_netscape_cert_type Ta Netscape certificate type (obsolete) +.El +.Sh RETURN VALUES +.Fn i2s_ASN1_ENUMERATED , +.Fn i2s_ASN1_ENUMERATED_TABLE , +.Fn i2s_ASN1_INTEGER , +and +.Fn i2s_ASN1_OCTET_STRING +return a NUL-terminated string, or NULL on memory allocation failure. +.Pp +.Fn s2i_ASN1_INTEGER +returns an +.Vt ASN1_INTEGER , +or NULL on error. +Error conditions are memory allocation failure or if +.Fa value +is not a valid decimal or hexadecimal encoding of an integer. +.Pp +.Fn s2i_ASN1_OCTET_STRING +returns an +.Vt ASN1_OCTET_STRING , +or NULL on error. +Error conditions are memory allocation failure or if +.Fa value +contains an odd number of hexadecimal digits or anything except +colons at the start, the end or between pairs of hexadecimal digits. +.Pp +Error codes can sometimes be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr a2i_ASN1_INTEGER 3 , +.Xr a2i_ipadd 3 , +.Xr ASN1_INTEGER_new 3 , +.Xr ASN1_INTEGER_to_BN 3 , +.Xr ASN1_OCTET_STRING_new 3 , +.Xr crypto 3 , +.Xr v2i_ASN1_BIT_STRING 3 , +.Xr X509V3_get_d2i 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.4 and +have been available since +.Ox 2.6 . +.Sh BUGS +Of these functions at least +.Fn i2s_ASN1_ENUMERATED_TABLE +can succeed while setting an error and fail without setting an error +on the error stack. diff --git a/static/openbsd/man3/scalbn.3 b/static/openbsd/man3/scalbn.3 new file mode 100644 index 00000000..3f34b051 --- /dev/null +++ b/static/openbsd/man3/scalbn.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: scalbn.3,v 1.6 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt SCALBN 3 +.Os +.Sh NAME +.Nm scalbln , +.Nm scalblnf , +.Nm scalblnl , +.Nm scalbn , +.Nm scalbnf , +.Nm scalbnl +.Nd adjust exponent by radix +.Sh SYNOPSIS +.Lb libm +.In math.h +.Ft double +.Fn scalbln "double x" "long n" +.Ft float +.Fn scalblnf "float x" "long n" +.Ft long double +.Fn scalblnl "long double x" "long n" +.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 +.Fn scalbln +and +.Fn scalbn +return +.Fa x Ns *(2** Ns Fa n ) +computed by exponent manipulation. +The +.Fn scalblnf +and +.Fn scalbnf +functions are single precision versions of +.Fn scalbln +and +.Fn scalbn , +respectively. +The +.Fn scalblnl +and +.Fn scalbnl +functions are extended precision versions of +.Fn scalbln +and +.Fn scalbn , +respectively. +.Sh STANDARDS +.St -ieee754 +.Sh HISTORY +The +.Nm scalbln , +.Nm scalblnf +and +.Nm scalblnl +functions appeared in +.Ox 4.7 . +The +.Nm scalbn , +.Nm scalbnf , +and +.Nm scalbnl , +functions appeared in +.Bx 4.3 , +.Nx 1.1 +and +.Ox 4.5 , +respectively. diff --git a/static/openbsd/man3/scandir.3 b/static/openbsd/man3/scandir.3 new file mode 100644 index 00000000..fda3a82f --- /dev/null +++ b/static/openbsd/man3/scandir.3 @@ -0,0 +1,172 @@ +.\" $OpenBSD: scandir.3,v 1.17 2024/04/15 15:47:58 florian 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 $Mdocdate: April 15 2024 $ +.Dt SCANDIR 3 +.Os +.Sh NAME +.Nm scandir , +.Nm scandirat , +.Nm alphasort +.Nd scan a directory +.Sh SYNOPSIS +.In sys/types.h +.In dirent.h +.Ft int +.Fo scandir +.Fa "const char *dirname" +.Fa "struct dirent ***namelist" +.Fa "int (*select)(const struct dirent *)" +.Fa "int (*compar)(const struct dirent **, const struct dirent **)" +.Fc +.Ft int +.Fo scandirat +.Fa "int dirfd" +.Fa "const char *dirname" +.Fa "struct dirent ***namelist" +.Fa "int (*select)(const struct dirent *)" +.Fa "int (*compar)(const struct dirent **, const struct dirent **)" +.Fc +.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 +.Dv NULL , +then all 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 +.Dv 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. +.Pp +The +.Fn scandirat +function is similar to +.Fn scandir , +but takes an additional +.Fa dirfd +argument. +If +.Fa dirname +is relative, +.Fa dirfd +must be a valid file descriptor referencing a directory, in which case the +.Fa dirname +lookup is performed relative to the directory referenced by +.Fa dirfd . +If +.Fa dirfd +has the special value +.Va AT_FDCWD , +then the current process directory is used as the base for relative lookups. +See +.Xr openat 2 +for additional details. +.Sh DIAGNOSTICS +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 malloc 3 , +.Xr opendir 3 , +.Xr qsort 3 , +.Xr dir 5 +.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 +The argument types for +.Fn alphasort +and for the +.Fa compar +argument to +.Fn scandir +were originally +.Vt "void *" , +then changed to +.Vt "const void *" , +and then finally changed by +.St -p1003.1-2008 +to their current form of +.Vt "const struct dirent **" . +Similarly, the +.Fn select +argument to +.Fn scandir +was originally +.Vt "struct dirent *" +until it was changed to its current form of +.Vt "const struct dirent *" . diff --git a/static/openbsd/man3/scanf.3 b/static/openbsd/man3/scanf.3 new file mode 100644 index 00000000..5383f904 --- /dev/null +++ b/static/openbsd/man3/scanf.3 @@ -0,0 +1,479 @@ +.\" $OpenBSD: scanf.3,v 1.26 2022/03/31 17:27:16 naddy 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. +.\" +.Dd $Mdocdate: March 31 2022 $ +.Dt SCANF 3 +.Os +.Sh NAME +.Nm scanf , +.Nm fscanf , +.Nm sscanf , +.Nm vscanf , +.Nm vsscanf , +.Nm vfscanf +.Nd input format conversion +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn scanf "const char *format" ... +.Ft int +.Fn fscanf "FILE *stream" "const char *format" ... +.Ft int +.Fn sscanf "const char *str" "const char *format" ... +.In stdarg.h +.Ft int +.Fn vscanf "const char *format" "va_list ap" +.Ft int +.Fn vsscanf "const char *str" "const char *format" "va_list ap" +.Ft int +.Fn vfscanf "FILE *stream" "const char *format" "va_list ap" +.Sh DESCRIPTION +The +.Fn scanf +family of functions read input according to the given +.Fa format +as described below. +This format may contain +.Dq conversion specifiers ; +the results of such conversions, if any, are stored through a set of pointer +arguments. +.Pp +The +.Fn scanf +function reads input from the standard input stream +.Em stdin , +.Fn fscanf +reads input from the supplied stream pointer +.Fa stream , +and +.Fn sscanf +reads its input from the character string pointed to by +.Fa str . +.Pp +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 va_start 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 the +.Cm * +conversion below). +All conversions are introduced by the +.Cm % +(percent sign) character. +The +.Fa format +string may also contain other characters. +Whitespace (such as blanks, tabs, or newlines) in the +.Fa format +string match any amount of whitespace, 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 "ll (ell 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 either 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 ) , +or that the conversion will be one of +.Cm efg +and the next pointer is a pointer to +.Vt double +(rather than +.Vt float ) , +or that the conversion will be one of +.Cm sc[ . +.Pp +If the conversion is one of +.Cm sc[ , +the expected conversion input is a multibyte character sequence. +Each multibyte character in the sequence is converted with a call to the +.Fn mbrtowc +function. +The field width specifies the maximum amount of bytes read from the +multibyte character sequence and passed to +.Fn mbrtowc +for conversion. +The next pointer is a pointer to a +.Vt wchar_t +wide-character buffer large enough to accept the converted input sequence +including the terminating NUL wide character which will be added automatically. +.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 efg +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 an +.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 whitespace; +this whitespace 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 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 +.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 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 +.Vt "unsigned int" . +.It Cm xX +Matches an optionally signed hexadecimal integer; +the next pointer must be a pointer to +.Vt "unsigned int" . +.It Cm eE +Equivalent to +.Cm f . +.It Cm fF +Matches an optionally signed floating-point number; +the next pointer must be a pointer to +.Vt float . +.It Cm gG +Equivalent to +.Cm f . +.It Cm aA +Equivalent to +.Cm f . +.It Cm s +Matches a sequence of non-whitespace characters; +the next pointer must be a pointer to +.Vt char , +or to +.Vt wchar_t +if the +.Vt l +length modifier is present. +The provided array must be large enough to accept and store +the whole sequence and the terminating NUL character. +The input string stops at whitespace +or at the maximum field width, whichever occurs first. +If specified, the maximum field length refers to the sequence +being scanned rather than the storage space, hence the provided +array must be 1 larger for the terminating NUL character. +.It Cm c +Matches a sequence of characters consuming the number of bytes +specified by the field width (defaults to 1 if unspecified); +the next pointer must be a pointer to +.Vt char , +or to +.Vt wchar_t +if the +.Vt l +length modifier is present. +There must be enough room for all the characters +(no terminating NUL is added). +The usual skip of leading whitespace is suppressed. +To skip whitespace 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 +.Vt char , +or to +.Vt wchar_t +if the +.Vt l +length modifier is present. +There must be enough room for all the characters in the string, +plus a terminating NUL character. +The usual skip of leading whitespace is suppressed. +.Pp +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. +.Pp +For instance, +.Ql [^]0-9-] +means the set +.Do +everything except close bracket, zero through nine, and hyphen +.Dc . +The string ends with the appearance of a character not in +(or, with a circumflex, in) the 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 +.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 +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 . +.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, +such as an end-of-file, +occurs before any conversion. +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 mbrtowc 3 , +.Xr printf 3 , +.Xr strtod 3 , +.Xr strtol 3 , +.Xr strtoul 3 , +.Xr wscanf 3 +.Sh STANDARDS +The functions +.Fn fscanf , +.Fn scanf , +and +.Fn sscanf +conform to +.St -ansiC . +.Sh HISTORY +The functions +.Fn scanf , +.Fn fscanf , +and +.Fn sscanf +first appeared in +.At v7 , +and +.Fn vscanf , +.Fn vsscanf , +and +.Fn vfscanf +in +.Bx 4.3 Reno . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_NUMERIC +.Xr locale 1 +category can cause parsing failures; see CAVEATS in +.Xr setlocale 3 +for details. +.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/openbsd/man3/sched_get_priority_min.3 b/static/openbsd/man3/sched_get_priority_min.3 new file mode 100644 index 00000000..781b59fe --- /dev/null +++ b/static/openbsd/man3/sched_get_priority_min.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: sched_get_priority_min.3,v 1.3 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2010 Federico G. Schwindt +.\" +.\" 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: June 7 2025 $ +.Dt SCHED_GET_PRIORITY_MIN 3 +.Os +.Sh NAME +.Nm sched_get_priority_max , +.Nm sched_get_priority_min +.Nd get priority limits +.Sh SYNOPSIS +.Lb libpthread +.In sched.h +.Ft int +.Fn sched_get_priority_max "int policy" +.Ft int +.Fn sched_get_priority_min "int policy" +.Sh DESCRIPTION +The +.Fn sched_get_priority_max +and +.Fn sched_get_priority_min +functions return the maximum and minimum priority values, respectively, +for the scheduling policy specified by +.Fa policy . +.Pp +The scheduling policy for a thread can either be +.Dv SCHED_FIFO +(first in, first out), +.Dv SCHED_RR +(round-robin) or +.Dv SCHED_OTHER . +.Sh RETURN VALUES +Upon successful completion, +.Fn sched_get_priority_max +and +.Fn sched_get_priority_min +return the maximum and minimum priority values, respectively. +Otherwise, a value of \-1 is returned and errno is set to indicate the error. +.Sh ERRORS +The +.Fn sched_get_priority_max +and +.Fn sched_get_priority_min +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa policy . +.El +.Sh STANDARDS +The +.Fn sched_get_priority_max +and +.Fn sched_get_priority_min +functions conform to +.St -p1003.1-2008 . +.Pp +This implementation does not support process scheduling. diff --git a/static/openbsd/man3/sdbm.3 b/static/openbsd/man3/sdbm.3 new file mode 100644 index 00000000..25afcbe4 --- /dev/null +++ b/static/openbsd/man3/sdbm.3 @@ -0,0 +1,295 @@ +.\" $Id: sdbm.3,v 1.2 90/12/13 13:00:57 oz Exp $ +.TH SDBM 3 "1 March 1990" +.SH NAME +sdbm, sdbm_open, sdbm_prep, sdbm_close, sdbm_fetch, sdbm_store, sdbm_delete, sdbm_exists, sdbm_firstkey, sdbm_nextkey, sdbm_hash, sdbm_rdonly, sdbm_error, sdbm_clearerr, sdbm_dirfno, sdbm_pagfno \- data base subroutines +.SH SYNOPSIS +.nf +.ft B +#include +.sp +typedef struct { + char *dptr; + int dsize; +} datum; +.sp +datum nullitem = { NULL, 0 }; +.sp +\s-1DBM\s0 *sdbm_open(char *file, int flags, int mode) +.sp +\s-1DBM\s0 *sdbm_prep(char *dirname, char *pagname, int flags, int mode) +.sp +void sdbm_close(\s-1DBM\s0 *db) +.sp +datum sdbm_fetch(\s-1DBM\s0 *db, key) +.sp +int sdbm_store(\s-1DBM\s0 *db, datum key, datum val, int flags) +.sp +int sdbm_delete(\s-1DBM\s0 *db, datum key) +.sp +int sdbm_exists(\s-1DBM\s0 *db, datum key) +.sp +datum sdbm_firstkey(\s-1DBM\s0 *db) +.sp +datum sdbm_nextkey(\s-1DBM\s0 *db) +.sp +long sdbm_hash(char *string, int len) +.sp +int sdbm_rdonly(\s-1DBM\s0 *db) +int sdbm_error(\s-1DBM\s0 *db) +sdbm_clearerr(\s-1DBM\s0 *db) +int sdbm_dirfno(\s-1DBM\s0 *db) +int sdbm_pagfno(\s-1DBM\s0 *db) +.ft R +.fi +.SH DESCRIPTION +.IX "database library" sdbm "" "\fLsdbm\fR" +.IX sdbm_open "" "\fLsdbm_open\fR \(em open \fLsdbm\fR database" +.IX sdbm_prep "" "\fLsdbm_prep\fR \(em prepare \fLsdbm\fR database" +.IX sdbm_close "" "\fLsdbm_close\fR \(em close \fLsdbm\fR routine" +.IX sdbm_fetch "" "\fLsdbm_fetch\fR \(em fetch \fLsdbm\fR database data" +.IX sdbm_store "" "\fLsdbm_store\fR \(em add data to \fLsdbm\fR database" +.IX sdbm_delete "" "\fLsdbm_delete\fR \(em remove data from \fLsdbm\fR database" +.IX sdbm_exists "" "\fLsdbm_exists\fR \(em test \fLsdbm\fR key existence" +.IX sdbm_firstkey "" "\fLsdbm_firstkey\fR \(em access \fLsdbm\fR database" +.IX sdbm_nextkey "" "\fLsdbm_nextkey\fR \(em access \fLsdbm\fR database" +.IX sdbm_hash "" "\fLsdbm_hash\fR \(em string hash for \fLsdbm\fR database" +.IX sdbm_rdonly "" "\fLsdbm_rdonly\fR \(em return \fLsdbm\fR database read-only mode" +.IX sdbm_error "" "\fLsdbm_error\fR \(em return \fLsdbm\fR database error condition" +.IX sdbm_clearerr "" "\fLsdbm_clearerr\fR \(em clear \fLsdbm\fR database error condition" +.IX sdbm_dirfno "" "\fLsdbm_dirfno\fR \(em return \fLsdbm\fR database bitmap file descriptor" +.IX sdbm_pagfno "" "\fLsdbm_pagfno\fR \(em return \fLsdbm\fR database data file descriptor" +.IX "database functions \(em \fLsdbm\fR" sdbm_open "" \fLsdbm_open\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_prep "" \fLsdbm_prep\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_close "" \fLsdbm_close\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_fetch "" \fLsdbm_fetch\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_store "" \fLsdbm_store\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_delete "" \fLsdbm_delete\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_firstkey "" \fLsdbm_firstkey\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_nextkey "" \fLsdbm_nextkey\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_rdonly "" \fLsdbm_rdonly\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_error "" \fLsdbm_error\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_clearerr "" \fLsdbm_clearerr\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_dirfno "" \fLsdbm_dirfno\fP +.IX "database functions \(em \fLsdbm\fR" sdbm_pagfno "" \fLsdbm_pagfno\fP +.LP +This package allows an application to maintain a mapping of pairs +in disk files. This is not to be considered a real database system, but is +still useful in many simple applications built around fast retrieval of a data +value from a key. This implementation uses an external hashing scheme, +called Dynamic Hashing, as described by Per-Aake Larson in BIT 18 (1978) pp. +184-201. Retrieval of any item usually requires a single disk access. +The application interface is compatible with the +.IR ndbm (3) +library. +.LP +An +.B sdbm +database is kept in two files usually given the extensions +.B \.dir +and +.BR \.pag . +The +.B \.dir +file contains a bitmap representing a forest of binary hash trees, the leaves +of which indicate data pages in the +.B \.pag +file. +.LP +The application interface uses the +.B datum +structure to describe both +.I keys +and +.IR value s. +A +.B datum +specifies a byte sequence of +.I dsize +size pointed to by +.IR dptr . +If you use +.SM ASCII +strings as +.IR key s +or +.IR value s, +then you must decide whether or not to include the terminating +.SM NUL +byte which sometimes defines strings. Including it will require larger +database files, but it will be possible to get sensible output from a +.IR strings (1) +command applied to the data file. +.LP +In order to allow a process using this package to manipulate multiple +databases, the applications interface always requires a +.IR handle , +a +.BR "DBM *" , +to identify the database to be manipulated. Such a handle can be obtained +from the only routines that do not require it, namely +.BR sdbm_open (\|) +or +.BR sdbm_prep (\|). +Either of these will open or create the two necessary files. The +difference is that the latter allows explicitly naming the bitmap and data +files whereas +.BR sdbm_open (\|) +will take a base file name and call +.BR sdbm_prep (\|) +with the default extensions. +The +.I flags +and +.I mode +parameters are the same as for +.BR open (2). +.LP +To free the resources occupied while a database handle is active, call +.BR sdbm_close (\|). +.LP +Given a handle, one can retrieve data associated with a key by using the +.BR sdbm_fetch (\|) +routine, and associate data with a key by using the +.BR sdbm_store (\|) +routine. +.BR sdbm_exists (\|) +will say whether a given key exists in the database. +.LP +The values of the +.I flags +parameter for +.BR sdbm_store (\|) +can be either +.BR \s-1DBM_INSERT\s0 , +which will not change an existing entry with the same key, or +.BR \s-1DBM_REPLACE\s0 , +which will replace an existing entry with the same key. +Keys are unique within the database. +.LP +To delete a key and its associated value use the +.BR sdbm_delete (\|) +routine. +.LP +To retrieve every key in the database, use a loop like: +.sp +.nf +.ft B +for (key = sdbm_firstkey(db); key.dptr != NULL; key = sdbm_nextkey(db)) + ; +.ft R +.fi +.LP +The order of retrieval is unspecified. +.LP +If you determine that the performance of the database is inadequate or +you notice clustering or other effects that may be due to the hashing +algorithm used by this package, you can override it by supplying your +own +.BR sdbm_hash (\|) +routine. Doing so will make the database unintelligible to any other +applications that do not use your specialized hash function. +.sp +.LP +The following macros are defined in the header file: +.IP +.BR sdbm_rdonly (\|) +returns true if the database has been opened read\-only. +.IP +.BR sdbm_error (\|) +returns true if an I/O error has occurred. +.IP +.BR sdbm_clearerr (\|) +allows you to clear the error flag if you think you know what the error +was and insist on ignoring it. +.IP +.BR sdbm_dirfno (\|) +returns the file descriptor associated with the bitmap file. +.IP +.BR sdbm_pagfno (\|) +returns the file descriptor associated with the data file. +.SH SEE ALSO +.IR open (2). +.SH DIAGNOSTICS +Functions that return a +.B "DBM *" +handle will use +.SM NULL +to indicate an error. +Functions that return an +.B int +will use \-1 to indicate an error. The normal return value in that case is 0. +Functions that return a +.B datum +will return +.B nullitem +to indicate an error. +.LP +As a special case of +.BR sdbm_store (\|), +if it is called with the +.B \s-1DBM_INSERT\s0 +flag and the key already exists in the database, the return value will be 1. +.LP +In general, if a function parameter is invalid, +.B errno +will be set to +.BR \s-1EINVAL\s0 . +If a write operation is requested on a read-only database, +.B errno +will be set to +.BR \s-1ENOPERM\s0 . +If a memory allocation (using +.IR malloc (3)) +failed, +.B errno +will be set to +.BR \s-1ENOMEM\s0 . +For I/O operation failures +.B errno +will contain the value set by the relevant failed system call, either +.IR read (2), +.IR write (2), +or +.IR lseek (2). +.SH AUTHOR +.IP "Ozan S. Yigit" (oz@nexus.yorku.ca) +.SH BUGS +The sum of key and value data sizes must not exceed +.B \s-1PAIRMAX\s0 +(1008 bytes). +.LP +The sum of the key and value data sizes where several keys hash to the +same value must fit within one bitmap page. +.LP +The +.B \.pag +file will contain holes, so its apparent size is larger than its contents. +When copied through the filesystem the holes will be filled. +.LP +The contents of +.B datum +values returned are in volatile storage. If you want to retain the values +pointed to, you must copy them immediately before another call to this package. +.LP +The only safe way for multiple processes to (read and) update a database at +the same time, is to implement a private locking scheme outside this package +and open and close the database between lock acquisitions. It is safe for +multiple processes to concurrently access a database read-only. +.SH APPLICATIONS PORTABILITY +For complete source code compatibility with the Berkeley Unix +.IR ndbm (3) +library, the +.B sdbm.h +header file should be installed in +.BR /usr/include/ndbm.h . +.LP +The +.B nullitem +data item, and the +.BR sdbm_prep (\|), +.BR sdbm_hash (\|), +.BR sdbm_rdonly (\|), +.BR sdbm_dirfno (\|), +and +.BR sdbm_pagfno (\|) +functions are unique to this package. diff --git a/static/openbsd/man3/sem_destroy.3 b/static/openbsd/man3/sem_destroy.3 new file mode 100644 index 00000000..ba332c08 --- /dev/null +++ b/static/openbsd/man3/sem_destroy.3 @@ -0,0 +1,86 @@ +.\" $OpenBSD: sem_destroy.3,v 1.8 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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_r/man/sem_destroy.3,v 1.9 2001/10/01 16:09:09 ru Exp $ +.Dd $Mdocdate: June 7 2025 $ +.Dt SEM_DESTROY 3 +.Os +.Sh NAME +.Nm sem_destroy +.Nd destroy an unnamed semaphore +.Sh SYNOPSIS +.Lb libpthread +.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 +.Xr sem_init 3 . +.Sh RETURN VALUES +.Rv -std sem_destroy +.Sh ERRORS +.Fn sem_destroy +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.It Bq Er EBUSY +There are currently threads blocked on the semaphore that +.Fa sem +points to. +.El +.Sh SEE ALSO +.Xr sem_getvalue 3 , +.Xr sem_init 3 , +.Xr sem_open 3 , +.Xr sem_post 3 , +.Xr sem_wait 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/openbsd/man3/sem_getvalue.3 b/static/openbsd/man3/sem_getvalue.3 new file mode 100644 index 00000000..eeccc140 --- /dev/null +++ b/static/openbsd/man3/sem_getvalue.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: sem_getvalue.3,v 1.7 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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_r/man/sem_getvalue.3,v 1.9 2001/10/01 16:09:09 ru Exp $ +.Dd $Mdocdate: June 7 2025 $ +.Dt SEM_GETVALUE 3 +.Os +.Sh NAME +.Nm sem_getvalue +.Nd get the value of a semaphore +.Sh SYNOPSIS +.Lb libpthread +.In semaphore.h +.Ft int +.Fn sem_getvalue "sem_t *sem" "int *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_destroy 3 , +.Xr sem_init 3 , +.Xr sem_open 3 , +.Xr sem_post 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/openbsd/man3/sem_init.3 b/static/openbsd/man3/sem_init.3 new file mode 100644 index 00000000..a7ecd486 --- /dev/null +++ b/static/openbsd/man3/sem_init.3 @@ -0,0 +1,105 @@ +.\" $OpenBSD: sem_init.3,v 1.9 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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_r/man/sem_init.3,v 1.11 2001/10/01 16:09:09 ru Exp $ +.Dd $Mdocdate: June 7 2025 $ +.Dt SEM_INIT 3 +.Os +.Sh NAME +.Nm sem_init +.Nd initialize an unnamed semaphore +.Sh SYNOPSIS +.Lb libpthread +.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, which this +implementation is not capable of. +.Pp +Following a successful call to +.Fn sem_init , +.Fa sem +can be used as an argument in subsequent calls to +.Xr sem_wait 3 , +.Xr sem_trywait 3 , +.Xr sem_post 3 , +and +.Xr sem_destroy 3 . +.Fa sem +is no longer valid after a successful call to +.Xr sem_destroy 3 . +.Sh RETURN VALUES +.Rv -std sem_init +.Sh ERRORS +It is an error to call +.Xr sem_destroy 3 +on a named semaphore created by +.Xr sem_open 3 . +.Pp +.Fn sem_init +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa value +exceeds SEM_VALUE_MAX. +.It Bq Er ENOSPC +Memory allocation error. +.It Bq Er EPERM +Unable to initialize a shared semaphore. +.El +.Sh SEE ALSO +.Xr sem_destroy 3 , +.Xr sem_getvalue 3 , +.Xr sem_open 3 , +.Xr sem_post 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_init +conforms to +.St -p1003.1-96 . +.Pp +This implementation does not support shared semaphores, and reports this fact +by setting +.Va errno +to +.Er EPERM . +This is perhaps a stretch of the intention of POSIX, but is +compliant, with the caveat that +.Fn sem_init +always reports a permissions error when an attempt to create a shared semaphore +is made. diff --git a/static/openbsd/man3/sem_open.3 b/static/openbsd/man3/sem_open.3 new file mode 100644 index 00000000..55acaec1 --- /dev/null +++ b/static/openbsd/man3/sem_open.3 @@ -0,0 +1,94 @@ +.\" $OpenBSD: sem_open.3,v 1.13 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (c) 2013 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 $Mdocdate: June 7 2025 $ +.Dt SEM_OPEN 3 +.Os +.Sh NAME +.Nm sem_open , +.Nm sem_close , +.Nm sem_unlink +.Nd open and close named semaphores +.Sh SYNOPSIS +.Lb libpthread +.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 opens and returns a named semaphore. +The +.Fn sem_close +function closes a previously opened named semaphore without removing it. +The +.Fn sem_unlink +function removes the named semaphore from the system without closing it. +.Sh RETURN VALUES +On success, +.Fn sem_open +returns a pointer to a semaphore. +.Fn sem_close +and +.Fn sem_unlink +return 0 on success. +.Fn sem_open +returns SEM_FAILED and sets +.Va errno +to indicate an error. +.Fn sem_close +and +.Fn sem_unlink +return -1 and set +.Va errno +to indicate an error. +.Sh ERRORS +It is an error to call +.Fn sem_close +with an unnamed semaphore or to call +.Xr sem_destroy 3 +with a named semaphore. +.Pp +.Fn sem_open +may fail if: +.Bl -tag -width Er +.It Bq Er ENOSPC +Insufficient memory is available. +.It Bq Er EPERM +An attempt was made to open a shared semaphore owned by another user. +.El +.Pp +.Fn sem_unlink +may fail for any of the reasons listed in +.Xr unlink 2 . +.Sh SEE ALSO +.Xr sem_destroy 3 , +.Xr sem_getvalue 3 , +.Xr sem_init 3 , +.Xr sem_post 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_open , +.Fn sem_close , +and +.Fn sem_unlink +appear in +.St -p1003.1-96 . +This implementation deviates from the standard by permitting less sharing. diff --git a/static/openbsd/man3/sem_post.3 b/static/openbsd/man3/sem_post.3 new file mode 100644 index 00000000..54a7cd48 --- /dev/null +++ b/static/openbsd/man3/sem_post.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: sem_post.3,v 1.7 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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_r/man/sem_post.3,v 1.10 2001/10/01 16:09:09 ru Exp $ +.Dd $Mdocdate: June 7 2025 $ +.Dt SEM_POST 3 +.Os +.Sh NAME +.Nm sem_post +.Nd increment (unlock) a semaphore +.Sh SYNOPSIS +.Lb libpthread +.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 +.Xr sem_wait 3 . +.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_destroy 3 , +.Xr sem_getvalue 3 , +.Xr sem_init 3 , +.Xr sem_open 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_post +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/sem_wait.3 b/static/openbsd/man3/sem_wait.3 new file mode 100644 index 00000000..db0235bb --- /dev/null +++ b/static/openbsd/man3/sem_wait.3 @@ -0,0 +1,133 @@ +.\" $OpenBSD: sem_wait.3,v 1.11 2025/06/07 00:16:52 schwarze Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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_r/man/sem_wait.3,v 1.8 2001/10/01 16:09:09 ru Exp $ +.Dd $Mdocdate: June 7 2025 $ +.Dt SEM_WAIT 3 +.Os +.Sh NAME +.Nm sem_wait , +.Nm sem_timedwait , +.Nm sem_trywait +.Nd decrement (lock) a semaphore +.Sh SYNOPSIS +.Lb libpthread +.In semaphore.h +.Ft int +.Fn sem_wait "sem_t *sem" +.Ft int +.Fn sem_timedwait "sem_t *sem" "const struct timespec *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 decrements (locks) the semaphore pointed to by +.Fa sem , +but blocks if the value of +.Fa sem +is zero, until either the value is non-zero and can be decremented +or the system time specified by +.Fa abstime +is reached. +.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 sem_timedwait sem_trywait +.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_wait +and +.Fn sem_timedwait +will fail if: +.Bl -tag -width Er +.It Bq Er EINTR +The call was interrupted by a signal. +.El +.Pp +Additionally, +.Fn sem_timedwait +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa abstime +was +.Dv NULL +or specified a nanosecond value less than zero or greater than 1000 million. +.It Bq Er ETIMEDOUT +The semaphore value was zero and could not be decremented before +.Fa abstime +was reached. +.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 +.Sh SEE ALSO +.Xr sem_destroy 3 , +.Xr sem_getvalue 3 , +.Xr sem_init 3 , +.Xr sem_open 3 , +.Xr sem_post 3 +.Sh STANDARDS +.Fn sem_wait , +.Fn sem_timedwait , +and +.Fn sem_trywait +conform to +.St -p1003.1-2008 . diff --git a/static/openbsd/man3/setbuf.3 b/static/openbsd/man3/setbuf.3 new file mode 100644 index 00000000..8dd17aca --- /dev/null +++ b/static/openbsd/man3/setbuf.3 @@ -0,0 +1,140 @@ +.\" $OpenBSD: setbuf.3,v 1.16 2014/11/25 19:08:14 millert 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. +.\" +.Dd $Mdocdate: November 25 2014 $ +.Dt SETBUF 3 +.Os +.Sh NAME +.Nm setbuf , +.Nm setbuffer , +.Nm setlinebuf +.Nd stream buffering operations +.Sh SYNOPSIS +.In stdio.h +.Ft void +.Fn setbuf "FILE *stream" "char *buf" +.Ft void +.Fn setbuffer "FILE *stream" "char *buf" "size_t size" +.Ft int +.Fn setlinebuf "FILE *stream" +.Sh DESCRIPTION +.Bf -symbolic +These interfaces are obsoleted by +.Xr setvbuf 3 . +.Ef +.Pp +The +.Fn setbuf , +.Fn setbuffer , +and +.Fn setlinebuf +functions are used to modify the buffering of a stream. +These functions are provided for compatibility with legacy code. +New code should use +.Xr setvbuf 3 +instead. +.Pp +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 . +.Pp +The +.Fn setlinebuf +function is exactly equivalent to the call: +.Pp +.Dl "setvbuf(stream, NULL, _IOLBF, 0);" +.Sh RETURN VALUES +Upon successful completion, the +.Fn setlinebuf +function returns 0. +If the request cannot be honored, a non-zero value is returned, +possibly setting +.Va errno +to indicate the error. +The stream is not modified in the error case. +.Sh ERRORS +The +.Fn setbuf , +.Fn setbuffer , +and +.Fn setlinebuf +functions will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa stream +specified is not associated with a valid file descriptor. +.El +.Sh SEE ALSO +.Xr fclose 3 , +.Xr fopen 3 , +.Xr fread 3 , +.Xr malloc 3 , +.Xr printf 3 , +.Xr puts 3 , +.Xr setvbuf 3 +.Sh STANDARDS +The +.Fn setbuf +function conforms to +.St -isoC-99 . +The +.Fn setbuffer +and +.Fn setlinebuf +functions are non-standard and should not be used if portability is required. +.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 . +.Sh BUGS +The +.Fn setbuf +function usually uses a suboptimal buffer size and should be avoided. diff --git a/static/openbsd/man3/setjmp.3 b/static/openbsd/man3/setjmp.3 new file mode 100644 index 00000000..ce9ca0ad --- /dev/null +++ b/static/openbsd/man3/setjmp.3 @@ -0,0 +1,211 @@ +.\" $OpenBSD: setjmp.3,v 1.26 2022/09/11 06:38:10 jmc 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt SETJMP 3 +.Os +.Sh NAME +.Nm sigsetjmp , +.Nm siglongjmp , +.Nm setjmp , +.Nm longjmp , +.Nm _setjmp , +.Nm _longjmp +.Nd non-local jumps +.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" +.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 value specified by +.Fa val +must be non-zero; a 0 value is treated as 1 to allow the programmer +to differentiate between a direct invocation of +.Fn setjmp +and a return via +.Fn longjmp . +.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 \(em 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 the +.Fn longjmp +routine was called, except that the values of objects of automatic storage +invocation duration that do not have the +.Vt 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 the +.Fn _setjmp Ns / Ns Fn _longjmp +function pairs save and restore only the register set and the stack (see +.Xr 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 SEE ALSO +.Xr sigprocmask 2 +.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 HISTORY +The +.Fn setjmp +and +.Fn longjmp +functions first appeared in the Programmer's Workbench (PWB/UNIX). +.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, as discussed in +.Xr signal 3 . +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/openbsd/man3/setlocale.3 b/static/openbsd/man3/setlocale.3 new file mode 100644 index 00000000..be2728fb --- /dev/null +++ b/static/openbsd/man3/setlocale.3 @@ -0,0 +1,326 @@ +.\" $OpenBSD: setlocale.3,v 1.24 2022/08/04 06:20:24 jsg Exp $ +.\" $NetBSD: setlocale.3,v 1.3 1997/07/14 23:19:47 kleink 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 $Mdocdate: August 4 2022 $ +.Dt SETLOCALE 3 +.Os +.Sh NAME +.Nm setlocale +.Nd select character encoding +.Sh SYNOPSIS +.In locale.h +.Ft char * +.Fn setlocale "int category" "const char *locale" +.Sh DESCRIPTION +The +.Fn setlocale +function sets and retrieves the active +.Fa locale +for the current process. +The locale modifies the behaviour of some functions in the C library +with respect to the character encoding, and on other operating systems +also with respect to some language and cultural conventions. +For more information about locales in general, see the +.Xr locale 1 +manual page. +.Pp +On +.Ox , +the only useful value for the +.Fa category +is +.Dv LC_CTYPE . +It sets the locale used for character encoding, character classification, +and case conversion. +For compatibility with natural language support in +.Xr packages 7 , +all other categories \(em +.Dv LC_COLLATE , +.Dv LC_MESSAGES , +.Dv LC_MONETARY , +.Dv LC_NUMERIC , +and +.Dv LC_TIME +\(em can be set and retrieved, too, but their values are ignored by the +.Ox +C library. +A category of +.Dv LC_ALL +sets the entire locale generically, which is strongly discouraged for +security reasons in portable programs. +.Pp +The syntax and semantics of the +.Fa locale +argument are not standardized and vary among operating systems. +On +.Ox , +if the +.Fa locale +string ends with +.Qq ".UTF-8" , +the UTF-8 locale is selected; otherwise, the +.Qq C +locale is selected, which uses the ASCII character set. +If the +.Fa locale +contains a dot but does not end with +.Qq ".UTF-8" , +.Fn setlocale +fails. +.Pp +If +.Fa locale +is an empty string +.Pq Qq , +the value of the environment variable +.Ev LC_ALL , +with a fallback to the variable corresponding to +.Fa category , +and with a further fallback to +.Ev LANG , +is used instead, as documented in the +.Xr locale 1 +manual page. +.Pp +If +.Fa locale +is +.Dv NULL , +the locale remains unchanged. +This can be used to determine the currently active locale. +.Pp +By default, C programs start in the +.Qq C +locale. +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 +The +.Dv LC_CTYPE +category modifies the behaviour of at least the following functions: +.Xr iswctype 3 , +.Xr mblen 3 , +.Xr mbrlen 3 , +.Xr mbrtowc 3 , +.Xr mbsrtowcs 3 , +.Xr mbstowcs 3 , +.Xr mbtowc 3 , +.Xr towctrans 3 , +.Xr towlower 3 , +.Xr towupper 3 , +.Xr wcrtomb 3 , +.Xr wcscasecmp 3 , +.Xr wcsrtombs 3 , +.Xr wcstombs 3 , +.Xr wctomb 3 , +.Xr wctrans 3 , +.Xr wctype 3 , +and the functions documented in +.Xr iswalnum 3 . +.Sh RETURN VALUES +In case of success, +.Fn setlocale +returns a pointer to a static string describing the locale +that is in force after the call. +Subsequent calls to +.Fn setlocale +may change the content of the string. +The format of the string is not standardized and varies among +operating systems. +.Pp +On +.Ox , +if +.Fn setlocale +was never called with a +.Pf non- Dv NULL +.Fa locale +argument, the string +.Qq C +is returned. +Otherwise, if the +.Fa category +was not +.Dv LC_ALL +or if the locale is the same for all categories, a copy of the +.Fa locale +argument is returned. +Otherwise, the locales for the six categories +.Dv LC_COLLATE , +.Dv LC_CTYPE , +.Dv LC_MESSAGES , +.Dv LC_MONETARY , +.Dv LC_NUMERIC , +.Dv LC_TIME +are concatenated in that order, with slash +.Pq Ql / +characters in between. +.Pp +In case of failure, +.Fn setlocale +returns +.Dv NULL . +On +.Ox , +that can only happen if the +.Fa category +is invalid, if a character encoding other than UTF-8 is requested, +if the requested +.Fa locale +name is of excessive length, or if memory allocation fails. +.Sh EXAMPLES +Calling +.Pp +.Dl setlocale(LC_CTYPE, \(dqen_US.UTF-8\(dq); +.Pp +at the beginning of a program selects the UTF-8 locale and returns +.Qq en_US.UTF-8 . +Calling +.Pp +.Dl setlocale(LC_ALL, NULL); +.Pp +right afterwards leaves the locale unchanged and returns +.Qq C/en_US.UTF-8/C/C/C/C . +.Sh SEE ALSO +.Xr locale 1 , +.Xr newlocale 3 , +.Xr nl_langinfo 3 , +.Xr uselocale 3 +.Sh STANDARDS +The +.Fn setlocale +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn setlocale +function first appeared in +.Bx 4.3 Net/2 . +.Sh CAVEATS +On systems other than +.Ox , +calling +.Fn setlocale +or +.Xr uselocale 3 +with a +.Fa category +other than +.Dv LC_CTYPE +can cause erratic behaviour of many library functions. +For security reasons, make sure that portable programs only use +.Dv LC_CTYPE . +.Pp +For example, the following functions may be affected. +The list is probably incomplete. +For example, additional library functions may be impacted +if they directly or indirectly call affected functions, +or if they attempt to imitate aspects of their behaviour. +Functions that are not standardized may be affected too. +.Bl -tag -width Ds +.It Dv LC_COLLATE +.Xr glob 3 , +.Xr strcoll 3 , +.Xr strxfrm 3 , +.Xr wcscoll 3 , +.Xr wcsxfrm 3 , +and the functions documented in +.Xr regexec 3 +.It Dv LC_MESSAGES +.Xr catgets 3 , +.Xr catopen 3 , +.Xr nl_langinfo 3 , +.Xr perror 3 , +.Xr psignal 3 , +.Xr strerror 3 , +.Xr strsignal 3 , +and the functions documented in +.Xr err 3 +.It Dv LC_MONETARY +.Xr localeconv 3 , +.Xr nl_langinfo 3 , +.Fn strfmon +.It Dv LC_NUMERIC +.Xr atof 3 , +.Xr localeconv 3 , +.Xr nl_langinfo 3 , +.Fn strfmon , +and the functions documented in +.Xr printf 3 , +.Xr scanf 3 , +.Xr strtod 3 , +.Xr wcstod 3 , +.Xr wprintf 3 , +.Xr wscanf 3 . +This category is particularly dangerous because it can cause bugs +in the parsing and formatting of numbers, for example failures to +recognize or properly write decimal points. +.It Dv LC_TIME +.Fn getdate , +.Xr nl_langinfo 3 , +.Xr strftime 3 , +.Xr strptime 3 . +Similarly, this is prone to causing bugs in the parsing and formatting +of date strings. +.It Dv LC_CTYPE +On systems other than +.Ox , +this category may affect the behaviour of additional functions, +for example: +.Xr btowc 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 mbsinit 3 , +.Xr strcasecmp 3 , +.Xr strcoll 3 , +.Xr strxfrm 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr vis 3 , +.Xr wcscoll 3 , +.Xr wcsxfrm 3 , +.Xr wctob 3 +.El diff --git a/static/openbsd/man3/setmode.3 b/static/openbsd/man3/setmode.3 new file mode 100644 index 00000000..fd54ed56 --- /dev/null +++ b/static/openbsd/man3/setmode.3 @@ -0,0 +1,108 @@ +.\" $OpenBSD: setmode.3,v 1.15 2022/07/30 07:19:30 jsg 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. +.\" +.Dd $Mdocdate: July 30 2022 $ +.Dt SETMODE 3 +.Os +.Sh NAME +.Nm getmode , +.Nm setmode +.Nd modify mode bits +.Sh SYNOPSIS +.In unistd.h +.Ft mode_t +.Fn getmode "const void *set" "mode_t mode" +.Ft void * +.Fn setmode "const char *mode_str" +.Sh DESCRIPTION +The +.Fn getmode +function returns a copy of the file permission bits +.Fa mode +as altered by the values pointed to by +.Fa set . +While only the mode bits are altered, other parts of the file mode +may be examined. +.Pp +The +.Fn setmode +function takes an absolute (octal) or symbolic value, as described in +.Xr chmod 1 , +as an argument +and returns a pointer to mode values to be supplied to +.Fn getmode . +Because some of the symbolic values are relative to the file +creation mask, +.Fn setmode +may call +.Xr umask 2 . +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 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 . +The caller is responsible for freeing the pointer that +.Fn setmode +returns. +.Sh ERRORS +The +.Fn setmode +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr malloc 3 +or to +.Er ERANGE +if an invalid octal value was specified, or +.Er EINVAL +if an invalid symbolic value was specified. +.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.3 Reno . diff --git a/static/openbsd/man3/setproctitle.3 b/static/openbsd/man3/setproctitle.3 new file mode 100644 index 00000000..1eef7d0e --- /dev/null +++ b/static/openbsd/man3/setproctitle.3 @@ -0,0 +1,94 @@ +.\" $OpenBSD: setproctitle.3,v 1.18 2013/06/05 03:39:22 tedu 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 by Christopher G. Demetriou +.\" for the NetBSD Project. +.\" 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 $Mdocdate: June 5 2013 $ +.Dt SETPROCTITLE 3 +.Os +.Sh NAME +.Nm setproctitle +.Nd set process title +.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, a single space, and the formatted string specified +by +.Fa fmt . +If +.Fa 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 0.9a . +.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 the stack, +leading to a possible security hole. +This holds true even if the string has been built +.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/openbsd/man3/setvbuf.3 b/static/openbsd/man3/setvbuf.3 new file mode 100644 index 00000000..b36e8b45 --- /dev/null +++ b/static/openbsd/man3/setvbuf.3 @@ -0,0 +1,161 @@ +.\" $OpenBSD: setvbuf.3,v 1.5 2022/07/25 02:25:55 jsg 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. +.\" +.Dd $Mdocdate: July 25 2022 $ +.Dt SETVBUF 3 +.Os +.Sh NAME +.Nm setvbuf +.Nd stream buffering operations +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn setvbuf "FILE *stream" "char *buf" "int mode" "size_t size" +.Sh DESCRIPTION +The three types of stream 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 line buffered, characters are saved up until a newline +.Pq Ql \en +is output or input is read from any stream attached to a terminal device +(typically +.Em stdin ) . +.Pp +The +.Xr fflush 3 +function may be used to force the block out early. +.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 +.Em stdout +normally does), it is line buffered. +.Pp +The standard error stream +.Em 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: +.Pp +.Bl -tag -width _IOFBF -offset indent -compact +.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 +.Dq active . +Portable applications should call it only once on any given stream, +and before any I/O is performed. +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +If +.Fa mode +is invalid or if the request cannot be honored, a non-zero value is returned, +possibly setting +.Va errno +to indicate the error. +The stream is not modified in the error case. +.Sh ERRORS +The +.Fn setvbuf +function will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa stream +specified is not associated with a valid file descriptor. +.El +.Sh SEE ALSO +.Xr fclose 3 , +.Xr fopen 3 , +.Xr fread 3 , +.Xr malloc 3 , +.Xr printf 3 , +.Xr puts 3 , +.Xr setbuf 3 +.Sh STANDARDS +The +.Fn setvbuf +function conforms to +.St -isoC-99 . +.Sh HISTORY +The +.Fn setvbuf +function first appeared in +.At V.2 +and was reimplemented for +.Bx 4.3 Net/2 . diff --git a/static/openbsd/man3/shm_open.3 b/static/openbsd/man3/shm_open.3 new file mode 100644 index 00000000..ea6c0e6f --- /dev/null +++ b/static/openbsd/man3/shm_open.3 @@ -0,0 +1,105 @@ +.\" $OpenBSD: shm_open.3,v 1.6 2025/08/04 04:59:31 guenther Exp $ +.\" +.\" Copyright (c) 2013 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 $Mdocdate: August 4 2025 $ +.Dt SHM_OPEN 3 +.Os +.Sh NAME +.Nm shm_open , +.Nm shm_unlink , +.Nm shm_mkstemp +.Nd create and destroy shared memory objects +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn shm_open "const char *path" "int flags" "mode_t mode" +.Ft int +.Fn shm_unlink "const char *path" +.Ft int +.Fn shm_mkstemp "char *template" +.Sh DESCRIPTION +The +.Fn shm_open +function opens a shared memory object and returns a file descriptor suitable +for use with +.Xr mmap 2 . +The +.Fa flags +argument has the same meaning as provided to +.Xr open 2 +and must include at least +.Dv O_RDONLY +or +.Dv O_RDWR +and may also include a combination of +.Dv O_CREAT , O_EXCL , O_CLOEXEC , O_CLOFORK , O_NOFOLLOW , +or +.Dv O_TRUNC . +This implementation forces the +.Fa mode +to be 0600 or 0400, and prohibits sharing between different UIDs. +.Pp +.Fn shm_unlink +is used to remove a shared memory object. +The object is not freed until all references to it have been released via +.Xr close 2 . +.Pp +If a temporary shared memory object is desired, the +.Fn shm_mkstemp +function should be preferred as it avoids several possible security +holes that tend to appear in programs trying to create their own unique +temporary names. +The +.Fa template +argument is a string with at least six trailing Xs as described in +.Xr mkstemp 3 . +.Sh RETURN VALUES +.Fn shm_open +and +.Fn shm_mkstemp +return a file descriptor on successful completion. +They may fail for any of the reasons listed in +.Xr open 2 . +.Sh SEE ALSO +.Xr mmap 2 +.Sh STANDARDS +.Fn shm_open +and +.Fn shm_unlink +appear in +.St -p1003.1-2001 . +Using +.Dv O_CLOEXEC , +.Dv O_CLOFORK , +or +.Dv O_NOFOLLOW +with +.Fn shm_open +is an extension to that standard. +This implementation deviates from the standard by permitting less sharing. +.Pp +.Fn shm_mkstemp +is an extension. +.Sh HISTORY +The +.Fn shm_open , +.Fn shm_unlink , +and +.Fn shm_mkstemp +functions have been available since +.Ox 5.4 . +.Sh AUTHORS +.An Ted Unangst Aq Mt tedu@openbsd.org . diff --git a/static/openbsd/man3/sigaddset.3 b/static/openbsd/man3/sigaddset.3 new file mode 100644 index 00000000..6e8bc5c8 --- /dev/null +++ b/static/openbsd/man3/sigaddset.3 @@ -0,0 +1,116 @@ +.\" $OpenBSD: sigaddset.3,v 1.1 2017/05/29 09:40:02 deraadt 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 $Mdocdate: May 29 2017 $ +.Dt SIGADDSET 3 +.Os +.Sh NAME +.Nm sigemptyset , +.Nm sigfillset , +.Nm sigaddset , +.Nm sigdelset , +.Nm sigismember +.Nd manipulate signal sets +.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 "const 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. +.Fn sigemptyset +and +.Fn sigfillset +are provided as macros, but actual functions are available +if their names are undefined (with #undef +.Ar name ) . +.Pp +The +.Fn sigemptyset +function initializes a signal set to be empty. +.Pp +.Fn sigfillset +initializes a signal set to contain all signals. +.Pp +.Fn sigaddset +adds the specified signal +.Fa signo +to the signal set. +.Pp +.Fn sigdelset +deletes the specified signal +.Fa signo +from the signal set. +.Pp +.Fn sigismember +returns whether a specified signal +.Fa signo +is contained in the signal set. +.Sh RETURN VALUES +The +.Fn sigismember +function returns 1 +if the signal is a member of the set and 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 may fail if one of the following occurs: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified signal +.Fa signo +is not a valid signal number. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 +.Sh STANDARDS +These functions are defined by +.St -p1003.1-90 . diff --git a/static/openbsd/man3/sigblock.3 b/static/openbsd/man3/sigblock.3 new file mode 100644 index 00000000..73ef8c69 --- /dev/null +++ b/static/openbsd/man3/sigblock.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) 1983, 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. +.\" +.\" $OpenBSD: sigblock.3,v 1.21 2022/12/13 06:56:06 jmc Exp $ +.\" +.Dd $Mdocdate: December 13 2022 $ +.Dt SIGBLOCK 3 +.Os +.Sh NAME +.Nm sigblock , +.Nm sigmask +.Nd block signals +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigblock "int mask" +.Ft int +.Fn sigmask "int 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 utilizing +.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 sigaddset 3 , +.Xr sigsetmask 3 +.Sh HISTORY +A +.Fn sigblock +system call first appeared in +.Bx 4.2 . +In +.Bx 4.3 Reno , +it was reimplemented as a wrapper around +.Xr sigprocmask 2 . +The old system call was kept for compatibility until +.Ox 4.9 . diff --git a/static/openbsd/man3/siginterrupt.3 b/static/openbsd/man3/siginterrupt.3 new file mode 100644 index 00000000..68d2e038 --- /dev/null +++ b/static/openbsd/man3/siginterrupt.3 @@ -0,0 +1,91 @@ +.\" $OpenBSD: siginterrupt.3,v 1.14 2013/06/05 03:39:22 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt SIGINTERRUPT 3 +.Os +.Sh NAME +.Nm siginterrupt +.Nd allow signals to interrupt system calls +.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 +.Fa flag +is false (0), system calls will be restarted if +they are interrupted by the specified signal +.Fa sig +and no data has been transferred yet. +System call restart is the default behavior on +.Ox . +.Pp +If +.Fa flag +is true (1), +the 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 +systems prior to +.Bx 4.2 +as well as most systems based upon +.At V . +.Pp +Programs may switch between restartable and interruptible +system call operation as often as desired in the execution of a program. +Issuing a +.Fn siginterrupt +call during the execution of a signal handler will cause +the new action to take place on the next signal to be caught. +.Sh RETURN VALUES +.Fn siginterrupt +returns 0 on success or \-1 if an invalid signal number has been +specified. +.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/openbsd/man3/signal.3 b/static/openbsd/man3/signal.3 new file mode 100644 index 00000000..9b045e0a --- /dev/null +++ b/static/openbsd/man3/signal.3 @@ -0,0 +1,513 @@ +.\" $OpenBSD: signal.3,v 1.61 2025/11/06 17:46:34 schwarze 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. +.\" +.Dd $Mdocdate: November 6 2025 $ +.Dt SIGNAL 3 +.Os +.Sh NAME +.Nm signal , +.Nm bsd_signal +.Nd simplified software signal facilities +.Sh SYNOPSIS +.In signal.h +.Ft void +.Fo "(*signal(int sigcatch, void (*func)(int sigraised)))" +.Fa int +.Fc +.Ft void +.Fo "(*bsd_signal(int sigcatch, void (*func)(int sigraised)))" +.Fa int +.Fc +.Sh DESCRIPTION +The +.Fn signal +and +.Fn bsd_signal +facilities are simplified interfaces to the more general +.Xr sigaction 2 +facility. +The +.Fn bsd_signal +interface is provided for source compatibility only. +It is mainly used on systems where the standard +.Fn signal +does not have +.Bx +semantics. +On +.Ox +the two interfaces are identical. +.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 +.Dq interrupt +character. +.Pp +Signals are used when a process is stopped because it wishes to access +its controlling 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 controlling 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. +.Pp +Except for the +.Dv SIGKILL +and +.Dv SIGSTOP +signals, the +.Fn signal +function allows for any signal to be caught, to be ignored, or to generate +an interrupt. +These signals are defined in the file +.In signal.h : +.Bl -column "SIGVTALRM" "create core image" "terminal line hangup" +.It Sy "Name" Ta Sy "Default Action" Ta Sy "Description" +.It Dv SIGHUP Ta "terminate process" Ta "terminal line hangup" +.It Dv SIGINT Ta "terminate process" Ta "interrupt program" +.It Dv SIGQUIT Ta "create core image" Ta "quit program" +.It Dv SIGILL Ta "create core image" Ta "illegal instruction" +.It Dv SIGTRAP Ta "create core image" Ta "trace trap" +.It Dv SIGABRT Ta "create core image" Ta "abort(3) call (formerly SIGIOT)" +.It Dv SIGEMT Ta "create core image" Ta "emulate instruction executed" +.It Dv SIGFPE Ta "create core image" Ta "floating-point exception" +.It Dv SIGKILL Ta "terminate process" Ta "kill program (cannot be caught or ignored)" +.It Dv SIGBUS Ta "create core image" Ta "bus error" +.It Dv SIGSEGV Ta "create core image" Ta "segmentation violation" +.It Dv SIGSYS Ta "create core image" Ta "system call given invalid argument" +.It Dv SIGPIPE Ta "terminate process" Ta "write on a pipe with no reader" +.It Dv SIGALRM Ta "terminate process" Ta "real-time timer expired" +.It Dv SIGTERM Ta "terminate process" Ta "software termination signal" +.It Dv SIGURG Ta "discard signal" Ta "urgent condition present on socket" +.It Dv SIGSTOP Ta "stop process" Ta "stop (cannot be caught or ignored)" +.It Dv SIGTSTP Ta "stop process" Ta "stop signal generated from keyboard" +.It Dv SIGCONT Ta "discard signal" Ta "continue after stop" +.It Dv SIGCHLD Ta "discard signal" Ta "child status has changed" +.It Dv SIGTTIN Ta "stop process" Ta "background read attempted from controlling terminal" +.It Dv SIGTTOU Ta "stop process" Ta "background write attempted to controlling terminal" +.It Dv SIGIO Ta "discard signal" Ta "I/O is possible on a descriptor (see" +.Xr fcntl 2 ) +.It Dv SIGXCPU Ta "terminate process" Ta "CPU time limit exceeded (see" +.Xr setrlimit 2 ) +.It Dv SIGXFSZ Ta "terminate process" Ta "file size limit exceeded (see" +.Xr setrlimit 2 ) +.It Dv SIGVTALRM Ta "terminate process" Ta "virtual time alarm (see" +.Xr setitimer 2 ) +.It Dv SIGPROF Ta "terminate process" Ta "profiling timer alarm (see" +.Xr setitimer 2 ) +.It Dv SIGWINCH Ta "discard signal" Ta "window size change" +.It Dv SIGINFO Ta "discard signal" Ta "status request from keyboard" +.It Dv SIGUSR1 Ta "terminate process" Ta "user-defined signal 1" +.It Dv SIGUSR2 Ta "terminate process" Ta "user-defined signal 2" +.It Dv SIGTHR Ta "discard signal" Ta "thread AST" +.El +.Pp +The +.Fa func +argument is a function to be called as the action upon receipt of the signal +.Fa sigcatch . +The function will be called with one argument, +.Fa sigraised , +which is the signal raised (thus the same function, +.Fa func , +can be used by more than one 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 +If the +.Fa func +is set to +.Dv SIG_IGN +for the +.Dv SIGCHLD +signal, the system will not create zombie processes when children of +the calling process exit. +If the calling process subsequently issues a +.Xr wait 2 +(or equivalent), it blocks until all of the calling process's child +processes terminate, and then returns a value of \-1 with +.Va errno +set to +.Dv ECHILD . +.Bf -symbolic +This differs from historical +.Bx +behavior but is consistent with +.At V +as well as the +.St -xpg4.2 . +.Ef +.Pp +The handled signal is unblocked when +.Fa func +returns and +the process continues from where it left off when the signal occurred. +.Bf -symbolic +Unlike previous signal facilities, the handler +func() remains installed after a signal has been delivered. +.Ef +.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 an +.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). +The +.Xr siginterrupt 3 +function can be used to change the system call restart behavior for +a specific signal. +.Pp +When a process which has installed signal handlers forks, +the child process inherits the signals. +All caught signals, as well as +.Dv SIGCHLD , +are reset to their default action by a call +to the +.Xr execve 2 +function; +other +ignored signals remain ignored. +.Pp +Signal handlers should be as minimal as possible, and use only signal-safe +operations. +The safest handlers only change a single variable of type +.Va volatile sig_atomic_t , +which is inspected by an event loop. +Other variables accessed inside the handler must be either const, or +local to the handler. +More complicated global variables (such as strings, structs, or lists) +will require external methods to guarantee consistency, such as +signal-blocking with +.Xr sigprocmask 2 . +.Pp +More complicated handlers must restrict themselves to calling only the following +list of signal-safe functions directly. +Avoid abstracting the work to helper functions which are also called from +other contexts because future coders will forget the signal-safe requirement. +.Pp +Standard Interfaces: +.Pp +.Fn _exit , +.Fn _Exit , +.Fn abort , +.Fn accept , +.Fn access , +.Fn alarm , +.Fn bind , +.Fn cfgetispeed , +.Fn cfgetospeed , +.Fn cfsetispeed , +.Fn cfsetospeed , +.Fn chdir , +.Fn chmod , +.Fn chown , +.Fn clock_gettime , +.Fn close , +.Fn connect , +.Fn creat , +.Fn dup , +.Fn dup2 , +.Fn execl , +.Fn execle , +.Fn execv , +.Fn execve , +.Fn faccessat , +.Fn fchdir , +.Fn fchmod , +.Fn fchmodat , +.Fn fchown , +.Fn fchownat , +.Fn fcntl , +.Fn fdatasync , +.Fn fork , +.Fn fpathconf , +.Fn fstat , +.Fn fstatat , +.Fn fsync , +.Fn ftruncate , +.Fn futimens , +.Fn futimes , +.Fn getegid , +.Fn geteuid , +.Fn getgid , +.Fn getgroups , +.Fn getpeername , +.Fn getpgrp , +.Fn getpid , +.Fn getppid , +.Fn getsockname , +.Fn getsockopt , +.Fn getuid , +.Fn kill , +.Fn link , +.Fn linkat , +.Fn listen , +.Fn lseek , +.Fn lstat , +.Fn mkdir , +.Fn mkdirat , +.Fn mkfifo , +.Fn mkfifoat , +.Fn mknod , +.Fn mknodat , +.Fn open , +.Fn openat , +.Fn pathconf , +.Fn pause , +.Fn pipe , +.Fn poll , +.Fn pselect , +.Fn pthread_sigmask , +.Fn raise , +.Fn read , +.Fn readlink , +.Fn readlinkat , +.Fn recv , +.Fn recvfrom , +.Fn recvmsg , +.Fn rename , +.Fn renameat , +.Fn rmdir , +.Fn select , +.Fn send , +.Fn sendmsg , +.Fn sendto , +.Fn setgid , +.Fn setpgid , +.Fn setsid , +.Fn setsockopt , +.Fn setuid , +.Fn shutdown , +.Fn sigaction , +.Fn sigaddset , +.Fn sigdelset , +.Fn sigemptyset , +.Fn sigfillset , +.Fn sigismember , +.Fn signal , +.Fn sigpause , +.Fn sigpending , +.Fn sigprocmask , +.Fn sigsuspend , +.Fn sleep , +.Fn sockatmark , +.Fn socket , +.Fn socketpair , +.Fn stat , +.Fn strcat , +.Fn strcpy , +.Fn strncat , +.Fn strncpy , +.Fn symlink , +.Fn symlinkat , +.Fn sysconf , +.Fn tcdrain , +.Fn tcflow , +.Fn tcflush , +.Fn tcgetattr , +.Fn tcgetpgrp , +.Fn tcsendbreak , +.Fn tcsetattr , +.Fn tcsetpgrp , +.Fn time , +.Fn times , +.Fn umask , +.Fn uname , +.Fn unlink , +.Fn unlinkat , +.Fn utime , +.Fn utimensat , +.Fn utimes , +.Fn wait , +.Fn waitpid , +.Fn write , +and perhaps some others. +.\" unimplemented functions that should be async-sig-safe, if we had them +.\" POSIX Issue 7 additions +.\" .Pp +.\" .Fn fexecve . +.\" +.\" Realtime Interfaces: +.\" .Pp +.\" .Fn aio_error , +.\" .Fn aio_return , +.\" .Fn aio_suspend , +.\" .Fn sem_post , +.\" .Fn sigqueue , +.\" .Fn timer_getoverrun , +.\" .Fn timer_gettime , +.\" .Fn timer_settime . +.Pp +Extension Interfaces: +.Pp +.Fn accept4 , +.Fn chflags , +.Fn chflagsat , +.Fn dup3 , +.Fn fchflags , +.Fn getentropy , +.Fn getresgid , +.Fn getresuid , +.Fn pipe2 , +.Fn ppoll , +.Fn sendsyslog , +.Fn setresgid , +.Fn setresuid , +.Fn strlcat , +.Fn strlcpy , +.Fn wait3 , +.Fn wait4 . +.Pp +Since signal-safe functions can encounter system call errors, +.Va errno +should be protected inside the handler with the following pattern: +.Bd -literal -offset indent +void +handler(int sig) +{ + int save_errno = errno; + + ... + errno = save_errno; +} +.Ed +.Pp +On +.Ox , +a few more functions are signal-safe (except when the format string contains +floating-point arguments). +These functions are expected to be unsafe on other systems, +so be very cautious of the portability trap! +.Pp +.Bl -tag -offset indent -compact -width foofoofoofoo +.It Fn dprintf +Safe. +.It Fn vdprintf +Safe. +.It Fn snprintf +Safe. +.It Fn vsnprintf +Safe. +.It Fn syslog_r +Safe if the +.Va syslog_data +struct is initialized as a local variable. +.El +.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 occurs: +.Bl -tag -width Er +.It Bq Er EINVAL +A specified signal +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 sigsuspend 2 , +.Xr setjmp 3 , +.Xr siginterrupt 3 , +.Xr tty 4 +.Sh HISTORY +A +.Fn signal +system call first appeared in +.At v4 . +In +.Bx 4.2 , +it was reimplemented as a wrapper around the former +.Fn sigvec +system call, and for +.Bx 4.3 Reno , +it was rewritten to use +.Xr sigaction 2 +instead. diff --git a/static/openbsd/man3/sigpause.3 b/static/openbsd/man3/sigpause.3 new file mode 100644 index 00000000..7562ec68 --- /dev/null +++ b/static/openbsd/man3/sigpause.3 @@ -0,0 +1,77 @@ +.\" Copyright (c) 1983, 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. +.\" +.\" $OpenBSD: sigpause.3,v 1.15 2022/12/13 06:56:06 jmc Exp $ +.\" +.Dd $Mdocdate: December 13 2022 $ +.Dt SIGPAUSE 3 +.Os +.Sh NAME +.Nm sigpause +.Nd atomically release blocked signals and wait for interrupt +.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 +A +.Fn sigpause +system call first appeared in +.Bx 4.2 . +In +.Bx 4.3 Reno , +it was reimplemented as a wrapper around +.Xr sigsuspend 2 . +The old system call was kept for compatibility until +.Ox 4.9 . diff --git a/static/openbsd/man3/sigsetmask.3 b/static/openbsd/man3/sigsetmask.3 new file mode 100644 index 00000000..c64f2de6 --- /dev/null +++ b/static/openbsd/man3/sigsetmask.3 @@ -0,0 +1,141 @@ +.\" Copyright (c) 1983, 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. +.\" +.\" $OpenBSD: sigsetmask.3,v 1.19 2022/12/13 06:56:06 jmc Exp $ +.\" +.Dd $Mdocdate: December 13 2022 $ +.Dt SIGSETMASK 3 +.Os +.Sh NAME +.Nm sigsetmask +.Nd set current signal mask +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigsetmask "int mask" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr sigprocmask 2 . +.Ef +.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 +.Xr sigmask 3 +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 utilizing +.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 sigaddset 3 , +.Xr sigblock 3 , +.Xr sigvec 3 +.Sh HISTORY +A +.Fn sigsetmask +system call first appeared in +.Bx 4.2 . +In +.Bx 4.3 Reno , +it was reimplemented as a wrapper around +.Xr sigprocmask 2 . +The old system call was kept for compatibility until +.Ox 4.9 . diff --git a/static/openbsd/man3/sigvec.3 b/static/openbsd/man3/sigvec.3 new file mode 100644 index 00000000..b014ed9f --- /dev/null +++ b/static/openbsd/man3/sigvec.3 @@ -0,0 +1,331 @@ +.\" Copyright (c) 1980, 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. +.\" +.\" $OpenBSD: sigvec.3,v 1.37 2022/10/13 21:37:05 jmc Exp $ +.\" +.Dd $Mdocdate: October 13 2022 $ +.Dt SIGVEC 3 +.Os +.Sh NAME +.Nm sigvec +.Nd software signal facilities +.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 . +.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 blocked +or +.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 +All signals have the same +.Em priority . +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. +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_IGN , +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 sigaltstack 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 +.Xr execve 2 +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 +The following is a list of all signals +with names as in the include file +.In signal.h : +.Bl -column "SIGVTALRM" "create core image" "terminal line hangup" +.It Sy "Name" Ta Sy "Default Action" Ta Sy "Description" +.It Dv SIGHUP Ta "terminate process" Ta "terminal line hangup" +.It Dv SIGINT Ta "terminate process" Ta "interrupt program" +.It Dv SIGQUIT Ta "create core image" Ta "quit program" +.It Dv SIGILL Ta "create core image" Ta "illegal instruction" +.It Dv SIGTRAP Ta "create core image" Ta "trace trap" +.It Dv SIGABRT Ta "create core image" Ta "abort(3) call (formerly SIGIOT)" +.It Dv SIGEMT Ta "create core image" Ta "emulate instruction executed" +.It Dv SIGFPE Ta "create core image" Ta "floating-point exception" +.It Dv SIGKILL Ta "terminate process" Ta "kill program (cannot be caught or ignored)" +.It Dv SIGBUS Ta "create core image" Ta "bus error" +.It Dv SIGSEGV Ta "create core image" Ta "segmentation violation" +.It Dv SIGSYS Ta "create core image" Ta "system call given invalid argument" +.It Dv SIGPIPE Ta "terminate process" Ta "write on a pipe with no reader" +.It Dv SIGALRM Ta "terminate process" Ta "real-time timer expired" +.It Dv SIGTERM Ta "terminate process" Ta "software termination signal" +.It Dv SIGURG Ta "discard signal" Ta "urgent condition present on socket" +.It Dv SIGSTOP Ta "stop process" Ta "stop (cannot be caught or ignored)" +.It Dv SIGTSTP Ta "stop process" Ta "stop signal generated from keyboard" +.It Dv SIGCONT Ta "discard signal" Ta "continue after stop" +.It Dv SIGCHLD Ta "discard signal" Ta "child status has changed" +.It Dv SIGTTIN Ta "stop process" Ta "background read attempted from controlling terminal" +.It Dv SIGTTOU Ta "stop process" Ta "background write attempted to controlling terminal" +.It Dv SIGIO Ta "discard signal" Ta "I/O is possible on a descriptor (see" +.Xr fcntl 2 ) +.It Dv SIGXCPU Ta "terminate process" Ta "CPU time limit exceeded (see" +.Xr setrlimit 2 ) +.It Dv SIGXFSZ Ta "terminate process" Ta "file size limit exceeded (see" +.Xr setrlimit 2 ) +.It Dv SIGVTALRM Ta "terminate process" Ta "virtual time alarm (see" +.Xr setitimer 2 ) +.It Dv SIGPROF Ta "terminate process" Ta "profiling timer alarm (see" +.Xr setitimer 2 ) +.It Dv SIGWINCH Ta "discard signal" Ta "window size change" +.It Dv SIGINFO Ta "discard signal" Ta "status request from keyboard" +.It Dv SIGUSR1 Ta "terminate process" Ta "user-defined signal 1" +.It Dv SIGUSR2 Ta "terminate process" Ta "user-defined signal 2" +.El +.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 +For an example of signal handler declarations, see +.Xr sigaction 2 . +.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 sigsuspend 2 , +.Xr setjmp 3 , +.Xr sigaddset 3 , +.Xr sigblock 3 , +.Xr siginterrupt 3 , +.Xr sigpause 3 , +.Xr sigsetmask 3 , +.Xr tty 4 +.Sh HISTORY +A +.Fn sigvec +system call first appeared in +.Bx 4.2 . +It was reimplemented as a wrapper around +.Xr sigaction 2 +in +.Bx 4.3 Reno . +The old system call was kept for compatibility until +.Ox 4.9 . diff --git a/static/openbsd/man3/sigwait.3 b/static/openbsd/man3/sigwait.3 new file mode 100644 index 00000000..17ad5610 --- /dev/null +++ b/static/openbsd/man3/sigwait.3 @@ -0,0 +1,76 @@ +.\" $OpenBSD: sigwait.3,v 1.2 2019/01/13 16:16:43 jca Exp $ +.\" +.\" David Leonard , 1998. Public domain. +.Dd $Mdocdate: January 13 2019 $ +.Dt SIGWAIT 3 +.Os +.Sh NAME +.Nm sigwait +.Nd synchronously accept a signal +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigwait "const sigset_t *set" "int *sig" +.Sh DESCRIPTION +The +.Fn sigwait +function selects a pending signal from +.Fa set , +atomically clears it from the system's set of pending signals, and returns +that signal number in the location referenced by +.Fa sig . +If prior to the call to +.Fn sigwait +there are multiple pending instances of a single signal number, +it is undefined whether upon successful return there are any remaining pending +signals for that signal number. +If no signal in +.Fa set +is pending at the time of the call, +the thread shall be suspended until one or more becomes pending. +The signals defined by +.Fa set +should have been blocked at the time of the call to +.Fn sigwait ; +otherwise the behaviour is undefined. +The effect of +.Fn sigwait +on the signal actions for the signals in +.Fa set +is unspecified. +.Pp +If more than one thread is using +.Fn sigwait +to wait for the same signal, +no more than one of these threads shall return from +.Fn sigwait +with the signal number. +Which thread returns from +.Fn sigwait +if more than a single thread is waiting is unspecified. +.Sh RETURN VALUES +Upon successful completion, +.Fn sigwait +stores the signal number of the received signal at the location referenced by +.Fa sig +and returns zero. +.Sh ERRORS +On error, +.Fn sigwait +returns one of these error values: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa set +argument contains an invalid or unsupported signal number. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigsuspend 2 , +.Xr pause 3 , +.Xr pthread_sigmask 3 +.Sh STANDARDS +.Fn sigwait +conforms to +.St -p1003.1-96 . diff --git a/static/openbsd/man3/sin.3 b/static/openbsd/man3/sin.3 new file mode 100644 index 00000000..0fc7c494 --- /dev/null +++ b/static/openbsd/man3/sin.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: sin.3,v 1.18 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt SIN 3 +.Os +.Sh NAME +.Nm sin , +.Nm sinf , +.Nm sinl +.Nd sine functions +.Sh SYNOPSIS +.Lb libm +.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). +The +.Fn sinf +function is a single precision version of +.Fn sin . +The +.Fn sinl +function is an extended precision version of +.Fn sin . +A large magnitude argument may yield a result with little or no +significance. +.Sh RETURN VALUES +The +.Fn sin , +.Fn sinf +and +.Fn sinl +functions return 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 sinh 3 , +.Xr tan 3 , +.Xr tanh 3 +.Sh STANDARDS +The +.Fn sin +function conforms to +.St -ansiC . +.Sh HISTORY +A +.Fn sin +function first appeared in +.At v1 . diff --git a/static/openbsd/man3/sincos.3 b/static/openbsd/man3/sincos.3 new file mode 100644 index 00000000..8cb6afdb --- /dev/null +++ b/static/openbsd/man3/sincos.3 @@ -0,0 +1,79 @@ +.\" $OpenBSD: sincos.3,v 1.3 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 319047 2017-05-28 06:13:38Z mmel $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt SINCOS 3 +.Os +.Sh NAME +.Nm sincos , +.Nm sincosf , +.Nm sincosl +.Nd sine and cosine functions +.Sh SYNOPSIS +.Lb libm +.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 objects pointed to by +.Fa s +and +.Fa c +are assigned the values of sine and cosine, respectively. +.Sh SEE ALSO +.Xr cos 3 , +.Xr sin 3 +.Sh HISTORY +These functions first appeared in +.Ox 6.3 . diff --git a/static/openbsd/man3/sinh.3 b/static/openbsd/man3/sinh.3 new file mode 100644 index 00000000..0b6e48fd --- /dev/null +++ b/static/openbsd/man3/sinh.3 @@ -0,0 +1,93 @@ +.\" $OpenBSD: sinh.3,v 1.16 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.Dd $Mdocdate: June 7 2025 $ +.Dt SINH 3 +.Os +.Sh NAME +.Nm sinh , +.Nm sinhf , +.Nm sinhl +.Nd hyperbolic sine functions +.Sh SYNOPSIS +.Lb libm +.In math.h +.Ft double +.Fn sinh "double x" +.Ft float +.Fn sinhf "float x" +.Ft long double +.Fn sinhl "long double x" +.Sh DESCRIPTION +The +.Fn sinh +function computes the hyperbolic sine of +.Fa x . +The +.Fn sinhf +function is a single precision version of +.Fn sinh . +The +.Fn sinhl +function is an extended precision version of +.Fn sinh . +.Sh RETURN VALUES +The +.Fn sinh , +.Fn sinhf +and +.Fn sinhl +functions return 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 sin 3 , +.Xr tan 3 , +.Xr tanh 3 +.Sh STANDARDS +The +.Fn sinh +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn sinh +function first appeared in +.At v7 . diff --git a/static/openbsd/man3/sio_open.3 b/static/openbsd/man3/sio_open.3 new file mode 100644 index 00000000..83fa55cc --- /dev/null +++ b/static/openbsd/man3/sio_open.3 @@ -0,0 +1,872 @@ +.\" $OpenBSD: sio_open.3,v 1.59 2026/01/22 09:24:26 ratchov Exp $ +.\" +.\" Copyright (c) 2007 Alexandre Ratchov +.\" +.\" 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: January 22 2026 $ +.Dt SIO_OPEN 3 +.Os +.Sh NAME +.Nm sio_open , +.Nm sio_close , +.Nm sio_setpar , +.Nm sio_getpar , +.Nm sio_getcap , +.Nm sio_start , +.Nm sio_stop , +.Nm sio_flush , +.Nm sio_read , +.Nm sio_write , +.Nm sio_onmove , +.Nm sio_onxrun , +.Nm sio_nfds , +.Nm sio_pollfd , +.Nm sio_revents , +.Nm sio_eof , +.Nm sio_setvol , +.Nm sio_onvol , +.Nm sio_initpar , +.Nm SIO_BPS +.Nd sndio interface to audio devices +.Sh SYNOPSIS +.Lb libsndio +.In sndio.h +.Ft struct sio_hdl * +.Fn sio_open "const char *name" "unsigned int mode" "int nbio_flag" +.Ft void +.Fn sio_close "struct sio_hdl *hdl" +.Ft int +.Fn sio_setpar "struct sio_hdl *hdl" "struct sio_par *par" +.Ft int +.Fn sio_getpar "struct sio_hdl *hdl" "struct sio_par *par" +.Ft int +.Fn sio_getcap "struct sio_hdl *hdl" "struct sio_cap *cap" +.Ft int +.Fn sio_start "struct sio_hdl *hdl" +.Ft int +.Fn sio_stop "struct sio_hdl *hdl" +.Ft int +.Fn sio_flush "struct sio_hdl *hdl" +.Ft size_t +.Fn sio_read "struct sio_hdl *hdl" "void *addr" "size_t nbytes" +.Ft size_t +.Fn sio_write "struct sio_hdl *hdl" "const void *addr" "size_t nbytes" +.Ft void +.Fo sio_onmove +.Fa "struct sio_hdl *hdl" +.Fa "void (*cb)(void *arg, int delta)" +.Fa "void *arg" +.Fc +.Ft void +.Fo sio_onxrun +.Fa "struct sio_hdl *hdl" +.Fa "void (*cb)(void *arg)" +.Fa "void *arg" +.Fc +.Ft int +.Fn sio_nfds "struct sio_hdl *hdl" +.Ft int +.Fn sio_pollfd "struct sio_hdl *hdl" "struct pollfd *pfd" "int events" +.Ft int +.Fn sio_revents "struct sio_hdl *hdl" "struct pollfd *pfd" +.Ft int +.Fn sio_eof "struct sio_hdl *hdl" +.Ft int +.Fn sio_setvol "struct sio_hdl *hdl" "unsigned int vol" +.Ft int +.Fo sio_onvol +.Fa "struct sio_hdl *hdl" +.Fa "void (*cb)(void *arg, unsigned int vol)" +.Fa "void *arg" +.Fc +.Ft void +.Fn sio_initpar "struct sio_par *par" +.Ft unsigned int +.Fn SIO_BPS "unsigned int bits" +.Sh DESCRIPTION +The +.Nm sndio +library allows user processes to access +.Xr audio 4 +hardware and the +.Xr sndiod 8 +audio server in a uniform way. +.Ss Opening and closing an audio device +First the application must call the +.Fn sio_open +function to obtain a handle to the device; +later it will be passed as the +.Fa hdl +argument of most other functions. +The +.Fa name +parameter gives the device string discussed in +.Xr sndio 7 . +In most cases it should be set to +.Dv SIO_DEVANY +to allow the user to select it using the +.Ev AUDIODEVICE +environment variable. +.Pp +The following values of the +.Fa mode +parameter are supported: +.Bl -tag -width "SIO_PLAY | SIO_REC" +.It Dv SIO_PLAY +Play-only mode: data written will be played by the device. +.It Dv SIO_REC +Record-only mode: samples are recorded by the device and must be read. +.It Dv SIO_PLAY | SIO_REC +The device plays and records synchronously; this means that +the n-th recorded sample was physically sampled exactly when +the n-th played sample was actually played. +.El +.Pp +If the +.Fa nbio_flag +argument is true (i.e. non-zero), then the +.Fn sio_read +and +.Fn sio_write +functions (see below) will be non-blocking. +.Pp +The +.Fn sio_close +function stops the device as if +.Fn sio_stop +is called and frees the handle. +Thus, no samples submitted with +.Fn sio_write +are discarded. +.Ss Negotiating audio parameters +Audio samples are interleaved. +A frame consists of one sample for each channel. +For example, a 16-bit stereo encoding has two samples per frame +and, two bytes per sample (thus 4 bytes per frame). +.Pp +The set of parameters of the device that can be controlled +is given by the following structure: +.Bd -literal +struct sio_par { + unsigned int bits; /* bits per sample */ + unsigned int bps; /* bytes per sample */ + unsigned int sig; /* 1 = signed, 0 = unsigned int */ + unsigned int le; /* 1 = LE, 0 = BE byte order */ + unsigned int msb; /* 1 = MSB, 0 = LSB aligned */ + unsigned int rchan; /* number channels for recording */ + unsigned int pchan; /* number channels for playback */ + unsigned int rate; /* frames per second */ + unsigned int appbufsz; /* minimum buffer size without xruns */ + unsigned int bufsz; /* end-to-end buffer size (read-only) */ + unsigned int round; /* optimal buffer size divisor */ +#define SIO_IGNORE 0 /* pause during xrun */ +#define SIO_SYNC 1 /* resync after xrun */ +#define SIO_ERROR 2 /* terminate on xrun */ + unsigned int xrun; /* what to do on overrun/underrun */ +}; +.Ed +.Pp +The parameters are as follows: +.Bl -tag -width "appbufsz" +.It Fa bits +Number of bits per sample: must be between 1 and 32. +.It Fa bps +Bytes per samples; if specified, it must be large enough to hold all bits. +By default it's set to the smallest power of two large enough to hold +.Fa bits . +.It Fa sig +If set (i.e. non-zero) then the samples are signed, else unsigned. +.It Fa le +If set, then the byte order is little endian, else big endian; +it's meaningful only if +.Fa bps No > 1 . +.It Fa msb +If set, then the +.Fa bits +are aligned in the packet to the most significant bit +(i.e. lower bits are padded), +else to the least significant bit +(i.e. higher bits are padded); +it's meaningful only if +.Fa bits No < Fa bps No * 8 . +.It Fa rchan +The number of recorded channels; meaningful only if +.Dv SIO_REC +mode was selected. +.It Fa pchan +The number of played channels; meaningful only if +.Dv SIO_PLAY +mode was selected. +.It Fa rate +The sampling frequency in Hz. +.It Fa appbufsz +Size of the buffer in frames the application must maintain non-empty +(on the play end) or non-full (on the record end) by calling +.Fn sio_write +or +.Fn sio_read +fast enough to avoid overrun or underrun conditions. +The audio subsystem may use additional buffering, thus this +parameter cannot be used for latency calculations. +.It Fa bufsz +The maximum number of frames that may be buffered. +This parameter takes into account any buffers, and +can be used for latency calculations. +It is read-only. +.It Fa round +Optimal number of frames that the application buffers +should be a multiple of, to get best performance. +Applications can use this parameter to round their block size. +.It Fa xrun +The action when the client doesn't accept +recorded data or doesn't provide data to play fast enough; +it can be set to one of the +.Dv SIO_IGNORE , +.Dv SIO_SYNC , +or +.Dv SIO_ERROR +constants. +.El +.Pp +The following approach is recommended to negotiate device parameters: +.Bl -bullet +.It +Initialize a +.Vt sio_par +structure using +.Fn sio_initpar +and fill it with +the desired parameters. +Then call +.Fn sio_setpar +to request the device to use them. +Parameters left unset in the +.Vt sio_par +structure will be set to device-specific defaults. +.It +Call +.Fn sio_getpar +to retrieve the actual parameters of the device +and check that they are usable. +If they are not, then fail or set up a conversion layer. +Sometimes the rate set can be slightly different to what was requested. +A difference of about 0.5% is not audible and should be ignored. +.El +.Pp +Parameters cannot be changed after +.Fn sio_start +has been called, +.Fn sio_stop +or +.Fn sio_flush +must be called before parameters can be changed. +.Pp +If the device is exposed by the +.Xr sndiod 8 +server, which is the default configuration, +a transparent emulation layer will +automatically be set up, and in this case any combination of +rate, encoding and numbers of channels is supported. +.Pp +To ease filling the +.Vt sio_par +structure, the +following macros can be used: +.Bl -tag -width "SIO_BPS(bits)" +.It Fn SIO_BPS bits +Return the smallest value for +.Fa bps +that is a power of two and that is large enough to +hold +.Fa bits . +.It Dv SIO_LE_NATIVE +Can be used to set the +.Fa le +parameter when native byte order is required. +It is 1 if the native byte order is little endian or 0 otherwise. +.El +.Ss Getting device capabilities +There's no way to get an exhaustive list of all parameter +combinations the device supports. +Applications that need to have a set of working +parameter combinations in advance can use the +.Fn sio_getcap +function. +However, for most new applications it's generally +not recommended to use +.Fn sio_getcap . +Instead, follow the recommendations for negotiating +device parameters (see above). +.Pp +The +.Vt sio_cap +structure contains the list of parameter configurations. +Each configuration contains multiple parameter sets. +The application must examine all configurations, and +choose its parameter set from +.Em one +of the configurations. +Parameters of different configurations +.Em are not +usable together. +.Bd -literal +struct sio_cap { + struct sio_enc { /* allowed encodings */ + unsigned int bits; + unsigned int bps; + unsigned int sig; + unsigned int le; + unsigned int msb; + } enc[SIO_NENC]; + unsigned int rchan[SIO_NCHAN]; /* allowed rchans */ + unsigned int pchan[SIO_NCHAN]; /* allowed pchans */ + unsigned int rate[SIO_NRATE]; /* allowed rates */ + unsigned int nconf; /* num. of confs[] */ + struct sio_conf { + unsigned int enc; /* bitmask of enc[] indexes */ + unsigned int rchan; /* bitmask of rchan[] indexes */ + unsigned int pchan; /* bitmask of pchan[] indexes */ + unsigned int rate; /* bitmask of rate[] indexes */ + } confs[SIO_NCONF]; +}; +.Ed +.Pp +The parameters are as follows: +.Bl -tag -width "rchan[SIO_NCHAN]" +.It Fa enc Ns Bq Dv SIO_NENC +Array of supported encodings. +The tuple of +.Fa bits , +.Fa bps , +.Fa sig , +.Fa le , +and +.Fa msb +parameters are usable in the corresponding parameters +of the +.Vt sio_par +structure. +.It Fa rchan Ns Bq Dv SIO_NCHAN +Array of supported channel numbers for recording usable +in the +.Vt sio_par +structure. +.It Fa pchan Ns Bq Dv SIO_NCHAN +Array of supported channel numbers for playback usable +in the +.Vt sio_par +structure. +.It Fa rate Ns Bq Dv SIO_NRATE +Array of supported sample rates usable +in the +.Vt sio_par +structure. +.It Fa nconf +Number of different configurations available, i.e. number +of filled elements of the +.Fa confs Ns Bq +array. +.It Fa confs Ns Bq Dv SIO_NCONF +Array of available configurations. +Each configuration contains bitmasks indicating which +elements of the above parameter arrays are valid for the +given configuration. +For instance, if the second bit of +.Fa rate +is set, in the +.Vt sio_conf +structure, then the second element of the +.Fa rate Ns Bq Dv SIO_NRATE +array of the +.Vt sio_cap +structure is valid for this configuration. +As such, when reading the array elements in the +.Vt sio_cap +structure, the corresponding +.Vt sio_conf +bitmasks should always be used. +.El +.Ss Starting and stopping the device +The +.Fn sio_start +function prepares the device to start. +Once the play buffer is full, i.e.\& +.Fa sio_par.bufsz +samples are queued with +.Fn sio_write , +playback starts automatically. +If record-only mode is selected, then +.Fn sio_start +starts recording immediately. +In full-duplex mode, playback and recording will start +synchronously as soon as the play buffer is full. +.Pp +The +.Fn sio_stop +function puts the audio subsystem +in the same state as before +.Fn sio_start +was called. +It stops recording, drains the play buffer and then stops playback. +If samples to play are queued but playback hasn't started yet +then playback is forced immediately; playback will actually stop +once the buffer is drained. +In no case are samples in the play buffer discarded. +.Pp +The +.Fn sio_flush +function stops playback and recording immediately, +possibly discarding play buffer contents, and puts the audio subsystem +in the same state as before +.Fn sio_start +was called. +.Ss Playing and recording +When record mode is selected, the +.Fn sio_read +function must be called to retrieve recorded data; it must be called +often enough to ensure that internal buffers will not overrun. +It will store at most +.Fa nbytes +bytes at the +.Fa addr +location and return the number of bytes stored. +Unless the +.Fa nbio_flag +flag is set, it will block until data becomes available and +will return zero only on error. +.Pp +Similarly, when play mode is selected, the +.Fn sio_write +function must be called to provide data to play. +Unless the +.Fa nbio_flag +is set, +.Fn sio_write +will block until the requested amount of data is written. +.Ss Non-blocking mode operation +If the +.Fa nbio_flag +is set on +.Fn sio_open , +then the +.Fn sio_read +and +.Fn sio_write +functions will never block; if no data is available, they will +return zero immediately. +.Pp +The +.Xr poll 2 +system call can be used to check if data can be +read from or written to the device. +The +.Fn sio_pollfd +function fills the array +.Fa pfd +of +.Vt pollfd +structures, used by +.Xr poll 2 , +with +.Fa events ; +the latter is a bit-mask of +.Dv POLLIN +and +.Dv POLLOUT +constants; refer to +.Xr poll 2 +for more details. +The +.Fn sio_revents +function returns the bit-mask set by +.Xr poll 2 +in the +.Fa pfd +array of +.Vt pollfd +structures. +If +.Dv POLLIN +is set, recorded samples are available in the device buffer +and can be read with +.Fn sio_read . +If +.Dv POLLOUT +is set, space is available in the device buffer and new samples +to play can be submitted with +.Fn sio_write . +.Dv POLLHUP +may be set if an error occurs, even if +it is not selected with +.Fn sio_pollfd . +.Pp +The size of the +.Fa pfd +array, which the caller must pre-allocate, is provided by the +.Fn sio_nfds +function. +.Ss Synchronizing non-audio events to the audio stream in real-time +In order to perform actions at precise positions of the audio stream, +such as displaying video in sync with the audio stream, +the application must be notified in real-time of the exact +position in the stream the hardware is processing. +.Pp +The +.Fn sio_onmove +function can be used to register the +.Fn cb +callback function called at regular time intervals. +The +.Fa delta +argument contains the number of frames the hardware played and/or recorded +since the last call of +.Fn cb . +It is called by +.Fn sio_read , +.Fn sio_write , +and +.Fn sio_revents . +When the first sample is played and/or recorded, right after the device starts, +the callback is invoked with a zero +.Fa delta +argument. +The value of the +.Fa arg +pointer is passed to the callback and can contain anything. +.Pp +If desired, the application can maintain the current position by +starting from zero (when +.Fn sio_start +is called) and adding to the current position +.Fa delta +every time +.Fn cb +is called. +.Ss Measuring the latency and buffers usage +The playback latency is the delay it will take for the +frame just written to become audible, expressed in number of frames. +The exact playback +latency can be obtained by subtracting the current position +from the number of frames written. +Once playback is actually started (first sample audible), +the latency will never exceed the +.Fa bufsz +parameter (see the sections above). +There's a phase during which +.Fn sio_write +only queues data; +once there's enough data, actual playback starts. +During this phase talking about latency is meaningless. +.Pp +In any cases, at most +.Fa bufsz +frames are buffered. +This value takes into account all buffers. +The number of frames stored is equal to the number of frames +written minus the current position. +.Pp +The recording latency is obtained similarly, by subtracting +the number of frames read from the current position. +.Pp +Note that +.Fn sio_write +might block even if there is buffer space left; +using the buffer usage to guess if +.Fn sio_write +would block is false and leads to unreliable programs \(en consider using +.Xr poll 2 +for this. +.Ss Handling buffer overruns and underruns +When the application cannot accept recorded data fast enough, +the record buffer (of size +.Fa appbufsz ) +might overrun; in this case recorded data is lost. +Similarly if the application cannot provide data to play +fast enough, the play buffer underruns and silence is played +instead. +.Pp +The +.Fn sio_onxrun +function can be used to register the +.Fn cb +callback function called at buffer underrun or overrun. +It is called by +.Fn sio_read , +.Fn sio_write , +and +.Fn sio_revents . +The value of the +.Fa arg +pointer is passed to the callback and can contain anything. +.Pp +Depending on the +.Fa xrun +parameter of the +.Vt sio_par +structure, the audio subsystem will behave as follows: +.Bl -tag -width "SIO_IGNORE" +.It Dv SIO_IGNORE +The device pauses during overruns and underruns, +thus the current position (obtained through +.Fn sio_onmove ) +stops being incremented. +Once the overrun and/or underrun condition is gone, the device resumes; +play and record are always kept in sync. +With this mode, the application cannot notice +underruns and/or overruns and shouldn't care about them. +.Pp +This mode is the default. +It's suitable for applications, +like audio players and telephony, where time +is not important and overruns or underruns are not short. +.It Dv SIO_SYNC +If the play buffer underruns, then silence is played, +but in order to reach the right position in time, +the same amount of written samples will be +discarded once the application is unblocked. +Similarly, if the record buffer overruns, then +samples are discarded, but the same amount of silence will be +returned later. +The current position (obtained through +.Fn sio_onmove ) +is still incremented. +When the play buffer underruns the play latency might become negative; +when the record buffer overruns, the record latency might become +larger than +.Fa bufsz . +.Pp +This mode is suitable for applications, like music production, +where time is important and where underruns or overruns are +short and rare. +.It Dv SIO_ERROR +With this mode, on the first play buffer underrun or +record buffer overrun, playback and/or recording is terminated and +no other function than +.Fn sio_close +will succeed. +.Pp +This mode is mostly useful for testing. +.El +.Ss Controlling the volume +The +.Fn sio_setvol +function can be used to set playback attenuation. +The +.Fa vol +parameter takes a value between 0 (maximum attenuation) +and +.Dv SIO_MAXVOL +(no attenuation). +It specifies the weight the audio subsystem will +give to this stream. +It is not meant to control hardware parameters like +speaker gain; the +.Xr mixerctl 8 +interface should be used for that purpose instead. +.Pp +An application can use the +.Fn sio_onvol +function to register a callback function that +will be called each time the volume is changed, +including when +.Fn sio_setvol +is used. +The callback is always invoked when +.Fn sio_onvol +is called in order to provide the initial volume. +An application can safely assume that once +.Fn sio_onvol +has returned a non-zero value, +the callback has been invoked and thus +the current volume is available. +If there's no volume setting available, +.Fn sio_onvol +returns 0 and the callback is never invoked and calls to +.Fn sio_setvol +are ignored. +.Pp +The +.Fn sio_onvol +function can be called with a +.Dv NULL +argument to check whether a volume knob is available. +.Ss Error handling +Errors related to the audio subsystem +(like hardware errors, dropped connections) and +programming errors (e.g. call to +.Fn sio_read +on a play-only stream) are considered fatal. +Once an error occurs, all functions taking a +.Fa sio_hdl +argument, except +.Fn sio_close +and +.Fn sio_eof , +stop working (i.e. always return 0). +The +.Fn sio_eof +function can be used at any stage. +.Ss Use with Xr pledge 2 +If the +.Nm sndio +library is used in combination with +.Xr pledge 2 , +then the +.Fn sio_open +function needs the +.Cm stdio , +.Cm rpath , +.Cm wpath , +.Cm cpath , +.Cm inet , +.Cm unix , +.Cm dns , +and +.Cm audio +.Xr pledge 2 +promises. +.Bl -bullet +.It +.Cm rpath , +.Cm wpath , +and +.Cm cpath +are needed to read, write or create the authentication cookie +.Pa ~/.sndio/cookie . +.It +.Cm rpath , +.Cm wpath , +and +.Cm audio +are needed when the device is a local raw device. +.It +.Cm unix +is needed when the device is a local +.Xr sndiod 8 +sub-device. +.It +.Cm inet +and +.Cm dns +are needed when the device is a remote +.Xr sndiod 8 +sub-device. +.El +.Pp +Once no further calls to +.Fn sio_open +will be made, all these +.Xr pledge 2 +promises may be dropped, except for the +.Cm audio +promise. +.Sh RETURN VALUES +The +.Fn sio_open +function returns the newly created handle on success or +.Dv NULL +on failure. +.Pp +The +.Fn sio_setpar , +.Fn sio_getpar , +.Fn sio_getcap , +.Fn sio_start , +.Fn sio_stop , +.Fn sio_flush , +and +.Fn sio_setvol +functions return 1 on success and 0 on failure. +.Pp +The +.Fn sio_pollfd +function returns the number of +.Vt pollfd +structures filled. +The +.Fn sio_nfds +function returns the number of +.Vt pollfd +structures the caller must preallocate in order to be sure +that +.Fn sio_pollfd +will never overrun. +.Pp +The +.Fn sio_read +and +.Fn sio_write +functions return the number of bytes transferred. +.Pp +The +.Fn sio_eof +function returns 0 if there's no pending error, and a non-zero +value if there's an error. +.Sh ENVIRONMENT +.Bl -tag -width "SNDIO_DEBUGXXX" -compact +.It Ev AUDIODEVICE +Device to use if +.Fn sio_open +is called with +.Dv SIO_DEVANY +as the +.Fa name +argument. +.It Ev SNDIO_DEBUG +The debug level: +may be a value between 0 and 2. +.El +.Sh SEE ALSO +.Xr pledge 2 , +.Xr mio_open 3 , +.Xr sioctl_open 3 , +.Xr audio 4 , +.Xr sndio 7 , +.Xr sndiod 8 , +.Xr audio 9 +.Sh HISTORY +These functions first appeared in +.Ox 4.5 . +.Sh AUTHORS +.An Alexandre Ratchov Aq Mt ratchov@openbsd.org +.Sh BUGS +The +.Xr audio 4 +driver doesn't drain playback buffers, thus if sndio +is used to directly access an +.Xr audio 4 +device, +the +.Fn sio_stop +function will stop playback immediately. +.Pp +If the application doesn't consume recorded data fast enough then +.Dq "control messages" +from the +.Xr sndiod 8 +server are delayed and consequently +.Fn sio_onmove +callback or volume changes may be delayed. +.Pp +The +.Fn sio_open , +.Fn sio_setpar , +.Fn sio_getpar , +.Fn sio_getcap , +.Fn sio_start , +.Fn sio_stop , +and +.Fn sio_flush +functions may block for a very short period of time, thus they should +be avoided in code sections where blocking is not desirable. diff --git a/static/openbsd/man3/sioctl_open.3 b/static/openbsd/man3/sioctl_open.3 new file mode 100644 index 00000000..2c0e65b9 --- /dev/null +++ b/static/openbsd/man3/sioctl_open.3 @@ -0,0 +1,324 @@ +.\" $OpenBSD: sioctl_open.3,v 1.15 2025/06/07 09:51:54 schwarze Exp $ +.\" +.\" Copyright (c) 2011-2020 Alexandre Ratchov +.\" +.\" 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: June 7 2025 $ +.Dt SIOCTL_OPEN 3 +.Os +.Sh NAME +.Nm sioctl_open , +.Nm sioctl_close , +.Nm sioctl_ondesc , +.Nm sioctl_onval , +.Nm sioctl_setval , +.Nm sioctl_nfds , +.Nm sioctl_pollfd , +.Nm sioctl_revents , +.Nm sioctl_eof +.Nd interface to audio parameters +.Sh SYNOPSIS +.Lb libsndio +.Fd #include +.Ft struct sioctl_hdl * +.Fo sioctl_open +.Fa "const char *name" +.Fa "unsigned int mode" +.Fa "int nbio_flag" +.Fc +.Ft void +.Fo sioctl_close +.Fa "struct sioctl_hdl *hdl" +.Fc +.Ft int +.Fo sioctl_ondesc +.Fa "struct sioctl_hdl *hdl" +.Fa "void (*cb)(void *arg, struct sioctl_desc *desc, int val)" +.Fa "void *arg" +.Fc +.Ft int +.Fo sioctl_onval +.Fa "struct sioctl_hdl *hdl" +.Fa "void (*cb)(void *arg, unsigned int addr, unsigned int val)" +.Fa "void *arg" +.Fc +.Ft int +.Fo sioctl_setval +.Fa "struct sioctl_hdl *hdl" +.Fa "unsigned int addr" +.Fa "unsigned int val" +.Fc +.Ft int +.Fo sioctl_nfds +.Fa "struct sioctl_hdl *hdl" +.Fc +.Ft int +.Fo sioctl_pollfd +.Fa "struct sioctl_hdl *hdl" +.Fa "struct pollfd *pfd" +.Fa "int events" +.Fc +.Ft int +.Fo sioctl_revents +.Fa "struct sioctl_hdl *hdl" +.Fa "struct pollfd *pfd" +.Fc +.Ft int +.Fo sioctl_eof +.Fa "struct sioctl_hdl *hdl" +.Fc +.Sh DESCRIPTION +Audio devices may expose a number of controls, like the playback volume control. +Each control has an integer +.Em address +and an integer +.Em value . +Some values are boolean and can only be switched to either 0 (off) or 1 (on). +Any control may be changed by submitting +a new value to its address. +When values change, asynchronous notifications are sent. +.Pp +Control descriptions are available, allowing them to be grouped and +represented in a human readable form. +.Ss Opening and closing the control device +First the application must call the +.Fn sioctl_open +function to obtain a handle +that will be passed as the +.Fa hdl +argument to other functions. +.Pp +The +.Fa name +parameter gives the device string discussed in +.Xr sndio 7 . +In most cases it should be set to SIO_DEVANY to allow +the user to select it using the +.Ev AUDIODEVICE +environment variable. +The +.Fa mode +parameter is a bitmap of the +.Dv SIOCTL_READ +and +.Dv SIOCTL_WRITE +constants indicating whether control values can be read and +modified respectively. +.Pp +If the +.Fa nbio_flag +argument is 1, then the +.Fn sioctl_setval +function (see below) may fail instead of blocking and +the +.Fn sioctl_ondesc +function doesn't block. +.Pp +The +.Fn sioctl_close +function closes the control device and frees any allocated resources +associated with the handle. +.Ss Control descriptions +The +.Fn sioctl_ondesc +function can be used to obtain the description of all available controls +and their initial values. +It registers a callback function that is immediately invoked for all +controls. +It is called once with a +.Dv NULL +argument to indicate that the full +description was sent and that the caller has a consistent +representation of the control set. +.Pp +Then, whenever a control description changes, the callback is +invoked with the updated information followed by a call with a +.Dv NULL +argument. +.Pp +Controls are described by the +.Vt sioctl_desc +structure as follows: +.Bd -literal +struct sioctl_node { + char name[SIOCTL_NAMEMAX]; /* ex. "spkr" */ + int unit; /* optional number or -1 */ +}; + +struct sioctl_desc { + unsigned int addr; /* control address */ +#define SIOCTL_NONE 0 /* deleted */ +#define SIOCTL_NUM 2 /* integer in the maxval range */ +#define SIOCTL_SW 3 /* on/off switch (1 or 0) */ +#define SIOCTL_VEC 4 /* number, element of vector */ +#define SIOCTL_LIST 5 /* switch, element of a list */ +#define SIOCTL_SEL 6 /* element of a selector */ + unsigned int type; /* one of above */ + char func[SIOCTL_NAMEMAX]; /* function name, ex. "level" */ + char group[SIOCTL_NAMEMAX]; /* group this control belongs to */ + struct sioctl_node node0; /* affected node */ + struct sioctl_node node1; /* dito for SIOCTL_{VEC,LIST,SEL} */ + unsigned int maxval; /* max value */ + char display[SIOCTL_DISPLAYMAX]; /* free-format hint */ +}; +.Ed +.Pp +The +.Fa addr +attribute is the control address, usable with +.Fn sioctl_setval +to set its value. +.Pp +The +.Fa type +attribute indicates what the structure describes. +Possible types are: +.Bl -tag -width "SIOCTL_LIST" +.It Dv SIOCTL_NONE +A previously valid control was deleted. +.It Dv SIOCTL_NUM +An integer control in the range from 0 to +.Fa maxval , +inclusive. +For instance the volume of the speaker. +.It Dv SIOCTL_SW +A boolean control. +For instance the switch to mute the speaker. +.It Dv SIOCTL_VEC +Element of an array of integer controls. +For instance the knob to control the amount of signal flowing +from the line input to the speaker. +.It Dv SIOCTL_LIST +An element of an array of boolean switches. +For instance the line-in position of the +speaker source selector. +.It Dv SIOCTL_SEL +Same as +.Dv SIOCTL_LIST +but exactly one element is selected at a time. +.El +.Pp +The +.Fa func +attribute is the name of the parameter being controlled. +There may be no parameters of different types with the same name. +.Pp +The +.Fa node0 +and +.Fa node1 +attributes indicate the names of the controlled nodes, typically +channels of audio streams. +.Fa node1 +is meaningful for +.Dv SIOCTL_VEC , +.Dv SIOCTL_LIST , +and +.Dv SIOCTL_SEL +only. +.Pp +Names in the +.Fa node0 +and +.Fa node1 +attributes and +.Fa func +are strings usable as unique identifiers within the given +.Fa group . +.Pp +The +.Fa maxval +attribute indicates the maximum value of this control. +For boolean control types it is set to 1. +.Pp +The +.Fa display +attribute contains an optional free-format string providing additional +hints about the control, like the hardware model, or the units. +.Ss Changing and reading control values +Controls are changed with the +.Fn sioctl_setval +function, by giving the index of the control and the new value. +The +.Fn sioctl_onval +function can be used to register a callback which will be invoked whenever +a control changes. +Integer values are in the range from 0 to +.Fa maxval . +.Ss Interface to poll(2) +The +.Fn sioctl_pollfd +function fills the array +.Fa pfd +of +.Vt pollfd +structures, used by +.Xr poll 2 , +with +.Fa events ; +the latter is a bit-mask of +.Dv POLLIN +and +.Dv POLLOUT +constants. +.Fn sioctl_pollfd +returns the number of +.Vt pollfd +structures filled. +The +.Fn sioctl_revents +function returns the bit-mask set by +.Xr poll 2 +in the +.Fa pfd +array of +.Vt pollfd +structures. +If +.Dv POLLOUT +is set, +.Fn sioctl_setval +can be called without blocking. +.Dv POLLHUP +may be set if an error occurs, even if it is not selected with +.Fn sioctl_pollfd . +.Dv POLLIN +is not used yet. +.Pp +The +.Fn sioctl_nfds +function returns the number of +.Vt pollfd +structures the caller must preallocate in order to be sure +that +.Fn sioctl_pollfd +will never overrun. +.Sh ENVIRONMENT +.Bl -tag -width AUDIODEVICE +.It Ev AUDIODEVICE +The default +.Xr sndio 7 +device used by +.Fn sioctl_open . +.El +.Sh SEE ALSO +.Xr sndioctl 1 , +.Xr poll 2 , +.Xr sio_open 3 , +.Xr sndio 7 +.Sh HISTORY +These functions first appeared in +.Ox 6.7 . +.Sh AUTHORS +.An Alexandre Ratchov Aq Mt ratchov@openbsd.org diff --git a/static/openbsd/man3/skey.3 b/static/openbsd/man3/skey.3 new file mode 100644 index 00000000..94f91972 --- /dev/null +++ b/static/openbsd/man3/skey.3 @@ -0,0 +1,387 @@ +.\" $OpenBSD: skey.3,v 1.17 2025/06/06 21:34:12 schwarze Exp $ +.\" +.\" Copyright (c) 2001 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. +.\" +.Dd $Mdocdate: June 6 2025 $ +.Dt SKEYLOOKUP 3 +.Os +.Sh NAME +.Nm atob8 , +.Nm backspace , +.Nm btoa8 , +.Nm btoe , +.Nm etob , +.Nm f , +.Nm htoi , +.Nm keycrunch , +.Nm put8 , +.Nm readpass , +.Nm readskey , +.Nm rip , +.Nm sevenbit , +.Nm skey_authenticate , +.Nm skey_get_algorithm , +.Nm skey_haskey , +.Nm skey_keyinfo , +.Nm skey_passcheck , +.Nm skey_set_algorithm , +.Nm skey_unlock , +.Nm skeychallenge , +.Nm skeychallenge2 , +.Nm skeygetnext , +.Nm skeylookup , +.Nm skeyverify , +.Nm skipspace +.Nd S/Key library functions +.Sh SYNOPSIS +.Lb libskey +.In skey.h +.Ft int +.Fn atob8 "char *out" "char *in" +.Ft void +.Fn backspace "char *buf" +.Ft int +.Fn btoa8 "char *out" "char *in" +.Ft char * +.Fn btoe "char *engout" "char *c" +.Ft int +.Fn etob "char *out" "char *e" +.Ft void +.Fn f "char *x" +.Ft int +.Fn htoi "int h" +.Ft int +.Fn keycrunch "char *result" "char *seed" "char *passwd" +.Ft char * +.Fn put8 "char *out" "char *s" +.Ft char * +.Fn readpass "char *buf" "int n" +.Ft char * +.Fn readskey "char *buf" "int n" +.Ft void +.Fn rip "char *buf" +.Ft void +.Fn sevenbit "char *s" +.Ft int +.Fn skey_authenticate "char *user" +.Ft const char * +.Fn skey_get_algorithm "void" +.Ft int +.Fn skey_haskey "char *user" +.Ft char * +.Fn skey_keyinfo "char *user" +.Ft int +.Fn skey_passcheck "char *user" "char *passwd" +.Ft char * +.Fn skey_set_algorithm "char *new" +.Ft int +.Fn skey_unlock "struct skey *rec" +.Ft int +.Fn skeychallenge "struct skey *rec" "char *user" "char *buf" +.Ft int +.Fn skeychallenge2 "int fd" "struct skey *rec" "char *user" "char *buf" +.Ft int +.Fn skeygetnext "struct skey *rec" +.Ft int +.Fn skeylookup "struct skey *rec" "char *user" +.Ft int +.Fn skeyverify "struct skey *rec" "char *response" +.Ft char * +.Fn skipspace "char *" +.Sh DESCRIPTION +These functions implement the S/Key one time password authentication +mechanism. +.Pp +The +.Fn atob8 +function converts the 16-byte hex string +.Fa in +to an 8-byte binary array stored in +.Fa out . +The +.Fn atob8 +function returns 0 on success and \-1 if an invalid hex character is encountered. +.Pp +The +.Fn backspace +function removes backspaced over characters from +.Fa buf . +Note that +.Fn backspace +assumes the actual backspace character is 0x8 (^H). +.Pp +The +.Fn btoa8 +function converts the 8-byte binary array +.Fa in +to a 16-byte string of hex digits stored in +.Fa out ; +the caller must supply enough space (17 bytes including the final NUL). +The +.Fn btoa8 +function returns 0 on success and \-1 if an error occurred. +.Pp +The +.Fn btoe +function encodes the 8 bytes in +.Fa c +into a string of 6 English words, stored in +.Fa engout . +The caller must supply enough space (30 bytes including the final NUL) +to store the words. +The +.Fn btoe +function returns +.Fa engout . +.Pp +The +.Fn etob +function converts the 6 English words in +.Fa e +into an 8-byte binary representation. +The +.Fn etob +function returns 1 if the words are all in the database and parity is correct, +0 if a word is not in the database, \-1 if the number of words is incorrect, +or \-2 if there is a parity error. +.Pp +The +.Fn f +function is a one-way hash that overwrites the 8-byte input buffer +.Fa x +with the hashed result. +.Pp +The +.Fn htoi +function converts a single hex digit +.Fa h +to an integer. +The +.Fn htoi +function returns the converted integer on success or \-1 if +.Fa h +not a valid hex digit. +.Pp +The +.Fn keycrunch +function concatenates the +.Fa seed +and +.Fa passwd , +runs them through a hash function and collapses the +.Fa result +to 64 bits. +The +.Fn keycrunch +function returns 0 on success or \-1 if there is a memory allocation failure. +.Pp +The +.Fn put8 +function converts the 8 bytes stored in +.Fa s +into a series of 4 16-bit hex digit stored in +.Fa out . +There must be at least 20 bytes (including the NUL) in the output buffer, +.Fa out . +The +.Fn put8 +function returns +.Fa out . +.Pp +The +.Fn readpass +function reads up to +.Fa n +characters from standard input with echo turned off, converting the +resulting string to 7 bits, storing the result in +.Fa buf . +The +.Fn readpass +function returns +.Fa buf . +.Pp +The +.Fn readskey +function reads up to +.Fa n +characters from standard input with echo turned on, converting the +resulting string to 7 bits, storing the result in +.Fa buf . +The +.Fn readskey +function returns +.Fa buf . +.Pp +The +.Fn rip +function strips trailing linefeeds and carriage returns from +.Fa buf . +.Pp +The +.Fn sevenbit +function strips the high bit from each character in +.Fa s , +converting the characters to seven bit ASCII. +.Pp +The +.Fn skey_authenticate +function presents the +.Fa user +with an S/Key challenge and authenticates the response. +The +.Fn skey_authenticate +function returns 0 if authentication is successful or \-1 if not. +.Pp +The +.Fn skey_get_algorithm +function returns a string corresponding to the hash algorithm for +the current user. +The default algorithm is +.Dq md5 . +.Pp +The +.Fn skey_haskey +function returns 0 if the +.Fa user +exists in the S/Key database, 1 if the user does not exist, or \-1 +if there was an error reading the database. +.Pp +The +.Fn skey_keyinfo +function returns a string containing the current sequence number and seed for +.Fa user . +The returned string points to internal static storage that will be +overwritten by subsequent calls to +.Fn skey_keyinfo . +.Pp +The +.Fn skey_passcheck +function checks a +.Fa user +and +.Fa passwd +pair against the S/Key database. +It returns 0 on successful authentication or \-1 on failure. +.Pp +The +.Fn skey_set_algorithm +function sets the user's hash algorithm based on the string +.Fa new . +The +.Fn skey_set_algorithm +function returns the specified algorithm if it is supported, +or the null pointer if the hash algorithm is not supported. +.Pp +The +.Fn skey_unlock +function unlocks the record in the S/Key database specified by +.Fa rec . +The +.Fn skey_unlock +function returns 0 on success or \-1 on failure. +Either way, the S/Key database is not closed nor is the database +file pointer affected. +.Pp +The +.Fn skeychallenge +function stores the (potentially fake) S/Key challenge for +.Fa user +in +.Fa buf , +which is at least SKEY_MAX_CHALLENGE bytes long. +It also fills in the skey struct +.Fa rec +and locks the user's record in the S/Key database. +The +.Fn skeychallenge +function returns 0 on success or \-1 on failure. +On success the S/Key database remains open and the read/write file +pointer is set to the beginning of the record. +.Pp +The +.Fn skeychallenge2 +function is identical to +.Fn skeychallenge +except that instead of opening the user's entry in the S/Key database, +the open file referenced by +.Ar fd +is used instead. +When +.Ar fd +is \-1, the behavior is equivalent to +.Fn skeychallenge . +.Pp +The +.Fn skeygetnext +function stores the next record in the S/Key database in +.Fa rec +and locks that record in the S/Key database. +The +.Fn skeygetnext +function returns 0 on success, 1 if there are no more entries, +or \-1 if there was an error accessing the S/Key database. +The S/Key database remains open after a call to +.Fn skeygetnext . +If no error was encountered accessing the S/Key database, the read/write +file pointer is set to the beginning of the record or at EOF if +there are no more records. +.br +Because it exposes other users' S/Key records, only the superuser may use +.Fn skeygetnext . +.Pp +The +.Fn skeylookup +function looks up the specified +.Fa user +in the S/Key database then fills in the skey struct +.Fa rec +and locks the user's record in the database. +The +.Fn skeylookup +function returns 0 on success, 1 if +.Fa user +was not found, or \-1 if there was an error accessing the S/Key database. +If no error was encountered accessing the S/Key database, the read/write +file pointer is set to the beginning of the record. +.Pp +The +.Fn skeyverify +function verifies the user's +.Fa response +based on the S/Key record +.Fa rec . +It returns 0 on success (updating the database), 1 on failure, or +\-1 if there was an error accessing the database. +The database is always closed by a call to +.Fn skeyverify . +.Sh SEE ALSO +.Xr skey 1 , +.Xr skeyinit 1 +.Sh STANDARDS +There is no standard API for S/Key. +The de facto standard is the free S/Key distribution released by Bellcore. +.Pp +The following functions are extensions and do not appear in +the original Bellcore S/Key distribution: +.Fn readskey , +.Fn skey_authenticate , +.Fn skey_get_algorithm , +.Fn skey_haskey , +.Fn skey_keyinfo , +.Fn skey_passcheck , +.Fn skey_set_algorithm , +.Fn skey_unlock . +.Pp +S/Key is a Trademark of Bellcore. diff --git a/static/openbsd/man3/sleep.3 b/static/openbsd/man3/sleep.3 new file mode 100644 index 00000000..e51e7b62 --- /dev/null +++ b/static/openbsd/man3/sleep.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: sleep.3,v 1.18 2022/03/31 17:27:15 naddy 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. +.\" +.Dd $Mdocdate: March 31 2022 $ +.Dt SLEEP 3 +.Os +.Sh NAME +.Nm sleep +.Nd suspend execution for an interval of seconds +.Sh SYNOPSIS +.In unistd.h +.Ft unsigned int +.Fn sleep "unsigned int seconds" +.Sh DESCRIPTION +The +.Fn sleep +function suspends execution of the calling thread until at least the +given number of +.Fa seconds +have elapsed or an unmasked signal is delivered to the calling thread. +.Pp +This version of +.Fn sleep +is implemented with +.Xr nanosleep 2 , +so delivery of any unmasked signal will terminate the sleep early, +even if +.Dv SA_RESTART +is set with +.Xr sigaction 2 +for the interrupting signal. +.Sh RETURN VALUES +If +.Fn sleep +sleeps for the full count of +.Fa seconds , +it returns 0. +Otherwise, +.Fn sleep +returns the number of seconds remaining from the original request. +.Sh ERRORS +The +.Fn sleep +function sets +.Va errno +to +.Dv EINTR +if it is interrupted by the delivery of a signal. +.Sh SEE ALSO +.Xr sleep 1 , +.Xr nanosleep 2 , +.Xr sigaction 2 +.Sh STANDARDS +The +.Fn sleep +function conforms to +.St -p1003.1-2008 . +.Pp +Setting +.Va errno +is an extension to that specification. +.Sh HISTORY +A +.Fn sleep +system call first appeared in +.At v2 . +In +.At v7 , +it was removed and replaced by a C library implementation based on +.Xr signal 3 +and +.Xr alarm 3 . +For +.Ox 2.1 , +it was reimplemented as a wrapper around the +.Xr nanosleep 2 +system call. diff --git a/static/openbsd/man3/sockatmark.3 b/static/openbsd/man3/sockatmark.3 new file mode 100644 index 00000000..524536c1 --- /dev/null +++ b/static/openbsd/man3/sockatmark.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2002 William C. Fenner. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (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: r108087 2002-12-19 01:40:28 -0800 +.\" $OpenBSD: sockatmark.3,v 1.2 2019/06/20 14:19:25 deraadt Exp $ +.\" +.Dd $Mdocdate: June 20 2019 $ +.Dt SOCKATMARK 3 +.Os +.Sh NAME +.Nm sockatmark +.Nd determine whether the read pointer is at the out-of-band data mark +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn sockatmark "int s" +.Sh DESCRIPTION +The +.Fn sockatmark +function returns 1 if the read pointer for the socket +.Fa s +is currently at the out-of-band data mark. +Otherwise, it returns 0 if the socket doesn't have an out-of-band +data mark or if there is normal data to be received before the mark. +.Sh RETURN VALUES +Upon successful completion, the +.Fn sockatmark +function returns the value 1 if the read pointer is pointing at +the out-of-band data mark, 0 if it is not. +Otherwise the value \-1 is returned +and the global variable +.Va errno +is set to +indicate the error. +.Sh EXAMPLES +The routine used in the historical remote login process to flush +output on receipt of an interrupt or quit signal is shown below. +It reads the normal data up to the mark (to discard it), +then reads the out-of-band byte. +.Bd -literal -offset indent +#include +\&... +oob() +{ + int mark; + char waste[BUFSIZ]; + + for (;;) { + if ((mark = sockatmark(rem)) == -1) { + perror("sockatmark"); + break; + } + if (mark) + break; + (void) read(rem, waste, sizeof (waste)); + } + if (recv(rem, &mark, 1, MSG_OOB) == -1) { + perror("recv"); + ... + } + ... +} +.Ed +.Sh ERRORS +The +.Fn sockatmark +call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +.Fa s +is not a valid descriptor. +.It Bq Er ENOTTY +.Fa s +is valid but does not refer to a socket. +.El +.Sh SEE ALSO +.Xr recv 2 , +.Xr send 2 +.Sh STANDARDS +The +.Fn sockatmark +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn sockatmark +function was introduced by +.St -p1003.1-2001 +to standardize the historical +.Dv SIOCATMARK +.Xr ioctl 2 . +The +.Fn sockatmark +function appeared in +.Ox 5.7 . +.Pp +The +.Er ENOTTY +error is returned instead of the usual +.Er ENOTSOCK +error to match the historical behavior of +.Dv SIOCATMARK . diff --git a/static/openbsd/man3/sqrt.3 b/static/openbsd/man3/sqrt.3 new file mode 100644 index 00000000..c818c081 --- /dev/null +++ b/static/openbsd/man3/sqrt.3 @@ -0,0 +1,105 @@ +.\" $OpenBSD: sqrt.3,v 1.19 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.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 SYNOPSIS +.Lb libm +.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 +function computes the cube root of +.Fa x . +The +.Fn cbrtf +function is a single precision version of +.Fn cbrt . +The +.Fn cbrtl +function is an extended precision version of +.Fn cbrt . +.Pp +The +.Fn sqrt +function computes +the non-negative square root of +.Fa x . +The +.Fn sqrtf +function is a single precision version of +.Fn sqrt . +The +.Fn sqrtl +function is an extended precision version of +.Fn sqrt . +.Sh RETURN VALUES +If +.Fa x +is negative, +.Fn sqrt "x" , +.Fn sqrtf "x" +and +.Fn sqrtl "x" +set the global variable +.Va errno +to +.Er EDOM . +.Sh HISTORY +A +.Fn sqrt +function first appeared in +.At v2 . +.Pp +The +.Fn cbrt +function appeared in +.Bx 4.3 . diff --git a/static/openbsd/man3/ssl.3 b/static/openbsd/man3/ssl.3 new file mode 100644 index 00000000..314a1b0a --- /dev/null +++ b/static/openbsd/man3/ssl.3 @@ -0,0 +1,353 @@ +.\" $OpenBSD: ssl.3,v 1.26 2024/08/31 10:51:48 tb Exp $ +.\" full merge up to: OpenSSL e330f55d Nov 11 00:51:04 2016 +0100 +.\" selective merge up to: OpenSSL 322755cc Sep 1 08:40:51 2018 +0800 +.\" +.\" This file was written by Ralf S. Engelschall , +.\" Ben Laurie , and Ulf Moeller . +.\" Copyright (c) 1998-2002, 2005, 2013, 2015 The OpenSSL 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. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: August 31 2024 $ +.Dt SSL 3 +.Os +.Sh NAME +.Nm ssl +.Nd OpenSSL TLS library +.Sh DESCRIPTION +The +.Nm ssl +library implements the Transport Layer Security (TLS) protocol, +the successor to the Secure Sockets Layer (SSL) protocol. +.Pp +An +.Vt SSL_CTX +object is created as a framework to establish TLS/SSL enabled connections (see +.Xr SSL_CTX_new 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 +.Vt SSL +object. +After the +.Vt SSL +object has been created using +.Xr SSL_new 3 , +.Xr SSL_set_fd 3 +or +.Xr SSL_set_bio 3 +can be used to associate the network connection with the object. +.Pp +Then the TLS/SSL handshake is performed using +.Xr SSL_accept 3 +or +.Xr SSL_connect 3 +respectively. +.Xr SSL_read 3 +and +.Xr SSL_write 3 +are used to read and write data on the TLS/SSL connection. +.Xr SSL_shutdown 3 +can be used to shut down the TLS/SSL connection. +.Sh DATA STRUCTURES +Currently the +.Nm ssl +library functions deal with the following data structures: +.Bl -tag -width Ds +.It Vt SSL_METHOD No (SSL Method) +That's a dispatch structure describing the internal +.Nm ssl +library methods/functions which implement the various protocol versions. +It's needed to create an +.Vt SSL_CTX . +See +.Xr TLS_method 3 +for constructors. +.It Vt SSL_CIPHER No (SSL Cipher) +This structure holds the algorithm information for a particular cipher which +is a core part of the SSL/TLS protocol. +The available ciphers are configured on an +.Vt SSL_CTX +basis and the actually used ones are then part of the +.Vt SSL_SESSION . +.It Vt SSL_CTX No (SSL Context) +That's the global context structure which is created by a server or client +once per program lifetime and which holds mainly default values for the +.Vt SSL +structures which are later created for the connections. +.It Vt SSL_SESSION No (SSL Session) +This is a structure containing the current TLS/SSL session details for a +connection: +.Vt SSL_CIPHER Ns s , +client and server certificates, keys, etc. +.It Vt SSL No (SSL Connection) +That's the main SSL/TLS structure which is created by a server or client per +established connection. +This actually is the core structure in the SSL API. +At run-time the application usually deals with this structure which has +links to mostly all other structures. +.El +.Sh HEADER FILES +Currently the +.Nm ssl +library provides the following C header files containing the prototypes for the +data structures and functions: +.Bl -tag -width Ds +.It Pa ssl.h +That's the common header file for the SSL/TLS API. +Include it into your program to make the API of the +.Nm ssl +library available. +It internally includes both more private SSL headers and headers from the +.Em crypto +library. +Whenever you need hardcore details on the internals of the SSL API, look inside +this header file. +.It Pa ssl3.h +That's the sub header file dealing with the SSLv3 protocol only. +.Bf Em +Usually you don't have to include it explicitly because it's already included +by +.Pa ssl.h . +.Ef +.It Pa tls1.h +That's the sub header file dealing with the TLSv1 protocol only. +.Bf Em +Usually you don't have to include it explicitly because it's already included +by +.Pa ssl.h . +.Ef +.El +.Sh API FUNCTIONS +.Ss Ciphers +The following pages describe functions acting on +.Vt SSL_CIPHER +objects: +.Xr SSL_get_ciphers 3 , +.Xr SSL_get_current_cipher 3 , +.Xr SSL_CIPHER_get_name 3 +.Ss Protocol contexts +The following pages describe functions acting on +.Vt SSL_CTX +objects. +.Pp +Constructors and destructors: +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_set_ssl_version 3 , +.Xr SSL_CTX_free 3 +.Pp +Certificate configuration: +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_get0_certificate 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_cert_store 3 , +.Xr SSL_CTX_set_cert_verify_callback 3 , +.Xr SSL_CTX_set_client_cert_cb 3 , +.Xr SSL_CTX_set_default_passwd_cb 3 , +.Xr SSL_CTX_set_tlsext_status_cb 3 +.Pp +Session configuration: +.Xr SSL_CTX_add_session 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_sess_number 3 , +.Xr SSL_CTX_sess_set_cache_size 3 , +.Xr SSL_CTX_sess_set_get_cb 3 , +.Xr SSL_CTX_sessions 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_CTX_set_timeout 3 , +.Xr SSL_CTX_set_tlsext_ticket_key_cb 3 +.Pp +Various configuration: +.Xr SSL_CTX_get_ex_new_index 3 , +.Xr SSL_CTX_set_tlsext_servername_callback 3 +.Ss Common configuration of contexts and connections +The functions on the following pages each come in two variants: +one to directly configure a single +.Vt SSL +connection and another to be called on an +.Vt SSL_CTX +object, to set up defaults for all future +.Vt SSL +connections created from that context. +.Pp +Protocol and algorithm configuration: +.Xr SSL_CTX_set_alpn_select_cb 3 , +.Xr SSL_CTX_set_cipher_list 3 , +.Xr SSL_CTX_set_min_proto_version 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_CTX_set_security_level 3 , +.Xr SSL_CTX_set_tlsext_use_srtp 3 , +.Xr SSL_CTX_set_tmp_dh_callback 3 , +.Xr SSL_CTX_set1_groups 3 +.Pp +Certificate configuration: +.Xr SSL_CTX_add1_chain_cert 3 , +.Xr SSL_CTX_get_verify_mode 3 , +.Xr SSL_CTX_set_client_CA_list 3 , +.Xr SSL_CTX_set_max_cert_list 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr SSL_CTX_use_certificate 3 , +.Xr SSL_get_client_CA_list 3 +.Xr SSL_set1_param 3 +.Pp +Session configuration: +.Xr SSL_CTX_set_generate_session_id 3 , +.Xr SSL_CTX_set_session_id_context 3 +.Pp +Various configuration: +.Xr SSL_CTX_ctrl 3 , +.Xr SSL_CTX_set_info_callback 3 , +.Xr SSL_CTX_set_mode 3 , +.Xr SSL_CTX_set_msg_callback 3 , +.Xr SSL_CTX_set_quiet_shutdown 3 , +.Xr SSL_CTX_set_read_ahead 3 , +.Xr SSL_set_max_send_fragment 3 +.Ss Sessions +The following pages describe functions acting on +.Vt SSL_SESSION +objects. +.Pp +Constructors and destructors: +.Xr SSL_SESSION_new 3 , +.Xr SSL_SESSION_free 3 +.Pp +Accessors: +.Xr SSL_SESSION_get_compress_id 3 , +.Xr SSL_SESSION_get_ex_new_index 3 , +.Xr SSL_SESSION_get_id 3 , +.Xr SSL_SESSION_get_protocol_version 3 , +.Xr SSL_SESSION_get_time 3 , +.Xr SSL_SESSION_get0_peer 3 , +.Xr SSL_SESSION_has_ticket 3 , +.Xr SSL_SESSION_set1_id_context 3 +.Pp +Encoding and decoding: +.Xr d2i_SSL_SESSION 3 , +.Xr PEM_read_SSL_SESSION 3 , +.Xr SSL_SESSION_print 3 +.Ss Connections +The following pages describe functions acting on +.Vt SSL +connection objects: +.Pp +Constructors and destructors: +.Xr SSL_new 3 , +.Xr SSL_dup 3 , +.Xr SSL_free 3 , +.Xr BIO_f_ssl 3 +.Pp +To change the configuration: +.Xr SSL_clear 3 , +.Xr SSL_set_SSL_CTX 3 , +.Xr SSL_copy_session_id 3 , +.Xr SSL_set_bio 3 , +.Xr SSL_set_connect_state 3 , +.Xr SSL_set_fd 3 , +.Xr SSL_set_session 3 , +.Xr SSL_set1_host 3 , +.Xr SSL_set_verify_result 3 +.Pp +To inspect the configuration: +.Xr SSL_get_certificate 3 , +.Xr SSL_get_default_timeout 3 , +.Xr SSL_get_ex_new_index 3 , +.Xr SSL_get_fd 3 , +.Xr SSL_get_rbio 3 , +.Xr SSL_get_SSL_CTX 3 +.Pp +To transmit data: +.Xr DTLSv1_listen 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_read 3 , +.Xr SSL_read_early_data 3 , +.Xr SSL_renegotiate 3 , +.Xr SSL_shutdown 3 , +.Xr SSL_write 3 +.Pp +To inspect the state after a connection is established: +.Xr SSL_export_keying_material 3 , +.Xr SSL_get_client_random 3 , +.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 , +.Xr SSL_get_peer_cert_chain 3 , +.Xr SSL_get_peer_certificate 3 , +.Xr SSL_get_server_tmp_key 3 , +.Xr SSL_get_servername 3 , +.Xr SSL_get_session 3 , +.Xr SSL_get_shared_ciphers 3 , +.Xr SSL_get_verify_result 3 , +.Xr SSL_get_version 3 , +.Xr SSL_session_reused 3 +.Pp +To inspect the state during ongoing communication: +.Xr SSL_get_error 3 , +.Xr SSL_get_shutdown 3 , +.Xr SSL_get_state 3 , +.Xr SSL_num_renegotiations 3 , +.Xr SSL_pending 3 , +.Xr SSL_rstate_string 3 , +.Xr SSL_state_string 3 , +.Xr SSL_want 3 +.Ss Utility functions +.Xr SSL_alert_type_string 3 , +.Xr SSL_dup_CA_list 3 , +.Xr SSL_load_client_CA_file 3 +.Ss Obsolete functions +.Xr OPENSSL_init_ssl 3 , +.Xr SSL_COMP_get_compression_methods 3 , +.Xr SSL_CTX_set_tmp_rsa_callback 3 , +.Xr SSL_library_init 3 , +.Xr SSL_set_tmp_ecdh 3 +.Sh SEE ALSO +.Xr openssl 1 , +.Xr crypto 3 , +.Xr tls_init 3 +.Sh HISTORY +The +.Nm +document appeared in OpenSSL 0.9.2. diff --git a/static/openbsd/man3/statvfs.3 b/static/openbsd/man3/statvfs.3 new file mode 100644 index 00000000..733748b8 --- /dev/null +++ b/static/openbsd/man3/statvfs.3 @@ -0,0 +1,148 @@ +.\" $OpenBSD: statvfs.3,v 1.9 2022/02/11 15:11:35 millert Exp $ +.\" $NetBSD: statfs.2,v 1.10 1995/06/29 11:40:48 cgd 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. +.\" +.\" @(#)statfs.2 8.3 (Berkeley) 2/11/94 +.\" +.Dd $Mdocdate: February 11 2022 $ +.Dt STATVFS 3 +.Os +.Sh NAME +.Nm statvfs , +.Nm fstatvfs +.Nd get file system statistics +.Sh SYNOPSIS +.In sys/statvfs.h +.Ft int +.Fn statvfs "const char *path" "struct statvfs *buf" +.Ft int +.Fn fstatvfs "int fd" "struct statvfs *buf" +.Sh DESCRIPTION +.Fn statvfs +returns information about a mounted file system. +.Fa path +is the path name of any file within the mounted file system. +.Fa buf +is a pointer to a +.Nm statvfs +structure defined as follows: +.Bd -literal +struct statvfs { + unsigned long f_bsize; /* file system block size */ + unsigned long f_frsize; /* fundamental file system block size */ + fsblkcnt_t f_blocks; /* number of blocks (unit f_frsize) */ + fsblkcnt_t f_bfree; /* free blocks in file system */ + fsblkcnt_t f_bavail; /* free blocks for non-root */ + fsfilcnt_t f_files; /* total file inodes */ + fsfilcnt_t f_ffree; /* free file inodes */ + fsfilcnt_t f_favail; /* free file inodes for non-root */ + unsigned long f_fsid; /* file system id */ + unsigned long f_flag; /* bit mask of f_flag values */ + unsigned long f_namemax; /* maximum filename length */ +}; + +#define ST_RDONLY 0x0001UL /* read-only filesystem */ +#define ST_NOSUID 0x0002UL /* nosuid flag set */ +.Ed +.Pp +The fields of type +.Vt fsblkcnt_t +are reported in units of +.Fa f_frsize . +.Pp +.Fn fstatvfs +returns the same information about an open file referenced by descriptor +.Fa fd . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Fn statvfs +fails if one or more of the following are true: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix of +.Fa path +is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Dv NAME_MAX +characters, or an entire pathname (including the terminating NUL) +exceeded +.Dv PATH_MAX +bytes. +.It Bq Er ENOENT +The file referred to by +.Fa path +does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix of +.Fa path . +.It Bq Er ELOOP +Too many symbolic links were encountered in translating +.Fa path . +.It Bq Er EFAULT +.Fa buf +or +.Fa path +points to an invalid address. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Pp +.Fn fstatvfs +fails if one or more of the following are true: +.Bl -tag -width Er +.It Bq Er EBADF +.Fa fd +is not a valid open file descriptor. +.It Bq Er EFAULT +.Fa buf +points to an invalid address. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr df 1 , +.Xr mount 2 , +.Xr stat 2 , +.Xr statfs 2 +.Sh STANDARDS +The +.Fn statvfs +and +.Fn fstatvfs +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn statvfs +and +.Fn fstatvfs +functions first appeared in +.Ox 4.4 . diff --git a/static/openbsd/man3/stdio.3 b/static/openbsd/man3/stdio.3 new file mode 100644 index 00000000..4b2555de --- /dev/null +++ b/static/openbsd/man3/stdio.3 @@ -0,0 +1,308 @@ +.\" $OpenBSD: stdio.3,v 1.31 2014/07/03 06:08:06 jmc 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. +.\" +.Dd $Mdocdate: July 3 2014 $ +.Dt STDIO 3 +.Os +.Sh NAME +.Nm stdio +.Nd standard input/output library functions +.Sh SYNOPSIS +.In stdio.h +.Pp +.Fd FILE *stdin; +.Fd FILE *stdout; +.Fd FILE *stderr; +.Sh DESCRIPTION +The standard I/O library +provides a simple and efficient buffered stream I/O interface. +Input and output is mapped into logical data streams and the physical I/O +characteristics are concealed. +The functions and macros are listed below; +more information is available from the individual man pages. +.Pp +A stream is associated with an external file (which may be a physical +device) by +.Dq 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 +.Dq 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 will be 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 +.Dq closing +it. +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 (garbage) after a file is closed. +.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 may not close files properly and hence +buffered output may be lost. +In particular, +.Xr _exit 2 +does not flush +.Nm +files. +Neither does an exit due to a signal. +Buffers are flushed by +.Xr abort 3 , +as required by POSIX, although in previous implementations they were not. +.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: +.Pp +.Bl -bullet -compact -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 . +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 so that the output will appear immediately. +Alternatively, these defaults may be modified via the +.Xr setvbuf 3 +function. +.Pp +The +.Nm stdio +library is a part of the library libc +and routines are automatically loaded as needed by the compiler. +The SYNOPSIS +sections of the following manual pages indicate which include files +are to be used, what the compiler declaration for the function +looks like, and which external variables are of interest. +.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_ctermid , +.Dv L_tmpnam , +.Dv NULL , +.Dv SEEK_END , +.Dv SEEK_SET , +.Dv SEEK_CUR , +.Dv TMP_MAX , +.Dv clearerr , +.Dv feof , +.Dv ferror , +.Dv fileno , +.Dv freopen , +.Dv fwopen , +.Dv getc , +.Dv getchar , +.Dv putc , +.Dv putchar , +.Dv stderr , +.Dv stdin , +.Dv stdout . +Function versions of the macro functions +.Xr feof 3 , +.Xr ferror 3 , +.Xr clearerr 3 , +.Xr fileno 3 , +.Xr getc 3 , +.Xr getchar 3 , +.Xr putc 3 , +and +.Xr putchar 3 +exist and will be used if the macro +definitions are explicitly removed. +.Sh LIST OF FUNCTIONS +.Bl -column "sys_errlist" "Description" +.It Sy Function Ta Sy Description +.It asprintf Ta "formatted output conversion with allocation" +.It clearerr Ta "check and reset stream status" +.It dprintf Ta "formatted output conversion" +.It fclose Ta "close a stream" +.It fdopen Ta "stream open functions" +.It feof Ta "check and reset stream status" +.It ferror Ta "check and reset stream status" +.It fflush Ta "flush a stream" +.It fgetc Ta "get next character or word from input stream" +.It fgetln Ta "get a line from a stream" +.It fgetpos Ta "reposition a stream" +.It fgets Ta "get a line from a stream" +.It fgetwc Ta "get next wide character from input stream" +.It fgetws Ta "get a line of wide characters from a stream" +.It fileno Ta "get a stream's underlying file descriptor" +.It fopen Ta "stream open functions" +.It fprintf Ta "formatted output conversion" +.It fpurge Ta "flush a stream" +.It fputc Ta "output a character or word to a stream" +.It fputs Ta "output a line to a stream" +.It fputwc Ta "output a wide character to a stream" +.It fputws Ta "output a line of wide characters to a stream" +.It fread Ta "binary stream input/output" +.It freopen Ta "stream open functions" +.It fropen Ta "open a stream" +.It fscanf Ta "input format conversion" +.It fseek Ta "reposition a stream" +.It fsetpos Ta "reposition a stream" +.It ftell Ta "reposition a stream" +.It funopen Ta "open a stream" +.It fwide Ta "set/get orientation of stream" +.It fwopen Ta "open a stream" +.It fwprintf Ta "formatted wide character output conversion" +.It fwrite Ta "binary stream input/output" +.It getc Ta "get next character or word from input stream" +.It getchar Ta "get next character or word from input stream" +.It getdelim Ta "read a delimited record from a stream" +.It getline Ta "read a delimited record from a stream" +.It getw Ta "get next character or word from input stream" +.It getwc Ta "get next wide character from input stream" +.It getwchar Ta "get next wide character from input stream" +.It mkdtemp Ta "create unique temporary directory" +.It mkstemp Ta "create unique temporary file" +.It mktemp Ta "create unique temporary file" +.It perror Ta "system error messages" +.It printf Ta "formatted output conversion" +.It putc Ta "output a character or word to a stream" +.It putchar Ta "output a character or word to a stream" +.It puts Ta "output a line to a stream" +.It putw Ta "output a character or word to a stream" +.It putwc Ta "output a wide character to a stream" +.It putwchar Ta "output a wide character to a stream" +.It remove Ta "remove directory entry" +.It rewind Ta "reposition a stream" +.It scanf Ta "input format conversion" +.It setbuf Ta "stream buffering operations" +.It setbuffer Ta "stream buffering operations" +.It setlinebuf Ta "stream buffering operations" +.It setvbuf Ta "stream buffering operations" +.It snprintf Ta "formatted output conversion" +.It sprintf Ta "formatted output conversion" +.It sscanf Ta "input format conversion" +.It strerror Ta "system error messages" +.It swprintf Ta "formatted wide character output conversion" +.It sys_errlist Ta "system error messages" +.It sys_nerr Ta "system error messages" +.It tempnam Ta "temporary file routines" +.It tmpfile Ta "temporary file routines" +.It tmpnam Ta "temporary file routines" +.It ungetc Ta "un-get character from input stream" +.It ungetwc Ta "un-get wide character from input stream" +.It vasprintf Ta "formatted output conversion with allocation" +.It vdprintf Ta "formatted output conversion" +.It vfprintf Ta "formatted output conversion" +.It vfscanf Ta "input format conversion" +.It vfwprintf Ta "formatted wide character output conversion" +.It vprintf Ta "formatted output conversion" +.It vscanf Ta "input format conversion" +.It vsnprintf Ta "formatted output conversion" +.It vsprintf Ta "formatted output conversion" +.It vsscanf Ta "input format conversion" +.It vswprintf Ta "formatted wide character output conversion" +.It vwprintf Ta "formatted wide character output conversion" +.It wprintf Ta "formatted wide character output conversion" +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr open 2 , +.Xr read 2 , +.Xr write 2 +.Sh STANDARDS +The +.Nm stdio +library conforms to +.St -isoC-99 . +.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/openbsd/man3/stpcpy.3 b/static/openbsd/man3/stpcpy.3 new file mode 100644 index 00000000..973eebec --- /dev/null +++ b/static/openbsd/man3/stpcpy.3 @@ -0,0 +1,184 @@ +.\" $OpenBSD: stpcpy.3,v 1.6 2014/02/23 23:09:34 schwarze 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. +.\" +.Dd $Mdocdate: February 23 2014 $ +.Dt STPCPY 3 +.Os +.Sh NAME +.Nm stpcpy , +.Nm stpncpy +.Nd copy strings +.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 len" +.Sh DESCRIPTION +The +.Fn stpcpy +and +.Fn stpncpy +functions copy the string +.Fa src +to +.Fa dst +(including the terminating +.Ql \e0 +character). +.Pp +The +.Fn stpncpy +function copies not more than +.Fa len +characters into +.Fa dst , +appending +.Ql \e0 +characters if +.Fa src +is less than +.Fa len +characters long, and +.Em not +terminating +.Fa dst +if the length of +.Fa src +is greater than or equal to +.Fa len . +.Pp +If the +.Fa src +and +.Fa dst +strings overlap, the behavior is undefined. +.Sh RETURN VALUES +The +.Fn stpcpy +function returns a pointer to the terminating +.Ql \e0 +character written into +.Fa dst . +.Pp +The +.Fn stpncpy +function returns a pointer to the first +.Ql \e0 +character written into +.Fa dst , +or to +.Fa &dst[len] +if the length of +.Fa src +is greater than or equal to +.Fa len . +.Sh EXAMPLES +The most common use of +.Fn stpcpy +is to build up a string from multiple elements. +The following example builds up a pathname from +directory and file components using +.Fn stpcpy : +.Bd -literal -offset indent +char *dir, *file, pname[PATH_MAX]; + +\&... + +if (strlen(dir) + strlen("/") + strlen(file) >= sizeof(pname)) + goto toolong; +stpcpy(stpcpy(stpcpy(pname, dir), "/"), file); +.Ed +.Pp +However, the size check required to avoid a buffer overflow is error +prone since the check can become out of sync with the code that +performs the copy. +.Pp +One might expect that +.Fn stpncpy +could be safely used instead, but it suffers from the same defects as +.Fn strncpy . +The example below using +.Fn stpncpy +is even more prone to error and will not detect when truncation occurs: +.Bd -literal -offset indent +char *dir, *file, pname[PATH_MAX]; +char *p1, *p2; + +\&... + +p1 = stpncpy(pname, dir, sizeof(pname) - 1); +p2 = stpncpy(p1, "/", sizeof(pname) - 1 - (p1 - pname)); +stpncpy(p2, file, sizeof(pname) - 1 - (p2 - pname)); +pname[sizeof(pname) - 1] = '\e0'; +.Ed +.Pp +A safer (and simpler) approach is to use +.Fn snprintf : +.Bd -literal -offset indent +char *dir, *file, pname[PATH_MAX]; +int len; + +\&... + +len = snprintf(pname, sizeof(pname), "%s/%s", dir, file); +if (len >= sizeof(pname)) + goto toolong; +.Ed +.Pp +In most cases, it is better to use +.Fn snprintf , +.Fn strlcpy , +or +.Fn strlcat . +.Sh SEE ALSO +.Xr snprintf 3 , +.Xr strcpy 3 , +.Xr strlcpy 3 , +.Xr strncpy 3 +.Sh STANDARDS +The +.Fn stpcpy +and +.Fn stpncpy +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The function +.Fn stpcpy +first appeared in the Lattice C AmigaDOS compiler (1986 or earlier). +The function +.Fn stpncpy +first appeared in the GNU C library version 1.07 (1993). +Both functions have been available since +.Ox 5.1 . diff --git a/static/openbsd/man3/strcasecmp.3 b/static/openbsd/man3/strcasecmp.3 new file mode 100644 index 00000000..bb39df89 --- /dev/null +++ b/static/openbsd/man3/strcasecmp.3 @@ -0,0 +1,128 @@ +.\" $OpenBSD: strcasecmp.3,v 1.14 2017/09/05 03:16:13 schwarze Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2017 Ingo Schwarze +.\" +.\" 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. +.\" +.\" @(#)strcasecmp.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd $Mdocdate: September 5 2017 $ +.Dt STRCASECMP 3 +.Os +.Sh NAME +.Nm strcasecmp , +.Nm strcasecmp_l , +.Nm strncasecmp , +.Nm strncasecmp_l +.Nd compare strings, ignoring case +.Sh SYNOPSIS +.In strings.h +.Ft int +.Fo strcasecmp +.Fa "const char *s1" +.Fa "const char *s2" +.Fc +.Ft int +.Fo strcasecmp_l +.Fa "const char *s1" +.Fa "const char *s2" +.Fa "locale_t locale" +.Fc +.Ft int +.Fo strncasecmp +.Fa "const char *s1" +.Fa "const char *s2" +.Fa "size_t len" +.Fc +.Ft int +.Fo strncasecmp_l +.Fa "const char *s1" +.Fa "const char *s2" +.Fa "size_t len" +.Fa "locale_t locale" +.Fc +.Sh DESCRIPTION +These 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 +.Fn strncasecmp +and +.Fn strncasecmp_l +compare at most +.Fa len +characters. +.Pp +On +.Ox , +these functions always use the C locale and ignore +the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh ENVIRONMENT +On other operating systems, the behaviour of +.Fn strcasecmp +and +.Fn strncasecmp +may depend on the +.Dv LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.Xr strcmp 3 , +.Xr strcoll 3 , +.Xr strxfrm 3 , +.Xr wcscasecmp 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn strcasecmp +and +.Fn strncasecmp +functions have been available since +.Bx 4.3 Tahoe , +and +.Fn strcasecmp_l +and +.Fn strncasecmp_l +since +.Ox 6.2 . diff --git a/static/openbsd/man3/strcat.3 b/static/openbsd/man3/strcat.3 new file mode 100644 index 00000000..68da4ed4 --- /dev/null +++ b/static/openbsd/man3/strcat.3 @@ -0,0 +1,76 @@ +.\" $OpenBSD: strcat.3,v 1.19 2022/08/01 00:04:46 jsg 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. +.\" +.Dd $Mdocdate: August 1 2022 $ +.Dt STRCAT 3 +.Os +.Sh NAME +.Nm strcat +.Nd concatenate two strings without bounds checking +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strcat "char *dst" "const char *append" +.Sh DESCRIPTION +The +.Fn strcat +function appends a copy of the NUL-terminated string +.Fa append +to the end of the NUL-terminated string +.Fa dst , +then adds a terminating +.Ql \e0 . +.Pp +No bounds checking is performed. +If the buffer +.Fa dst +is not large enough to hold the result, +subsequent memory will be damaged. +.Sh RETURN VALUES +The +.Fn strcat +function return the pointer +.Fa dst . +.Sh SEE ALSO +.Xr strlcpy 3 , +.Xr wcscat 3 , +.Xr wcslcpy 3 +.Sh STANDARDS +The +.Fn strcat +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn strcat +function first appeared outside of Bell Labs in PWB/UNIX 1.0. diff --git a/static/openbsd/man3/strchr.3 b/static/openbsd/man3/strchr.3 new file mode 100644 index 00000000..d1dc67e5 --- /dev/null +++ b/static/openbsd/man3/strchr.3 @@ -0,0 +1,116 @@ +.\" $OpenBSD: strchr.3,v 1.14 2024/12/11 23:28:20 jsg 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. +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt STRCHR 3 +.Os +.Sh NAME +.Nm strchr , +.Nm index +.Nd locate first occurrence of a character in a string +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strchr "const char *s" "int c" +.In strings.h +.Ft char * +.Fn index "const char *s" "int c" +.Sh DESCRIPTION +The +.Fn strchr +function locates the first occurrence of the character +.Fa c +.Pq converted to a char +in the string +.Fa s . +The terminating NUL character is considered part of the string. +If +.Fa c +is +.Ql \e0 , +.Fn strchr +locates the terminating +.Ql \e0 . +.Pp +The +.Fn index +function is an old synonym for +.Fn strchr . +.Sh RETURN VALUES +The +.Fn strchr +function returns a pointer to the located character or +.Dv NULL +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 memchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 , +.Xr wcschr 3 +.Sh STANDARDS +The +.Fn strchr +function conforms to +.St -ansiC . +.Pp +The +.Fn index +function is deprecated and shouldn't be used in new code. +.Sh HISTORY +The +.Fn index +function first appeared in +.At v7 . +The +.Fn strchr +function first appeared in +.At III +and was reimplemented for +.Bx 4.3 . diff --git a/static/openbsd/man3/strcmp.3 b/static/openbsd/man3/strcmp.3 new file mode 100644 index 00000000..4ef341e5 --- /dev/null +++ b/static/openbsd/man3/strcmp.3 @@ -0,0 +1,95 @@ +.\" $OpenBSD: strcmp.3,v 1.15 2022/08/01 00:04:46 jsg 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. +.\" +.Dd $Mdocdate: August 1 2022 $ +.Dt STRCMP 3 +.Os +.Sh NAME +.Nm strcmp , +.Nm strncmp +.Nd compare strings +.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 . +The +.Fn strncmp +function compares at most +.Fa len +characters. +.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 . +.Sh SEE ALSO +.Xr bcmp 3 , +.Xr memcmp 3 , +.Xr strcasecmp 3 , +.Xr strcoll 3 , +.Xr strxfrm 3 , +.Xr wcscmp 3 +.Sh STANDARDS +The +.Fn strcmp +and +.Fn strncmp +functions conform to +.St -ansiC . +.Sh HISTORY +The +.Fn strcmp +function first appeared outside of Bell Labs in PWB/UNIX 1.0. +.Fn strncmp +first appeared in +.At v7 . diff --git a/static/openbsd/man3/strcoll.3 b/static/openbsd/man3/strcoll.3 new file mode 100644 index 00000000..9daa6cd9 --- /dev/null +++ b/static/openbsd/man3/strcoll.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: strcoll.3,v 1.11 2019/01/18 07:43:36 schwarze Exp $ +.\" +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: January 18 2019 $ +.Dt STRCOLL 3 +.Os +.Sh NAME +.Nm strcoll , +.Nm strcoll_l +.Nd compare strings according to current collation +.Sh SYNOPSIS +.In string.h +.Ft int +.Fn strcoll "const char *s1" "const char *s2" +.Ft int +.Fn strcoll_l "const char *s1" "const char *s2" "locale_t locale" +.Sh DESCRIPTION +The +.Fn strcoll +and +.Fn strcoll_l +functions lexicographically compare the NUL-terminated strings +.Fa s1 +and +.Fa s2 +according to the current locale collation +and return 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 . +.Pp +On +.Ox , +they have the same effect as +.Xr strcmp 3 , +and the global locale, the thread-specific locale, and the +.Fa locale +argument are ignored. +On other operating systems, results may depend on the +.Dv LC_CTYPE +and +.Dv LC_COLLATE +locale categories set with +.Xr setlocale 3 , +.Xr uselocale 3 , +or +.Xr newlocale 3 . +.Sh SEE ALSO +.Xr newlocale 3 , +.Xr setlocale 3 , +.Xr strcmp 3 , +.Xr strxfrm 3 , +.Xr wcscoll 3 +.Sh STANDARDS +The +.Fn strcoll +function conforms to +.St -ansiC , +and +.Fn strcoll_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn strcoll +function has been available since +.Bx 4.3 Reno , +and +.Fn strcoll_l +since +.Ox 6.2 . diff --git a/static/openbsd/man3/strcpy.3 b/static/openbsd/man3/strcpy.3 new file mode 100644 index 00000000..4bf690ba --- /dev/null +++ b/static/openbsd/man3/strcpy.3 @@ -0,0 +1,82 @@ +.\" $OpenBSD: strcpy.3,v 1.22 2022/08/01 00:04:46 jsg 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. +.\" +.Dd $Mdocdate: August 1 2022 $ +.Dt STRCPY 3 +.Os +.Sh NAME +.Nm strcpy +.Nd copy a string without bounds checking +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strcpy "char *dst" "const char *src" +.Sh DESCRIPTION +The +.Fn strcpy +function copies the string +.Fa src +(including the terminating +.Ql \e0 +character) to the buffer +.Fa dst . +.Pp +No bounds checking is performed. +If the buffer +.Fa dst +is not large enough to hold the result, +subsequent memory will be damaged. +.Pp +If the +.Fa src +string is inside the +.Fa dst +buffer, the behavior is undefined. +.Sh RETURN VALUES +The +.Fn strcpy +function returns +.Fa dst . +.Sh SEE ALSO +.Xr strlcpy 3 , +.Xr wcscpy 3 , +.Xr wcslcpy 3 +.Sh STANDARDS +The +.Fn strcpy +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn strcpy +function first appeared outside of Bell Labs in PWB/UNIX 1.0. diff --git a/static/openbsd/man3/strcspn.3 b/static/openbsd/man3/strcspn.3 new file mode 100644 index 00000000..91e5c3f1 --- /dev/null +++ b/static/openbsd/man3/strcspn.3 @@ -0,0 +1,108 @@ +.\" $OpenBSD: strcspn.3,v 1.12 2024/12/11 23:28:20 jsg 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. +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt STRCSPN 3 +.Os +.Sh NAME +.Nm strcspn +.Nd span the complement of a string +.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 +.Pp +The following removes the first (if any) newline character from string +.Fa line . +This is useful for trimming the newline after a +.Xr fgets 3 +call. +.Bd -literal -offset indent +char line[BUFSIZ]; + +if (fgets(line, sizeof(line), fp) != NULL) + line[strcspn(line, "\en")] = '\e0'; +.Ed +.Sh SEE ALSO +.Xr memchr 3 , +.Xr strchr 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 , +.Xr wcscspn 3 +.Sh STANDARDS +The +.Fn strcspn +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn strcspn +function first appeared in +.At III +and was reimplemented for +.Bx 4.3 . diff --git a/static/openbsd/man3/strdup.3 b/static/openbsd/man3/strdup.3 new file mode 100644 index 00000000..283f3bc0 --- /dev/null +++ b/static/openbsd/man3/strdup.3 @@ -0,0 +1,119 @@ +.\" $OpenBSD: strdup.3,v 1.22 2015/12/01 01:32:48 mmcc 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. +.\" +.\" @(#)strdup.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd $Mdocdate: December 1 2015 $ +.Dt STRDUP 3 +.Os +.Sh NAME +.Nm strdup , +.Nm strndup +.Nd save a copy of a string +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strdup "const char *s" +.Ft char * +.Fn strndup "const char *s" "size_t maxlen" +.Sh DESCRIPTION +The +.Fn strdup +function allocates sufficient memory for a copy of the string +.Fa s , +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 +The +.Fn strndup +function behaves similarly to +.Nm strdup +but only copies up to +.Fa maxlen +characters from +.Fa s . +The resulting string is always NUL-terminated. +.Pp +If the memory allocation fails, +.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 +char *p; + +p = strdup("foobar"); +if (p == NULL) + err(1, NULL); +.Ed +.Sh ERRORS +The +.Fn strdup +and +.Fn strndup +functions 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 strlcpy 3 , +.Xr strlen 3 , +.Xr wcsdup 3 +.Sh STANDARDS +The +.Fn strdup +and +.Fn strndup +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +A +.Fn strdup +macro was first used in the +.Bx 4.1c +debugger, +.Sy dbx . +It was rewritten as a C function for the +.Bx 4.3 +.Xr inetd 8 +and first appeared in the C library of +.Bx 4.3 Reno . +The +.Fn strndup +function appeared in glibc 2.0, was reimplemented for +.Nx 4.0 , +and ported to +.Ox 4.8 . diff --git a/static/openbsd/man3/strerror.3 b/static/openbsd/man3/strerror.3 new file mode 100644 index 00000000..6c5b890f --- /dev/null +++ b/static/openbsd/man3/strerror.3 @@ -0,0 +1,154 @@ +.\" $OpenBSD: strerror.3,v 1.16 2019/05/16 13:35:16 schwarze Exp $ +.\" +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: May 16 2019 $ +.Dt STRERROR 3 +.Os +.Sh NAME +.Nm strerror , +.Nm strerror_l , +.Nm strerror_r +.Nd get error message string +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strerror "int errnum" +.Ft char * +.Fn strerror_l "int errnum" "locale_t locale" +.Ft int +.Fn strerror_r "int errnum" "char *strerrbuf" "size_t buflen" +.Sh DESCRIPTION +These functions map the error number +.Fa errnum +to an error message string. +.Pp +.Fn strerror +and +.Fn strerror_l +return a string containing a maximum of +.Dv NL_TEXTMAX +characters, including the trailing NUL. +This string is not to be modified by the calling program. +The string returned by +.Fn strerror +may be overwritten by subsequent calls to +.Fn strerror +in any thread. +The string returned by +.Fn strerror_l +may be overwritten by subsequent calls to +.Fn strerror_l +in the same thread. +.Pp +.Fn strerror_r +is a thread safe version of +.Fn strerror +that places the error message in the specified buffer +.Fa strerrbuf . +.Pp +On +.Ox , +the global locale, the thread-specific locale, and the +.Fa locale +argument are ignored. +.Sh RETURN VALUES +.Fn strerror +and +.Fn strerror_l +return a pointer to the error message string. +If an error occurs, the error code is stored in +.Va errno . +.Pp +.Fn strerror_r +returns zero upon successful completion. +If an error occurs, the error code is stored in +.Va errno +and the error code is returned. +.Sh ERRORS +All these functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa errnum +is not a valid error number. +The returned error string will consist of an error message that includes +.Fa errnum . +.El +.Pp +.Fn strerror_r +may also fail if: +.Bl -tag -width Er +.It Bq Er ERANGE +The error message is larger than +.Fa buflen +characters. +The message will be truncated to fit. +.El +.Sh SEE ALSO +.Xr intro 2 , +.Xr newlocale 3 , +.Xr perror 3 , +.Xr setlocale 3 +.Sh STANDARDS +The +.Fn strerror +function conforms to +.St -isoC-99 . +The +.Fn strerror_l +and +.Fn strerror_r +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn strerror +function has been available since +.Bx 4.3 Reno , +.Fn strerror_r +since +.Ox 3.3 , +and +.Fn strerror_l +since +.Ox 6.2 . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_MESSAGES +.Xr locale 1 +category can cause different strings to be returned instead of the +normal error messages; see CAVEATS in +.Xr setlocale 3 +for details. diff --git a/static/openbsd/man3/strftime.3 b/static/openbsd/man3/strftime.3 new file mode 100644 index 00000000..de627584 --- /dev/null +++ b/static/openbsd/man3/strftime.3 @@ -0,0 +1,329 @@ +.\" $OpenBSD: strftime.3,v 1.40 2025/06/23 13:53:11 millert 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. +.\" +.\" from: @(#)strftime.3 5.12 (Berkeley) 6/29/91 +.\" +.Dd $Mdocdate: June 23 2025 $ +.Dt STRFTIME 3 +.Os +.Sh NAME +.Nm strftime , +.Nm strftime_l +.Nd format date and time +.Sh SYNOPSIS +.In time.h +.Ft size_t +.Fo strftime +.Fa "char *buf" +.Fa "size_t maxsize" +.Fa "const char *format" +.Fa "const struct tm *timeptr" +.Fc +.Ft size_t +.Fo strftime_l +.Fa "char *buf" +.Fa "size_t maxsize" +.Fa "const char *format" +.Fa "const struct tm *timeptr" +.Fa "locale_t locale" +.Fc +.Sh DESCRIPTION +These functions format the information from +.Fa timeptr +(as described in +.Xr mktime 3 ) +into the buffer +.Fa buf +according to the string pointed to by +.Fa format . +.Pp +The +.Fa format +string consists of zero or more conversion specifications and +ordinary characters. +All ordinary characters are copied directly into the buffer. +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. +.Pp +Each conversion specification is replaced by the characters as +follows which are then copied into the buffer. +.Bl -tag -width "xxxx" +.It Cm \&%A +is replaced by the locale's full weekday name. +.It Cm \&%a +is replaced by the locale's abbreviated weekday name. +.It Cm \&%B +is replaced by the locale's full month name. +.It Cm \&%b No or Cm \&%h +is replaced by the locale's abbreviated month name. +.It Cm \&%C +is replaced by the century (a year divided by 100 and truncated to an integer) +as a decimal number (00\-99). +.It Cm \&%c +is replaced by the locale's appropriate date and time representation. +.It Cm \&%D +is replaced by the date in the format +.Dq Li %m/%d/%y . +.It Cm \&%d +is replaced by the day of the month as a decimal number (01\-31). +.It Cm \&%e +is replaced by the day of month as a decimal number (1\-31); +single digits are preceded by a blank. +.It Cm \&%F +is replaced by the date in the format +.Dq Li %Y-%m-%d . +.It Cm \&%G +is replaced by the +.St -iso8601 +week-numbering year with century as a decimal number. +See also the +.Cm \&%V +conversion specification and the +.Sx STANDARDS +section for more details. +.It Cm \&%g +is replaced by the +.St -iso8601 +week-numbering year without century as a decimal number (00\-99). +See also the +.Cm \&%V +conversion specification and the +.Sx STANDARDS +section for more details. +.It Cm \&%H +is replaced by the hour (24-hour clock) as a decimal number (00\-23). +.It Cm \&%I +is replaced by the hour (12-hour clock) as a decimal number (01\-12). +.It Cm \&%j +is replaced by the day of the year as a decimal number (001\-366). +.It Cm \&%k +is replaced by the hour (24-hour clock) as a decimal number (0\-23); +single digits are preceded by a blank. +.It Cm \&%l +is replaced by the hour (12-hour clock) as a decimal number (1\-12); +single digits are preceded by a blank. +.It Cm \&%M +is replaced by the minute as a decimal number (00\-59). +.It Cm %m +is replaced by the month as a decimal number (01\-12). +.It Cm %n +is replaced by a newline. +.It Cm %p +is replaced by the locale's equivalent of either +.Dq AM +or +.Dq PM . +.It Cm \&%R +is replaced by the time in the format +.Dq Li %H:%M . +.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. +.It Cm %s +is replaced by the number of seconds since the Epoch (see +.Xr ctime 3 ) . +.It Cm \&%T +is replaced by the time in the format +.Dq Li %H:%M:%S . +.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). +.It Cm \&%u +is replaced by the weekday (Monday as the first day of the week) +as a decimal number (1\-7). +.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). +If the week containing January +1 has four or more days in the new year, then it is week 1; otherwise +it is week 53 of the previous year, and the next week is week 1. +The year is given by the +.Cm \&%G +conversion specification. +See the +.Sx STANDARDS +section for more details. +.It Cm \&%v +is replaced by the date in the format +.Dq Li "%e-%b-%Y" . +.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). +.It Cm \&%w +is replaced by the weekday (Sunday as the first day of the week) +as a decimal number (0\-6). +.It Cm \&%X +is replaced by the locale's appropriate time representation. +.It Cm \&%x +is replaced by the locale's appropriate date representation. +.It Cm \&%Y +is replaced by the year with century as a decimal number. +.It Cm \&%y +is replaced by the year without century as a decimal number (00\-99). +.It Cm \&%Z +is replaced by the time zone name, +or by the empty string if this is not determinable. +.It Cm \&%z +is replaced by the offset from the Prime Meridian in the format +.Dq Li +HHMM +or +.Dq Li -HHMM +as appropriate, with positive values representing locations east +of Greenwich, or by the empty string if this is not determinable. +.It Cm %% +is replaced by +.Ql % . +.It Cm %+ +is replaced by the date and time in +.Xr date 1 +format. +.El +.Pp +The +.Ox +implementation always uses the C locale and ignores +the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +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 placed in the array, not counting the +terminating NUL. +Otherwise, zero is returned. +.Sh SEE ALSO +.Xr date 1 , +.Xr printf 1 , +.Xr ctime 3 , +.Xr getenv 3 , +.Xr printf 3 , +.Xr strptime 3 , +.Xr time 3 , +.Xr tzset 3 , +.Xr tzfile 5 +.Sh STANDARDS +The +.Fn strftime +function +conforms to +.St -isoC-99 , +and +.Fn strftime_l +to +.St -p1003.1-2008 , +except that the +.Ql E +and +.Ql O +conversion modifiers are ignored by this implementation. +.Pp +The +.Ql \&%k , +.Ql \&%l , +.Ql \&%s , +.Ql \&%v , +and +.Ql \&%+ +conversion specifications are extensions. +.Pp +Use of the +.St -iso8601 +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 HISTORY +A predecessor to +.Fn strftime , +.Fn ptime , +first appeared in +.At v1 . +The +.Fn strftime +function has been available since +.Bx 4.3 Reno , +and +.Fn strftime_l +since +.Ox 6.2 . +.Sh AUTHORS +.An Keith Bostic +implemented the +.Bx +version of +.Fn strftime +in 1989. +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_TIME +.Xr locale 1 +category can cause erratic output; see CAVEATS in +.Xr setlocale 3 +for details. +.Sh BUGS +There is no conversion specification for the phase of the moon. +.Pp +Note that while this implementation of +.Fn strftime +will always NUL terminate +.Fa buf , +other implementations may not do so when +.Fa maxsize +is not large enough to store the entire time string. +The contents of +.Fa buf +are implementation specific in this case. diff --git a/static/openbsd/man3/strlcpy.3 b/static/openbsd/man3/strlcpy.3 new file mode 100644 index 00000000..46072898 --- /dev/null +++ b/static/openbsd/man3/strlcpy.3 @@ -0,0 +1,195 @@ +.\" $OpenBSD: strlcpy.3,v 1.28 2024/08/03 20:13:23 guenther Exp $ +.\" +.\" Copyright (c) 1998, 2000 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. +.\" +.Dd $Mdocdate: August 3 2024 $ +.Dt STRLCPY 3 +.Os +.Sh NAME +.Nm strlcpy , +.Nm strlcat +.Nd size-bounded string copying and concatenation +.Sh SYNOPSIS +.In string.h +.Ft size_t +.Fn strlcpy "char * restrict dst" "const char * restrict src" "size_t dstsize" +.Ft size_t +.Fn strlcat "char * restrict dst" "const char * restrict src" "size_t dstsize" +.Sh DESCRIPTION +The +.Fn strlcpy +and +.Fn strlcat +functions copy and concatenate strings with the +same input parameters and output result as +.Xr snprintf 3 . +They are designed to be safer, more consistent, and less error +prone replacements for the easily misused functions +.Xr strncpy 3 +and +.Xr strncat 3 . +.Pp +.Fn strlcpy +and +.Fn strlcat +take the full size of the destination buffer and guarantee +NUL-termination if there is room. +Note that room for the NUL should be included in +.Fa dstsize . +.Pp +.Fn strlcpy +copies up to +.Fa dstsize +\- 1 characters from the string +.Fa src +to +.Fa dst , +NUL-terminating the result if +.Fa dstsize +is not 0. +.Pp +.Fn strlcat +appends string +.Fa src +to the end of +.Fa dst . +It will append at most +.Fa dstsize +\- strlen(dst) \- 1 characters. +It will then NUL-terminate, unless +.Fa dstsize +is 0 or the original +.Fa dst +string was longer than +.Fa dstsize +(in practice this should not happen +as it means that either +.Fa dstsize +is incorrect or that +.Fa dst +is not a proper string). +.Pp +If the +.Fa src +and +.Fa dst +strings overlap, the behavior is undefined. +.Sh RETURN VALUES +Besides quibbles over the return type +.Pf ( Va size_t +versus +.Va int ) +and signal handler safety +.Pf ( Xr snprintf 3 +is not entirely safe on some systems), the +following two are equivalent: +.Bd -literal -offset indent +n = strlcpy(dst, src, len); +n = snprintf(dst, len, "%s", src); +.Ed +.Pp +Like +.Xr snprintf 3 , +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 . +.Pp +If the return value is +.Cm >= +.Va dstsize , +the output string has been truncated. +It is the caller's responsibility to handle this. +.Sh EXAMPLES +The following code fragment illustrates the simple case: +.Bd -literal -offset indent +char *s, *p, buf[BUFSIZ]; + +\&... + +(void)strlcpy(buf, s, sizeof(buf)); +(void)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[PATH_MAX]; + +\&... + +if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname)) + goto toolong; +if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname)) + goto toolong; +.Ed +.Pp +Since it is known how many characters were copied the first time, things +can be sped up a bit by using a copy instead of an append: +.Bd -literal -offset indent +char *dir, *file, pname[PATH_MAX]; +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 . +As a matter of fact, the first version of this manual page got it wrong. +.Sh SEE ALSO +.Xr snprintf 3 , +.Xr strncat 3 , +.Xr strncpy 3 , +.Xr wcslcpy 3 +.Sh STANDARDS +The +.Fn strlcat +and +.Fn strlcpy +functions conform to +.St -p1003.1-2024 . +.Sh HISTORY +.Fn strlcpy +and +.Fn strlcat +first appeared in +.Ox 2.4 . +.Sh AUTHORS +.Fn strlcpy +and +.Fn strlcat +were created by +.An Todd C. Miller Aq Mt millert@openbsd.org . diff --git a/static/openbsd/man3/strlen.3 b/static/openbsd/man3/strlen.3 new file mode 100644 index 00000000..18569d58 --- /dev/null +++ b/static/openbsd/man3/strlen.3 @@ -0,0 +1,103 @@ +.\" $OpenBSD: strlen.3,v 1.14 2022/07/31 14:50:32 jsg 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. +.\" +.Dd $Mdocdate: July 31 2022 $ +.Dt STRLEN 3 +.Os +.Sh NAME +.Nm strlen , +.Nm strnlen +.Nd find length of a string +.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 computes the length of the string +.Fa s , +up to +.Fa maxlen +characters. +The +.Fn strnlen +function will never attempt to address more than +.Fa maxlen +characters, making it suitable for use with character arrays that are +not guaranteed to be NUL-terminated. +.Sh RETURN VALUES +The +.Fn strlen +function returns the number of characters that precede the terminating +.Tn NUL +character. +.Pp +The +.Fn strnlen +function returns the number of characters that precede the terminating +.Tn NUL +or +.Fa maxlen , +whichever is smaller. +.Sh SEE ALSO +.Xr wcslen 3 +.Sh STANDARDS +The +.Fn strlen +function conforms to +.St -ansiC . +.Pp +The +.Fn strlen +and +.Fn strnlen +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn strlen +function first appeared in +.At v6 . +The +.Fn strnlen +function appeared in glibc 2.0 +and was reimplemented for +.Ox 4.8 . diff --git a/static/openbsd/man3/strmode.3 b/static/openbsd/man3/strmode.3 new file mode 100644 index 00000000..8135d30b --- /dev/null +++ b/static/openbsd/man3/strmode.3 @@ -0,0 +1,153 @@ +.\" $OpenBSD: strmode.3,v 1.17 2017/07/05 11:44:35 tb 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. +.\" +.\" @(#)strmode.3 8.3 (Berkeley) 7/28/94 +.\" +.Dd $Mdocdate: July 5 2017 $ +.Dt STRMODE 3 +.Os +.Sh NAME +.Nm strmode +.Nd convert inode status information into a symbolic string +.Sh SYNOPSIS +.In string.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 b +block special +.It c +character special +.It d +directory +.It l +symbolic link +.It p +FIFO +.It s +socket +.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 +.Dq 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 +.Dq other +permissions allow reading. +.Pp +If the first character of the three character set is an +.Sq r , +the file is readable for that set of users; if a dash +.Pq Ql - , +it is not readable. +.Pp +If the second character of the three character set is a +.Sq w , +the file is writable for that set of users; if a dash +.Pq Ql - , +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 +.Dq 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 +.Dq 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 +.Pq Ql + +if there are any alternate +or additional access control methods associated with the inode, otherwise +it will be a space. +.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.3 Reno . diff --git a/static/openbsd/man3/strncat.3 b/static/openbsd/man3/strncat.3 new file mode 100644 index 00000000..d314a999 --- /dev/null +++ b/static/openbsd/man3/strncat.3 @@ -0,0 +1,132 @@ +.\" $OpenBSD: strncat.3,v 1.4 2014/04/19 16:50:46 jmc 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. +.\" +.Dd $Mdocdate: April 19 2014 $ +.Dt STRNCAT 3 +.Os +.Sh NAME +.Nm strncat +.Nd concatenate a string with part of another +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strncat "char *dst" "const char *append" "size_t count" +.Sh DESCRIPTION +The +.Fn strncat +function appends not more than +.Fa count +characters of the string +.Fa append +to the end of the string found in the buffer +.Fa dst . +Space for the terminating +.Ql \e0 +should not be included in +.Fa count . +.Pp +Bounds checking must be performed manually with great care. +If the buffer +.Fa dst +is not large enough to hold the result, +subsequent memory will be damaged. +.Sh RETURN VALUES +The +.Fn strncat +function returns the pointer +.Fa dst . +.Sh EXAMPLES +The following example shows how to use +.Fn strncat +in conjunction with +.Xr strncpy 3 : +.Bd -literal -offset indent +char buf[BUFSIZ]; +char *base, *suffix; + +(void)strncpy(buf, base, 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 +.Va base +to +.Va buf +as will fit. +It then appends as many characters from +.Va suffix +as will fit. +If either +.Va base +or +.Va suffix +are too large, truncation will occur without detection. +.Pp +The above example shows dangerous coding patterns, including an +inability to detect truncation. +.Fn strncat +and +.Fn strncpy +are dangerously easy to misuse. +The +.Xr strlcpy 3 +and +.Xr strlcat 3 +functions are safer for this kind of operation: +.Bd -literal -offset indent +if (strlcpy(buf, base, sizeof(buf)) >= sizeof(buf) || + strlcat(buf, suffix, sizeof(buf)) >= sizeof(buf)) + goto toolong; + +.Ed +or for greatest portability, +.Bd -literal -offset indent +if (snprintf(buf, sizeof(buf), "%s%s", + base, suffix) >= sizeof(buf)) + goto toolong; +.Ed +.Sh SEE ALSO +.Xr strlcpy 3 , +.Xr wcscat 3 , +.Xr wcslcpy 3 +.Sh STANDARDS +The +.Fn strncat +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn strncat +function first appeared in +.At v7 . diff --git a/static/openbsd/man3/strncpy.3 b/static/openbsd/man3/strncpy.3 new file mode 100644 index 00000000..3a68a0bd --- /dev/null +++ b/static/openbsd/man3/strncpy.3 @@ -0,0 +1,138 @@ +.\" $OpenBSD: strncpy.3,v 1.2 2014/04/19 11:30:40 deraadt 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. +.\" +.Dd $Mdocdate: April 19 2014 $ +.Dt STRNCPY 3 +.Os +.Sh NAME +.Nm strncpy +.Nd copy part of a string to another +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strncpy "char *dst" "const char *src" "size_t len" +.Sh DESCRIPTION +The +.Fn strncpy +function copies not more than +.Fa len +characters from the string +.Fa src +to the buffer +.Fa dst . +If +.Fa src +is less than +.Fa len +characters long, +it fills the remaining buffer with +.Ql \e0 +characters. +If the length of +.Fa src +is greater than or equal to +.Fa len , +.Fa dst +will +.Em not +be NUL-terminated. +.Pp +.Fn strncpy +.Em only +NUL terminates the destination string when the length of the source +string is less than the length parameter. +.Pp +If the +.Fa src +and +.Fa dst +strings overlap, the behavior is undefined. +.Sh RETURN VALUES +The +.Fn strncpy +function returns +.Fa dst . +.Sh EXAMPLES +The following sets +.Va chararray +to +.Dq abc\e0\e0\e0 : +.Bd -literal -offset indent +(void)strncpy(chararray, "abc", 6); +.Ed +.Pp +The following sets +.Va chararray +to +.Dq abcdef , +without a NUL-terminator: +.Bd -literal -offset indent +(void)strncpy(chararray, "abcdefgh", 6); +.Ed +.Pp +The following sequence copies as many characters from +.Va input +to +.Va buf +as will fit, and then NUL terminates the result by hand: +.Bd -literal -offset indent +char buf[BUFSIZ]; + +(void)strncpy(buf, input, sizeof(buf) - 1); +buf[sizeof(buf) - 1] = '\e0'; +.Ed +.Pp +By now it is clear that +.Nm strncpy +is dangerously easy to misuse. +The +.Xr strlcpy 3 +function is safer for this kind of operation: +.Bd -literal -offset indent +if (strlcpy(buf, input, sizeof(buf)) >= sizeof(buf)) + goto toolong; +.Ed +.Sh SEE ALSO +.Xr strlcpy 3 , +.Xr wcscpy 3 , +.Xr wcslcpy 3 +.Sh STANDARDS +The +.Fn strncpy +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn strncpy +function first appeared in +.At v7 . diff --git a/static/openbsd/man3/strpbrk.3 b/static/openbsd/man3/strpbrk.3 new file mode 100644 index 00000000..51d2edf5 --- /dev/null +++ b/static/openbsd/man3/strpbrk.3 @@ -0,0 +1,80 @@ +.\" $OpenBSD: strpbrk.3,v 1.11 2024/12/11 23:28:20 jsg 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. +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt STRPBRK 3 +.Os +.Sh NAME +.Nm strpbrk +.Nd locate multiple characters in string +.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 memchr 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 , +.Xr wcspbrk 3 +.Sh STANDARDS +The +.Fn strpbrk +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn strpbrk +function first appeared in +.At III +and was reimplemented for +.Bx 4.3 . diff --git a/static/openbsd/man3/strptime.3 b/static/openbsd/man3/strptime.3 new file mode 100644 index 00000000..574ba8bc --- /dev/null +++ b/static/openbsd/man3/strptime.3 @@ -0,0 +1,333 @@ +.\" $OpenBSD: strptime.3,v 1.31 2025/08/26 22:30:42 millert Exp $ +.\" +.\" Copyright (c) 1997, 1998, 2005, 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 $Mdocdate: August 26 2025 $ +.Dt STRPTIME 3 +.Os +.Sh NAME +.Nm strptime +.Nd converts a character string to a time value +.Sh SYNOPSIS +.In time.h +.Ft char * +.Fn strptime "const char *buf" "const char *format" "struct tm *tm" +.Sh DESCRIPTION +The +.Nm +function parses the string +.Fa buf +according to the specified +.Fa format +and fills matching data into the structure +.Fa tm +(described in +.Xr mktime 3 ) . +.Pp +The +.Fa format +string consists of zero or more directives. +A directive is composed of either one or more whitespace characters as +defined by +.Xr isspace 3 , +an ordinary character (neither +.Sq % +nor a whitespace), or a conversion +specification. +A conversion specification consists of a percent sign +.Pq Sq % +followed by one or two conversion characters which specify the +replacement required. +There must be whitespace or other +non-alphanumeric characters between any two conversion specifications. +.Pp +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. +Note that the converted value is added to the current value of the +.Fa tm_year +field (in order that the "\&%y" conversion be useful). +.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 day of month [1,31]; +leading spaces or zeros are permitted but not required. +.It Cm \&%F +the date as %Y-%m-%d +(the +.St -iso8601 +date format). +.It Cm \&%g +the year corresponding to the ISO week number, without the century. +.It Cm \&%G +the year corresponding to the ISO week number, with the century. +.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 whitespace. +.It Cm \&%p +the locale's equivalent of +.Dq AM +or +.Dq PM . +.It Cm \&%r +the time as %I:%M:%S %p. +.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 ) . +.It Cm \&%t +any whitespace. +.It Cm \&%T +the time as %H:%M:%S. +.It Cm \&%u +the day of the week as a decimal number, where Monday = 1. +.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 +.St -iso8601 +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. +.It Cm \&%v +the date as %e-%b-%Y. +.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 current century. +When a century is not otherwise +specified, values in the range 69\-99 refer to years in the twentieth +century (1969 to 1999 inclusive); values in the range 00\-68 refer +to years in the twenty-first century (2000 to 2068 inclusive). +Leading zeros are permitted but not required. +.It Cm \&%Y +the year, including the century (i.e., 1998). +.It Cm \&%z +an +.St -iso8601 +or RFC 5322 timezone specification. +This is one of the following: +the offset from +Coordinated Universal Time +.Pq Ql UTC +specified as: +.Dq [+-]hhmm , +.Dq [+-]hh:mm , +or +.Dq [+-]hh ; +.Ql UTC +specified as: +.Dq GMT +.Pq Ql Greenwich Mean Time , +.Dq UT +.Pq Ql Universal Time , +or +.Dq Z +.Pq Ql Zulu Time ; +a three character US timezone specified as: +.Dq EDT , +.Dq EST , +.Dq CDT , +.Dq CST , +.Dq MDT , +.Dq MST , +.Dq PDT , +or +.Dq PST , +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 Cm \&%Z +timezone name or no characters when timezone information is unavailable. +.It Cm \&%% +A `%' is read. +No argument is converted. +.El +.Pp +The +.Ox +implementation always uses the C locale and ignores the +global locale and the thread-specific locale. +Alternative conversion modifiers have no effect. +.Pp +There is no way to specify whether Daylight Saving Time is in effect when +calling +.Nm . +To use the resulting +.Fa tm +structure with functions that check the +.Fa tm_isdst +field, either set it to a negative value, which will cause +.Xr mktime 3 +to attempt to divine whether Daylight Saving Time would be in effect +for the given time, or compute the value manually. +.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 +.Nm +function returns a pointer to the character following the last character +parsed. +Otherwise, a null pointer is returned. +.Sh SEE ALSO +.Xr mktime 3 , +.Xr strftime 3 +.Sh STANDARDS +The +.Fn strptime +function conforms to the X/Open System Interfaces option of +.St -p1003.1-2008 , +except that flags and field width specifications are not supported. +.Pp +The +.Ql \&%F , +.Ql \&%g , +.Ql \&%G , +.Ql \&%k , +.Ql \&%l , +.Ql \&%s , +.Ql \&%u , +.Ql \&%V , +.Ql \&%z , +and +.Ql \&%Z +conversion specifications are extensions. +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_TIME +.Xr locale 1 +category can cause parsing failures; see CAVEATS in +.Xr setlocale 3 +for details. +.Sh BUGS +The +.Cm \&%Z +format specifier only accepts timezone +abbreviations of the local timezone, +or the value +.Dq GMT . +This limitation is caused by the ambiguity +of overloaded timezone abbreviations, +for example EST is both Eastern Standard +Time and Eastern Australia Summer Time. diff --git a/static/openbsd/man3/strrchr.3 b/static/openbsd/man3/strrchr.3 new file mode 100644 index 00000000..231260f7 --- /dev/null +++ b/static/openbsd/man3/strrchr.3 @@ -0,0 +1,118 @@ +.\" $OpenBSD: strrchr.3,v 1.13 2024/12/11 23:28:20 jsg 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. +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt STRRCHR 3 +.Os +.Sh NAME +.Nm strrchr , +.Nm rindex +.Nd locate last occurrence of a character in a string +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strrchr "const char *s" "int c" +.In strings.h +.Ft char * +.Fn rindex "const char *s" "int c" +.Sh DESCRIPTION +The +.Fn strrchr +function locates the last occurrence of the character +.Fa c +.Pq converted to a char +in the string +.Fa s . +The terminating +.Tn NUL +character is considered part of the string. +If +.Fa c +is +.Ql \e0 , +.Fn strrchr +locates the terminating +.Ql \e0 . +.Pp +The +.Fn rindex +function is an old synonym for +.Fn strrchr . +.Sh RETURN VALUES +The +.Fn strrchr +function returns a pointer to the located character or +.Dv NULL +if the character does not appear in the string. +.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 memchr 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 , +.Xr wcsrchr 3 +.Sh STANDARDS +The +.Fn strrchr +function conforms to +.St -ansiC . +.Pp +The +.Fn rindex +function is deprecated and shouldn't be used in new code. +.Sh HISTORY +The +.Fn rindex +function first appeared in +.At v7 . +The +.Fn strrchr +function first appeared in +.At III +and was reimplemented for +.Bx 4.3 . diff --git a/static/openbsd/man3/strsep.3 b/static/openbsd/man3/strsep.3 new file mode 100644 index 00000000..77053f66 --- /dev/null +++ b/static/openbsd/man3/strsep.3 @@ -0,0 +1,110 @@ +.\" $OpenBSD: strsep.3,v 1.14 2013/06/05 03:39:23 tedu 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. +.\" +.\" @(#)strsep.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt STRSEP 3 +.Os +.Sh NAME +.Nm strsep +.Nd separate strings +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strsep "char **stringp" "const char *delim" +.Sh DESCRIPTION +The +.Fn strsep +function locates, in the 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 . +.Sh EXAMPLES +The following uses +.Fn strsep +to parse a string, containing tokens delimited by whitespace, 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++; +} +*ap = NULL; +.Ed +.Sh HISTORY +The +.Fn strsep +function first appeared in +.Bx 4.3 Reno . +It is intended as a replacement for the +.Xr strtok 3 +function. +While the +.Xr strtok 3 +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. diff --git a/static/openbsd/man3/strsignal.3 b/static/openbsd/man3/strsignal.3 new file mode 100644 index 00000000..b46be893 --- /dev/null +++ b/static/openbsd/man3/strsignal.3 @@ -0,0 +1,78 @@ +.\" 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. +.\" +.\" $OpenBSD: strsignal.3,v 1.9 2019/05/16 13:35:16 schwarze Exp $ +.\" +.Dd $Mdocdate: May 16 2019 $ +.Dt STRSIGNAL 3 +.Os +.Sh NAME +.Nm strsignal +.Nd get signal description string +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strsignal "int sig" +.Sh DESCRIPTION +The +.Fn strsignal +function returns a pointer to the string describing the signal +.Fa sig . +.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 . +.Sh HISTORY +The +.Fn strsignal +function first appeared in +.At V.4 +and was reimplemented for +.Nx 1.0 . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_MESSAGES +.Xr locale 1 +category can cause different strings to be returned instead of the +normal signal descriptions; see CAVEATS in +.Xr setlocale 3 +for details. diff --git a/static/openbsd/man3/strspn.3 b/static/openbsd/man3/strspn.3 new file mode 100644 index 00000000..e677ba15 --- /dev/null +++ b/static/openbsd/man3/strspn.3 @@ -0,0 +1,92 @@ +.\" $OpenBSD: strspn.3,v 1.12 2024/12/11 23:28:20 jsg 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. +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt STRSPN 3 +.Os +.Sh NAME +.Nm strspn +.Nd span a string +.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 memchr 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strstr 3 , +.Xr strtok 3 , +.Xr wcsspn 3 +.Sh STANDARDS +The +.Fn strspn +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn strspn +function first appeared in +.At III +and was reimplemented for +.Bx 4.3 . diff --git a/static/openbsd/man3/strstr.3 b/static/openbsd/man3/strstr.3 new file mode 100644 index 00000000..60d2a721 --- /dev/null +++ b/static/openbsd/man3/strstr.3 @@ -0,0 +1,101 @@ +.\" $OpenBSD: strstr.3,v 1.13 2016/05/11 17:51:50 schwarze 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. +.\" +.Dd $Mdocdate: May 11 2016 $ +.Dt STRSTR 3 +.Os +.Sh NAME +.Nm strstr , strcasestr +.Nd locate a substring in a string +.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" +.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. +.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 SEE ALSO +.Xr memchr 3 , +.Xr memmem 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strtok 3 , +.Xr wcsstr 3 +.Sh STANDARDS +The +.Fn strstr +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn strstr +function first appeared in +.Bx 4.3 Reno . +The +.Fn strcasestr +function appeared in glibc 2.1, +was reimplemented for +.Fx 4.5 +and ported to +.Ox 3.8 . diff --git a/static/openbsd/man3/strtod.3 b/static/openbsd/man3/strtod.3 new file mode 100644 index 00000000..ad8f28a0 --- /dev/null +++ b/static/openbsd/man3/strtod.3 @@ -0,0 +1,176 @@ +.\" 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. +.\" +.\" $OpenBSD: strtod.3,v 1.23 2022/09/11 06:38:11 jmc Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt STRTOD 3 +.Os +.Sh NAME +.Nm strtod , +.Nm strtof , +.Nm strtold +.Nd convert ASCII string to double, float or long double +.Sh SYNOPSIS +.In stdlib.h +.Ft double +.Fn strtod "const char *nptr" "char **endptr" +.Pp +.Ft float +.Fn strtof "const char *nptr" "char **endptr" +.Pp +.Ft long double +.Fn strtold "const char *nptr" "char **endptr" +.Sh DESCRIPTION +The +.Fn strtod +function converts the initial portion of the string pointed to by +.Fa nptr +to +.Vt double +representation. +The +.Fn strtof +function converts the initial portion of the string pointed to by +.Fa nptr +to +.Vt float +representation. +The +.Fn strtold +function converts the initial portion of the string pointed to by +.Fa nptr +to +.Vt long double +representation. +.Pp +The expected form of the string is an optional plus +.Pq Ql + +or minus sign +.Pq Ql - +followed by 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. +.Pp +Alternatively, if the portion of the string following the optional +plus or minus sign begins with +.Dq INF +or +.Dq NAN , +ignoring case, it is interpreted as an infinity or a quiet \*(Na, +respectively. +The syntax +.Dq NAN Ns Pq Ar s , +where +.Ar s +is an alphanumeric string, produces the same value as the call +.Fo nan +.Qq Ar s Ns +.Fc +(respectively, +.Fo nanf +.Qq Ar s Ns +.Fc +and +.Fo nanl +.Qq Ar s Ns +.Fc ) . +.Pp +In any of the above cases, leading whitespace 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 +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 would cause overflow, plus or minus +.Dv HUGE_VAL +is returned (according to the sign of the value), and +.Er ERANGE +is stored in +.Va errno . +If the correct value would cause underflow, zero is returned and +.Er ERANGE +is stored in +.Va errno . +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ERANGE +Overflow or underflow occurred. +.El +.Sh SEE ALSO +.Xr atof 3 , +.Xr atoi 3 , +.Xr atol 3 , +.Xr strtol 3 , +.Xr strtoul 3 +.Sh STANDARDS +The +.Fn strtod +function conforms to +.St -ansiC-89 . +The +.Fn strtof +and +.Fn strtold +functions conform to +.St -isoC-99 . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_NUMERIC +.Xr locale 1 +category can cause parsing failures; see CAVEATS in +.Xr setlocale 3 +for details. diff --git a/static/openbsd/man3/strtofflags.3 b/static/openbsd/man3/strtofflags.3 new file mode 100644 index 00000000..c9e71040 --- /dev/null +++ b/static/openbsd/man3/strtofflags.3 @@ -0,0 +1,98 @@ +.\" $OpenBSD: strtofflags.3,v 1.7 2013/06/05 03:39:22 tedu 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 +.\" $FreeBSD: src/lib/libc/gen/strtofflags.3,v 1.5 2000/06/17 11:09:24 joe Exp $ +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt STRTOFFLAGS 3 +.Os +.Sh NAME +.Nm fflagstostr , +.Nm strtofflags +.Nd convert between file flag bits and their string names +.Sh SYNOPSIS +.In unistd.h +.Ft char * +.Fn fflagstostr "u_int32_t flags" +.Ft int +.Fn strtofflags "char **stringp" "u_int32_t *setp" "u_int32_t *clrp" +.Sh DESCRIPTION +The +.Fn fflagstostr +function returns a comma separated string of the file flags represented by +.Fa flags . +If no flags are set, a zero length string is returned. +.Pp +If memory cannot be allocated for the return value, +.Fn fflagstostr +returns +.Dv NULL . +.Pp +The value returned from +.Fn fflagstostr +is obtained from +.Xr malloc 3 +and should be returned to the system with +.Xr free 3 +when the program is done with it. +.Pp +The +.Fn strtofflags +function takes a string of file flags, as described in +.Xr chflags 1 , +parses it, and returns the +.Dq set +and +.Dq clear +flags such as would be given as arguments to +.Xr chflags 2 . +On success, +.Fn strtofflags +returns 0, otherwise it returns non-zero and +.Fa stringp +is left pointing to the offending token. +.Sh ERRORS +The +.Fn fflagstostr +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr malloc 3 . +.Sh SEE ALSO +.Xr chflags 1 , +.Xr chflags 2 , +.Xr malloc 3 +.Sh HISTORY +The +.Fn fflagstostr +and +.Fn strtofflags +functions first appeared in +.Ox 2.8 . diff --git a/static/openbsd/man3/strtok.3 b/static/openbsd/man3/strtok.3 new file mode 100644 index 00000000..a28f72d6 --- /dev/null +++ b/static/openbsd/man3/strtok.3 @@ -0,0 +1,169 @@ +.\" $OpenBSD: strtok.3,v 1.24 2024/12/11 23:28:20 jsg Exp $ +.\" +.\" Copyright (c) 1988, 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. +.\" +.Dd $Mdocdate: December 11 2024 $ +.Dt STRTOK 3 +.Os +.Sh NAME +.Nm strtok , +.Nm strtok_r +.Nd string token operations +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strtok "char *str" "const char *sep" +.Ft char * +.Fn strtok_r "char *str" "const char *sep" "char **last" +.Sh DESCRIPTION +.Bf -symbolic +This interface is obsoleted by +.Xr strsep 3 . +.Ef +.Pp +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_r +function is a version of +.Fn strtok +that takes an explicit context argument and is reentrant. +.Pp +Since +.Fn strtok +and +.Fn strtok_r +modify the string, +.Fa str +should not point to an area in the initialized data segment. +.Sh RETURN VALUES +The +.Fn strtok +and +.Fn strtok_r +functions return a pointer to the beginning of each subsequent token +in the string, after replacing the separator character itself with +a NUL character. +When no more tokens remain, a null pointer is returned. +.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]; +char *last; +int i = 0; + +snprintf(s, sizeof(s), "cat dog horse cow"); + +for ((p = strtok_r(s, " ", &last)); p; + (p = strtok_r(NULL, " ", &last))) { + if (i < MAXTOKENS - 1) + 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 . +.Sh SEE ALSO +.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 wcstok 3 +.Sh STANDARDS +The +.Fn strtok +function conforms to +.St -ansiC . +The +.Fn strtok_r +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn strtok +function first appeared in +.At III +and was reimplemented for +.Bx 4.3 . +The +.Fn strtok_r +function first appeared in +.Nx 1.3 +and was reimplemented for +.Ox 2.7 . +.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 non-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/openbsd/man3/strtol.3 b/static/openbsd/man3/strtol.3 new file mode 100644 index 00000000..92774d08 --- /dev/null +++ b/static/openbsd/man3/strtol.3 @@ -0,0 +1,273 @@ +.\" 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. +.\" +.\" $OpenBSD: strtol.3,v 1.27 2015/04/14 22:16:03 nicm Exp $ +.\" +.Dd $Mdocdate: April 14 2015 $ +.Dt STRTOL 3 +.Os +.Sh NAME +.Nm strtol , +.Nm strtoll , +.Nm strtoimax , +.Nm strtoq +.Nd convert string value to a long, long long or intmax_t integer +.Sh SYNOPSIS +.In limits.h +.In stdlib.h +.Ft long +.Fn strtol "const char *nptr" "char **endptr" "int base" +.Ft long long +.Fn strtoll "const char *nptr" "char **endptr" "int base" +.In inttypes.h +.Ft intmax_t +.Fn strtoimax "const char *nptr" "char **endptr" "int base" +.In sys/types.h +.In limits.h +.In stdlib.h +.Ft quad_t +.Fn strtoq "const char *nptr" "char **endptr" "int base" +.Sh DESCRIPTION +The +.Fn strtol +function converts the string in +.Fa nptr +to a +.Vt long +value. +The +.Fn strtoll +function converts the string in +.Fa nptr +to a +.Vt long long +value. +The +.Fn strtoimax +function converts the string in +.Fa nptr +to an +.Vt intmax_t +value. +The +.Fn strtoq +function is a deprecated equivalent of +.Fn strtoll +and is provided for backwards compatibility with legacy programs. +The conversion is done according to the given +.Fa base , +which must be a number between 2 and 36 inclusive or the special value 0. +.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. +If +.Fa base +is zero or 16, the string may then include a +.Ql 0x +prefix, and the number will be read in base 16; 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 a +.Vt long , +.Vt long long , +or +.Vt intmax_t +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-null, +.Fn strtol +stores the address of the first invalid character in +.Fa *endptr . +If there were no digits at all, however, +.Fn strtol +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.) +.Sh RETURN VALUES +The +.Fn strtol , +.Fn strtoll , +.Fn strtoimax , +and +.Fn strtoq +functions return the result of the conversion. +If overflow or underflow occurs, +.Va errno +is set to +.Er ERANGE +and the function return value is as follows: +.Bl -column "strtoimaxXX" "INTMAX_MIN" "INTMAX_MAX" -offset indent +.It Sy Function Ta Sy underflow Ta Sy overflow +.It Fn strtol Ta Dv LONG_MIN Ta Dv LONG_MAX +.It Fn strtoll Ta Dv LLONG_MIN Ta Dv LLONG_MAX +.It Fn strtoimax Ta Dv INTMAX_MIN Ta Dv INTMAX_MAX +.It Fn strtoq Ta Dv LLONG_MIN Ta Dv LLONG_MAX +.El +.Pp +If there is no valid digit, 0 is returned. +If +.Ar base +is invalid, 0 is returned and the global variable +.Va errno +is set to +.Er EINVAL . +.Sh EXAMPLES +Ensuring that a string is a valid number (i.e., in range and containing no +trailing characters) requires clearing +.Va errno +beforehand explicitly since +.Va errno +is not changed on a successful call to +.Fn strtol , +and the return value of +.Fn strtol +cannot be used unambiguously to signal an error: +.Bd -literal -offset indent +char *ep; +long lval; + +\&... + +errno = 0; +lval = strtol(buf, &ep, 10); +if (buf[0] == '\e0' || *ep != '\e0') + goto not_a_number; +if (errno == ERANGE && (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 +.Vt int +rather than a +.Vt 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 (buf[0] == '\e0' || *ep != '\e0') + goto not_a_number; +if ((errno == ERANGE && (lval == LONG_MAX || lval == LONG_MIN)) || + (lval > INT_MAX || lval < INT_MIN)) + goto out_of_range; +ival = lval; +.Ed +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The value of +.Ar base +was neither between 2 and 36 inclusive nor 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 sscanf 3 , +.Xr strtod 3 , +.Xr strtonum 3 , +.Xr strtoul 3 +.Sh STANDARDS +The +.Fn strtol , +.Fn strtoll , +and +.Fn strtoimax +functions conform to +.St -isoC-99 . +Setting +.Va errno +to +.Dv EINVAL +is an extension to that standard required by +.St -p1003.1-2008 . +.Pp +The +.Fn strtoq +function is a +.Bx +extension and is provided for backwards compatibility with legacy programs. +.Sh BUGS +Ignores the current locale. diff --git a/static/openbsd/man3/strtonum.3 b/static/openbsd/man3/strtonum.3 new file mode 100644 index 00000000..87a3ccd5 --- /dev/null +++ b/static/openbsd/man3/strtonum.3 @@ -0,0 +1,152 @@ +.\" $OpenBSD: strtonum.3,v 1.19 2022/09/11 06:38:11 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 $Mdocdate: September 11 2022 $ +.Dt STRTONUM 3 +.Os +.Sh NAME +.Nm strtonum +.Nd reliably convert string value to an integer +.Sh SYNOPSIS +.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 +.Vt long long +value. +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. +.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 +.Vt 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 != NULL) + 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 ERANGE +The given string was out of range. +.It Bq Er EINVAL +The given string did not consist solely of digit characters. +.It Bq Er EINVAL +.Ar minval +was larger than +.Ar maxval . +.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 strtol 3 , +.Xr strtoul 3 +.Sh STANDARDS +.Fn strtonum +is an +.Ox +extension. +The existing alternatives, such as +.Xr atoi 3 +and +.Xr strtol 3 , +are either impossible or difficult to use safely. +.Sh HISTORY +The +.Fn strtonum +function first appeared in +.Ox 3.6 . diff --git a/static/openbsd/man3/strtoul.3 b/static/openbsd/man3/strtoul.3 new file mode 100644 index 00000000..dd5668d1 --- /dev/null +++ b/static/openbsd/man3/strtoul.3 @@ -0,0 +1,260 @@ +.\" 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. +.\" +.\" $OpenBSD: strtoul.3,v 1.24 2014/11/30 21:21:59 schwarze Exp $ +.\" +.Dd $Mdocdate: November 30 2014 $ +.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 or uintmax_t integer +.Sh SYNOPSIS +.In limits.h +.In stdlib.h +.Ft unsigned long +.Fn strtoul "const char *nptr" "char **endptr" "int base" +.Ft unsigned long long +.Fn strtoull "const char *nptr" "char **endptr" "int base" +.In inttypes.h +.Ft uintmax_t +.Fn strtoumax "const char *nptr" "char **endptr" "int base" +.In sys/types.h +.In limits.h +.In stdlib.h +.Ft u_quad_t +.Fn strtouq "const char *nptr" "char **endptr" "int base" +.Sh DESCRIPTION +The +.Fn strtoul +function converts the string in +.Fa nptr +to an +.Vt unsigned long +value. +The +.Fn strtoull +function converts the string in +.Fa nptr +to an +.Vt unsigned long long +value. +The +.Fn strtoumax +function converts the string in +.Fa nptr +to a +.Vt umaxint_t +value. +The +.Fn strtouq +function is a deprecated equivalent of +.Fn strtoull +and is provided for backwards compatibility with legacy programs. +The conversion is done according to the given +.Fa base , +which must be a number between 2 and 36 inclusive or the special value 0. +If the string in +.Fa nptr +represents a negative number, it will be converted to its unsigned equivalent. +This behavior is consistent with what happens when a signed integer type is +cast to its unsigned counterpart. +.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. +If +.Fa base +is zero or 16, the string may then include a +.Ql 0x +prefix, and the number will be read in base 16; 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 +.Vt unsigned long , +.Vt unsigned long long , +or +.Vt uintmax_t +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-null, +.Fn strtoul +stores the address of the first invalid character in +.Fa *endptr . +If there were no digits at all, however, +.Fn strtoul +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.) +.Sh RETURN VALUES +The +.Fn strtoul , +.Fn strtoull , +.Fn strtoumax +and +.Fn strtouq +functions return 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. +If overflow occurs, +.Fn strtoul +returns +.Dv ULONG_MAX , +.Fn strtoull +returns +.Dv ULLONG_MAX , +.Fn strtoumax +returns +.Dv UINTMAX_MAX , +.Fn strtouq +returns +.Dv ULLONG_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. +.Pp +If there is no valid digit, 0 is returned. +If +.Ar base +is invalid, 0 is returned and the global variable +.Va errno +is set to +.Er EINVAL . +.Sh EXAMPLES +Ensuring that a string is a valid number (i.e., in range and containing no +trailing characters) requires clearing +.Va errno +beforehand explicitly since +.Va errno +is not changed on a successful call to +.Fn strtoul , +and the return value of +.Fn strtoul +cannot be used unambiguously to signal an error: +.Bd -literal -offset indent +char *ep; +unsigned long ulval; + +\&... + +errno = 0; +ulval = strtoul(buf, &ep, 10); +if (buf[0] == '\e0' || *ep != '\e0') + goto not_a_number; +if (errno == ERANGE && 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 value of +.Ar base +was neither between 2 and 36 inclusive nor 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 sscanf 3 , +.Xr strtol 3 +.Sh STANDARDS +The +.Fn strtoul , +.Fn strtoull , +and +.Fn strtoumax +functions conform to +.St -isoC-99 . +Setting +.Va errno +to +.Dv EINVAL +is an extension to that standard required by +.St -p1003.1-2008 . +.Pp +The +.Fn strtouq +function is a +.Bx +extension and is provided for backwards compatibility with legacy programs. +.Sh BUGS +Ignores the current locale. diff --git a/static/openbsd/man3/strxfrm.3 b/static/openbsd/man3/strxfrm.3 new file mode 100644 index 00000000..dab3673f --- /dev/null +++ b/static/openbsd/man3/strxfrm.3 @@ -0,0 +1,105 @@ +.\" $OpenBSD: strxfrm.3,v 1.12 2019/01/18 07:43:36 schwarze Exp $ +.\" +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: January 18 2019 $ +.Dt STRXFRM 3 +.Os +.Sh NAME +.Nm strxfrm , +.Nm strxfrm_l +.Nd transform a string under locale +.Sh SYNOPSIS +.In string.h +.Ft size_t +.Fn strxfrm "char *dst" "const char *src" "size_t n" +.Ft size_t +.Fn strxfrm_l "char *dst" "const char *src" "size_t n" "locale_t locale" +.Sh DESCRIPTION +The idea of +.Fn strxfrm +and +.Fn strxfrm_l +is to +.Dq un-localize +a string: the functions transform +.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. +.Pp +On +.Ox , +both have the same effect as +.Xr strlcpy 3 , +and the global locale, the thread-specific locale, and the +.Fa locale +argument are ignored. +On other operating systems, the behaviour may depend on the +.Dv LC_CTYPE +and +.Dv LC_COLLATE +locale categories set with +.Xr setlocale 3 , +.Xr uselocale 3 , +or +.Xr newlocale 3 . +.Sh SEE ALSO +.Xr newlocale 3 , +.Xr setlocale 3 , +.Xr strcmp 3 , +.Xr strcoll 3 , +.Xr strlcpy 3 , +.Xr wcsxfrm 3 +.Sh STANDARDS +The +.Fn strxfrm +function conforms to +.St -ansiC , +and +.Fn strxfrm_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn strxfrm +function has been available since +.Bx 4.3 Reno , +and +.Fn strxfrm_l +since +.Ox 6.2 . diff --git a/static/openbsd/man3/swab.3 b/static/openbsd/man3/swab.3 new file mode 100644 index 00000000..777f2833 --- /dev/null +++ b/static/openbsd/man3/swab.3 @@ -0,0 +1,79 @@ +.\" 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. +.\" +.\" $OpenBSD: swab.3,v 1.10 2022/09/28 20:27:12 jmc Exp $ +.\" +.Dd $Mdocdate: September 28 2022 $ +.Dt SWAB 3 +.Os +.Sh NAME +.Nm swab +.Nd swap adjacent bytes +.Sh SYNOPSIS +.In unistd.h +.Ft void +.Fo swab +.Fa "const void *restrict src" +.Fa "void *restrict dst" +.Fa "ssize_t len" +.Fc +.Sh DESCRIPTION +The +.Fn swab +function 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 zero or less, +.Fn swab +does nothing. +If it is odd, what happens to the last byte is unspecified. +If +.Fa src +and +.Fa dst +overlap, behaviour is undefined. +.Sh SEE ALSO +.Xr bzero 3 , +.Xr memset 3 +.Sh STANDARDS +The +.Fn swab +function is compliant with the X/Open System Interfaces option of the +.St -p1003.1-2008 +specification. +.Sh HISTORY +The +.Fn swab +function first appeared in +.At v7 . diff --git a/static/openbsd/man3/sysconf.3 b/static/openbsd/man3/sysconf.3 new file mode 100644 index 00000000..b5d06e78 --- /dev/null +++ b/static/openbsd/man3/sysconf.3 @@ -0,0 +1,222 @@ +.\" $OpenBSD: sysconf.3,v 1.35 2019/08/11 15:48:08 deraadt 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. +.\" +.Dd $Mdocdate: August 11 2019 $ +.Dt SYSCONF 3 +.Os +.Sh NAME +.Nm sysconf +.Nd get configurable system variables +.Sh SYNOPSIS +.In unistd.h +.Ft long +.Fn sysconf "int name" +.Sh DESCRIPTION +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 "123456" +.It Li _SC_ARG_MAX +The maximum bytes of arguments to +.Xr execve 2 +(including the environment). +.It Li _SC_CHILD_MAX +The maximum number of simultaneous processes per user ID. +.It Li _SC_CLK_TCK +The number of clock ticks per second. +.It Li _SC_NGROUPS_MAX +The maximum number of supplemental groups. +.It Li _SC_OPEN_MAX +The maximum number of open files per user ID. +.It Li _SC_STREAM_MAX +The minimum maximum number of streams that a process may have open +at any one time. +.It Li _SC_TZNAME_MAX +The minimum maximum number of types supported for the name of a +time zone. +.It Li _SC_JOB_CONTROL +Returns 1 if job control is available on this system, otherwise \-1. +.It Li _SC_SAVED_IDS +Returns 1 if saved set-group-ID and saved set-user-ID is available, +otherwise \-1. +.It Li _SC_VERSION +The version of ISO/IEC 9945 (POSIX 1003.1) with which the system +attempts to comply. +.It Li _SC_BC_BASE_MAX +The maximum ibase/obase values in the +.Xr bc 1 +utility. +.It Li _SC_BC_DIM_MAX +The maximum array size in the +.Xr bc 1 +utility. +.It Li _SC_BC_SCALE_MAX +The maximum scale value in the +.Xr bc 1 +utility. +.It Li _SC_BC_STRING_MAX +The maximum string length in the +.Xr bc 1 +utility. +.It Li _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 Li _SC_EXPR_NEST_MAX +The maximum number of expressions that can be nested within +parentheses by the +.Xr expr 1 +utility. +.It Li _SC_LINE_MAX +The maximum length in bytes of a text-processing utility's input +line. +.It Li _SC_RE_DUP_MAX +The maximum number of repeated occurrences of a regular expression +permitted when using interval notation. +.It Li _SC_2_VERSION +The version of POSIX 1003.2 with which the system attempts to comply. +.It Li _SC_2_C_BIND +Return 1 if the system's C-language development facilities support the +C-Language Bindings Option, otherwise \-1. +.It Li _SC_2_C_DEV +Return 1 if the system supports the C-Language Development Utilities Option, +otherwise \-1. +.It Li _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 Li _SC_2_FORT_DEV +Return 1 if the system supports the FORTRAN Development Utilities Option, +otherwise \-1. +.It Li _SC_2_FORT_RUN +Return 1 if the system supports the FORTRAN Runtime Utilities Option, +otherwise \-1. +.It Li _SC_2_LOCALEDEF +Return 1 if the system supports the creation of locales, otherwise \-1. +.It Li _SC_2_SW_DEV +Return 1 if the system supports the Software Development Utilities Option, +otherwise \-1. +.It Li _SC_2_UPE +Return 1 if the system supports the User Portability Utilities Option, +otherwise \-1. +.It Li _SC_PAGESIZE +The size of a system page in bytes. +.It Li _SC_FSYNC +Return 1 if the system supports the File Synchronisation Option, otherwise \-1. +.It Li _SC_XOPEN_SHM +Return 1 if the system supports the Shared Memory Option, otherwise \-1. +.It Li _SC_SEM_NSEMS_MAX +The maximum number of semaphores in the system or \-1 if the system +does not support the Semaphores Option. +.It Li _SC_SEM_VALUE_MAX +The maximum value a semaphore may have or \-1 if the system +does not support the Semaphores Option. +.It Li _SC_PHYS_PAGES +The number of pages of physical memory. +.It Li _SC_AVPHYS_PAGES +The number of pages of physical memory not currently in use by the system. +.It Li _SC_GETGR_R_SIZE_MAX +The maximum size of the data buffer for the +.Fn getgrgid_r +and +.Fn getgrnam_r +functions. +.It Li _SC_GETPW_R_SIZE_MAX +The maximum size of the data buffer for the +.Fn getpwuid_r +and +.Fn getpwnam_r +functions. +.It Li _SC_LOGIN_NAME_MAX +The maximum length of a login name. +.It Li _SC_THREAD_SAFE_FUNCTIONS +The level of support for thread-safe (re-entrant) functions. +.It Li _SC_NPROCESSORS_CONF +The number of processors configured. +.It Li _SC_NPROCESSORS_ONLN +The number of processors online (capable of running processes). +.It Li _SC_HOST_NAME_MAX +The maximum size of a hostname, not counting NULL. +.It Li _SC_MONOTONIC_CLOCK +Return the POSIX version of the implementation of the Monotonic Clock +option that this system conforms to, or \-1 if unavailable. +.El +.Sh RETURN VALUES +If the call to +.Fn 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 function +.Xr sysctl 2 . +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 pathconf 2 , +.Xr sysctl 2 +.Sh STANDARDS +The +.Fn sysconf +function conforms to +.St -p1003.1-88 . +The constants +.Li _SC_NPROCESSORS_CONF +and +.Li _SC_NPROCESSORS_ONLN +are not part of the standard, but are provided by many systems. +.Sh HISTORY +The +.Fn sysconf +function first appeared in +.Bx 4.4 . +.Sh BUGS +The value for _SC_STREAM_MAX is a minimum maximum, and required to be +the same as ANSI C's FOPEN_MAX, so the returned value is a ridiculously +small and misleading number. diff --git a/static/openbsd/man3/syslog.3 b/static/openbsd/man3/syslog.3 new file mode 100644 index 00000000..ab411f3a --- /dev/null +++ b/static/openbsd/man3/syslog.3 @@ -0,0 +1,423 @@ +.\" $OpenBSD: syslog.3,v 1.38 2024/06/11 23:35:27 jsg 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. +.\" +.Dd $Mdocdate: June 11 2024 $ +.Dt SYSLOG 3 +.Os +.Sh NAME +.Nm syslog , +.Nm syslog_r , +.Nm vsyslog , +.Nm vsyslog_r , +.Nm openlog , +.Nm openlog_r , +.Nm closelog , +.Nm closelog_r , +.Nm setlogmask , +.Nm setlogmask_r +.Nd control system log +.Sh SYNOPSIS +.In syslog.h +.In stdarg.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 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 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" +.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. +.Pp +The +.Fn syslog_r +function is a reentrant 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. +.Pp +The +.Fn vsyslog +function is an alternate form in which the arguments have already been captured +using the variable-length argument facilities of +.Xr va_start 3 . +.Pp +The message is tagged with +.Fa priority . +Priorities are encoded as a +.Fa facility +and a +.Fa level . +The +.Fa facility +describes the part of the system +generating the message: +.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 dhcpd 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 +.Fa level +(ORed with the +.Fa facility ) +is selected from the following list, ordered by decreasing importance: +.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 +function is used the same way as +.Fn vsyslog +except that it takes an additional pointer to a +.Fa syslog_data +structure. +It is a reentrant version of the +.Fn vsyslog +function described above. +.Pp +The +.Fn openlog +function provides for more specialized processing of the messages sent by +.Fn syslog +and +.Fn vsyslog . +The parameter +.Fa ident +points to a string that will be prepended to every message; +its storage must persist until +.Fn closelog +or the corresponding +.Fn closelog_r . +If the content of the string is changed, behaviour is unspecified. +.Pp +The +.Fa logopt +argument +is a bit field specifying logging options, which is formed by OR'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 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. +This option must be used in programs that call +.Xr chroot 2 +where the new root does not have its own log socket. +.It Dv LOG_ODELAY +Delay opening the connection to +.Xr syslogd 8 +until the first message is logged. +This is the opposite of +.Dv LOG_NDELAY +and is the default behaviour when neither option is specified. +.It Dv LOG_PERROR +Write the message to standard error output as well as to the system log. +.It Dv LOG_PID +Log the process ID with each message; useful for identifying +instantiations of daemons. +.El +.Pp +The +.Fa facility +parameter encodes a default facility to be assigned to all messages +that do not have an explicit facility encoded. +.Pp +The +.Fn openlog_r +function is the reentrant 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 +reentrant functions. +.Pp +The +.Fn closelog +function can be used to close the log file. +.Fn closelog_r +does the same thing but in a reentrant 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, which +corresponds to +.Li setlogmask(LOG_UPTO(LOG_DEBUG)) . +.Pp +The +.Fn setlogmask_r +function is the reentrant version of +.Fn setlogmask . +It takes an additional pointer to a +.Fa syslog_data +structure. +.Sh RETURN VALUES +The routines +.Fn setlogmask +and +.Fn setlogmask_r +always return the previous log mask level. +.Sh EXAMPLES +.Bd -literal -offset indent +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"); +.Ed +.Pp +For the reentrant 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 +.Sh STANDARDS +The functions +.Fn syslog , +.Fn openlog , +.Fn closelog , +and +.Fn setlogmask +conform to the X/Open Systems Interfaces option of +.St -p1003.1-2008 . +.Pp +The facilities +.Dv LOG_AUTHPRIV , +.Dv LOG_FTP , +and +.Dv LOG_SYSLOG , +the option +.Dv LOG_PERROR , +and the macro +.Fn LOG_UPTO +are extensions to that standard. +.Pp +The standard option +.Dv LOG_NOWAIT +is deprecated in +.Ox +and has no effect. +.Sh HISTORY +The functions +.Fn syslog , +.Fn openlog , +and +.Fn closelog +appeared in +.Bx 4.2 , +.Fn setlogmask +in +.Bx 4.3 , +and +.Fn vsyslog +in +.Bx 4.3 Net/1 . +.Pp +The functions +.Fn syslog_r , +.Fn vsyslog_r , +.Fn openlog_r , +.Fn closelog_r , +and +.Fn setlogmask_r +appeared in +.Ox 3.1 . +.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 the stack, +leading to a possible security hole. +This holds true even if the string has been built +.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 +.Fn syslog_r +and the other reentrant functions should only be used where +reentrancy is required (for instance, in a signal handler). +.Fn syslog +being not reentrant, only +.Fn syslog_r +should be used here. +For more information about reentrancy and signal handlers, see +.Xr signal 3 . diff --git a/static/openbsd/man3/system.3 b/static/openbsd/man3/system.3 new file mode 100644 index 00000000..bdd94c01 --- /dev/null +++ b/static/openbsd/man3/system.3 @@ -0,0 +1,116 @@ +.\" 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. +.\" +.\" $OpenBSD: system.3,v 1.14 2016/02/05 18:09:19 espie Exp $ +.\" +.Dd $Mdocdate: February 5 2016 $ +.Dt SYSTEM 3 +.Os +.Sh NAME +.Nm system +.Nd pass a command to the shell +.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 +.Dv NULL , +.Fn system +will return non-zero. +Otherwise, +.Fn system +returns the termination status of the shell in the format specified by +.Xr waitpid 2 . +.Pp +Note that fork handlers established using +.Xr pthread_atfork 3 +are not called when a multithreaded program calls +.Fn system . +.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 +.Sh STANDARDS +The +.Fn system +function conforms to +.St -ansiC +and +.St -p1003.2-92 . +.Sh HISTORY +The +.Fn system +function first appeared in +.At v6 . +.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. +.Pp +It is often simpler to bypass the shell and run an external command using +.Xr fork 2 , +.Xr execlp 3 , +and +.Xr waitpid 2 +directly instead of having to sanitize a string for shell consumption. diff --git a/static/openbsd/man3/tan.3 b/static/openbsd/man3/tan.3 new file mode 100644 index 00000000..91800e08 --- /dev/null +++ b/static/openbsd/man3/tan.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: tan.3,v 1.13 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt TAN 3 +.Os +.Sh NAME +.Nm tan , +.Nm tanf , +.Nm tanl +.Nd tangent functions +.Sh SYNOPSIS +.Lb libm +.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 +function computes the tangent of +.Fa x +(measured in radians). +The +.Fn tanf +function is a single precision version of +.Fn tan . +The +.Fn tanl +function is an extended precision version of +.Fn tan . +A large magnitude argument may yield a result +with little or no significance. +.Sh RETURN VALUES +The +.Fn tan , +.Fn tanf +and +.Fn tanl +functions return 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 sin 3 , +.Xr sinh 3 , +.Xr tanh 3 +.Sh STANDARDS +The +.Fn tan +function conforms to +.St -ansiC . diff --git a/static/openbsd/man3/tanh.3 b/static/openbsd/man3/tanh.3 new file mode 100644 index 00000000..e2d2cb8f --- /dev/null +++ b/static/openbsd/man3/tanh.3 @@ -0,0 +1,87 @@ +.\" $OpenBSD: tanh.3,v 1.14 2025/06/07 10:33:06 schwarze Exp $ +.\" 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 +.\" +.Dd $Mdocdate: June 7 2025 $ +.Dt TANH 3 +.Os +.Sh NAME +.Nm tanh , +.Nm tanhf , +.Nm tanhl +.Nd hyperbolic tangent functions +.Sh SYNOPSIS +.Lb libm +.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 +function computes the hyperbolic tangent of +.Fa x . +The +.Fn tanhf +function is a single precision version of +.Fn tanh . +The +.Fn tanhl +function is an extended precision version of +.Fn tanh . +.Sh RETURN VALUES +The +.Fn tanh , +.Fn tanhf , +and +.Fn tanhl +functions return the hyperbolic tangent value. +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 +.Sh STANDARDS +The +.Fn tanh +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn tanh +function first appeared in +.At v7 . diff --git a/static/openbsd/man3/tcgetpgrp.3 b/static/openbsd/man3/tcgetpgrp.3 new file mode 100644 index 00000000..befba1a4 --- /dev/null +++ b/static/openbsd/man3/tcgetpgrp.3 @@ -0,0 +1,74 @@ +.\" $OpenBSD: tcgetpgrp.3,v 1.11 2023/01/12 12:56:07 jsg Exp $ +.\" +.\" 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. +.\" +.Dd $Mdocdate: January 12 2023 $ +.Dt TCGETPGRP 3 +.Os +.Sh NAME +.Nm tcgetpgrp +.Nd get foreground process group ID +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn tcgetpgrp "int fd" +.Sh DESCRIPTION +The +.Fn 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, +.Fn tcgetpgrp +returns an invalid process ID. +.Sh ERRORS +If an error occurs, +.Fn 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 +.Fn tcgetpgrp +function is compliant with the +.St -p1003.1-88 +specification. diff --git a/static/openbsd/man3/tcgetsid.3 b/static/openbsd/man3/tcgetsid.3 new file mode 100644 index 00000000..40f2f0bd --- /dev/null +++ b/static/openbsd/man3/tcgetsid.3 @@ -0,0 +1,77 @@ +.\" $OpenBSD: tcgetsid.3,v 1.3 2023/01/12 12:56:07 jsg Exp $ +.\" +.\" 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. +.\" +.Dd $Mdocdate: January 12 2023 $ +.Dt TCGETSID 3 +.Os +.Sh NAME +.Nm tcgetsid +.Nd get session ID associated with a controlling terminal +.Sh SYNOPSIS +.In termios.h +.Ft pid_t +.Fn tcgetsid "int fd" +.Sh DESCRIPTION +The +.Fn 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, +.Fn 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 +.Fn tcgetsid +function is compliant with the +.St -p1003.1-2008 +specification. +.Sh HISTORY +The +.Fn tcgetsid +function has been available since +.Ox 5.5 . diff --git a/static/openbsd/man3/tcsendbreak.3 b/static/openbsd/man3/tcsendbreak.3 new file mode 100644 index 00000000..4dbaceae --- /dev/null +++ b/static/openbsd/man3/tcsendbreak.3 @@ -0,0 +1,153 @@ +.\" $OpenBSD: tcsendbreak.3,v 1.10 2023/01/12 12:56:07 jsg Exp $ +.\" +.\" 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. +.\" +.Dd $Mdocdate: January 12 2023 $ +.Dt TCSENDBREAK 3 +.Os +.Sh NAME +.Nm tcdrain , +.Nm tcflow , +.Nm tcflush , +.Nm tcsendbreak +.Nd line control functions +.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 +.Fn tcdrain +function waits until all output written to the terminal referenced by +.Fa fd +has been transmitted to the terminal. +.Pp +The +.Fn 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 Dv TCOOFF +Suspend output. +.It Dv TCOON +Restart suspended output. +.It Dv TCIOFF +Transmit a STOP character, which is intended to cause the terminal to stop +transmitting data to the system. +(See the description of +.Dv IXOFF +in the +.Ql Input Modes +section of +.Xr termios 4 ) . +.It Dv TCION +Transmit a START character, which is intended to cause the terminal to start +transmitting data to the system. +(See the description of +.Dv IXOFF in the +.Ql Input Modes +section of +.Xr termios 4 ) . +.El +.Pp +The +.Fn 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 Dv TCIFLUSH +Flush data received but not read. +.It Dv TCOFLUSH +Flush data written but not transmitted. +.It Dv TCIOFLUSH +Flush both data received but not read and data written but not transmitted. +.El +.Pp +The +.Fn 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 +.Fn tcdrain +function. +.El +.Sh SEE ALSO +.Xr tcsetattr 3 , +.Xr termios 4 +.Sh STANDARDS +The +.Fn tcdrain , +.Fn tcflow , +.Fn tcflush , +and +.Fn tcsendbreak +functions are compliant with the +.St -p1003.1-88 +specification. diff --git a/static/openbsd/man3/tcsetattr.3 b/static/openbsd/man3/tcsetattr.3 new file mode 100644 index 00000000..d53d3949 --- /dev/null +++ b/static/openbsd/man3/tcsetattr.3 @@ -0,0 +1,361 @@ +.\" $OpenBSD: tcsetattr.3,v 1.19 2023/01/12 12:56:07 jsg Exp $ +.\" +.\" 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. +.\" +.Dd $Mdocdate: January 12 2023 $ +.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 SYNOPSIS +.In termios.h +.Ft speed_t +.Fn cfgetispeed "const struct termios *tp" +.Ft int +.Fn cfsetispeed "struct termios *tp" "speed_t speed" +.Ft speed_t +.Fn cfgetospeed "const struct termios *tp" +.Ft int +.Fn cfsetospeed "struct termios *tp" "speed_t speed" +.Ft int +.Fn cfsetspeed "struct termios *tp" "speed_t speed" +.Ft void +.Fn cfmakeraw "struct termios *tp" +.Ft int +.Fn tcgetattr "int fd" "struct termios *tp" +.Ft int +.Fn tcsetattr "int fd" "int action" "const struct termios *tp" +.Sh DESCRIPTION +The +.Fn cfmakeraw , +.Fn tcgetattr , +and +.Fn tcsetattr +functions are provided for getting and setting the +.Vt termios +structure. +.Pp +The +.Fn cfgetispeed , +.Fn cfsetispeed , +.Fn cfgetospeed , +.Fn cfsetospeed , +and +.Fn cfsetspeed +functions are provided for getting and setting the baud rate values in +the +.Vt termios +structure. +The effects of the functions on the terminal as described below +do not become effective, nor are all errors detected, until the +.Fn tcsetattr +function is called. +Certain values for baud rates set in the +.Vt termios +structure and passed to +.Fn tcsetattr +have special meanings. +These are discussed in the portion of the manual page that describes the +.Fn tcsetattr +function. +.Sh GETTING AND SETTING THE BAUD RATE +The input and output baud rates are found in the +.Vt termios +structure. +The unsigned integer +.Vt speed_t +is typedef'd in the include file +.In termios.h . +On +.Ox , +the value of the integer corresponds directly to the baud rate being +represented. +However, this is not true of all systems and new code should use the +symbolic value for maximum portability. +.Bd -literal -offset indent +#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 +.Fn cfgetispeed +function returns the input baud rate in the +.Vt termios +structure referenced by +.Fa tp . +.Pp +The +.Fn cfsetispeed +function sets the input baud rate in the +.Vt termios +structure referenced by +.Fa tp +to +.Fa speed . +.Pp +The +.Fn cfgetospeed +function returns the output baud rate in the +.Vt termios +structure referenced by +.Fa tp . +.Pp +The +.Fn cfsetospeed +function sets the output baud rate in the +.Vt termios +structure referenced by +.Fa tp +to +.Fa speed . +.Pp +The +.Fn cfsetspeed +function sets both the input and output baud rate in the +.Vt termios +structure referenced by +.Fa tp +to +.Fa speed . +.Pp +Upon successful completion, the functions +.Fn cfsetispeed , +.Fn cfsetospeed , +and +.Fn 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 +.Dv SIGTTOU +signal. +If the calling process is blocking or ignoring +.Dv SIGTTOU +signals, the process +is allowed to perform the operation and the +.Dv 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 +.Fn cfmakeraw +function sets the flags stored in the +.Vt termios +structure 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 +.Fn tcgetattr , +setting raw mode with +.Fn cfmakeraw +and the subsequent +.Fn tcsetattr , +and then using another +.Fn tcsetattr +with the saved state to revert to the previous terminal state. +.Pp +The +.Fn tcgetattr +function copies the parameters associated with the terminal referenced +by +.Fa fd +in the +.Vt termios +structure referenced by +.Fa tp . +This function is allowed from a background process, although the terminal +attributes may be subsequently changed by a foreground process. +.Pp +The +.Fn tcsetattr +function sets the parameters associated with the terminal from the +.Vt termios +structure referenced by +.Fa tp . +The +.Fa action +field is created by +.Tn OR Ns 'ing +the following values, as specified in the include file +.In termios.h . +.Bl -tag -width "TCSADRAIN" +.It Dv TCSANOW +The change occurs immediately. +.It Dv 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 Dv 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 Dv TCSASOFT +If this value is +.Tn OR Ns 'ed +into the +.Fa action +value, the values of the +.Fa c_cflag , +.Fa c_ispeed , +and +.Fa 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 +.Fn 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 +.Fn tcsetattr , +the input baud rate will be set to the same value as that specified by +the output baud rate. +.Sh RETURN VALUES +If +.Fn tcsetattr +is unable to make any of the requested changes, it returns \-1 and +sets +.Va 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. +.Sh ERRORS +Upon successful completion, the functions +.Fn tcgetattr +and +.Fn 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 +.Fn tcgetattr +or +.Fn tcsetattr +was not a valid file descriptor. +.It Bq Er EINTR +The +.Fn tcsetattr +function was interrupted by a signal. +.It Bq Er EINVAL +The +.Fa action +argument to the +.Fn tcsetattr +function was not valid, or an attempt was made to change an attribute +represented in the +.Vt termios +structure to an unsupported value. +.It Bq Er ENOTTY +The file associated with the +.Fa fd +argument to +.Fn tcgetattr +or +.Fn tcsetattr +is not a terminal. +.El +.Sh SEE ALSO +.Xr tcsendbreak 3 , +.Xr termios 4 +.Sh STANDARDS +The +.Fn cfgetispeed , +.Fn cfsetispeed , +.Fn cfgetospeed , +.Fn cfsetospeed , +.Fn tcgetattr , +and +.Fn tcsetattr +functions are compliant with the +.St -p1003.1-88 +specification. +The +.Fn cfmakeraw +and +.Fn cfsetspeed +functions, +as well as the +.Dv TCSASOFT +option to the +.Fn tcsetattr +function are extensions to the +.St -p1003.1-88 +specification. diff --git a/static/openbsd/man3/tcsetpgrp.3 b/static/openbsd/man3/tcsetpgrp.3 new file mode 100644 index 00000000..5502e934 --- /dev/null +++ b/static/openbsd/man3/tcsetpgrp.3 @@ -0,0 +1,109 @@ +.\" $OpenBSD: tcsetpgrp.3,v 1.15 2023/01/12 12:56:07 jsg Exp $ +.\" +.\" 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. +.\" +.Dd $Mdocdate: January 12 2023 $ +.Dt TCSETPGRP 3 +.Os +.Sh NAME +.Nm tcsetpgrp +.Nd set foreground process group ID +.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 +.Fn 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 +If the calling process is a member of a background process group, +the process group will be sent a +.Dv SIGTTOU +signal. +If the calling process is blocking or ignoring +.Dv SIGTTOU +signals, the process is allowed to perform the operation and the +.Dv SIGTTOU +signal is not sent. +.Pp +Upon successful completion, +.Fn tcsetpgrp +returns a value of zero. +.Sh ERRORS +If an error occurs, +.Fn tcsetpgrp +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 EINTR +The +.Fn tcsetpgrp +function was interrupted by a signal. +.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 +.Fn tcsetpgrp +function is compliant with the +.St -p1003.1-88 +specification. diff --git a/static/openbsd/man3/term_variables.3 b/static/openbsd/man3/term_variables.3 new file mode 100644 index 00000000..49ae267d --- /dev/null +++ b/static/openbsd/man3/term_variables.3 @@ -0,0 +1,193 @@ +.\"*************************************************************************** +.\" Copyright 2019-2022,2023 Thomas E. Dickey * +.\" Copyright 2010-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: term_variables.3,v 1.1 2023/10/17 09:52:08 nicm Exp $ +.TH term_variables 3 2023-07-01 "ncurses 6.4" "Library calls" +.ds n 5 +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.na +.hy 0 +.SH NAME +\fBSP\fP, +\fBacs_map\fP, +\fBboolcodes\fP, +\fBboolfnames\fP, +\fBboolnames\fP, +\fBcur_term\fP, +\fBnumcodes\fP, +\fBnumfnames\fP, +\fBnumnames\fP, +\fBstrcodes\fP, +\fBstrfnames\fP, +\fBstrnames\fP, +\fBttytype\fP +\- \fBcurses\fP terminfo global variables +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +.br +\fB#include \fP +.PP +\fBchtype acs_map[];\fP +.sp +\fBSCREEN * SP;\fP +.sp +\fBTERMINAL * cur_term;\fP +.sp +\fBchar ttytype[];\fP +.sp +\fBNCURSES_CONST char * const boolcodes[];\fP +.br +\fBNCURSES_CONST char * const boolfnames[];\fP +.br +\fBNCURSES_CONST char * const boolnames[];\fP +.sp +\fBNCURSES_CONST char * const numcodes[];\fP +.br +\fBNCURSES_CONST char * const numfnames[];\fP +.br +\fBNCURSES_CONST char * const numnames[];\fP +.sp +\fBNCURSES_CONST char * const strcodes[];\fP +.br +\fBNCURSES_CONST char * const strfnames[];\fP +.br +\fBNCURSES_CONST char * const strnames[];\fP +.br +.fi +.SH DESCRIPTION +This page summarizes variables provided by the \fBcurses\fP library's +low-level terminfo interface. +A more complete description is given in the \fBterminfo\fP(3) manual page. +.PP +Depending on the configuration, these may be actual variables, +or macros (see \fBcurs_threads\fP(3)) +which provide read-only access to \fIcurses\fP's state. +In either case, applications should treat them as read-only to avoid +confusing the library. +.SS Alternate Character Set Mapping +After initializing the curses or terminfo interfaces, +the \fBacs_map\fP array holds information used to translate cells +with the \fBA_ALTCHARSET\fP video attribute into line-drawing characters. +.PP +The encoding of the information in this array has changed periodically. +Application developers need only know that it is used for the \*(``ACS_\*('' +constants in . +.PP +The comparable data for the wide-character library is a private variable. +.SS Current Terminal Data +After initializing the curses or terminfo interfaces, +the \fBcur_term\fP contains data describing the current terminal. +This variable is also set as a side-effect of \fBset_term\fP(3) +and \fBdelscreen\fP(3). +.PP +It is possible to save a value of \fBcur_term\fP for subsequent +use as a parameter to \fBset_term\fP, for switching between screens. +Alternatively, one can save the return value from \fBnewterm\fP +or \fBsetupterm\fP(3) to reuse in \fBset_term\fP. +.SS Terminfo Lookup Tables +The \fBtic\fP(1) and \fBinfocmp\fP(1) programs use lookup tables for +the long and short names of terminfo capabilities, +as well as the corresponding names for termcap capabilities. +These are available to other applications, +although the hash-tables used by +the terminfo and termcap functions are not available. +.PP +The long terminfo capability names use a \*(``f\*('' (eff) in their names: +\fBboolfnames\fP, +\fBnumfnames\fP, and +\fBstrfnames\fP. +.PP +These are the short names for terminfo capabilities: +\fBboolnames\fP, +\fBnumnames\fP, and +\fBstrnames\fP. +.PP +These are the corresponding names used for termcap descriptions: +\fBboolcodes\fP, +\fBnumcodes\fP, and +\fBstrcodes\fP. +.\" +.SS Terminal Type +A terminal description begins with one or more terminal names +separated by \*(``|\*('' (vertical bars). +On initialization of the curses or terminfo interfaces, +\fBsetupterm\fP(3) copies the terminal names to the array \fBttytype\fP. +.\" +.SS Terminfo Names +In addition to the variables, \fB\fP also defines a symbol for each +terminfo capability \fIlong name\fP. +These are in terms of the symbol \fBCUR\fP, +which is defined +.PP +.nf +.ft CW +#define CUR ((TERMTYPE *)(cur_term))-> +.fi +.ft R +.PP +These symbols provide a faster method of accessing terminfo capabilities +than using \fBtigetstr\fP(3), etc. +.PP +The actual definition of \fBCUR\fP depends upon the implementation, +but each terminfo library provides these long names defined to point +into the current terminal description loaded into memory. +.\" +.SH NOTES +The low-level terminfo interface is initialized using +.hy 0 +\fBsetupterm\fP(3). +.hy +The upper-level curses interface uses the low-level terminfo interface, +internally. +.\" +.SH PORTABILITY +X/Open Curses does not describe any of these except for \fBcur_term\fP. +(The inclusion of \fBcur_term\fP appears to be an oversight, +since other comparable low-level information is omitted by X/Open). +.PP +Other implementations may have comparable variables. +Some implementations provide the variables in their libraries, +but omit them from the header files. +.PP +All implementations which provide terminfo interfaces add definitions +as described in the \fBTerminfo Names\fP section. +Most, but not all, base the definition upon the \fBcur_term\fP variable. +.SH SEE ALSO +.hy 0 +\fBcurses\fP(3), +\fBterminfo\fP(3), +\fBcurs_threads\fP(3), +\fBterminfo\fP(\*n). +.hy diff --git a/static/openbsd/man3/termcap.3 b/static/openbsd/man3/termcap.3 new file mode 100644 index 00000000..1486bdc9 --- /dev/null +++ b/static/openbsd/man3/termcap.3 @@ -0,0 +1,389 @@ +.\" $OpenBSD: termcap.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2017,2018 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: termcap.3,v 1.10 2023/10/17 09:52:08 nicm Exp $ +.TH termcap 3 2023-07-01 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.na +.hy 0 +.ds n 5 +.SH NAME +\fBPC\fP, +\fBUP\fP, +\fBBC\fP, +\fBospeed\fP, +\fBtgetent\fP, +\fBtgetflag\fP, +\fBtgetnum\fP, +\fBtgetstr\fP, +\fBtgoto\fP, +\fBtputs\fP \- \fBcurses\fP emulation of termcap +.ad +.hy +.SH SYNOPSIS +\fB#include \fP +.br +\fB#include \fP +.sp +\fBextern char PC;\fP +.br +\fBextern char * UP;\fP +.br +\fBextern char * BC;\fP +.br +\fBextern int ospeed;\fP +.sp +\fBint tgetent(char *\fIbp\fB, const char *\fIname\fB);\fR +.br +\fBint tgetflag(const char *\fIid\fB);\fR +.br +\fBint tgetnum(const char *\fIid\fB);\fR +.br +\fBchar *tgetstr(const char *\fIid\fB, char **\fIarea\fB);\fR +.br +\fBchar *tgoto(const char *\fIcap\fB, int \fIcol\fB, int \fIrow\fB);\fR +.br +\fBint tputs(const char *\fIstr\fB, int \fIaffcnt\fB, int (*\fIputc\fB)(int));\fR +.SH DESCRIPTION +These routines are included as a conversion aid for programs that use +the \fItermcap\fP library. +Their parameters are the same, but the +routines are emulated using the \fIterminfo\fP database. +Thus, they +can only be used to query the capabilities of entries for which a +terminfo entry has been compiled. +.SS Initialization +The \fBtgetent\fP routine loads the entry for \fIname\fP. +It returns: +.RS 3 +.TP 3 +1 +on success, +.TP 3 +0 +if there is no such entry +(or that it is a generic type, having too little information for curses +applications to run), and +.TP 3 +\-1 +if the terminfo database could not be found. +.RE +.PP +This differs from the \fItermcap\fP library in two ways: +.RS 3 +.bP +The emulation ignores the buffer pointer \fIbp\fP. +The \fItermcap\fP library would store a copy of the terminal +description in the area referenced by this pointer. +However, ncurses stores its terminal descriptions in compiled +binary form, which is not the same thing. +.bP +There is a difference in return codes. +The \fItermcap\fP library does not check if the terminal +description is marked with the \fIgeneric\fP capability, +or if the terminal description has cursor-addressing. +.RE +.SS Capability Values +The \fBtgetflag\fP routine gets the boolean entry for \fIid\fP, +or zero if it is not available. +.PP +The \fBtgetnum\fP routine gets the numeric entry for \fIid\fP, +or \-1 if it is not available. +.PP +The \fBtgetstr\fP routine returns the string entry for \fIid\fP, +or zero if it is not available. +Use \fBtputs\fP to output the returned string. +The \fIarea\fP parameter is used as follows: +.RS 3 +.bP +It is assumed to be the address of a pointer to a buffer managed by the +calling application. +.bP +However, ncurses checks to ensure that \fBarea\fP is not NULL, +and also that the resulting buffer pointer is not NULL. +If either check fails, the \fIarea\fP parameter is ignored. +.bP +If the checks succeed, ncurses also copies the return value to +the buffer pointed to by \fIarea\fP, +and the \fIarea\fP value will be updated to point past the null ending +this value. +.bP +The return value itself is an address in the terminal description which +is loaded into memory. +.RE +.PP +Only the first two characters of the \fBid\fP parameter of +\fBtgetflag\fP, +\fBtgetnum\fP and +\fBtgetstr\fP are compared in lookups. +.SS Formatting Capabilities +The \fBtgoto\fP routine expands the given capability using the parameters. +.bP +Because the capability may have padding characters, +the output of \fBtgoto\fP should be passed to \fBtputs\fP +rather than some other output function such as \fBprintf\fP(3). +.bP +While \fBtgoto\fP is assumed to be used for the two-parameter +cursor positioning capability, +termcap applications also use it for single-parameter capabilities. +.IP +Doing this shows a quirk in \fBtgoto\fP: most hardware +terminals use cursor addressing with \fIrow\fP first, +but the original developers of the termcap interface chose to +put the \fIcolumn\fP parameter first. +The \fBtgoto\fP function swaps the order of parameters. +It does this also for calls requiring only a single parameter. +In that case, the first parameter is merely a placeholder. +.bP +Normally the ncurses library is compiled with terminfo support. +In that case, \fBtgoto\fP uses an internal version of +\fBtparm\fP(3) (a more capable formatter). +.IP +With terminfo support, \fBtgoto\fP is able to use some of the terminfo +features, but not all. +In particular, it allows only numeric parameters; +\fBtparm\fP supports string parameters. +.IP +However, \fBtparm\fP is not a \fItermcap\fP feature, +and portable \fItermcap\fP applications should not rely upon its availability. +.PP +The \fBtputs\fP routine is described on the \fBterminfo\fP(3) manual +page. +It can retrieve capabilities by either termcap or terminfo name. +.SS Global Variables +The variables +\fBPC\fP, +\fBUP\fP and +\fBBC\fP +are set by \fBtgetent\fP to the terminfo entry's data for +\fBpad_char\fP, +\fBcursor_up\fP and +\fBbackspace_if_not_bs\fP, +respectively. +\fBUP\fP is not used by ncurses. +\fBPC\fP is used in the \fBtdelay_output\fP function. +\fBBC\fP is used in the \fBtgoto\fP emulation. +The variable \fBospeed\fP is set by ncurses in a system-specific coding +to reflect the terminal speed. +.SS Releasing Memory +The termcap functions provide no means for freeing memory, +because legacy termcap implementations used only the buffer +areas provided by the caller via \fBtgetent\fP and \fBtgetstr\fP. +Those buffers are unused in terminfo. +.PP +On the other hand, terminfo allocates memory. +It uses \fBsetupterm\fP to retrieve the data used by \fBtgetent\fP +and the functions which return capability values such as \fBtgetstr\fP. +One could use +.sp + \fBdel_curterm(cur_term);\fP +.sp +.PP +to free this memory, but there is an additional complication with ncurses. +It uses a fixed-size \fIpool\fP of storage locations, +one per setting of the \fBTERM\fP variable when \fBtgetent\fP is called. +The \fBscreen\fP(1) program relies upon this arrangement, +to improve its performance. +.PP +An application which uses only the low-level termcap functions could +free the memory using \fBdel_curterm\fP, +because the pool is freed using other functions +(see \fBcurs_memleaks\fP(3)). +. +.SH RETURN VALUE +Except where explicitly noted, +routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +(SVr4 only specifies "an integer value other than \fBERR\fP") upon successful +completion. +.PP +Routines that return pointers return \fBNULL\fP on error. +.PP +A few special cases apply: +.bP +If the terminal database has not been initialized, +these return an error. +.bP +The calls with a string parameter (\fBtgoto\fP, \fBtputs\fP) +check if the string is null, or cancelled. +Those return an error. +.bP +A call to \fBtgoto\fP using a capability with string parameters is an error. +.bP +A call to \fBtgoto\fP using a capability with more than two parameters +is an error. +.SH BUGS +If you call \fBtgetstr\fP to fetch \fBca\fP or any other parameterized string, +be aware that it will be returned in terminfo notation, not the older and +not-quite-compatible termcap notation. +This will not cause problems if all +you do with it is call \fBtgoto\fP or \fBtparm\fP, which both expand +terminfo-style strings as terminfo. +(The \fBtgoto\fP function, if configured to support termcap, will check +if the string is indeed terminfo-style by looking for "%p" parameters or +"$<..>" delays, and invoke a termcap-style parser if the string does not +appear to be terminfo). +.PP +Because terminfo conventions for representing padding in string capabilities +differ from termcap's, +users can be surprised: +.bP +\fBtputs("50")\fP in a terminfo system will put out a literal \*(``50\*('' +rather than busy-waiting for 50 milliseconds. +.bP +However, if ncurses is configured to support termcap, +it may also have been configured to support the BSD-style padding. +.IP +In that case, \fBtputs\fP inspects strings passed to it, +looking for digits at the beginning of the string. +.IP +\fBtputs("50")\fP in a termcap system may wait for 50 milliseconds +rather than put out a literal \*(``50\*('' +.PP +Note that termcap has nothing analogous to terminfo's \fBsgr\fP string. +One consequence of this is that termcap applications assume \fBme\fP +(terminfo \fBsgr0\fP) does not reset the alternate character set. +This implementation checks for, and modifies the data shown to the +termcap interface to accommodate termcap's limitation in this respect. +.SH PORTABILITY +.SS Standards +These functions are provided for supporting legacy applications, +and should not be used in new programs: +.bP +The XSI Curses standard, Issue 4 describes these functions. +However, they +are marked TO BE WITHDRAWN and may be removed in future versions. +.bP +X/Open Curses, Issue 5 (December 2007) marked the termcap interface +(along with \fBvwprintw\fP and \fBvwscanw\fP) as withdrawn. +.PP +Neither the XSI Curses standard nor the SVr4 man pages documented the return +values of \fBtgetent\fP correctly, though all three were in fact returned ever +since SVr1. +In particular, an omission in the XSI Curses documentation has been +misinterpreted to mean that \fBtgetent\fP returns \fBOK\fP or \fBERR\fP. +Because the purpose of these functions is to provide compatibility with +the \fItermcap\fP library, that is a defect in XCurses, Issue 4, Version 2 +rather than in ncurses. +.SS Compatibility with BSD Termcap +External variables are provided for support of certain termcap applications. +However, termcap applications' use of those variables is poorly documented, +e.g., not distinguishing between input and output. +In particular, some applications are reported to declare and/or +modify \fBospeed\fP. +.PP +The comment that only the first two characters of the \fBid\fP parameter +are used escapes many application developers. +The original BSD 4.2 termcap library (and historical relics thereof) +did not require a trailing null NUL on the parameter name passed +to \fBtgetstr\fP, \fBtgetnum\fP and \fBtgetflag\fP. +Some applications assume that the termcap interface does not require +the trailing NUL for the parameter name. +Taking into account these issues: +.bP +As a special case, +\fBtgetflag\fP matched against a single-character identifier +provided that was at the end of the terminal description. +You should not rely upon this behavior in portable programs. +This implementation disallows matches against single-character capability names. +.bP +This implementation disallows matches by the termcap interface against +extended capability names which are longer than two characters. +.PP +The BSD termcap function \fBtgetent\fP returns the text of a termcap +entry in the buffer passed as an argument. +This library (like other terminfo implementations) does not store +terminal descriptions as text. +It sets the buffer contents to a null-terminated string. +.SS Other Compatibility +This library includes a termcap.h header, +for compatibility with other implementations. +But the header is rarely used because the other implementations +are not strictly compatible. +.PP +The original BSD termcap (through 4.3BSD) had no header file which +gave function prototypes, because that was a feature of ANSI C. +BSD termcap was written several years before C was standardized. +However, there were two different termcap.h header files in the BSD +sources: +.bP +One was used internally by the \fBjove\fP editor in 2BSD through 4.4BSD. +It defined global symbols for the termcap variables which it used. +.bP +The other appeared in 4.4BSD Lite Release 2 (mid-1993) +as part of \fIlibedit\fP (also known as the \fIeditline\fP library). +The CSRG source history shows that this was added in mid-1992. +The \fIlibedit\fP header file was used internally, +as a convenience for compiling the \fIeditline\fP library. +It declared function prototypes, but no global variables. +.PP +The header file from \fIlibedit\fP was added to NetBSD's termcap +library in mid-1994. +.PP +Meanwhile, GNU termcap was under development, starting in 1990. +The first release (termcap 1.0) in 1991 included a termcap.h header. +The second release (termcap 1.1) in September 1992 modified the +header to use \fBconst\fP for the function prototypes in the header +where one would expect the parameters to be read-only. +This was a difference versus the original BSD termcap. +The prototype for \fBtputs\fP also differed, +but in that instance, it was \fIlibedit\fP which differed from BSD termcap. +.PP +A copy of GNU termcap 1.3 was bundled with \fIbash\fP in mid-1993, +to support the \fBreadline\fP(3) library. +.PP +A termcap.h file was provided in ncurses 1.8.1 (November 1993). +That reflected influence by \fBemacs\fP(1) (rather than \fBjove\fP(1)) +and GNU termcap: +.bP +it provided declarations for a few global symbols used by \fBemacs\fP +.bP +it provided function prototypes (using \fBconst\fP). +.bP +a prototype for \fBtparam\fP (a GNU termcap feature) was provided. +.PP +Later (in mid-1996) the \fBtparam\fP function was removed from ncurses. +As a result, there are differences between any of the four implementations, +which must be taken into account by programs which can work with all +termcap library interfaces. +.SH SEE ALSO +\fBcurses\fP(3), +\fBputc\fP(3), +\fBterm_variables\fP(3), +\fBterminfo\fP(\*n). +.sp +https://invisible-island.net/ncurses/tctest.html diff --git a/static/openbsd/man3/terminfo.3 b/static/openbsd/man3/terminfo.3 new file mode 100644 index 00000000..257f0a3d --- /dev/null +++ b/static/openbsd/man3/terminfo.3 @@ -0,0 +1,784 @@ +'\" t +.\" $OpenBSD: terminfo.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: terminfo.3,v 1.11 2023/10/17 09:52:08 nicm Exp $ +.TH terminfo 3 2023-08-19 "ncurses 6.4" "Library calls" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.ds n 5 +.na +.hy 0 +.SH NAME +\fBdel_curterm\fP, +\fBmvcur\fP, +\fBputp\fP, +\fBrestartterm\fP, +\fBset_curterm\fP, +\fBsetupterm\fP, +\fBtigetflag\fP, +\fBtigetnum\fP, +\fBtigetstr\fP, +\fBtiparm\fP, +\fBtiparm_s\fP, +\fBtiscan_s\fP, +\fBtparm\fP, +\fBtputs\fP, +\fBvid_attr\fP, +\fBvid_puts\fP, +\fBvidattr\fP, +\fBvidputs\fP \- \fBcurses\fP interfaces to terminfo database +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include \fP +\fB#include \fP +.sp +\fBTERMINAL *cur_term;\fP +.sp +\fBconst char * const boolnames[];\fP +\fBconst char * const boolcodes[];\fP +\fBconst char * const boolfnames[];\fP +\fBconst char * const numnames[];\fP +\fBconst char * const numcodes[];\fP +\fBconst char * const numfnames[];\fP +\fBconst char * const strnames[];\fP +\fBconst char * const strcodes[];\fP +\fBconst char * const strfnames[];\fP +.sp +\fBint setupterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR +.br +\fBTERMINAL *set_curterm(TERMINAL *\fInterm\fB);\fR +.br +\fBint del_curterm(TERMINAL *\fIoterm\fB);\fR +.br +\fBint restartterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR +.sp +\fBchar *tparm(const char *\fIstr\fB, ...);\fR +.br + \fIor\fP +.br +\fBchar *tparm(const char *\fIstr\fB, long \fIp1 ... \fBlong \fIp9\fB);\fR +.sp +\fBint tputs(const char *\fIstr\fB, int \fIaffcnt\fB, int (*\fIputc\fB)(int));\fR +.br +\fBint putp(const char *\fIstr\fB);\fR +.sp +\fBint vidputs(chtype \fIattrs\fB, int (*\fIputc\fB)(int));\fR +.br +\fBint vidattr(chtype \fIattrs\fB);\fR +.br +\fBint vid_puts(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB, int (*\fIputc\fB)(int));\fR +.br +\fBint vid_attr(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR +.sp +\fBint mvcur(int \fIoldrow\fB, int \fIoldcol\fB, int \fInewrow\fR, int \fInewcol\fB);\fR +.sp +\fBint tigetflag(const char *\fIcapname\fB);\fR +.br +\fBint tigetnum(const char *\fIcapname\fB);\fR +.br +\fBchar *tigetstr(const char *\fIcapname\fB);\fR +.sp +\fBchar *tiparm(const char *\fIstr\fB, ...);\fR +.sp +/* extensions */ +.br +\fBchar *tiparm_s(int \fIexpected\fB, int \fImask\fB, const char *\fIstr\fB, ...);\fR +.br +\fBint tiscan_s(int *\fIexpected\fB, int *\fImask\fB, const char *\fIstr\fB);\fR +.br +.fi +.SH DESCRIPTION +These low-level routines must be called by programs that have to deal +directly with the \fBterminfo\fP database to handle certain terminal +capabilities, such as programming function keys. +For all other +functionality, \fBcurses\fP routines are more suitable and their use is +recommended. +.PP +None of these functions use (or are aware of) multibyte character strings +such as UTF-8: +.bP +capability names use the POSIX portable character set +.bP +capability string values have no associated encoding; +they are strings of 8-bit characters. +.SS Initialization +Initially, \fBsetupterm\fP should be called. +The high-level curses functions \fBinitscr\fP and +\fBnewterm\fP call \fBsetupterm\fP to initialize the +low-level set of terminal-dependent variables +[listed in \fBterminfo\fP(\*n)]. +.PP +Applications can use the +terminal capabilities either directly (via header definitions), +or by special functions. +The header files \fBcurses.h\fP and \fBterm.h\fP should be included (in this +order) to get the definitions for these strings, numbers, and flags. +.PP +The \fBterminfo\fP variables +\fBlines\fP and \fBcolumns\fP are initialized by \fBsetupterm\fP as +follows: +.bP +If \fBuse_env(FALSE)\fP has been called, values for +\fBlines\fP and \fBcolumns\fP specified in \fBterminfo\fP are used. +.bP +Otherwise, if the environment variables \fBLINES\fP and \fBCOLUMNS\fP +exist, their values are used. +If these environment variables do not +exist and the program is running in a window, the current window size +is used. +Otherwise, if the environment variables do not exist, the +values for \fBlines\fP and \fBcolumns\fP specified in the +\fBterminfo\fP database are used. +.PP +Parameterized strings should be passed through \fBtparm\fP to instantiate them. +All \fBterminfo\fP strings +(including the output of \fBtparm\fP) +should be printed +with \fBtputs\fP or \fBputp\fP. +Call \fBreset_shell_mode\fP to restore the +tty modes before exiting [see \fBcurs_kernel\fP(3)]. +.PP +Programs which use +cursor addressing should +.bP +output \fBenter_ca_mode\fP upon startup and +.bP +output \fBexit_ca_mode\fP before exiting. +.PP +Programs which execute shell subprocesses should +.bP +call \fBreset_shell_mode\fP and +output \fBexit_ca_mode\fP before the shell +is called and +.bP +output \fBenter_ca_mode\fP and +call \fBreset_prog_mode\fP after returning from the shell. +.PP +The \fBsetupterm\fP routine reads in the \fBterminfo\fP database, +initializing the \fBterminfo\fP structures, but does not set up the +output virtualization structures used by \fBcurses\fP. +These are its parameters: +.RS 3 +.TP 5 +\fIterm\fP +is the terminal type, a character string. +If \fIterm\fP is null, the environment variable \fBTERM\fP is used. +.TP 5 +\fIfiledes\fP +is the file descriptor used for getting and setting terminal I/O modes. +.IP +Higher-level applications use \fBnewterm\fP(3) for initializing the terminal, +passing an output \fIstream\fP rather than a \fIdescriptor\fP. +In curses, the two are the same because \fBnewterm\fP calls \fBsetupterm\fP, +passing the file descriptor derived from its output stream parameter. +.TP 5 +\fIerrret\fP +points to an optional location where an error status can be returned to +the caller. +If \fIerrret\fP is not null, +then \fBsetupterm\fP returns \fBOK\fP or +\fBERR\fP and stores a status value in the integer pointed to by +\fIerrret\fP. +A return value of \fBOK\fP combined with status of \fB1\fP in \fIerrret\fP +is normal. +.IP +If \fBERR\fP is returned, examine \fIerrret\fP: +.RS +.TP 5 +.B 1 +means that the terminal is hardcopy, cannot be used for curses applications. +.IP +\fBsetupterm\fP determines if the entry is a hardcopy type by +checking the \fBhc\fP (\fBhardcopy\fP) capability. +.TP 5 +.B 0 +means that the terminal could not be found, +or that it is a generic type, +having too little information for curses applications to run. +.IP +\fBsetupterm\fP determines if the entry is a generic type by +checking the \fBgn\fP (\fBgeneric_type\fP) capability. +.TP 5 +.B \-1 +means that the \fBterminfo\fP database could not be found. +.RE +.IP +If \fIerrret\fP is +null, \fBsetupterm\fP prints an error message upon finding an error +and exits. +Thus, the simplest call is: +.sp + \fBsetupterm((char *)0, 1, (int *)0);\fP, +.sp +which uses all the defaults and sends the output to \fBstdout\fP. +.RE +.\" *************************************************************************** +.SS The Terminal State +The \fBsetupterm\fP routine stores its information about the terminal +in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP. +If it detects an error, +or decides that the terminal is unsuitable (hardcopy or generic), +it discards this information, +making it not available to applications. +.PP +If \fBsetupterm\fP is called repeatedly for the same terminal type, +it will reuse the information. +It maintains only one copy of a given terminal's capabilities in memory. +If it is called for different terminal types, +\fBsetupterm\fP allocates new storage for each set of terminal capabilities. +.PP +The \fBset_curterm\fP routine sets \fBcur_term\fP to +\fInterm\fP, and makes all of the \fBterminfo\fP boolean, numeric, and +string variables use the values from \fInterm\fP. +It returns the old value of \fBcur_term\fP. +.PP +The \fBdel_curterm\fP routine frees the space pointed to by +\fIoterm\fP and makes it available for further use. +If \fIoterm\fP is +the same as \fBcur_term\fP, references to any of the \fBterminfo\fP +boolean, numeric, and string variables thereafter may refer to invalid +memory locations until another \fBsetupterm\fP has been called. +.PP +The \fBrestartterm\fP routine is similar to \fBsetupterm\fP and \fBinitscr\fP, +except that it is called after restoring memory to a previous state (for +example, when reloading a game saved as a core image dump). +\fBrestartterm\fP assumes that the windows and the input and output options +are the same as when memory was saved, +but the terminal type and baud rate may be different. +Accordingly, \fBrestartterm\fP saves various tty state bits, +calls \fBsetupterm\fP, and then restores the bits. +.\" *************************************************************************** +.SS Formatting Output +The \fBtparm\fP routine instantiates the string \fIstr\fP with +parameters \fIpi\fP. A pointer is returned to the result of \fIstr\fP +with the parameters applied. +Application developers should keep in mind these quirks of the interface: +.bP +Although \fBtparm\fP's actual parameters may be integers or strings, +the prototype expects \fBlong\fP (integer) values. +.bP +Aside from the \fBset_attributes\fP (\fBsgr\fP) capability, +most terminal capabilities require no more than one or two parameters. +.bP +Padding information is ignored by \fBtparm\fP; +it is interpreted by \fBtputs\fP. +.bP +The capability string is null-terminated. +Use \*(``\\200\*('' where an ASCII NUL is needed in the output. +.PP +\fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI\fP +rather than a fixed-parameter list. +Its numeric parameters are integers (int) rather than longs. +.PP +Both \fBtparm\fP and \fBtiparm\fP assume that the application passes +parameters consistent with the terminal description. +Two extensions are provided as alternatives to deal with untrusted data: +.bP +\fBtiparm_s\fP is an extension which is a safer formatting function +than \fBtparm\fR or \fBtiparm\fR, +because it allows the developer to tell the curses +library how many parameters to expect in the parameter list, +and which may be string parameters. +.IP +The \fImask\fP parameter has one bit set for each of the parameters +(up to 9) which will be passed as char* rather than numbers. +.bP +The extension \fBtiscan_s\fP allows the application +to inspect a formatting capability to see what the curses library would assume. +.\" *************************************************************************** +.SS Output Functions +The \fBtputs\fP routine applies padding information +(i.e., by interpreting marker embedded in the terminfo capability +such as \*(``$<5>\*('' as 5 milliseconds) +to the string +\fIstr\fP and outputs it: +.bP +The \fIstr\fP parameter must be a terminfo string +variable or the return value from +\fBtparm\fP, \fBtiparm\fP, \fBtgetstr\fP, or \fBtgoto\fP. +.IP +The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP +interface, +which happens to share this function name with the \fIterminfo\fP interface. +.bP +\fIaffcnt\fP is the number of lines affected, or 1 if +not applicable. +.bP +\fIputc\fP is a \fBputchar\fP-like routine to which +the characters are passed, one at a time. +.PP +The \fBputp\fR routine calls \fBtputs(\fIstr\fB, 1, putchar)\fR. +The output of \fBputp\fP always goes to \fBstdout\fP, rather than +the \fIfiledes\fP specified in \fBsetupterm\fP. +.PP +The \fBvidputs\fP routine displays the string on the terminal in the +video attribute mode \fIattrs\fP, which is any combination of the +attributes listed in \fBcurses\fP(3). +The characters are passed to +the \fBputchar\fP-like routine \fIputc\fP. +.PP +The \fBvidattr\fP routine is like the \fBvidputs\fP routine, except +that it outputs through \fBputchar\fP. +.PP +The \fBvid_attr\fP and \fBvid_puts\fP routines correspond +to vidattr and vidputs, respectively. +They use a set of arguments for representing the video attributes plus color, +i.e., +.bP +\fIattrs\fP of type \fBattr_t\fP for the attributes and +.bP +\fIpair\fP of type \fBshort\fP for the color-pair number. +.PP +The \fBvid_attr\fP and \fBvid_puts\fP routines +are designed to use the attribute constants with the \fBWA_\fP prefix. +.PP +X/Open Curses reserves the \fIopts\fP argument for future use, +saying that applications must provide a null pointer for that argument. +As an extension, +this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP, +which overrides the \fIpair\fP (\fBshort\fP) argument. +.PP +The \fBmvcur\fP routine provides low-level cursor motion. +It takes effect immediately (rather than at the next refresh). +Unlike the other low-level output functions, +which either write to the standard output or pass an output function parameter, +\fBmvcur\fP uses an output file descriptor derived from +the output stream parameter of \fBnewterm\fP(3). +.PP +While \fBputp\fP and \fBmvcur\fP are low-level functions which +do not use the high-level curses state, +they are declared in \fB\fP because SystemV did this +(see \fIHISTORY\fP). +.\" *************************************************************************** +.SS Terminal Capability Functions +The \fBtigetflag\fP, \fBtigetnum\fP and \fBtigetstr\fP routines return +the value of the capability corresponding to the \fBterminfo\fP +\fIcapname\fP passed to them, such as \fBxenl\fP. +The \fIcapname\fP for each capability is given in the table column entitled +\fIcapname\fP code in the capabilities section of \fBterminfo\fP(\*n). +.PP +These routines return special values to denote errors. +.PP +The \fBtigetflag\fP routine returns +.TP +\fB\-1\fP +if \fIcapname\fP is not a boolean capability, +or +.TP +\fB0\fP +if it is canceled or absent from the terminal description. +.PP +The \fBtigetnum\fP routine returns +.TP +\fB\-2\fP +if \fIcapname\fP is not a numeric capability, or +.TP +\fB\-1\fP +if it is canceled or absent from the terminal description. +.PP +The \fBtigetstr\fP routine returns +.TP +\fB(char *)\-1\fP +if \fIcapname\fP is not a string capability, +or +.TP +\fB0\fP +if it is canceled or absent from the terminal description. +.\" *************************************************************************** +.SS Terminal Capability Names +These null-terminated arrays contain +.bP +the short terminfo names (\*(``codes\*(''), +.bP +the \fBtermcap\fP names (\*(``names\*(''), and +.bP +the long terminfo names (\*(``fnames\*('') +.PP +for each of the predefined \fBterminfo\fP variables: +.sp +.RS +\fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP +.br +\fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP +.br +\fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP +.RE +.\" *************************************************************************** +.SS Releasing Memory +Each successful call to \fBsetupterm\fP allocates memory to hold the terminal +description. +As a side-effect, it sets \fBcur_term\fP to point to this memory. +If an application calls +.sp + \fBdel_curterm(cur_term);\fP +.sp +the memory will be freed. +.PP +The formatting functions \fBtparm\fP and \fBtiparm\fP extend the storage +allocated by \fBsetupterm\fP: +.bP +the \*(``static\*('' terminfo variables [a-z]. +Before ncurses 6.3, those were shared by all screens. +With ncurses 6.3, those are allocated per screen. +See \fBterminfo\fP(\*n) for details. +.bP +to improve performance, ncurses 6.3 caches the result of analyzing terminfo +strings for their parameter types. +That is stored as a binary tree referenced from the \fBTERMINAL\fP structure. +.PP +The higher-level \fBinitscr\fP and \fBnewterm\fP functions use \fBsetupterm\fP. +Normally they do not free this memory, but it is possible to do that using +the \fBdelscreen\fP(3) function. +.\" *************************************************************************** +.SH RETURN VALUE +Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +(SVr4 only specifies \*(``an integer value other than \fBERR\fP\*('') +upon successful completion, +unless otherwise noted in the preceding routine descriptions. +.PP +Routines that return pointers always return \fBNULL\fP on error. +.PP +X/Open defines no error conditions. +In this implementation +.RS 3 +.TP 5 +\fBdel_curterm\fP +returns an error +if its terminal parameter is null. +.TP 5 +\fBputp\fP +calls \fBtputs\fP, returning the same error-codes. +.TP 5 +\fBrestartterm\fP +returns an error +if the associated call to \fBsetupterm\fP returns an error. +.TP 5 +\fBsetupterm\fP +returns an error +if it cannot allocate enough memory, or +create the initial windows (stdscr, curscr, newscr). +Other error conditions are documented above. +.TP 5 +\fBtparm\fP +returns a null if the capability would require unexpected parameters, +e.g., too many, too few, or incorrect types +(strings where integers are expected, or vice versa). +.TP 5 +\fBtputs\fP +returns an error if the string parameter is null. +It does not detect I/O errors: +X/Open states that \fBtputs\fP ignores the return value +of the output function \fIputc\fP. +.RE +.\" *************************************************************************** +.SS Compatibility macros +This implementation provides a few macros for compatibility with systems +before SVr4 (see \fIHISTORY\fP). +Those include +\fBcrmode\fP, +\fBfixterm\fP, +\fBgettmode\fP, +\fBnocrmode\fP, +\fBresetterm\fP, +\fBsaveterm\fP, and +\fBsetterm\fP. +.PP +In SVr4, those are found in \fB\fP, +but except for \fBsetterm\fP, are likewise macros. +The one function, \fBsetterm\fP, is mentioned in the manual page. +The manual page notes that the \fBsetterm\fP routine +was replaced by \fBsetupterm\fP, stating that the call: +.sp + \fBsetupterm(\fIterm\fB, 1, (int *)0)\fR +.sp +provides the same functionality as \fBsetterm(\fIterm\fB)\fR, +and is not recommended for new programs. +This implementation provides each of those symbols +as macros for BSD compatibility, +.\" *************************************************************************** +.SH HISTORY +SVr2 introduced the terminfo feature. +Its programming manual mentioned these low-level functions: +.PP +.TS +l l. +\fBFunction\fP \fBDescription\fP +_ +fixterm restore tty to \*(``in curses\*('' state +gettmode establish current tty modes +mvcur low level cursor motion +putp T{ +utility function that uses \fBtputs\fP to send characters via \fBputchar\fP. +T} +resetterm set tty modes to \*(``out of curses\*('' state +resetty reset tty flags to stored value +saveterm save current modes as \*(``in curses\*('' state +savetty store current tty flags +setterm establish terminal with given type +setupterm establish terminal with given type +tparm instantiate a string expression with parameters +tputs apply padding information to a string +vidattr like \fBvidputs\fP, but outputs through \fBputchar\fP +vidputs T{ +output a string to put terminal in a specified video attribute mode +T} +.TE +.PP +The programming manual also mentioned +functions provided for termcap compatibility +(commenting that they \*(``may go away at a later date\*(''): +.PP +.TS +l l +_ _ +l l. +\fBFunction\fP \fBDescription\fP +tgetent look up termcap entry for given \fIname\fP +tgetflag get boolean entry for given \fIid\fP +tgetnum get numeric entry for given \fIid\fP +tgetstr get string entry for given \fIid\fP +tgoto apply parameters to given capability +tputs T{ +apply padding to capability, calling a function to put characters +T} +.TE +.PP +Early terminfo programs obtained capability values from the +\fBTERMINAL\fP structure initialized by \fBsetupterm\fP. +.PP +SVr3 extended terminfo by adding functions to retrieve capability values +(like the termcap interface), +and reusing tgoto and tputs: +.PP +.TS +l l +_ _ +l l. +\fBFunction\fP \fBDescription\fP +tigetflag get boolean entry for given \fIid\fP +tigetnum get numeric entry for given \fIid\fP +tigetstr get string entry for given \fIid\fP +.TE +.PP +SVr3 also replaced several of the SVr2 terminfo functions +which had no counterpart in the termcap interface, +documenting them as obsolete: +.TS +l l +_ _ +l l. +\fBFunction\fP \fBReplaced by\fP +crmode cbreak +fixterm reset_prog_mode +gettmode N/A +nocrmode nocbreak +resetterm reset_shell_mode +saveterm def_prog_mode +setterm setupterm +.TE +.PP +SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions, +along with \fBputp\fP, \fBtparm\fP and \fBtputs\fP. +The latter were needed to support padding, +and handling functions such as \fBvidattr\fP +(which used more than the two parameters supported by \fBtgoto\fP). +.PP +SVr3 introduced the functions for switching between terminal +descriptions, e.g., \fBset_curterm\fP. +Some of that was incremental improvements to the SVr2 library: +.bP +The \fBTERMINAL\fP type definition was introduced in SVr3.01, +for the \fBterm\fP structure provided in SVr2. +.bP +The various global variables such as \fBboolnames\fP were mentioned +in the programming manual at this point, +though the variables were provided in SVr2. +.PP +SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions. +.PP +There are other low-level functions declared in the curses header files +on Unix systems, +but none were documented. +The functions marked \*(``obsolete\*('' remained in use +by the Unix \fBvi\fP(1) editor. +.SH PORTABILITY +.SS Extensions +The functions marked as extensions were designed for \fBncurses\fP(3), +and are not found in SVr4 curses, 4.4BSD curses, +or any other previous version of curses. +.SS Legacy functions +X/Open notes that \fBvidattr\fP and \fBvidputs\fP may be macros. +.PP +The function \fBsetterm\fP is not described by X/Open and must +be considered non-portable. +All other functions are as described by X/Open. +.SS Legacy data +\fBsetupterm\fP copies the terminal name to the array \fBttytype\fP. +This is not part of X/Open Curses, but is assumed by some applications. +.PP +Other implementions may not declare the capability name arrays. +Some provide them without declaring them. +X/Open does not specify them. +.PP +Extended terminal capability names, e.g., as defined by \fBtic\ \-x\fP, +are not stored in the arrays described here. +.SS Output buffering +Older versions of \fBncurses\fP assumed that the file descriptor passed to +\fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses buffered I/O, +and would write to the corresponding stream. +In addition to the limitation that the terminal was left in block-buffered +mode on exit (like System V curses), +it was problematic because \fBncurses\fP +did not allow a reliable way to cleanup on receiving SIGTSTP. +.PP +The current version (ncurses6) +uses output buffers managed directly by \fBncurses\fP. +Some of the low-level functions described in this manual page write +to the standard output. +They are not signal-safe. +The high-level functions in \fBncurses\fP use +alternate versions of these functions +using the more reliable buffering scheme. +.SS Function prototypes +The X/Open Curses prototypes are based on the SVr4 curses header declarations, +which were defined at the same time the C language was first standardized in +the late 1980s. +.bP +X/Open Curses uses \fBconst\fP less effectively than a later design might, +in some cases applying it needlessly to values are already constant, +and in most cases overlooking parameters which normally would use \fBconst\fP. +Using constant parameters for functions which do not use \fBconst\fP +may prevent the program from compiling. +On the other hand, \fIwritable strings\fP are an obsolescent feature. +.IP +As an extension, this implementation can be configured to change the +function prototypes to use the \fBconst\fP keyword. +The ncurses ABI 6 enables this feature by default. +.bP +X/Open Curses prototypes \fBtparm\fP with a fixed number of parameters, +rather than a variable argument list. +.IP +This implementation uses a variable argument list, but can be +configured to use the fixed-parameter list. +Portable applications should provide 9 parameters after the format; +zeroes are fine for this purpose. +.IP +In response to review comments by Thomas E. Dickey, +X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009. +.IP +While \fBtiparm\fP is always provided in ncurses, +the older form is only available as a build-time configuration option. +If not specially configured, \fBtparm\fP is the same as \fBtiparm\fP. +.PP +Both forms of \fBtparm\fP have drawbacks: +.bP +Most of the calls to \fBtparm\fP use only one or two parameters. +Passing nine on each call is awkward. +.IP +Using \fBlong\fP for the numeric parameter type is a workaround +to make the parameter use the same amount of stack as a pointer. +That approach dates back to the mid-1980s, before C was standardized. +Since then, there is a standard +(and pointers are not required to fit in a long). +.bP +Providing the right number of parameters for a variadic function +such as \fBtiparm\fP can be a problem, in particular for string parameters. +However, only a few terminfo capabilities use string parameters +(e.g., the ones used for programmable function keys). +.IP +The ncurses library checks usage of these capabilities, +and returns an error if the capability mishandles string parameters. +But it cannot check if a calling program provides strings in the right +places for the \fBtparm\fP calls. +.IP +The \fBtput\fR(1) program checks its use of these capabilities with a table, +so that it calls \fBtparm\fP correctly. +.SS Special TERM treatment +If configured to use the terminal-driver, +e.g., for the MinGW port, +.bP +\fBsetupterm\fP interprets a missing/empty TERM variable as the +special value \*(``unknown\*(''. +.IP +SVr4 curses uses the +special value \*(``dumb\*(''. +.IP +The difference between the two is that +the former uses the \fBgn\fP (\fBgeneric_type\fR) terminfo capability, +while the latter does not. +A generic terminal is unsuitable for full-screen applications. +.bP +\fBsetupterm\fP allows explicit use of the +the windows console driver by checking if $TERM is set to +\*(``#win32con\*('' or an abbreviation of that string. +.SS Other portability issues +In System V Release 4, \fBset_curterm\fP has an \fBint\fP return type and +returns \fBOK\fP or \fBERR\fP. We have chosen to implement the X/Open Curses +semantics. +.PP +In System V Release 4, the third argument of \fBtputs\fP has the type +\fBint (*putc)(char)\fP. +.PP +At least one implementation of X/Open Curses (Solaris) returns a value +other than \fBOK\fP/\fBERR\fP from \fBtputs\fP. +That returns the length of the string, and does no error-checking. +.PP +X/Open notes that after calling \fBmvcur\fP, the curses state may not match the +actual terminal state, and that an application should touch and refresh +the window before resuming normal curses calls. +Both \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fP using +the SCREEN data allocated in either \fBinitscr\fP or \fBnewterm\fP. +So though it is documented as a terminfo function, +\fBmvcur\fP is really a curses function which is not well specified. +.PP +X/Open states that the old location must be given for \fBmvcur\fP. +This implementation allows the caller to use \-1's for the old ordinates. +In that case, the old location is unknown. +.SH SEE ALSO +\fBcurses\fP(3), +\fBcurs_initscr\fP(3), +\fBcurs_kernel\fP(3), +\fBcurs_memleaks\fP(3), +\fBtermcap\fP(3), +\fBcurs_variables\fP(3), +\fBterm_variables\fP(3), +\fBputc\fP(3), +\fBterminfo\fP(\*n) diff --git a/static/openbsd/man3/time.3 b/static/openbsd/man3/time.3 new file mode 100644 index 00000000..44ea3f33 --- /dev/null +++ b/static/openbsd/man3/time.3 @@ -0,0 +1,84 @@ +.\" $OpenBSD: time.3,v 1.18 2021/12/11 13:34:38 tb 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. +.\" +.Dd $Mdocdate: December 11 2021 $ +.Dt TIME 3 +.Os +.Sh NAME +.Nm time +.Nd get time of day +.Sh SYNOPSIS +.In time.h +.Ft time_t +.Fn time "time_t *now" +.Sh DESCRIPTION +The +.Fn time +function returns the number of seconds elapsed since +Jan 1 1970 00:00:00 UTC. +This value is also written to +.Fa now +unless +.Fa now +is +.Dv NULL . +.Sh RETURN VALUES +The +.Fn time +function is always successful, +and no return value is reserved to indicate an error. +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr gettimeofday 2 , +.Xr ctime 3 +.Sh STANDARDS +The +.Fn time +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +A +.Fn time +system call first appeared in +.At v1 . +That version counted time in sixtieths of a second with a 32-bit return value, +ensuring an integer overflow crisis every 2.26 years. +In +.At v6 +the granularity of the return value was reduced to whole seconds, +delaying the aforementioned crisis until 2038. +In +.Bx 4.1c +the function was moved out of the kernel into the C standard library and +reimplemented with +.Xr gettimeofday 2 . diff --git a/static/openbsd/man3/time2posix.3 b/static/openbsd/man3/time2posix.3 new file mode 100644 index 00000000..f318cf0c --- /dev/null +++ b/static/openbsd/man3/time2posix.3 @@ -0,0 +1,142 @@ +.\" $OpenBSD: time2posix.3,v 1.20 2015/02/23 19:05:36 bentley Exp $ +.Dd $Mdocdate: February 23 2015 $ +.Dt TIME2POSIX 3 +.Os +.Sh NAME +.Nm time2posix , +.Nm posix2time +.Nd convert seconds since the Epoch +.Sh SYNOPSIS +.In sys/types.h +.In time.h +.Ft time_t +.Fn time2posix "time_t t" +.Ft time_t +.Fn posix2time "time_t t" +.Sh DESCRIPTION +.St -p1003.1 +legislates that a +.Vt time_t +value of +536457599 shall correspond to +.Dq Wed Dec 31 23:59:59 UTC 1986 . +This effectively implies that a POSIX +.Vt time_t +cannot include 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 +.Vt time_t +values continue to increase over leap events +.Po +as a true +.Sq seconds since... +value +.Pc . +This means that these values will differ from those required by POSIX +by the net number of leap seconds inserted since the Epoch. +.Pp +Typically this is not a problem as the type +.Vt time_t +is intended to be +.Pq mostly +opaque. +.Vt time_t +values should only be obtained from and +passed to functions such as +.Xr time 3 , +.Xr localtime 3 , +.Xr mktime 3 , +and +.Xr difftime 3 . +However, +POSIX gives an arithmetic +expression for directly computing a +.Vt time_t +value from a given date/time, +and the same relationship is assumed by some +.Pq usually older +applications. +Any programs creating/dissecting +.Vt time_t +values +using such a relationship will typically not handle intervals +over leap seconds correctly. +.Pp +The +.Fn time2posix +and +.Fn posix2time +functions are provided to address this +.Vt time_t +mismatch by converting +between local +.Vt 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 in lieu of correcting the older +applications, +or when communicating with POSIX-compliant systems. +.Pp +.Fn time2posix +is single-valued. +That is, +every local +.Vt time_t +corresponds to a single POSIX +.Vt time_t . +.Fn posix2time +is less well-behaved: +for a positive leap second hit the result is not unique, +and for a negative leap second hit the corresponding +POSIX +.Vt time_t +doesn't exist so an adjacent value is returned. +Both of these are good indicators of the inferiority of the +POSIX representation. +.Pp +The following table summarizes the relationship between a time +T and its conversion to, +and back from, +the POSIX representation over the leap second inserted at the end of June, +1993. +.Bl -column 93/06/30 23:59:59 A+0 X=time2posix(T) posix2time(X) -offset indent +.It Em DATE Ta Em TIME Ta Em T Ta Em X=time2posix(T) Ta Em posix2time(X) +.It 93/06/30 Ta 23:59:59 Ta A+0 Ta B+0 Ta A+0 +.It 93/06/30 Ta 23:59:60 Ta A+1 Ta B+1 Ta A+1 or A+2 +.It 93/07/01 Ta 00:00:00 Ta A+2 Ta B+1 Ta A+1 or A+2 +.It 93/07/01 Ta 00:00:01 Ta A+3 Ta B+2 Ta 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 Em DATE Ta Em TIME Ta Em T Ta Em X=time2posix(T) Ta Em posix2time(X) +.It ??/06/30 Ta 23:59:58 Ta A+0 Ta B+0 Ta A+0 +.It ??/07/01 Ta 00:00:00 Ta A+1 Ta B+2 Ta A+1 +.It ??/07/01 Ta 00:00:01 Ta A+2 Ta B+3 Ta A+2 +.El +.Pp +[Note: posix2time(B+1) => A+0 or A+1] +.Pp +If leap-second support is not enabled, local +.Vt time_t +and +POSIX +.Vt time_t +are equivalent, and both +.Fn time2posix +and +.Fn posix2time +degenerate to the identity function. +.Sh SEE ALSO +.Xr difftime 3 , +.Xr localtime 3 , +.Xr mktime 3 , +.Xr time 3 +.\" This file is in the public domain, so clarified as of +.\" 1996-06-05 by Arthur David Olson. diff --git a/static/openbsd/man3/times.3 b/static/openbsd/man3/times.3 new file mode 100644 index 00000000..1dbbe19f --- /dev/null +++ b/static/openbsd/man3/times.3 @@ -0,0 +1,144 @@ +.\" $OpenBSD: times.3,v 1.17 2024/07/01 00:05:43 jsg 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. +.\" +.Dd $Mdocdate: July 1 2024 $ +.Dt TIMES 3 +.Os +.Sh NAME +.Nm times +.Nd process times +.Sh SYNOPSIS +.In sys/times.h +.Ft clock_t +.Fn times "struct tms *tp" +.Sh DESCRIPTION +.Bf -symbolic +This interface is obsoleted by +.Xr clock_gettime 2 +and +.Xr getrusage 2 . +.Ef +.Pp +The +.Fn times +function fills in the structure pointed to by +.Fa tp +with time-accounting information. +.Pp +The +.Vt tms +structure is defined as follows: +.Bd -literal -offset indent +struct tms { + 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 +.Fa tms_utime +and +.Fa tms_cutime +for all of the child processes. +.It Fa tms_cstime +The sum of +.Fa tms_stime +and +.Fa tms_cstime +for all of the child processes. +.El +.Pp +All times are in +.Dv CLK_TCK Ns s +of a second. +.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. +.Sh RETURN VALUES +Upon successful completion, +.Fn times +returns the value of real time, +in +.Dv CLK_TCK Ns s +of a second, +elapsed since an arbitrary point in the past. +This point does not change between invocations of +.Fn times +so two such return values constitute a real time interval. +.Pp +On failure, +.Fn times +returns +.Li "(clock_t)-1" +and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn times +function may fail and set +.Va errno +for any of the errors specified for +.Xr clock_gettime 2 +and +.Xr getrusage 2 . +.Sh SEE ALSO +.Xr time 1 , +.Xr clock_gettime 2 , +.Xr getrusage 2 , +.Xr wait 2 +.Sh STANDARDS +The +.Fn times +function conforms to +.St -p1003.1-88 . +.Sh HISTORY +A +.Fn times +function first appeared in +.At v3 . diff --git a/static/openbsd/man3/timespec_get.3 b/static/openbsd/man3/timespec_get.3 new file mode 100644 index 00000000..b53a2a62 --- /dev/null +++ b/static/openbsd/man3/timespec_get.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: timespec_get.3,v 1.3 2018/10/31 17:05:54 deraadt Exp $ +.\" $NetBSD: timespec_get.3,v 1.4 2018/08/13 06:08:48 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 $Mdocdate: October 31 2018 $ +.Dt TIMESPEC_GET 3 +.Os +.Sh NAME +.Nm timespec_get +.Nd get current calendar time +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn timespec_get "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 . +.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 +.Ox , +this corresponds to +.Dv CLOCK_REALTIME . +.Sh RETURN VALUES +The +.Nm +function returns the passed value of +.Fa base +if successful, otherwise +.Dv 0 +on failure. +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr gettimeofday 2 , +.Xr time 3 +.Sh STANDARDS +The +.Nm +function with a +.Fa base +of +.Dv TIME_UTC +conforms to +.St -isoC-2011 . +.Sh HISTORY +The +.Fn timespec_get +function was ported from +.Nx +and first appeared in +.Ox 6.5 . diff --git a/static/openbsd/man3/timingsafe_bcmp.3 b/static/openbsd/man3/timingsafe_bcmp.3 new file mode 100644 index 00000000..00da7691 --- /dev/null +++ b/static/openbsd/man3/timingsafe_bcmp.3 @@ -0,0 +1,87 @@ +.\" $OpenBSD: timingsafe_bcmp.3,v 1.2 2014/06/21 20:22:15 tedu Exp $ +.\" +.\" Copyright (c) 2014 Google 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 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: June 21 2014 $ +.Dt TIMINGSAFE_BCMP 3 +.Os +.Sh NAME +.Nm timingsafe_bcmp , +.Nm timingsafe_memcmp +.Nd timing-safe byte sequence comparisons +.Sh SYNOPSIS +.In string.h +.Ft int +.Fn timingsafe_bcmp "const void *b1" "const void *b2" "size_t len" +.Ft int +.Fn timingsafe_memcmp "const void *b1" "const void *b2" "size_t len" +.Sh DESCRIPTION +The +.Fn timingsafe_bcmp +and +.Fn timingsafe_memcmp +functions lexicographically compare the first +.Fa len +bytes (each interpreted as an +.Vt unsigned char ) +pointed to by +.Fa b1 +and +.Fa b2 . +.Pp +Additionally, their running times are independent of the byte sequences compared, +making them safe to use for comparing secret values such as cryptographic MACs. +In contrast, +.Xr bcmp 3 +and +.Xr memcmp 3 +may short-circuit after finding the first differing byte. +.Sh RETURN VALUES +The +.Fn timingsafe_bcmp +function returns 0 or not zero if the byte sequence pointed to by +.Fa b1 +compares equal to or not equal to (respectively) +the byte sequence pointed to by +.Fa b2 . +.Pp +The +.Fn timingsafe_memcmp +function returns a negative value, 0, or positive value if the byte sequence +pointed to by +.Fa b1 +compares less than, equal to, or greater than (respectively) +the byte sequence pointed to by +.Fa b2 . +.Sh SEE ALSO +.Xr bcmp 3 , +.Xr memcmp 3 +.Sh STANDARDS +The +.Fn timingsafe_bcmp +and +.Fn timingsafe_memcmp +functions are +.Ox +extensions. +.Sh HISTORY +The +.Fn timingsafe_bcmp +function first appeared in +.Ox 4.9 . +.Pp +The +.Fn timingsafe_memcmp +function first appeared in +.Ox 5.6 . diff --git a/static/openbsd/man3/tls_accept_socket.3 b/static/openbsd/man3/tls_accept_socket.3 new file mode 100644 index 00000000..8922708e --- /dev/null +++ b/static/openbsd/man3/tls_accept_socket.3 @@ -0,0 +1,108 @@ +.\" $OpenBSD: tls_accept_socket.3,v 1.5 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2015 Ted Unangst +.\" Copyright (c) 2015 Joel Sing +.\" Copyright (c) 2016 Brent Cook +.\" +.\" 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: July 7 2025 $ +.Dt TLS_ACCEPT_SOCKET 3 +.Os +.Sh NAME +.Nm tls_accept_socket , +.Nm tls_accept_fds , +.Nm tls_accept_cbs +.Nd accept an incoming client connection in a TLS server +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft int +.Fo tls_accept_socket +.Fa "struct tls *tls" +.Fa "struct tls **cctx" +.Fa "int socket" +.Fc +.Ft int +.Fo tls_accept_fds +.Fa "struct tls *tls" +.Fa "struct tls **cctx" +.Fa "int fd_read" +.Fa "int fd_write" +.Fc +.Ft int +.Fo tls_accept_cbs +.Fa "struct tls *tls" +.Fa "struct tls **cctx" +.Fa "ssize_t (*tls_read_cb)(struct tls *ctx,\ + void *buf, size_t buflen, void *cb_arg)" +.Fa "ssize_t (*tls_write_cb)(struct tls *ctx,\ + const void *buf, size_t buflen, void *cb_arg)" +.Fa "void *cb_arg" +.Fc +.Sh DESCRIPTION +After creating a TLS server context +.Fa tls +with +.Xr tls_server 3 +and configuring it with +.Xr tls_configure 3 , +a server can accept a new client connection by calling +.Fn tls_accept_socket +on an already established socket connection. +.Pp +Alternatively, a new client connection can be accepted over a pair of existing +file descriptors by calling +.Fn tls_accept_fds . +.Pp +Calling +.Fn tls_accept_cbs +allows read and write callback functions to handle data transfers. +The specified +.Fa cb_arg +parameter is passed back to the functions, +and can contain a pointer to any caller-specified data. +.Pp +All these functions create a new context suitable for reading and writing +and return it in +.Pf * Fa cctx . +.Sh RETURN VALUES +These functions return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_close 3 , +.Xr tls_config_set_session_id 3 , +.Xr tls_configure 3 , +.Xr tls_connect 3 , +.Xr tls_init 3 , +.Xr tls_server 3 +.Sh HISTORY +.Fn tls_accept_socket +appeared in +.Ox 5.6 +and got its final name in +.Ox 5.7 . +.Pp +.Fn tls_accept_fds +appeared in +.Ox 5.8 +and +.Fn tls_accept_cbs +in +.Ox 6.1 . +.Sh AUTHORS +.An Joel Sing Aq Mt jsing@openbsd.org +.Pp +.An -nosplit +.Fn tls_accept_cbs +was written by +.An Tobias Pape Aq Mt tobias@netshed.de . diff --git a/static/openbsd/man3/tls_client.3 b/static/openbsd/man3/tls_client.3 new file mode 100644 index 00000000..235c7795 --- /dev/null +++ b/static/openbsd/man3/tls_client.3 @@ -0,0 +1,111 @@ +.\" $OpenBSD: tls_client.3,v 1.5 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2014 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 $Mdocdate: July 7 2025 $ +.Dt TLS_CLIENT 3 +.Os +.Sh NAME +.Nm tls_client , +.Nm tls_server , +.Nm tls_configure , +.Nm tls_reset , +.Nm tls_free +.Nd configure a TLS connection +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft struct tls * +.Fn tls_client void +.Ft struct tls * +.Fn tls_server void +.Ft int +.Fo tls_configure +.Fa "struct tls *ctx" +.Fa "struct tls_config *config" +.Fc +.Ft void +.Fn tls_free "struct tls *ctx" +.Ft void +.Fn tls_reset "struct tls *ctx" +.Sh DESCRIPTION +A TLS connection is represented as a +.Vt struct tls +object called a +.Dq context . +A new context is created by either the +.Fn tls_client +or +.Fn tls_server +functions. +.Fn tls_client +is used in TLS client programs, +.Fn tls_server +in TLS server programs. +.Pp +The context can then be configured with the function +.Fn tls_configure . +The same +.Vt tls_config +object can be used to configure multiple contexts. +.Pp +After configuration, +.Xr tls_connect 3 +can be called on objects created with +.Fn tls_client , +and +.Xr tls_accept_socket 3 +on objects created with +.Fn tls_server . +.Pp +After use, a TLS context should be closed with +.Xr tls_close 3 , +and then freed by calling +.Fn tls_free . +If +.Fn tls_free +is called with an argument of +.Dv NULL , +no action occurs. +.Pp +A TLS context can be reset by calling +.Fn tls_reset , +allowing for it to be reused. +This is essentially equivalent to calling +.Fn tls_free , +followed by a call to the same function that was used to originally allocate +the TLS context. +.Sh RETURN VALUES +.Fn tls_client +and +.Fn tls_server +return +.Dv NULL +on error or an out of memory condition. +.Pp +.Fn tls_configure +returns 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_config_new 3 , +.Xr tls_connect 3 , +.Xr tls_init 3 +.Sh HISTORY +These functions appeared in +.Ox 5.6 +and got their final names in +.Ox 5.7 . +.Sh AUTHORS +.An Joel Sing Aq Mt jsing@openbsd.org diff --git a/static/openbsd/man3/tls_config_ocsp_require_stapling.3 b/static/openbsd/man3/tls_config_ocsp_require_stapling.3 new file mode 100644 index 00000000..d776b61a --- /dev/null +++ b/static/openbsd/man3/tls_config_ocsp_require_stapling.3 @@ -0,0 +1,41 @@ +.\" $OpenBSD: tls_config_ocsp_require_stapling.3,v 1.6 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2016 Bob Beck +.\" +.\" 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: July 7 2025 $ +.Dt TLS_CONFIG_OCSP_REQUIRE_STAPLING 3 +.Os +.Sh NAME +.Nm tls_config_ocsp_require_stapling +.Nd OCSP configuration for libtls +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft void +.Fn tls_config_ocsp_require_stapling "struct tls_config *config" +.Sh DESCRIPTION +.Fn tls_config_ocsp_require_stapling +requires that a valid stapled OCSP response be provided +during the TLS handshake. +.Sh SEE ALSO +.Xr tls_config_add_keypair_file 3 , +.Xr tls_handshake 3 , +.Xr tls_init 3 , +.Xr tls_ocsp_process_response 3 +.Sh HISTORY +These functions appeared in +.Ox 6.1 . +.Sh AUTHORS +.An Bob Beck Aq Mt beck@openbsd.org diff --git a/static/openbsd/man3/tls_config_set_protocols.3 b/static/openbsd/man3/tls_config_set_protocols.3 new file mode 100644 index 00000000..403bc10b --- /dev/null +++ b/static/openbsd/man3/tls_config_set_protocols.3 @@ -0,0 +1,231 @@ +.\" $OpenBSD: tls_config_set_protocols.3,v 1.13 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" Copyright (c) 2015, 2016 Joel Sing +.\" Copyright (c) 2015 Bob Beck +.\" +.\" 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: July 7 2025 $ +.Dt TLS_CONFIG_SET_PROTOCOLS 3 +.Os +.Sh NAME +.Nm tls_config_set_protocols , +.Nm tls_config_parse_protocols , +.Nm tls_config_set_alpn , +.Nm tls_config_set_ciphers , +.Nm tls_config_set_dheparams , +.Nm tls_config_set_ecdhecurves , +.\" .Nm tls_config_set_ecdhecurve is intentionally undocumented. +.Nm tls_config_prefer_ciphers_client , +.Nm tls_config_prefer_ciphers_server +.Nd TLS protocol and cipher selection +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft int +.Fo tls_config_set_protocols +.Fa "struct tls_config *config" +.Fa "uint32_t protocols" +.Fc +.Ft int +.Fo tls_config_parse_protocols +.Fa "uint32_t *protocols" +.Fa "const char *protostr" +.Fc +.Ft int +.Fo tls_config_set_alpn +.Fa "struct tls_config *config" +.Fa "const char *alpn" +.Fc +.Ft int +.Fo tls_config_set_ciphers +.Fa "struct tls_config *config" +.Fa "const char *ciphers" +.Fc +.Ft int +.Fo tls_config_set_dheparams +.Fa "struct tls_config *config" +.Fa "const char *params" +.Fc +.Ft int +.Fo tls_config_set_ecdhecurves +.Fa "struct tls_config *config" +.Fa "const char *curves" +.Fc +.Ft void +.Fn tls_config_prefer_ciphers_client "struct tls_config *config" +.Ft void +.Fn tls_config_prefer_ciphers_server "struct tls_config *config" +.Sh DESCRIPTION +These functions modify a configuration by setting parameters. +The configuration options apply to both clients and servers, unless noted +otherwise. +.Pp +.Fn tls_config_set_protocols +specifies which versions of the TLS protocol may be used. +Possible values are the bitwise OR of: +.Pp +.Bl -item -offset indent -compact +.It +.Dv TLS_PROTOCOL_TLSv1_2 +.It +.Dv TLS_PROTOCOL_TLSv1_3 +.El +.Pp +Additionally, the values +.Dv TLS_PROTOCOL_TLSv1 +(TLSv1.2, TLSv1.3), +.Dv TLS_PROTOCOLS_ALL +(all supported protocols) and +.Dv TLS_PROTOCOLS_DEFAULT +(TLSv1.2 and TLSv1.3) may be used. +.Pp +The +.Fn tls_config_parse_protocols +utility function parses a protocol string and returns the corresponding +value via the +.Ar protocols +argument. +This value can then be passed to the +.Fn tls_config_set_protocols +function. +The protocol string is a comma or colon separated list of keywords. +Valid keywords are: +.Pp +.Bl -tag -width "tlsv1.3" -offset indent -compact +.It Dv tlsv1.2 +.It Dv tlsv1.3 +.It Dv all +.Pq all supported protocols +.It Dv default +.Pq an alias for Dv secure +.It Dv legacy +.Pq an alias for Dv all +.It Dv secure +.Pq currently TLSv1.2 and TLSv1.3 +.El +.Pp +If a value has a negative prefix (in the form of a leading exclamation mark) +then it is removed from the list of available protocols, rather than being +added to it. +.Pp +.Fn tls_config_set_alpn +sets the ALPN protocols that are supported. +The alpn string is a comma separated list of protocols, in order of preference. +.Pp +.Fn tls_config_set_ciphers +sets the list of ciphers that may be used. +Lists of ciphers are specified by name, and the +permitted names are: +.Pp +.Bl -item -offset indent -compact +.It +.Dv secure Pq or alias Dv default +.It +.Dv compat +.It +.Dv legacy +.It +.Dv insecure Pq or alias Dv all +.El +.Pp +Alternatively, libssl cipher strings can be specified. +See the CIPHERS section of +.Xr openssl 1 +for further information. +.Pp +.Fn tls_config_set_dheparams +specifies the parameters that will be used during Diffie-Hellman Ephemeral +(DHE) key exchange. +Possible values are: +.Pp +.Bl -item -offset indent -compact +.It +.Dv none +.It +.Dv auto +.It +.Dv legacy +.El +.Pp +In +.Dv auto +mode, the key size for the ephemeral key is automatically selected +based on the size of the private key being used for signing. +In +.Dv legacy +mode, 1024 bit ephemeral keys are used. +The default value is +.Dv none , +which disables DHE key exchange. +.Pp +.Fn tls_config_set_ecdhecurves +specifies the names of the elliptic curves that may be used during Elliptic +Curve Diffie-Hellman Ephemeral (ECDHE) key exchange. +This is a comma separated list, given in order of preference. +The special value of "default" will use the default curves (currently X25519, +P-256 and P-384). +This function replaces +.Fn tls_config_set_ecdhecurve , +which is deprecated. +.Pp +.Fn tls_config_prefer_ciphers_client +prefers ciphers in the client's cipher list when selecting a cipher suite +(server only). +This is considered to be less secure than preferring the server's list. +.Pp +.Fn tls_config_prefer_ciphers_server +prefers ciphers in the server's cipher list when selecting a cipher suite +(server only). +This is considered to be more secure than preferring the client's list and is +the default. +.Sh RETURN VALUES +These functions return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_config_set_session_id 3 , +.Xr tls_config_verify 3 , +.Xr tls_init 3 , +.Xr tls_load_file 3 +.Sh HISTORY +.Fn tls_config_set_ciphers +appeared in +.Ox 5.6 +and got its final name in +.Ox 5.7 . +.Pp +.Fn tls_config_set_protocols , +.Fn tls_config_parse_protocols , +.Fn tls_config_set_dheparams , +and +.Fn tls_config_set_ecdhecurve +appeared in +.Ox 5.7 , +.Fn tls_config_prefer_ciphers_client +and +.Fn tls_config_prefer_ciphers_server +in +.Ox 5.9 , +and +.Fn tls_config_set_alpn +in +.Ox 6.1 . +.Sh AUTHORS +.An Joel Sing Aq Mt jsing@openbsd.org +with contributions from +.An Ted Unangst Aq Mt tedu@openbsd.org +.Pq Fn tls_config_set_ciphers +and +.An Reyk Floeter Aq Mt reyk@openbsd.org +.Pq Fn tls_config_set_ecdhecurve diff --git a/static/openbsd/man3/tls_config_set_session_id.3 b/static/openbsd/man3/tls_config_set_session_id.3 new file mode 100644 index 00000000..a869b3f2 --- /dev/null +++ b/static/openbsd/man3/tls_config_set_session_id.3 @@ -0,0 +1,106 @@ +.\" $OpenBSD: tls_config_set_session_id.3,v 1.6 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2017 Claudio Jeker +.\" Copyright (c) 2018 Joel Sing +.\" +.\" 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: July 7 2025 $ +.Dt TLS_CONFIG_SET_SESSION_ID 3 +.Os +.Sh NAME +.Nm tls_config_set_session_fd , +.Nm tls_config_set_session_id , +.Nm tls_config_set_session_lifetime , +.Nm tls_config_add_ticket_key +.Nd configure resuming of TLS handshakes +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft int +.Fo tls_config_set_session_fd +.Fa "struct tls_config *config" +.Fa "int session_fd" +.Fc +.Ft int +.Fo tls_config_set_session_id +.Fa "struct tls_config *config" +.Fa "const unsigned char *session_id" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_session_lifetime +.Fa "struct tls_config *config" +.Fa "int lifetime" +.Fc +.Ft int +.Fo tls_config_add_ticket_key +.Fa "struct tls_config *config" +.Fa "uint32_t keyrev" +.Fa "unsigned char *key" +.Fa "size_t keylen" +.Fc +.Sh DESCRIPTION +.Fn tls_config_set_session_fd +sets a file descriptor to be used to manage data for TLS sessions (client only). +The given file descriptor must be a regular file and be owned by the current +user, with permissions being restricted to only allow the owner to read and +write the file (0600). +If the file has a non-zero length, the client will attempt to read session +data from this file and resume the previous TLS session with the server. +Upon a successful handshake the file will be updated with current session +data, if available. +The caller is responsible for closing this file descriptor, after all TLS +contexts that have been configured to use it have been freed via +.Fn tls_free . +.Pp +.Fn tls_config_set_session_id +sets the session identifier that will be used by the TLS server when +sessions are enabled (server only). +By default a random value is used. +.Pp +.Fn tls_config_set_session_lifetime +sets the lifetime to be used for TLS sessions (server only). +Session support is disabled if a lifetime of zero is specified, which is the +default. +.Pp +.Fn tls_config_add_ticket_key +adds a key used for the encryption and authentication of TLS tickets +(server only). +By default keys are generated and rotated automatically based on their lifetime. +This function should only be used to synchronise ticket encryption key across +multiple processes. +Re-adding a known key will result in an error, unless it is the most recently +added key. +.Sh RETURN VALUES +These functions return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_config_set_protocols 3 , +.Xr tls_init 3 , +.Xr tls_load_file 3 , +.Xr tls_server 3 +.Sh HISTORY +.Fn tls_config_set_session_id , +.Fn tls_config_set_session_lifetime +and +.Fn tls_config_add_ticket_key +appeared in +.Ox 6.1 . +.Pp +.Fn tls_config_set_session_fd +appeared in +.Ox 6.3 . +.Sh AUTHORS +.An Claudio Jeker Aq Mt claudio@openbsd.org +.An Joel Sing Aq Mt jsing@openbsd.org diff --git a/static/openbsd/man3/tls_config_verify.3 b/static/openbsd/man3/tls_config_verify.3 new file mode 100644 index 00000000..d5b29e85 --- /dev/null +++ b/static/openbsd/man3/tls_config_verify.3 @@ -0,0 +1,80 @@ +.\" $OpenBSD: tls_config_verify.3,v 1.5 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" Copyright (c) 2015 Joel Sing +.\" +.\" 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: July 7 2025 $ +.Dt TLS_CONFIG_VERIFY 3 +.Os +.Sh NAME +.Nm tls_config_verify , +.Nm tls_config_insecure_noverifycert , +.Nm tls_config_insecure_noverifyname , +.Nm tls_config_insecure_noverifytime +.Nd insecure TLS configuration +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft void +.Fn tls_config_verify "struct tls_config *config" +.Ft void +.Fn tls_config_insecure_noverifycert "struct tls_config *config" +.Ft void +.Fn tls_config_insecure_noverifyname "struct tls_config *config" +.Ft void +.Fn tls_config_insecure_noverifytime "struct tls_config *config" +.Sh DESCRIPTION +These functions disable parts of the normal certificate verification +process, resulting in insecure configurations. +Be very careful when using them. +.Pp +.Fn tls_config_insecure_noverifycert +disables certificate verification and OCSP validation. +.Pp +.Fn tls_config_insecure_noverifyname +disables server name verification (client only). +.Pp +.Fn tls_config_insecure_noverifytime +disables validity checking of certificates and OCSP validation. +.Pp +.Fn tls_config_verify +reenables server name and certificate verification. +.Sh SEE ALSO +.Xr tls_client 3 , +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_config_set_protocols 3 , +.Xr tls_conn_version 3 , +.Xr tls_connect 3 , +.Xr tls_handshake 3 , +.Xr tls_init 3 +.Sh HISTORY +.Fn tls_config_verify +appeared in +.Ox 5.6 +and got its final name in +.Ox 5.7 . +.Pp +.Fn tls_config_insecure_noverifycert +and +.Fn tls_config_insecure_noverifyname +appeared in +.Ox 5.7 +and +.Nm tls_config_insecure_noverifytime +in +.Ox 5.9 . +.Sh AUTHORS +.An Joel Sing Aq Mt jsing@openbsd.org +.An Ted Unangst Aq Mt tedu@openbsd.org diff --git a/static/openbsd/man3/tls_conn_version.3 b/static/openbsd/man3/tls_conn_version.3 new file mode 100644 index 00000000..3a386cf1 --- /dev/null +++ b/static/openbsd/man3/tls_conn_version.3 @@ -0,0 +1,226 @@ +.\" $OpenBSD: tls_conn_version.3,v 1.12 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2015 Bob Beck +.\" Copyright (c) 2016, 2018 Joel Sing +.\" +.\" 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: July 7 2025 $ +.Dt TLS_CONN_VERSION 3 +.Os +.Sh NAME +.Nm tls_conn_version , +.Nm tls_conn_cipher , +.Nm tls_conn_cipher_strength , +.Nm tls_conn_alpn_selected , +.Nm tls_conn_servername , +.Nm tls_conn_session_resumed , +.Nm tls_peer_cert_provided , +.Nm tls_peer_cert_contains_name , +.Nm tls_peer_cert_chain_pem , +.Nm tls_peer_cert_issuer , +.Nm tls_peer_cert_subject , +.Nm tls_peer_cert_common_name , +.Nm tls_peer_cert_hash , +.Nm tls_peer_cert_notbefore , +.Nm tls_peer_cert_notafter +.Nd inspect an established TLS connection +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft const char * +.Fn tls_conn_version "struct tls *ctx" +.Ft const char * +.Fn tls_conn_cipher "struct tls *ctx" +.Ft int +.Fn tls_conn_cipher_strength "struct tls *ctx" +.Ft const char * +.Fn tls_conn_alpn_selected "struct tls *ctx" +.Ft const char * +.Fn tls_conn_servername "struct tls *ctx" +.Ft int +.Fn tls_conn_session_resumed "struct tls *ctx" +.Ft int +.Fn tls_peer_cert_provided "struct tls *ctx" +.Ft int +.Fo tls_peer_cert_contains_name +.Fa "struct tls *ctx" +.Fa "const char *name" +.Fc +.Ft const uint8_t * +.Fo tls_peer_cert_chain_pem +.Fa "struct tls *ctx" +.Fa "size_t *size" +.Fc +.Ft const char * +.Fn tls_peer_cert_issuer "struct tls *ctx" +.Ft const char * +.Fn tls_peer_cert_subject "struct tls *ctx" +.Ft const char * +.Fn tls_peer_cert_common_name "struct tls *ctx" +.Ft const char * +.Fn tls_peer_cert_hash "struct tls *ctx" +.Ft time_t +.Fn tls_peer_cert_notbefore "struct tls *ctx" +.Ft time_t +.Fn tls_peer_cert_notafter "struct tls *ctx" +.Sh DESCRIPTION +These functions return information about a TLS connection and will only +succeed after the handshake is complete (the connection information applies +to both clients and servers, unless noted otherwise): +.Pp +.Fn tls_conn_version +returns a string corresponding to a TLS version negotiated with the peer +connected to +.Ar ctx . +.Pp +.Fn tls_conn_cipher +returns a string corresponding to the cipher suite negotiated with the peer +connected to +.Ar ctx . +.Pp +.Fn tls_conn_cipher_strength +returns the strength in bits for the symmetric cipher that is being +used with the peer connected to +.Ar ctx . +.Pp +.Fn tls_conn_alpn_selected +returns a string that specifies the ALPN protocol selected for use with the peer +connected to +.Ar ctx . +If no protocol was selected then NULL is returned. +.Pp +.Fn tls_conn_servername +returns a string corresponding to the servername that the client connected to +.Ar ctx +requested by sending a TLS Server Name Indication extension (server only). +.Pp +.Fn tls_conn_session_resumed +indicates whether a TLS session has been resumed during the handshake with +the server connected to +.Ar ctx +(client only). +.Pp +.Fn tls_peer_cert_provided +checks if the peer of +.Ar ctx +has provided a certificate. +.Pp +.Fn tls_peer_cert_contains_name +checks if the peer of a TLS +.Ar ctx +has provided a certificate that contains a +SAN or CN that matches +.Ar name . +.Pp +.Fn tls_peer_cert_chain_pem +returns a pointer to memory containing a PEM-encoded certificate chain for the +peer certificate from +.Ar ctx . +.Pp +.Fn tls_peer_cert_subject +returns a string +corresponding to the subject of the peer certificate from +.Ar ctx . +.Pp +.Fn tls_peer_cert_issuer +returns a string +corresponding to the issuer of the peer certificate from +.Ar ctx . +.Fn tls_peer_cert_common_name +returns a string +corresponding to the common name of the peer certificate from +.Ar ctx +or the empty string if no common name is present. +.Pp +.Fn tls_peer_cert_hash +returns a string +corresponding to a hash of the raw peer certificate from +.Ar ctx +prefixed by a hash name followed by a colon. +The hash currently used is SHA256, though this +could change in the future. +The hash string for a certificate in file +.Ar mycert.crt +can be generated using the commands: +.Bd -literal -offset indent +h=$(openssl x509 -outform der -in mycert.crt | sha256) +printf "SHA256:${h}\\n" +.Ed +.Pp +.Fn tls_peer_cert_notbefore +returns the time corresponding to the start of the validity period of +the peer certificate from +.Ar ctx . +.Pp +.Fn tls_peer_cert_notafter +returns the time corresponding to the end of the validity period of +the peer certificate from +.Ar ctx . +.Sh RETURN VALUES +The +.Fn tls_conn_session_resumed +function returns 1 if a TLS session was resumed or 0 if it was not. +.Pp +The +.Fn tls_peer_cert_provided +and +.Fn tls_peer_cert_contains_name +functions return 1 if the check succeeds or 0 if it does not. +.Pp +.Fn tls_peer_cert_notbefore +and +.Fn tls_peer_cert_notafter +return a time in epoch-seconds on success or -1 on error. +.Pp +The functions that return a pointer return +.Dv NULL +on error or an out of memory condition. +.Sh SEE ALSO +.Xr tls_configure 3 , +.Xr tls_handshake 3 , +.Xr tls_init 3 , +.Xr tls_ocsp_process_response 3 +.Sh HISTORY +.Fn tls_conn_version , +.Fn tls_conn_cipher , +.Fn tls_peer_cert_provided , +.Fn tls_peer_cert_contains_name , +.Fn tls_peer_cert_issuer , +.Fn tls_peer_cert_subject , +.Fn tls_peer_cert_hash , +.Fn tls_peer_cert_notbefore , +and +.Fn tls_peer_cert_notafter +appeared in +.Ox 5.9 . +.Pp +.Fn tls_conn_servername +and +.Fn tls_conn_alpn_selected +appeared in +.Ox 6.1 . +.Pp +.Fn tls_conn_session_resumed +appeared in +.Ox 6.3 . +.Pp +.Fn tls_conn_cipher_strength +appeared in +.Ox 6.7 . +.Fn tls_peer_cert_common_name +appeared in +.Ox 7.7 . +.Sh AUTHORS +.An Bob Beck Aq Mt beck@openbsd.org +.An Joel Sing Aq Mt jsing@openbsd.org diff --git a/static/openbsd/man3/tls_connect.3 b/static/openbsd/man3/tls_connect.3 new file mode 100644 index 00000000..95a18864 --- /dev/null +++ b/static/openbsd/man3/tls_connect.3 @@ -0,0 +1,145 @@ +.\" $OpenBSD: tls_connect.3,v 1.5 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" Copyright (c) 2014, 2015 Joel Sing +.\" Copyright (c) 2016 Brent Cook +.\" +.\" 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: July 7 2025 $ +.Dt TLS_CONNECT 3 +.Os +.Sh NAME +.Nm tls_connect , +.Nm tls_connect_fds , +.Nm tls_connect_servername , +.Nm tls_connect_socket , +.Nm tls_connect_cbs +.Nd instruct a TLS client to establish a connection +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft int +.Fo tls_connect +.Fa "struct tls *ctx" +.Fa "const char *host" +.Fa "const char *port" +.Fc +.Ft int +.Fo tls_connect_fds +.Fa "struct tls *ctx" +.Fa "int fd_read" +.Fa "int fd_write" +.Fa "const char *servername" +.Fc +.Ft int +.Fo tls_connect_servername +.Fa "struct tls *ctx" +.Fa "const char *host" +.Fa "const char *port" +.Fa "const char *servername" +.Fc +.Ft int +.Fo tls_connect_socket +.Fa "struct tls *ctx" +.Fa "int s" +.Fa "const char *servername" +.Fc +.Ft int +.Fo tls_connect_cbs +.Fa "struct tls *ctx" +.Fa "ssize_t (*tls_read_cb)(struct tls *ctx,\ + void *buf, size_t buflen, void *cb_arg)" +.Fa "ssize_t (*tls_write_cb)(struct tls *ctx,\ + const void *buf, size_t buflen, void *cb_arg)" +.Fa "void *cb_arg" +.Fa "const char *servername" +.Fc +.Sh DESCRIPTION +After creating a TLS client context with +.Xr tls_client 3 +and configuring it with +.Xr tls_configure 3 , +a client connection is initiated by calling +.Fn tls_connect . +This function will create a new socket, connect to the specified +.Fa host +and +.Fa port , +and then establish a secure connection. +The +.Fa port +may be numeric or a service name. +If it is +.Dv NULL , +then a +.Fa host +of the format "hostname:port" is permitted. +The name to use for verification is inferred from the +.Ar host +value. +.Pp +The +.Fn tls_connect_servername +function has the same behaviour, however the name to use for verification is +explicitly provided, for the case where the TLS server name differs from the +DNS name. +.Pp +An already existing socket can be upgraded to a secure connection by calling +.Fn tls_connect_socket . +.Pp +Alternatively, a secure connection can be established over a pair of existing +file descriptors by calling +.Fn tls_connect_fds . +.Pp +Calling +.Fn tls_connect_cbs +allows read and write callback functions to handle data transfers. +The specified cb_arg parameter is passed back to the functions, +and can contain a pointer to any caller-specified data. +.Sh RETURN VALUES +These functions return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_client 3 , +.Xr tls_close 3 , +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_configure 3 , +.Xr tls_handshake 3 , +.Xr tls_init 3 +.Sh HISTORY +.Fn tls_connect +and +.Fn tls_connect_socket +appeared in +.Ox 5.6 +and got their final names in +.Ox 5.7 . +.Pp +.Fn tls_connect_fds +and +.Fn tls_connect_servername +appeared in +.Ox 5.7 +and +.Fn tls_connect_cbs +in +.Ox 6.1 . +.Sh AUTHORS +.An Joel Sing Aq Mt jsing@openbsd.org +.An Reyk Floeter Aq Mt reyk@openbsd.org +.Pp +.An -nosplit +.Fn tls_connect_cbs +was written by +.An Tobias Pape Aq Mt tobias@netshed.de . diff --git a/static/openbsd/man3/tls_init.3 b/static/openbsd/man3/tls_init.3 new file mode 100644 index 00000000..69879c04 --- /dev/null +++ b/static/openbsd/man3/tls_init.3 @@ -0,0 +1,181 @@ +.\" $OpenBSD: tls_init.3,v 1.14 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" Copyright (c) 2016 Joel Sing +.\" Copyright (c) 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 $Mdocdate: July 7 2025 $ +.Dt TLS_INIT 3 +.Os +.Sh NAME +.Nm tls_init , +.Nm tls_config_new , +.Nm tls_config_free , +.Nm tls_config_error +.Nd initialize TLS client and server API +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft int +.Fn tls_init void +.Ft struct tls_config * +.Fn tls_config_new void +.Ft void +.Fn tls_config_free "struct tls_config *config" +.Ft const char * +.Fn tls_config_error "struct tls_config *config" +.Sh DESCRIPTION +The +.Nm tls +family of functions establishes a secure communications channel +using the TLS socket protocol. +Both clients and servers are supported. +.Pp +The +.Fn tls_init +function initializes global data structures. +It is no longer necessary to call this function directly, +since it is invoked internally when needed. +It may be called more than once, and may be called concurrently. +.Pp +Before a connection is created, a configuration must be created. +The +.Fn tls_config_new +function allocates, initializes, and returns a new default configuration +object that can be used for future connections. +Several functions exist to change the options of the configuration; see +.Xr tls_config_set_protocols 3 , +.Xr tls_load_file 3 , +.Xr tls_config_ocsp_require_stapling 3 , +and +.Xr tls_config_verify 3 . +.Pp +The +.Fn tls_config_error +function may be used to retrieve a string containing more information +about the most recent error relating to a configuration. +.Pp +A TLS connection object is created by +.Xr tls_client 3 +or +.Xr tls_server 3 +and configured with +.Xr tls_configure 3 . +.Pp +A client connection is initiated after configuration by calling +.Xr tls_connect 3 . +A server can accept a new client connection by calling +.Xr tls_accept_socket 3 +on an already established socket connection. +.Pp +Two functions are provided for input and output, +.Xr tls_read 3 +and +.Xr tls_write 3 . +Both automatically perform the +.Xr tls_handshake 3 +when needed. +.Pp +The properties of established TLS connections +can be inspected with the functions described in +.Xr tls_conn_version 3 +and +.Xr tls_ocsp_process_response 3 . +.Pp +After use, a TLS connection should be closed with +.Xr tls_close 3 +and then freed by calling +.Xr tls_free 3 . +.Pp +When no more contexts are to be configured, +the configuration object should be freed by calling +.Fn tls_config_free . +It is safe to call +.Fn tls_config_free +as soon as the final call to +.Fn tls_configure +has been made. +If +.Fa config +is +.Dv NULL , +no action occurs. +.Sh RETURN VALUES +.Fn tls_init +returns 0 on success or -1 on error. +.Pp +.Fn tls_config_new +returns +.Dv NULL +on error or an out of memory condition. +.Pp +.Fn tls_config_error +returns +.Dv NULL +if no error occurred with +.Fa config +at all, or if memory allocation failed while trying to assemble the +string describing the most recent error related to +.Fa config . +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_client 3 , +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_config_set_protocols 3 , +.Xr tls_config_verify 3 , +.Xr tls_conn_version 3 , +.Xr tls_connect 3 , +.Xr tls_load_file 3 , +.Xr tls_ocsp_process_response 3 , +.Xr tls_read 3 +.Sh HISTORY +The +.Nm tls +API first appeared in +.Ox 5.6 +as a response to the unnecessary challenges other APIs present in +order to use them safely. +.Pp +All functions were renamed from +.Fn ressl_* +to +.Fn tls_* +for +.Ox 5.7 . +.Pp +.Fn tls_config_error +appeared in +.Ox 6.0 . +.Sh AUTHORS +.An Joel Sing Aq Mt jsing@openbsd.org +.An Ted Unangst Aq Mt tedu@openbsd.org +.Pp +Many others contributed to various parts of the library; see the +individual manual pages for more information. +.Sh CAVEATS +The function +.Fn tls_config_error +returns an internal pointer. +It must not be freed by the application, or a double free error +will occur. +The pointer will become invalid when the next error occurs with +.Fa config . +Consequently, if the application may need the message at a later +time, it has to copy the string before calling the next +.Sy libtls +function involving +.Fa config , +or a segmentation fault or read access to unintended data is the +likely result. diff --git a/static/openbsd/man3/tls_load_file.3 b/static/openbsd/man3/tls_load_file.3 new file mode 100644 index 00000000..33f486d5 --- /dev/null +++ b/static/openbsd/man3/tls_load_file.3 @@ -0,0 +1,370 @@ +.\" $OpenBSD: tls_load_file.3,v 1.15 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst +.\" Copyright (c) 2015 Reyk Floeter +.\" Copyright (c) 2015 Bob Beck +.\" Copyright (c) 2016, 2017 Joel Sing +.\" +.\" 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: July 7 2025 $ +.Dt TLS_LOAD_FILE 3 +.Os +.Sh NAME +.Nm tls_load_file , +.Nm tls_unload_file , +.Nm tls_config_set_ca_file , +.Nm tls_config_set_ca_path , +.Nm tls_config_set_ca_mem , +.Nm tls_config_set_cert_file , +.Nm tls_config_set_cert_mem , +.Nm tls_config_set_crl_file , +.Nm tls_config_set_crl_mem , +.Nm tls_config_set_key_file , +.Nm tls_config_set_key_mem , +.Nm tls_config_set_ocsp_staple_mem , +.Nm tls_config_set_ocsp_staple_file , +.Nm tls_config_set_keypair_file , +.Nm tls_config_set_keypair_mem , +.Nm tls_config_set_keypair_ocsp_file , +.Nm tls_config_set_keypair_ocsp_mem , +.Nm tls_config_add_keypair_file , +.Nm tls_config_add_keypair_ocsp_mem , +.Nm tls_config_add_keypair_ocsp_file , +.Nm tls_config_add_keypair_mem , +.Nm tls_config_clear_keys , +.Nm tls_config_set_verify_depth , +.Nm tls_config_verify_client , +.Nm tls_config_verify_client_optional , +.Nm tls_default_ca_cert_file +.Nd TLS certificate and key configuration +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft uint8_t * +.Fo tls_load_file +.Fa "const char *file" +.Fa "size_t *len" +.Fa "char *password" +.Fc +.Ft void +.Fo tls_unload_file +.Fa "uint8_t *buf" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_ca_file +.Fa "struct tls_config *config" +.Fa "const char *ca_file" +.Fc +.Ft int +.Fo tls_config_set_ca_path +.Fa "struct tls_config *config" +.Fa "const char *ca_path" +.Fc +.Ft int +.Fo tls_config_set_ca_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *cert" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_cert_file +.Fa "struct tls_config *config" +.Fa "const char *cert_file" +.Fc +.Ft int +.Fo tls_config_set_cert_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *cert" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_crl_file +.Fa "struct tls_config *config" +.Fa "const char *crl_file" +.Fc +.Ft int +.Fo tls_config_set_crl_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *crl" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_key_file +.Fa "struct tls_config *config" +.Fa "const char *key_file" +.Fc +.Ft int +.Fo tls_config_set_key_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *key" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_ocsp_staple_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *staple" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_ocsp_staple_file +.Fa "struct tls_config *config" +.Fa "const char *staple_file" +.Fc +.Ft int +.Fo tls_config_set_keypair_file +.Fa "struct tls_config *config" +.Fa "const char *cert_file" +.Fa "const char *key_file" +.Fc +.Ft int +.Fo tls_config_set_keypair_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *cert" +.Fa "size_t cert_len" +.Fa "const uint8_t *key" +.Fa "size_t key_len" +.Fc +.Ft int +.Fo tls_config_set_keypair_ocsp_file +.Fa "struct tls_config *config" +.Fa "const char *cert_file" +.Fa "const char *key_file" +.Fa "const char *staple_file" +.Fc +.Ft int +.Fo tls_config_set_keypair_ocsp_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *cert" +.Fa "size_t cert_len" +.Fa "const uint8_t *key" +.Fa "size_t key_len" +.Fa "const uint8_t *staple" +.Fa "size_t staple_len" +.Fc +.Ft int +.Fo tls_config_add_keypair_file +.Fa "struct tls_config *config" +.Fa "const char *cert_file" +.Fa "const char *key_file" +.Fc +.Ft int +.Fo tls_config_add_keypair_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *cert" +.Fa "size_t cert_len" +.Fa "const uint8_t *key" +.Fa "size_t key_len" +.Fc +.Ft int +.Fo tls_config_add_keypair_ocsp_file +.Fa "struct tls_config *config" +.Fa "const char *cert_file" +.Fa "const char *key_file" +.Fa "const char *staple_file" +.Fc +.Ft int +.Fo tls_config_add_keypair_ocsp_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *cert" +.Fa "size_t cert_len" +.Fa "const uint8_t *key" +.Fa "size_t key_len" +.Fa "const uint8_t *staple" +.Fa "size_t staple_len" +.Fc +.Ft void +.Fn tls_config_clear_keys "struct tls_config *config" +.Ft int +.Fo tls_config_set_verify_depth +.Fa "struct tls_config *config" +.Fa "int verify_depth" +.Fc +.Ft void +.Fn tls_config_verify_client "struct tls_config *config" +.Ft void +.Fn tls_config_verify_client_optional "struct tls_config *config" +.Ft const char * +.Fn tls_default_ca_cert_file "void" +.Sh DESCRIPTION +.Fn tls_load_file +loads a certificate or key from disk into memory to be used with +.Fn tls_config_set_ca_mem , +.Fn tls_config_set_cert_mem , +.Fn tls_config_set_crl_mem +or +.Fn tls_config_set_key_mem . +A private key will be decrypted if the optional +.Ar password +argument is specified. +.Pp +.Fn tls_unload_file +unloads the memory that was returned from an earlier +.Fn tls_load_file +call, ensuring that the memory contents is discarded. +.Pp +.Fn tls_default_ca_cert_file +returns the path of the file that contains the default root certificates. +.Pp +.Fn tls_config_set_ca_file +loads a file containing the root certificates. +.Pp +.Fn tls_config_set_ca_path +sets the path (directory) which should be searched for root +certificates. +.Pp +.Fn tls_config_set_ca_mem +sets the root certificates directly from memory. +.Pp +.Fn tls_config_set_cert_file +loads a file containing the public certificate. +.Pp +.Fn tls_config_set_cert_mem +sets the public certificate directly from memory. +.Pp +.Fn tls_config_set_crl_file +loads a file containing the Certificate Revocation List (CRL). +.Pp +.Fn tls_config_set_crl_mem +sets the CRL directly from memory. +.Pp +.Fn tls_config_set_key_file +loads a file containing the private key. +.Pp +.Fn tls_config_set_key_mem +directly sets the private key from memory. +.Pp +.Fn tls_config_set_ocsp_staple_file +loads a file containing a DER-encoded OCSP response to be stapled +during the TLS handshake. +.Pp +.Fn tls_config_set_ocsp_staple_mem +sets a DER-encoded OCSP response to be stapled during the TLS handshake from +memory. +.Pp +.Fn tls_config_set_keypair_file +loads two files from which the public certificate and private key will be read. +.Pp +.Fn tls_config_set_keypair_mem +directly sets the public certificate and private key from memory. +.Pp +.Fn tls_config_set_keypair_ocsp_file +loads three files containing the public certificate, private key, +and DER-encoded OCSP staple. +.Pp +.Fn tls_config_set_keypair_ocsp_mem +directly sets the public certificate, private key, and DER-encoded OCSP staple +from memory. +.Pp +.Fn tls_config_add_keypair_file +adds an additional public certificate and private key from the specified files, +used as an alternative certificate for Server Name Indication (server only). +.Pp +.Fn tls_config_add_keypair_mem +adds an additional public certificate and private key from memory, used as an +alternative certificate for Server Name Indication (server only). +.Pp +.Fn tls_config_add_keypair_ocsp_file +adds an additional public certificate, private key, and DER-encoded OCSP staple +from the specified files, used as an alternative certificate for Server Name +Indication (server only). +.Pp +.Fn tls_config_add_keypair_ocsp_mem +adds an additional public certificate, private key, and DER-encoded OCSP staple +from memory, used as an alternative certificate for Server Name Indication +(server only). +.Pp +.Fn tls_config_clear_keys +clears any secret keys from memory. +.Pp +.Fn tls_config_set_verify_depth +limits the number of intermediate certificates that will be followed during +certificate validation. +.Pp +.Fn tls_config_verify_client +enables client certificate verification, requiring the client to send +a certificate (server only). +.Pp +.Fn tls_config_verify_client_optional +enables client certificate verification, without requiring the client +to send a certificate (server only). +.Sh RETURN VALUES +.Fn tls_load_file +returns +.Dv NULL +on error or an out of memory condition. +.Pp +The other functions return 0 on success or -1 on error. +.Sh SEE ALSO +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_config_set_protocols 3 , +.Xr tls_config_set_session_id 3 , +.Xr tls_configure 3 , +.Xr tls_init 3 +.Sh HISTORY +.Fn tls_config_set_ca_file , +.Fn tls_config_set_ca_path , +.Fn tls_config_set_cert_file , +.Fn tls_config_set_cert_mem , +.Fn tls_config_set_key_file , +.Fn tls_config_set_key_mem , +and +.Fn tls_config_set_verify_depth +appeared in +.Ox 5.6 +and got their final names in +.Ox 5.7 . +.Pp +.Fn tls_load_file , +.Fn tls_config_set_ca_mem , +and +.Fn tls_config_clear_keys +appeared in +.Ox 5.7 . +.Pp +.Fn tls_config_verify_client +and +.Fn tls_config_verify_client_optional +appeared in +.Ox 5.9 . +.Pp +.Fn tls_config_set_keypair_file +and +.Fn tls_config_set_keypair_mem +appeared in +.Ox 6.0 , +and +.Fn tls_config_add_keypair_file +and +.Fn tls_config_add_keypair_mem +in +.Ox 6.1 . +.Pp +.Fn tls_config_set_crl_file +and +.Fn tls_config_set_crl_mem +appeared in +.Ox 6.2 . +.Sh AUTHORS +.An Joel Sing Aq Mt jsing@openbsd.org +with contributions from +.An Ted Unangst Aq Mt tedu@openbsd.org +and +.An Bob Beck Aq Mt beck@openbsd.org . +.Pp +.Fn tls_load_file +and +.Fn tls_config_set_ca_mem +were written by +.An Reyk Floeter Aq Mt reyk@openbsd.org . diff --git a/static/openbsd/man3/tls_ocsp_process_response.3 b/static/openbsd/man3/tls_ocsp_process_response.3 new file mode 100644 index 00000000..e7b57a68 --- /dev/null +++ b/static/openbsd/man3/tls_ocsp_process_response.3 @@ -0,0 +1,168 @@ +.\" $OpenBSD: tls_ocsp_process_response.3,v 1.7 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2016 Bob Beck +.\" +.\" 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: July 7 2025 $ +.Dt TLS_OCSP_PROCESS_RESPONSE 3 +.Os +.Sh NAME +.Nm tls_ocsp_process_response , +.Nm tls_peer_ocsp_url , +.Nm tls_peer_ocsp_response_status , +.Nm tls_peer_ocsp_cert_status , +.Nm tls_peer_ocsp_crl_reason , +.Nm tls_peer_ocsp_result , +.Nm tls_peer_ocsp_revocation_time , +.Nm tls_peer_ocsp_this_update , +.Nm tls_peer_ocsp_next_update +.Nd inspect an OCSP response +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft int +.Fo tls_ocsp_process_response +.Fa "struct tls *ctx" +.Fa "const unsigned char *response" +.Fa "size_t size" +.Fc +.Ft const char * +.Fn tls_peer_ocsp_url "struct tls *ctx" +.Ft int +.Fn tls_peer_ocsp_response_status "struct tls *ctx" +.Ft int +.Fn tls_peer_ocsp_cert_status "struct tls *ctx" +.Ft int +.Fn tls_peer_ocsp_crl_reason "struct tls *ctx" +.Ft const char * +.Fn tls_peer_ocsp_result "struct tls *ctx" +.Ft time_t +.Fn tls_peer_ocsp_revocation_time "struct tls *ctx" +.Ft time_t +.Fn tls_peer_ocsp_this_update "struct tls *ctx" +.Ft time_t +.Fn tls_peer_ocsp_next_update "struct tls *ctx" +.Sh DESCRIPTION +.Fn tls_ocsp_process_response +processes a raw OCSP response in +.Ar response +of size +.Ar size +to check the revocation status of the peer certificate from +.Ar ctx . +A successful return code of 0 indicates that the certificate +has not been revoked. +.Pp +.Fn tls_peer_ocsp_url +returns the URL for OCSP validation of the peer certificate from +.Ar ctx . +.Pp +The following functions return information about the peer certificate from +.Ar ctx +that was obtained by validating a stapled OCSP response during the handshake, +or via a previous call to +.Fn tls_ocsp_process_response . +.Pp +.Fn tls_peer_ocsp_response_status +returns the OCSP response status as per RFC 6960 section 2.3. +.Pp +.Fn tls_peer_ocsp_cert_status +returns the OCSP certificate status code as per RFC 6960 section 2.2. +.Pp +.Fn tls_peer_ocsp_crl_reason +returns the OCSP certificate revocation reason status code as per RFC 5280 +section 5.3.1. +.Pp +.Fn tls_peer_ocsp_result +returns a textual representation of the OCSP status code +returned by one of the previous three functions. +If the OCSP response was valid and the certificate was not +revoked, the string indicates the OCSP certificate status. +Otherwise, the string indicates +the OCSP certificate revocation reason or the OCSP error. +.Pp +.Fn tls_peer_ocsp_revocation_time +returns the OCSP revocation time. +.Pp +.Fn tls_peer_ocsp_this_update +returns the OCSP this update time. +.Pp +.Fn tls_peer_ocsp_next_update +returns the OCSP next update time. +.Sh RETURN VALUES +.Fn tls_ocsp_process_response +returns 0 on success or -1 on error. +.Pp +.Fn tls_peer_ocsp_url +and +.Fn tls_peer_ocsp_result +return +.Dv NULL +on error or an out of memory condition. +.Pp +The +.Fn tls_peer_ocsp_response_status +function returns one of +.Dv TLS_OCSP_RESPONSE_SUCCESSFUL , +.Dv TLS_OCSP_RESPONSE_MALFORMED , +.Dv TLS_OCSP_RESPONSE_INTERNALERROR , +.Dv TLS_OCSP_RESPONSE_TRYLATER , +.Dv TLS_OCSP_RESPONSE_SIGREQUIRED , +or +.Dv TLS_OCSP_RESPONSE_UNAUTHORIZED +on success or -1 on error. +.Pp +The +.Fn tls_peer_ocsp_cert_status +function returns one of +.Dv TLS_OCSP_CERT_GOOD , +.Dv TLS_OCSP_CERT_REVOKED , +or +.Dv TLS_OCSP_CERT_UNKNOWN +on success, and -1 on error. +.Pp +The +.Fn tls_peer_ocsp_crl_reason +function returns one of +.Dv TLS_CRL_REASON_UNSPECIFIED , +.Dv TLS_CRL_REASON_KEY_COMPROMISE , +.Dv TLS_CRL_REASON_CA_COMPROMISE , +.Dv TLS_CRL_REASON_AFFILIATION_CHANGED , +.Dv TLS_CRL_REASON_SUPERSEDED , +.Dv TLS_CRL_REASON_CESSATION_OF_OPERATION , +.Dv TLS_CRL_REASON_CERTIFICATE_HOLD , +.Dv TLS_CRL_REASON_REMOVE_FROM_CRL , +.Dv TLS_CRL_REASON_PRIVILEGE_WITHDRAWN , +or +.Dv TLS_CRL_REASON_AA_COMPROMISE +on success or -1 on error. +.Pp +.Fn tls_peer_ocsp_revocation_time , +.Fn tls_peer_ocsp_this_update , +and +.Fn tls_peer_ocsp_next_update +return a time in epoch-seconds on success or -1 on error. +.Sh SEE ALSO +.Xr tls_client 3 , +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_conn_version 3 , +.Xr tls_connect 3 , +.Xr tls_handshake 3 , +.Xr tls_init 3 +.Sh HISTORY +These functions appeared in +.Ox 6.1 . +.Sh AUTHORS +.An Bob Beck Aq Mt beck@openbsd.org +.An Marko Kreen Aq Mt markokr@gmail.com diff --git a/static/openbsd/man3/tls_read.3 b/static/openbsd/man3/tls_read.3 new file mode 100644 index 00000000..f72e63cf --- /dev/null +++ b/static/openbsd/man3/tls_read.3 @@ -0,0 +1,241 @@ +.\" $OpenBSD: tls_read.3,v 1.9 2025/07/07 10:54:00 schwarze Exp $ +.\" +.\" Copyright (c) 2014, 2015 Ted Unangst +.\" Copyright (c) 2015 Doug Hogan +.\" Copyright (c) 2015 Joel Sing +.\" Copyright (c) 2015 Bob Beck +.\" Copyright (c) 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 $Mdocdate: July 7 2025 $ +.Dt TLS_READ 3 +.Os +.Sh NAME +.Nm tls_read , +.Nm tls_write , +.Nm tls_handshake , +.Nm tls_error , +.Nm tls_close +.Nd use a TLS connection +.Sh SYNOPSIS +.Lb libtls libssl libcrypto +.In tls.h +.Ft ssize_t +.Fo tls_read +.Fa "struct tls *ctx" +.Fa "void *buf" +.Fa "size_t buflen" +.Fc +.Ft ssize_t +.Fo tls_write +.Fa "struct tls *ctx" +.Fa "const void *buf" +.Fa "size_t buflen" +.Fc +.Ft int +.Fn tls_handshake "struct tls *ctx" +.Ft const char * +.Fn tls_error "struct tls *ctx" +.Ft int +.Fn tls_close "struct tls *ctx" +.Sh DESCRIPTION +.Fn tls_read +reads +.Fa buflen +bytes of data from the socket into +.Fa buf . +It returns the amount of data read. +.Pp +.Fn tls_write +writes +.Fa buflen +bytes of data from +.Fa buf +to the socket. +It returns the amount of data written. +.Pp +.Fn tls_handshake +explicitly performs the TLS handshake. +It is only necessary to call this function if you need to guarantee that the +handshake has completed, as both +.Fn tls_read +and +.Fn tls_write +automatically perform the TLS handshake when necessary. +.Pp +The +.Fn tls_error +function may be used to retrieve a string containing more information +about the most recent error relating to a context. +.Pp +.Fn tls_close +closes a connection after use. +Only the TLS layer will be shut down and the caller is responsible for closing +the file descriptors, unless the connection was established using +.Xr tls_connect 3 +or +.Xr tls_connect_servername 3 . +After closing the connection, +.Fa ctx +can be passed to +.Xr tls_free 3 . +.Sh RETURN VALUES +.Fn tls_read +and +.Fn tls_write +return a size on success or -1 on error. +.Pp +.Fn tls_handshake +and +.Fn tls_close +return 0 on success or -1 on error. +.Pp +The +.Fn tls_read , +.Fn tls_write , +.Fn tls_handshake , +and +.Fn tls_close +functions also have two special return values: +.Pp +.Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact +.It Dv TLS_WANT_POLLIN +The underlying read file descriptor needs to be readable in order to continue. +.It Dv TLS_WANT_POLLOUT +The underlying write file descriptor needs to be writeable in order to continue. +.El +.Pp +In the case of blocking file descriptors, the same function call should be +repeated immediately. +In the case of non-blocking file descriptors, the same function call should be +repeated when the required condition has been met. +.Pp +Callers of these functions cannot rely on the value of the global +.Ar errno . +To prevent mishandling of error conditions, +.Fn tls_read , +.Fn tls_write , +.Fn tls_handshake , +and +.Fn tls_close +all explicitly clear +.Ar errno . +.Pp +.Fn tls_error +returns +.Dv NULL +if no error occurred with +.Fa ctx +during or since the last call to +.Fn tls_handshake , +.Fn tls_read , +.Fn tls_write , +.Fn tls_close , +or +.Xr tls_reset 3 +involving +.Fa ctx , +or if memory allocation failed while trying to assemble the string +describing the most recent error related to +.Fa ctx . +.Sh EXAMPLES +The following example demonstrates how to handle TLS writes on a blocking +file descriptor: +.Bd -literal -offset indent +\&... +while (len > 0) { + ssize_t ret; + + ret = tls_write(ctx, buf, len); + if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT) + continue; + if (ret == -1) + errx(1, "tls_write: %s", tls_error(ctx)); + buf += ret; + len -= ret; +} +\&... +.Ed +.Pp +The following example demonstrates how to handle TLS writes on a +non-blocking file descriptor using +.Xr poll 2 : +.Bd -literal -offset indent +\&... +pfd[0].fd = fd; +pfd[0].events = POLLIN|POLLOUT; +while (len > 0) { + nready = poll(pfd, 1, 0); + if (nready == -1) + err(1, "poll"); + if ((pfd[0].revents & (POLLERR|POLLNVAL))) + errx(1, "bad fd %d", pfd[0].fd); + if ((pfd[0].revents & (pfd[0].events|POLLHUP))) { + ssize_t ret; + + ret = tls_write(ctx, buf, len); + if (ret == TLS_WANT_POLLIN) + pfd[0].events = POLLIN; + else if (ret == TLS_WANT_POLLOUT) + pfd[0].events = POLLOUT; + else if (ret == -1) + errx(1, "tls_write: %s", tls_error(ctx)); + else { + buf += ret; + len -= ret; + } + } +} +\&... +.Ed +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_configure 3 , +.Xr tls_conn_version 3 , +.Xr tls_connect 3 , +.Xr tls_init 3 , +.Xr tls_ocsp_process_response 3 +.Sh HISTORY +.Fn tls_read , +.Fn tls_write , +.Fn tls_error , +and +.Fn tls_close +appeared in +.Ox 5.6 +and got their final names in +.Ox 5.7 . +.Pp +.Fn tls_handshake +appeared in +.Ox 5.9 . +.Sh AUTHORS +.An Joel Sing Aq Mt jsing@openbsd.org +with contributions from +.An Bob Beck Aq Mt beck@openbsd.org +.Sh CAVEATS +The function +.Fn tls_error +returns an internal pointer. +It must not be freed by the application, or a double free error +will occur. +The pointer will become invalid when the next error occurs with +.Fa ctx . +Consequently, if the application may need the message at a later +time, it has to copy the string before calling the next +.Sy libtls +function involving +.Fa ctx , +or a segmentation fault or read access to unintended data is the +likely result. diff --git a/static/openbsd/man3/tmpnam.3 b/static/openbsd/man3/tmpnam.3 new file mode 100644 index 00000000..d1213246 --- /dev/null +++ b/static/openbsd/man3/tmpnam.3 @@ -0,0 +1,228 @@ +.\" $OpenBSD: tmpnam.3,v 1.23 2019/08/30 23:33:45 deraadt 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. +.\" +.Dd $Mdocdate: August 30 2019 $ +.Dt TMPNAM 3 +.Os +.Sh NAME +.Nm tempnam , +.Nm tmpfile , +.Nm tmpnam +.Nd temporary file routines +.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 value +.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 str +is non-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 str +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 non-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 non-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 null +pointer on error. +.Pp +The +.Fn tmpnam +and +.Fn tempnam +functions return a pointer to a file name on success, and a null pointer +on error. +.Sh ENVIRONMENT +.Bl -tag -width Ds +.It Ev TMPDIR +.Pf [ Fn tempnam +only] +If set, +the directory in which the temporary file is stored. +.Ev TMPDIR +is ignored for processes +for which +.Xr issetugid 2 +is true. +.El +.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 issetugid 2 , +.Xr mkstemp 3 , +.Xr mktemp 3 +.Sh STANDARDS +The +.Fn tmpfile +and +.Fn tmpnam +functions conform to +.St -ansiC . +.Sh BUGS +.Fn tmpnam +and +.Fn tempnam +are provided for System V and ANSI compatibility only. +These interfaces are typically not used in safe ways. +The +.Xr mkstemp 3 +interface is strongly preferred. +.Pp +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 System V implementations of these functions (and of +.Xr mktemp 3 ) +use the +.Xr access 2 +function to determine whether or not the temporary file may be created. +This has obvious ramifications for daemons or setuid/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 does not have these flaws, but portable software +cannot depend on that. +.Pp +For these reasons, +.Xr ld 1 +will output a warning message whenever it links code that uses the functions +.Fn tmpnam +or +.Fn tempnam . diff --git a/static/openbsd/man3/toascii.3 b/static/openbsd/man3/toascii.3 new file mode 100644 index 00000000..7ca0d148 --- /dev/null +++ b/static/openbsd/man3/toascii.3 @@ -0,0 +1,69 @@ +.\" $OpenBSD: toascii.3,v 1.8 2013/06/05 03:39:22 tedu Exp $ +.\" $NetBSD: toascii.3,v 1.2 1997/07/16 06:20:20 mikel 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 $Mdocdate: June 5 2013 $ +.Dt TOASCII 3 +.Os +.Sh NAME +.Nm toascii +.Nd convert a byte to 7-bit ASCII +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn toascii "int c" +.Sh DESCRIPTION +The +.Fn toascii +function strips all but the low 7 bits from a letter, +including parity or other marker bits. +.Sh RETURN VALUES +The +.Fn toascii +function always returns a valid ASCII character. +.Sh SEE ALSO +.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 isxdigit 3 , +.Xr stdio 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 diff --git a/static/openbsd/man3/tolower.3 b/static/openbsd/man3/tolower.3 new file mode 100644 index 00000000..dbc72882 --- /dev/null +++ b/static/openbsd/man3/tolower.3 @@ -0,0 +1,143 @@ +.\" $OpenBSD: tolower.3,v 1.15 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1989, 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt TOLOWER 3 +.Os +.Sh NAME +.Nm tolower , +.Nm tolower_l , +.Nm _tolower +.Nd upper case to lower case letter conversion +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn tolower "int c" +.Ft int +.Fn tolower_l "int c" "locale_t locale" +.Ft int +.Fn _tolower "int c" +.Sh DESCRIPTION +The +.Fn tolower +and +.Fn tolower_l +functions convert an upper-case letter to the corresponding lower-case +letter. +The +.Fn _tolower +function is identical to +.Fn tolower +except that +.Fa c +must be an upper-case letter. +.Pp +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +If the argument to the +.Fn tolower +or +.Fn tolower_l +function is an upper-case letter, the corresponding lower-case letter +is returned if there is one; otherwise the argument is returned unchanged. +If the argument to the +.Fn _tolower +function is an upper-case letter, the corresponding lower-case letter +is returned; otherwise the output is undefined. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +the results of +.Fn tolower +and +.Fn _tolower +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr toupper 3 , +.Xr towlower 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn tolower +and +.Fn _tolower +functions conform to +.St -ansiC , +and +.Fn tolower_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn tolower +function first appeared in +.At v7 +and acquired the current semantics in +.At III , +where +.Fn _tolower +first appeared. +.Pp +The +.Fn tolower_l +function has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/toupper.3 b/static/openbsd/man3/toupper.3 new file mode 100644 index 00000000..19eb7d8e --- /dev/null +++ b/static/openbsd/man3/toupper.3 @@ -0,0 +1,141 @@ +.\" $OpenBSD: toupper.3,v 1.17 2022/09/11 06:38:10 jmc Exp $ +.\" +.\" Copyright (c) 1989, 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt TOUPPER 3 +.Os +.Sh NAME +.Nm toupper , +.Nm toupper_l , +.Nm _toupper +.Nd lower case to upper case letter conversion +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn toupper "int c" +.Ft int +.Fn toupper_l "int c" "locale_t locale" +.Ft int +.Fn _toupper "int c" +.Sh DESCRIPTION +The +.Fn toupper +and +.Fn toupper_l +functions convert a lower-case letter to the corresponding +upper-case letter. +The +.Fn _toupper +function is identical to +.Fn toupper +except that +.Fa c +must be a lower-case letter. +.Pp +.Ox +always uses the C locale for these functions, +ignoring the global locale, the thread-specific locale, and the +.Fa locale +argument. +.Sh RETURN VALUES +If the argument to the +.Fn toupper +or +.Fn toupper_l +function is a lower-case letter, the corresponding upper-case letter +is returned if there is one; otherwise the argument is returned unchanged. +If the argument to the +.Fn _toupper +function is a lower-case letter, the corresponding upper-case letter +is returned; otherwise the output is undefined. +.Sh ENVIRONMENT +On systems supporting non-ASCII single-byte character encodings, +the results of +.Fn toupper +and +.Fn _toupper +may depend on the +.Ev LC_CTYPE +.Xr locale 1 . +.Sh SEE ALSO +.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 isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr towupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn toupper +function conforms to +.St -ansiC , +and +.Fn toupper_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn toupper +function first appeared in +.At v7 +and acquired the current semantics in +.At III , +where +.Fn _toupper +first appeared. +.Pp +The +.Fn toupper_l +function has been available since +.Ox 6.2 . +.Sh CAVEATS +The argument +.Fa c +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the result is undefined. diff --git a/static/openbsd/man3/towctrans.3 b/static/openbsd/man3/towctrans.3 new file mode 100644 index 00000000..399dff7c --- /dev/null +++ b/static/openbsd/man3/towctrans.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: towctrans.3,v 1.3 2017/09/05 03:16:13 schwarze Exp $ +.\" $NetBSD: towctrans.3,v 1.5 2004/01/24 16:58:54 wiz Exp $ +.\" +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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 $Mdocdate: September 5 2017 $ +.Dt TOWCTRANS 3 +.Os +.Sh NAME +.Nm towctrans , +.Nm towctrans_l +.Nd convert a wide character with a specified map +.Sh SYNOPSIS +.In wctype.h +.Ft wint_t +.Fn towctrans "wint_t wc" "wctrans_t charmap" +.Ft wint_t +.Fn towctrans_l "wint_t wc" "wctrans_t charmap" "locale_t locale" +.Sh DESCRIPTION +These functions convert the wide character +.Fa wc +with a character mapping +.Fa charmap . +.Pp +The behaviour is undefined if +.Fa charmap +or +.Fa wc +is invalid. +When +.Fa charmap +is retrieved with +.Xr wctrans 3 , +it becomes invalid when the thread-specific character encoding locale +is changed with +.Xr uselocale 3 +or when the global character encoding locale is changed with +.Xr setlocale 3 . +When +.Fa charmap +is retrieved with +.Xr wctrans_l 3 , +it is only valid for use with the same +.Fa locale +argument. +.Sh RETURN VALUES +These functions return the resulting wide character, or +.Fa wc +if there is no corresponding character in +.Fa charmap . +.Sh SEE ALSO +.Xr iswctype 3 , +.Xr newlocale 3 , +.Xr setlocale 3 , +.Xr towlower 3 , +.Xr wctrans 3 +.Sh STANDARDS +The +.Fn towctrans +function conforms to +.St -isoC-amd1 , +and +.Fn towctrans_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn towctrans +function has been available since +.Ox 3.8 , +and +.Fn towctrans_l +since +.Ox 6.2 . diff --git a/static/openbsd/man3/towlower.3 b/static/openbsd/man3/towlower.3 new file mode 100644 index 00000000..d4f9422e --- /dev/null +++ b/static/openbsd/man3/towlower.3 @@ -0,0 +1,121 @@ +.\" $OpenBSD: towlower.3,v 1.6 2017/09/05 03:16:13 schwarze Exp $ +.\" $NetBSD: towlower.3,v 1.7 2003/09/08 17:54:31 wiz 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 $Mdocdate: September 5 2017 $ +.Dt TOWLOWER 3 +.Os +.Sh NAME +.Nm towlower , +.Nm towlower_l , +.Nm towupper , +.Nm towupper_l +.Nd wide-character case letter conversion utilities +.Sh SYNOPSIS +.In wctype.h +.Ft wint_t +.Fn towlower "wint_t wc" +.Ft wint_t +.Fn towlower_l "wint_t wc" "locale_t locale" +.Ft wint_t +.Fn towupper "wint_t wc" +.Ft wint_t +.Fn towupper_l "wint_t wc" "locale_t locale" +.Sh DESCRIPTION +The +.Fn towlower +and +.Fn towlower_l +functions convert an upper-case wide character +to the corresponding lower-case letter. +The +.Fn towupper +and +.Fn towupper_l +functions convert a lower-case wide character +to the corresponding upper-case letter. +.Pp +The functions +.Fn towlower_l +and +.Fn towupper_l +use the specified +.Fa locale , +whereas +.Fn towlower +and +.Fn towupper +use the thread-specific locale set with +.Xr uselocale 3 , +falling back to the global locale set with +.Xr setlocale 3 . +.Sh RETURN VALUES +These functions return the corresponding character, if any. +Otherwise, +.Fa wc +is returned unchanged. +.Sh SEE ALSO +.Xr iswlower 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr towctrans 3 +.Sh STANDARDS +The functions +.Fn towlower +and +.Fn towupper +conform to +.St -isoC-amd1 +and +.St -isoC-99 , +and +.Fn towlower_l +and +.Fn towupper_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The functions +.Fn towlower +and +.Fn towupper +have been available since +.Ox 3.8 , +and +.Fn towlower_l +and +.Fn towupper_l +since +.Ox 6.2 . diff --git a/static/openbsd/man3/trunc.3 b/static/openbsd/man3/trunc.3 new file mode 100644 index 00000000..a7e5d1f8 --- /dev/null +++ b/static/openbsd/man3/trunc.3 @@ -0,0 +1,75 @@ +.\" $OpenBSD: trunc.3,v 1.9 2025/06/07 10:33:06 schwarze Exp $ +.\" +.\" Copyright (c) 2004, 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: src/lib/msun/man/trunc.3,v 1.3 2005/06/15 19:04:04 ru Exp $ +.\" +.Dd $Mdocdate: June 7 2025 $ +.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 SYNOPSIS +.Lb libm +.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 rounding towards zero mode. +.Sh SEE ALSO +.Xr ceil 3 , +.Xr fesetround 3 , +.Xr floor 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/openbsd/man3/tsearch.3 b/static/openbsd/man3/tsearch.3 new file mode 100644 index 00000000..a7ab9850 --- /dev/null +++ b/static/openbsd/man3/tsearch.3 @@ -0,0 +1,126 @@ +.\" $OpenBSD: tsearch.3,v 1.22 2022/03/31 17:27:16 naddy Exp $ +.\" +.\" Copyright (c) 1997 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. +.\" +.Dd $Mdocdate: March 31 2022 $ +.Dt TSEARCH 3 +.Os +.Sh NAME +.Nm tsearch , +.Nm tfind , +.Nm tdelete , +.Nm twalk +.Nd manipulate binary search trees +.Sh SYNOPSIS +.In search.h +.Ft void * +.Fn tdelete "const void *key" "void **rootp" "int (*compar)(const void *, const void *)" +.Ft void * +.Fn tfind "const void *key" "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 +.Dv 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. +If the node to be deleted is the root of the binary search tree, +.Fa rootp +will be adjusted and an unspecified non-null pointer will be returned. +It takes the same arguments as +.Fn tfind +and +.Fn tsearch . +.Pp +.Fn twalk +walks the binary search tree rooted in +.Fa 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 +.Dv NULL +if allocation of a new node fails (usually +due to a lack of free memory). +.Pp +.Fn tdelete +returns a pointer to the parent of the deleted node or an unspecified +non-null pointer if the root node is deleted. +.Pp +.Fn tfind , +.Fn tsearch , +and +.Fn tdelete +return +.Dv NULL +if +.Fa rootp +is +.Dv NULL +or the datum cannot be found. +.Sh SEE ALSO +.Xr bsearch 3 , +.Xr lsearch 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2008 . +.Sh CAVEATS +The value returned when deleting the root node was unspecified before +the +.St -p1003.1-2008 +standard, so users of the +.Fn tdelete +function should be wary of relying on a specific behaviour. diff --git a/static/openbsd/man3/ttyname.3 b/static/openbsd/man3/ttyname.3 new file mode 100644 index 00000000..94d50d84 --- /dev/null +++ b/static/openbsd/man3/ttyname.3 @@ -0,0 +1,176 @@ +.\" $OpenBSD: ttyname.3,v 1.20 2022/10/13 21:37:05 jmc 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. +.\" +.Dd $Mdocdate: October 13 2022 $ +.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 SYNOPSIS +.In unistd.h +.Ft char * +.Fn ttyname "int fd" +.Ft int +.Fn ttyname_r "int fd" "char *name" "size_t namesize" +.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 ) . +.Pp +The +.Fn isatty +function determines if the file descriptor +.Fa fd +refers to a valid +terminal type device. +.Pp +The +.Fn ttyname +and +.Fn ttyname_r +functions get the related device name of a file descriptor for which +.Fn isatty +is true. +The +.Fn ttyname_r +function stores the NUL-terminated +pathname of the terminal associated with +the file descriptor +.Fa fd +in the character array referenced by +.Fa name . +The array is +.Fa namesize +characters long and should have space for the name and the terminating +NUL character. +The maximum length of the terminal name is +.Dv TTY_NAME_MAX . +.Pp +The +.Fn ttyslot +function fetches the current process's controlling terminal number from +the +.Xr ttys 5 +file entry. +.Sh RETURN VALUES +The +.Fn ttyname +function returns the NUL-terminated name if the device is found and +.Fn isatty +is true; otherwise +a null pointer is returned and +.Va errno +is set to indicate the error. +.Pp +The +.Fn ttyname_r +function returns zero if successful; otherwise an error number is returned. +.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. +.It Bq Er ERANGE +The value of +.Fa namesize +is smaller than the length of the string to be returned including the +terminating NUL character. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr ttys 5 , +.Xr dev_mkdb 8 +.Sh HISTORY +The +.Fn isatty , +.Fn ttyname , +and +.Fn ttyslot +functions appeared in +.At v7 . +The +.Fn ttyname_r +function appeared in the POSIX Threads Extension (1003.1c-1995). +.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/openbsd/man3/tzset.3 b/static/openbsd/man3/tzset.3 new file mode 100644 index 00000000..ed1bc3e8 --- /dev/null +++ b/static/openbsd/man3/tzset.3 @@ -0,0 +1,377 @@ +.\" $OpenBSD: tzset.3,v 1.27 2025/06/23 13:53:11 millert Exp $ +.Dd $Mdocdate: June 23 2025 $ +.Dt TZSET 3 +.Os +.Sh NAME +.Nm tzset , +.Nm tzsetwall +.Nd initialize time conversion information +.Sh SYNOPSIS +.In time.h +.Vt extern char *tzname[2]; +.Vt extern long timezone; +.Vt extern long daylight; +.Ft void +.Fn tzset "void" +.Ft void +.Fn tzsetwall "void" +.Sh DESCRIPTION +The +.Fn tzset +function uses the value of the environment variable +.Ev TZ +to set the time conversion information used by +.Xr localtime 3 . +It also sets the following external variables: +.Bl -tag -width "tzname[2]" +.It Vt tzname[2] +the designations for standard and daylight saving time; see the description of +.Ar std No and Ar dst +below +.It Vt timezone +the number of seconds west of the Prime Meridian +.It Vt daylight +0 if the time zone has never observed daylight saving time, otherwise +non-zero +.El +.Pp +Most programs do not need to call +.Fn tzset +directly; it will be called automatically as needed by the functions +described in +.Xr localtime 3 . +Privileged processes that use +.Xr chroot 2 +may wish to call +.Fn tzset +to initialize the time conversion information before changing to +a restricted root directory that does not include time conversion +data files. +.Pp +If +.Ev TZ +does not appear in the environment, or if the calling process has +changed its user or group ID, the system time zone file, +.Pa /etc/localtime , +is used. +.Pp +If +.Ev TZ +appears in the environment it may be one of two formats: +.Bl -bullet +.It +the pathname of a +.Xr tzfile 5 +format file from which to read the time conversion information, +optionally prefixed with a colon +.Pq Ql \&: , +such as +.Dq :America/Denver +or +.Dq Europe/Berlin +.It +a string that directly specifies the time conversion information +(see below) which may not begin with a colon +.Pq Ql \&: +.El +.Pp +If +.Ev TZ +appears in the environment and its value does not begin with a colon, +it is first used as the +pathname of a +.Xr tzfile 5 +format 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. +A value beginning with a colon +.Pq Ql \&: +is always treated as a pathname. +.Pp +If +.Ev TZ +is set to the empty string, Universal Time (UT) is used, with the abbreviation +.Dq UTC +and without leap second correction; please see +.Xr ctime 3 +for more about UT, UTC, and leap seconds. +.Pp +When +.Ev TZ +is used as a pathname, it must either be a path relative to the system time +conversion information directory, +.Pa /usr/share/zoneinfo , +or an absolute path that begins with +.Pa /usr/share/zoneinfo/ . +Other absolute paths, or paths that contain +.Ql \&../ , +will be ignored and the system local time zone file, +.Pa /etc/localtime , +will be used instead. +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 (without whitespace between +.Ar std +and +.Ar offset ) : +.Bd -ragged -offset indent +.Ar std +.Sm off +.Ar offset +.Op Ar dst Op Ar offset +.Op , Ar rule +.Sm on +.Ed +.Pp +Where: +.Bl -tag -width "std and dst" +.It Ar std No and Ar dst +Three or more bytes that are the designation for the standard +.Pq Ar std +or the daylight saving +.Pq Ar dst +time zone. +Only +.Ar std +is required; if +.Ar 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 +.Pq Ql \&: , +digits, comma +.Pq Ql \&, , +minus +.Pq Ql \&- , +plus +.Pq Ql \&+ , +and ASCII NUL are allowed. +.It Ar offset +Indicates the value one must add to the local time to arrive at +Coordinated Universal Time. +.Ar offset +has the form: +.Pp +.D1 Ar hh Ns Op : Ns Ar mm Ns Op : Ns Ar ss +.Pp +The minutes +.Pq Ar mm +and seconds +.Pq Ar ss +are optional. +The hour +.Pq Ar hh +is required and may be a single digit. +The +.Ar offset +following +.Ar std +is required. +If no +.Ar offset +follows +.Ar 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) \(em if present \(em between zero and 59. +If preceded by a +.Dq \&- , +the time zone shall be east of the Prime Meridian; otherwise it shall be +west (which may be indicated by an optional preceding +.Dq \&+ ) . +.It Ar rule +Indicates when to change to and back from daylight saving time. +.Ar rule +has the form: +.Pp +.D1 Ar date Ns / Ns Ar time , Ns Ar date Ns / Ns Ar time +.Pp +where the first +.Ar date +describes when the change from standard to daylight saving time occurs and the +second +.Ar date +describes when the change back happens. +Each +.Ar 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. +.Pp +The format of +.Ar date +is one of the following: +.Bl -tag -width Ds +.It Cm J Ns Ar n +The Julian day +.Ar n +.Pq 1 <= Ar n No <= 365 . +Leap days are not counted; that is, in all years \(em including leap +years \(em 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 +.Pq 0 <= Ar n No <= 365 . +Leap days are counted, and it is possible to refer to February 29. +.It Cm M Ns Ar m . Ns Ar n . Ns Ar d +Day +.Ar d +.Pq 1 <= Ar d No <= 6 +of week +.Ar n +.Pq 1 <= Ar n No <= 5 +of month +.Ar m +.Pq 1 <= Ar m No <= 12 , +where week 5 means +.Do +the last +.Ar d +day in month +.Ar m +.Dc +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 +.Pp +The +.Ar time +has the same format as +.Ar offset +except that POSIX does not allow a leading sign +.Po +.Dq \&- +or +.Dq \&+ +.Pc . +As an extension to POSIX, the hours part of +.Ar 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 +.Ar time +is not given, is +.Cm 02:00:00 . +.El +.Pp +Here are some examples of +.Ev TZ +values that directly specify the time zone rules; +they use some of the extensions to POSIX. +.Bl -tag -width Ds +.It EST5 +stands for US Eastern Standard Time (EST), +5 hours behind UT, without daylight saving. +.It FJT\-12FJST,M10.3.1/146,M1.3.4/75 +stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours ahead +of UT, springing forward on October's third Monday at +146:00 (i.e., 02:00 on the first Sunday on or after October 21), and +falling back on January's third Thursday at 75:00 (i.e., 03:00 on the +first Sunday on or after January 18). +.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 +Tuesday 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 WART4WARST,J1/0,J365/25 +stands for Western Argentina Summer Time (WARST), 3 hours behind UT. +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 +.Dq WART +is a placeholder. +.It WGT3WGST,M3.5.0/\-2,M10.5.0/\-1 +stands for Western Greenland Time (WGT) and Western Greenland Summer +Time (WGST), 3 hours behind UT, where clocks follow the EU rules of +springing forward on March's last Sunday at 01:00 UT (\-02:00 local +time) and falling back on October's last Sunday at 01:00 UT +(\-01:00 local time). +.Pp +If no +.Ar rule +is present in +.Ev TZ , +the rules specified +by the +.Xr tzfile 5 +format +file +.Cm posixrules +in the system time conversion information directory are used, with the +standard and daylight saving time offsets from UT replaced by those +specified by the +.Ar offset +values in +.Ev TZ . +.Pp +For compatibility with System V Release 3.1, a semicolon +.Pq Ql \&; +may be used to separate the +.Ar rule +from the rest of the specification. +.Pp +If the +.Ev TZ +environment variable does not specify a +.Xr tzfile 5 +format file +and cannot be interpreted as a direct specification, +UT is used. +.Pp +.Fn tzsetwall +behaves identically to +.Fn tzset +but it only uses the +.Pa /etc/localtime +file (that is, it ignores the +.Ev TZ +environment variable). +.Sh FILES +.Bl -tag -width "/usr/share/zoneinfo/posixrules" -compact +.It Pa /usr/share/zoneinfo +time zone information directory +.It Pa /etc/localtime +local time zone file +.It Pa /usr/share/zoneinfo/posixrules +used with POSIX-style +.Ev TZ Ns s +.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-2008 . +The +.Fn tzsetwall +function is an extension to that specification. +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. diff --git a/static/openbsd/man3/ualarm.3 b/static/openbsd/man3/ualarm.3 new file mode 100644 index 00000000..d25eda22 --- /dev/null +++ b/static/openbsd/man3/ualarm.3 @@ -0,0 +1,108 @@ +.\" $OpenBSD: ualarm.3,v 1.18 2023/08/01 01:17:25 cheloha 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. +.\" +.Dd $Mdocdate: August 1 2023 $ +.Dt UALARM 3 +.Os +.Sh NAME +.Nm ualarm +.Nd schedule high resolution SIGALRM delivery +.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 schedules the +.Dv SIGALRM +signal for delivery to the calling process after at least the given number of +.Fa microseconds +have elapsed. +If +.Fa interval +is non-zero, +the +.Dv SIGALRM +signal is scheduled for redelivery to the calling process every +.Fa interval +microseconds thereafter. +.Pp +If an alarm is already pending, +an additional call to +.Fn ualarm +supersedes the prior call. +.Pp +If +.Fa microseconds +is zero, +any pending alarm is cancelled and the value of +.Fa interval +is ignored. +.Sh RETURN VALUES +The +.Fn ualarm +function returns the number of microseconds remaining until the next +alarm is scheduled for delivery, +or zero if no alarm is pending. +.Sh SEE ALSO +.Xr setitimer 2 , +.Xr sigaction 2 , +.Xr sigsuspend 2 , +.Xr alarm 3 , +.Xr signal 3 , +.Xr sleep 3 , +.Xr usleep 3 +.Sh STANDARDS +The +.Fn ualarm +function conforms to +.St -xpg4.2 . +.Sh HISTORY +The +.Fn ualarm +function first appeared in +.Bx 4.3 . +.Sh CAVEATS +The +.Fn ualarm +function is implemented with the per-process +.Dv ITIMER_REAL +timer described in +.Xr setitimer 2 . +Use of both +.Fn ualarm +and +.Xr setitimer 2 +in the same program may yield confusing behavior. diff --git a/static/openbsd/man3/uname.3 b/static/openbsd/man3/uname.3 new file mode 100644 index 00000000..03d24765 --- /dev/null +++ b/static/openbsd/man3/uname.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: uname.3,v 1.19 2023/10/09 19:32:51 schwarze 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. +.\" +.Dd $Mdocdate: October 9 2023 $ +.Dt UNAME 3 +.Os +.Sh NAME +.Nm uname +.Nd get system identification +.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 +.Vt utsname +structure is defined in the +.In sys/utsname.h +header file, and contains the following members: +.Pp +.Bl -tag -width nodenameXXXX -offset indent -compact +.It Fa sysname +Name of the operating system implementation. +.It Fa nodename +Network name of this machine. +.It Fa release +Release level of the operating system. +.It Fa version +Version level of the operating system. +.It Fa machine +Machine hardware platform. +.El +.Pp +These are the same strings that can be displayed with +.Xr uname 1 . +Because their format and meaning depends on the operating system, +trying to parse or interpret them is discouraged in portable code. +The only reasonable way an application program can use them +is for displaying them to the user. +.Sh RETURN VALUES +The +.Fn uname +function returns a non-negative value if successful; +otherwise the value -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn uname +function may fail and set +.Va errno +for any of the errors specified for the library function +.Xr sysctl 2 . +.Sh SEE ALSO +.Xr uname 1 , +.Xr sysctl 2 +.Sh STANDARDS +The +.Fn uname +function conforms to +.St -p1003.1-88 . +.Sh HISTORY +The +.Fn uname +function first appeared in PWB/UNIX 1.0 +and was reimplemented for +.Bx 4.4 . diff --git a/static/openbsd/man3/ungetc.3 b/static/openbsd/man3/ungetc.3 new file mode 100644 index 00000000..bf72d12a --- /dev/null +++ b/static/openbsd/man3/ungetc.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: ungetc.3,v 1.11 2022/09/11 06:38:11 jmc 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt UNGETC 3 +.Os +.Sh NAME +.Nm ungetc +.Nd un-get character from input stream +.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 +.Vt 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 , +.Xr ungetwc 3 +.Sh STANDARDS +The +.Fn ungetc +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn ungetc +function first appeared in +.At v7 . diff --git a/static/openbsd/man3/ungetwc.3 b/static/openbsd/man3/ungetwc.3 new file mode 100644 index 00000000..155ce5f2 --- /dev/null +++ b/static/openbsd/man3/ungetwc.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: ungetwc.3,v 1.6 2021/02/02 07:33:29 jmc Exp $ +.\" +.\" $NetBSD: ungetwc.3,v 1.7 2003/09/08 17:54:32 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. +.\" +.\" @(#)ungetc.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd $Mdocdate: February 2 2021 $ +.Dt UNGETWC 3 +.Os +.Sh NAME +.Nm ungetwc +.Nd un-get wide character from input stream +.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 , +.Xr ungetc 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/openbsd/man3/unvis.3 b/static/openbsd/man3/unvis.3 new file mode 100644 index 00000000..c9bdfa67 --- /dev/null +++ b/static/openbsd/man3/unvis.3 @@ -0,0 +1,195 @@ +.\" $OpenBSD: unvis.3,v 1.19 2022/07/30 07:19:30 jsg 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. +.\" +.Dd $Mdocdate: July 30 2022 $ +.Dt UNVIS 3 +.Os +.Sh NAME +.Nm unvis , +.Nm strunvis , +.Nm strnunvis +.Nd decode a visual representation of characters +.Sh SYNOPSIS +.In vis.h +.Ft int +.Fn unvis "char *cp" "char c" "int *astate" "int flag" +.Ft int +.Fn strunvis "char *dst" "const char *src" +.Ft ssize_t +.Fn strnunvis "char *dst" "const char *src" "size_t size" +.Sh DESCRIPTION +The +.Fn unvis , +.Fn strunvis +and +.Fn strnunvis +functions are used to decode a visual representation of characters, +as produced by the +.Xr vis 3 +function, back into the original form. +.Fn unvis +is called with successive characters in +.Fa c +until a valid +sequence is recognized, at which time the decoded character is +available at the character pointed to by +.Fa cp . +.Pp +.Fn strunvis +decodes the characters pointed to by +.Fa src +into the buffer pointed to by +.Fa dst . +.Pp +.Fn strnunvis +decodes the characters pointed to by +.Fa src +into the buffer pointed to by +.Fa dst , +writing a maximum of +.Fa size +bytes. +The +.Fn strunvis +function simply copies +.Fa src +to +.Fa dst , +decoding any escape sequences along the way, +and returns the number of characters placed into +.Fa dst , +or \-1 if an +invalid escape sequence was detected. +The size of +.Fa dst +should be +equal to the size of +.Fa src +(that is, no expansion takes place during decoding). +.Fn strunvis +terminates the destination string with a trailing NUL byte; +.Fn strnunvis +does so if +.Fa size +is larger than 0. +.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. +.Sh RETURN VALUES +The +.Fn unvis +function has several return codes that must be handled properly. +They are: +.Bl -tag -width UNVIS_VALIDPUSH +.It Li \&0 (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 +.Fa flag +set to +.Dv UNVIS_END +to extract any remaining character (the character passed in is ignored). +.Pp +The +.Fn strunvis +function returns the number of bytes written (not counting +the trailing NUL byte) or \-1 if an error occurred. +.Pp +The +.Fn strnunvis +function returns the number of bytes (not counting the trailing NUL byte) +that would be needed to fully convert the input string, or \-1 if an +error occurred. +.Sh EXAMPLES +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: + (void)fprintf(stderr, "bad sequence!\en"); + exit(1); + } +} +if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID) + (void) putchar(out); +.Ed +.Sh SEE ALSO +.Xr unvis 1 , +.Xr vis 1 , +.Xr vis 3 +.Sh HISTORY +The +.Fn unvis +function first appeared in +.Bx 4.3 Reno . diff --git a/static/openbsd/man3/usbhid.3 b/static/openbsd/man3/usbhid.3 new file mode 100644 index 00000000..63c66076 --- /dev/null +++ b/static/openbsd/man3/usbhid.3 @@ -0,0 +1,231 @@ +.\" $OpenBSD: usbhid.3,v 1.24 2025/06/06 21:38:27 schwarze Exp $ +.\" $NetBSD: usbhid.3,v 1.5 2002/02/07 07:00:52 ross Exp $ +.\" +.\" Copyright (c) 1999, 2001 Lennart Augustsson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 6 2025 $ +.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_get_report_desc_data , +.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_start , +.Nm hid_init , +.Nm hid_get_data , +.Nm hid_set_data +.Nd USB HID access routines +.Sh SYNOPSIS +.Lb libusbhid +.In usbhid.h +.Ft report_desc_t +.Fn hid_get_report_desc "int file" +.Ft report_desc_t +.Fn hid_use_report_desc "unsigned char *data" "unsigned int size" +.Ft void +.Fn hid_dispose_report_desc "report_desc_t d" +.Ft void +.Fn hid_get_report_desc_data "report_desc_t d" "uint8_t **data" "uint32_t *size" +.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 const char * +.Fn hid_usage_page "int i" +.Ft const 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 "char *file" +.Ft int +.Fn hid_start "char *file" +.Ft int32_t +.Fn hid_get_data "void *data" "hid_item_t *h" +.Ft void +.Fn hid_set_data "void *data" "hid_item_t *h" "int32_t data" +.Sh DESCRIPTION +The +.Nm +library provides routines to extract data from USB Human Interface Devices. +.Ss INTRODUCTION +USB HIDs 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 which can be accessed with +.Fn hid_get_report_desc_data . +When the report descriptor is no longer needed, it should be freed by calling +.Fn hid_dispose_report_desc . +The type +.Vt report_desc_t +is opaque and should be used when calling the parsing functions. +.Fn hid_get_report_desc +and +.Fn hid_use_report_desc +return +.Dv NULL +on failure. +.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 are interesting. +The +.Fa kindset +is obtained by OR'ing together values +.Pq 1 << Va k +where +.Va k +is an item of type +.Vt hid_kind_t . +The desired report ID, or \-1 +to obtain items of all report IDs, +is given by +.Fa id . +The function returns +.Dv 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 +.Vt 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_start +with the name of the table. +Passing +.Dv NULL +to this function will cause it to use the default table. +A return value of \-1 indicates that an error has occurred, and +.Va errno +is set. +.Ss DATA EXTRACTION FUNCTIONS +Given the data obtained from a HID 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 +The USB specifications can be found at: +.Lk https://www.usb.org/documents/ +.Pp +.Xr uhid 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +library first appeared in +.Ox 3.0 . +.Sh BUGS +This man page is woefully incomplete. diff --git a/static/openbsd/man3/uselocale.3 b/static/openbsd/man3/uselocale.3 new file mode 100644 index 00000000..9597af87 --- /dev/null +++ b/static/openbsd/man3/uselocale.3 @@ -0,0 +1,101 @@ +.\" $OpenBSD: uselocale.3,v 1.1 2017/09/05 03:16:13 schwarze Exp $ +.\" +.\" Copyright (c) 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 $Mdocdate: September 5 2017 $ +.Dt USELOCALE 3 +.Os +.Sh NAME +.Nm uselocale +.Nd select the locale for the current thread +.Sh SYNOPSIS +.In locale.h +.Ft locale_t +.Fo uselocale +.Fa "locale_t newloc" +.Fc +.Sh DESCRIPTION +The function +.Fn uselocale +selects +.Fa newloc +for use by functions in the current thread that do not take a +.Vt locale_t +argument. +Neither the global locale set by +.Xr setlocale 3 +nor locales used by other threads change. +.Pp +The current thread uses +.Fa newloc +until +.Fn uselocale +is called again successfully with a non-null argument +in the same thread, and passing +.Fa newloc +to +.Xr freelocale 3 +or +.Xr newlocale 3 +before that results in undefined behaviour. +.Pp +To revoke the use of +.Fa newloc +in the current thread without installing another thread-specific locale, +instead reverting to the global locale, call +.Fn uselocale +with the special argument +.Dv LC_GLOBAL_LOCALE . +.Pp +When called with the argument +.Po Vt locale_t Pc Ns 0 , +the thread-specific locale remains unchanged. +.Sh RETURN VALUES +The function +.Fn uselocale +returns the thread-specific locale which is in use right before the call, +or the special return value +.Dv LC_GLOBAL_LOCALE +if the thread used the global locale before the call. +.Sh ERRORS +The function +.Fn uselocale +fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa newloc +argument is neither a valid locale object nor +.Po Vt locale_t Pc Ns 0 . +.El +.Sh SEE ALSO +.Xr iswalnum 3 , +.Xr iswctype 3 , +.Xr newlocale 3 , +.Xr towctrans 3 , +.Xr towlower 3 , +.Xr wcscasecmp 3 , +.Xr wctrans 3 , +.Xr wctype 3 +.Sh STANDARDS +The function +.Fn uselocale +conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The function +.Fn uselocale +has been available since +.Ox 6.2 . diff --git a/static/openbsd/man3/user_from_uid.3 b/static/openbsd/man3/user_from_uid.3 new file mode 100644 index 00000000..b01c42e7 --- /dev/null +++ b/static/openbsd/man3/user_from_uid.3 @@ -0,0 +1,138 @@ +.\" $OpenBSD: user_from_uid.3,v 1.2 2022/08/05 00:53:57 jsg 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. +.\" +.Dd $Mdocdate: August 5 2022 $ +.Dt USER_FROM_UID 3 +.Os +.Sh NAME +.Nm user_from_uid , +.Nm uid_from_user , +.Nm group_from_gid , +.Nm gid_from_group +.Nd cache password and group entries +.Sh SYNOPSIS +.In pwd.h +.Ft int +.Fn uid_from_user "const char *name" "uid_t *uid" +.Ft const char * +.Fn user_from_uid "uid_t uid" "int nouser" +.In grp.h +.Ft int +.Fn gid_from_group "const char *name" "gid_t *gid" +.Ft const char * +.Fn group_from_gid "gid_t gid" "int nogroup" +.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 null pointer is returned. +.Pp +The +.Fn uid_from_user +function returns the user ID associated with the argument +.Fa name . +The user ID is cached so that multiple calls with the same +.Fa name +do not require additional calls to +.Xr getpwnam 3 . +If there is no user ID associated with the +.Fa name , +the +.Fn uid_from_user +function returns -1; +otherwise it stores the user ID at the location pointed to by +.Fa uid +and returns 0. +.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 null pointer is returned. +.Pp +The +.Fn gid_from_group +function returns the group ID associated with the argument +.Fa name . +The group ID is cached so that multiple calls with the same +.Fa name +do not require additional calls to +.Xr getgrnam 3 . +If there is no group ID associated with the +.Fa name , +the +.Fn gid_from_group +function returns -1; +otherwise it stores the group ID at the location pointed to by +.Fa gid +and returns 0. +.Sh SEE ALSO +.Xr getgrgid 3 , +.Xr getpwuid 3 +.Sh HISTORY +The +.Fn user_from_uid +and +.Fn group_from_gid +functions first appeared in +.Bx 4.3 Reno +in libutil and moved to libc in +.Bx 4.4 . +.Pp +The +.Fn uid_from_user +and +.Fn gid_from_group +functions were ported from +.Nx +and first appeared in +.Ox 6.4 . diff --git a/static/openbsd/man3/usleep.3 b/static/openbsd/man3/usleep.3 new file mode 100644 index 00000000..d61af712 --- /dev/null +++ b/static/openbsd/man3/usleep.3 @@ -0,0 +1,99 @@ +.\" $OpenBSD: usleep.3,v 1.19 2013/06/05 03:39:22 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt USLEEP 3 +.Os +.Sh NAME +.Nm usleep +.Nd suspend process execution for interval measured in microseconds +.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 +.Fa microseconds +microseconds have elapsed or a signal is delivered to the 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. +.Pp +This function is implemented using +.Xr nanosleep 2 +by pausing for +.Fa microseconds +microseconds or until a signal occurs. +Consequently, in this implementation, +sleeping has no effect on the state of process timers, +and there is no special handling for +.Dv SIGALRM . +.Sh RETURN VALUES +.Rv -std usleep +.Sh ERRORS +The +.Fn usleep +function +will fail if: +.Bl -tag -width Er +.It Bq Er EINTR +A signal was delivered to the process and its +action was to invoke a signal-catching function. +.El +.Sh NOTES +A microsecond is 0.000001 seconds. +.Sh SEE ALSO +.Xr sleep 1 , +.Xr nanosleep 2 , +.Xr sleep 3 +.Sh STANDARDS +The +.Fn usleep +function conforms to +.St -xpg4.2 . +.Sh HISTORY +The +.Fn usleep +function appeared in +.Bx 4.3 . +.Sh CAVEATS +Some implementations of +.Fn usleep +return an error if +.Fa microseconds +is greater than or equal to 1,000,000. +Portable applications should be written with this limitation in mind. diff --git a/static/openbsd/man3/utime.3 b/static/openbsd/man3/utime.3 new file mode 100644 index 00000000..32675783 --- /dev/null +++ b/static/openbsd/man3/utime.3 @@ -0,0 +1,145 @@ +.\" $OpenBSD: utime.3,v 1.23 2022/09/11 06:38:10 jmc 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt UTIME 3 +.Os +.Sh NAME +.Nm utime +.Nd set file times +.Sh SYNOPSIS +.In sys/types.h +.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 non-null, it specifies a pointer to a +.Vt 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 +.Fa actime +member, and the modification +time is set to the value of the +.Fa 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 superuser. +.Pp +In either case, the inode change-time of the file is set to the current +time. +.Sh RETURN VALUES +.Rv -std +.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 timep +argument is +.Dv NULL +and the effective user ID of the process does not +match the owner of the file, the effective user ID is not that of the +superuser, +and write access is denied. +.It Bq Er EFAULT +.Fa file +or +.Fa timep +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 +.Dv NAME_MAX +characters, or an entire pathname (including the terminating NUL) +exceeded +.Dv PATH_MAX +bytes. +.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 timep +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 superuser. +.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-88 . +.Sh HISTORY +A +.Fn utime +function appeared in +.At v7 . diff --git a/static/openbsd/man3/uu_lock.3 b/static/openbsd/man3/uu_lock.3 new file mode 100644 index 00000000..ddeb7d78 --- /dev/null +++ b/static/openbsd/man3/uu_lock.3 @@ -0,0 +1,179 @@ +.\" $OpenBSD: uu_lock.3,v 1.2 2025/06/06 22:01:40 schwarze Exp $ +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" " +.Dd $Mdocdate: June 6 2025 $ +.Dt UU_LOCK 3 +.Os +.Sh NAME +.Nm uu_lock , +.Nm uu_unlock , +.Nm uu_lockerr , +.Nm uu_lock_txfr +.Nd acquire and release control of a serial device +.Sh SYNOPSIS +.Lb libutil +.In sys/types.h +.In util.h +.Ft int +.Fn uu_lock "const char *ttyname" +.Ft int +.Fn uu_lock_txfr "const char *ttyname" "pid_t pid" +.Ft int +.Fn uu_unlock "const char *ttyname" +.Ft const char * +.Fn uu_lockerr "int uu_lockresult" +.Sh DESCRIPTION +The +.Fn uu_lock +function attempts to create a lock file called +.Pa /var/spool/lock/LCK.. +with a suffix given by the passed +.Fa ttyname . +If the file already exists, it is expected to contain the process +ID of the locking program. +.Pp +If the file does not already exist, or the owning process given by +the process ID found in the lock file is no longer running, +.Fn uu_lock +will write its own process ID into the file and return success. +.Pp +.Fn uu_lock_txfr +transfers lock ownership to another process. +.Fn uu_lock +must have previously been successful. +.Pp +.Fn uu_unlock +removes the lockfile created by +.Fn uu_lock +for the given +.Fa ttyname . +Care should be taken that +.Fn uu_lock +was successful before calling +.Fn uu_unlock . +.Pp +.Fn uu_lockerr +returns an error string representing the error +.Fa uu_lockresult , +as returned from +.Fn uu_lock . +.Sh RETURN VALUES +.Fn uu_unlock +returns 0 on success and \-1 on failure. +.Pp +.Fn uu_lock +may return any of the following values: +.Pp +.Dv UU_LOCK_INUSE : +The lock is in use by another process. +.Pp +.Dv UU_LOCK_OK : +The lock was successfully created. +.Pp +.Dv UU_LOCK_OPEN_ERR : +The lock file could not be opened via +.Xr open 2 . +.Pp +.Dv UU_LOCK_READ_ERR : +The lock file could not be read via +.Xr read 2 . +.Pp +.Dv UU_LOCK_CREAT_ERR : +Can't create temporary lock file via +.Xr creat 3 . +.Pp +.Dv UU_LOCK_WRITE_ERR : +The current process ID could not be written to the lock file via a call to +.Xr write 2 . +.Pp +.Dv UU_LOCK_LINK_ERR : +Can't link temporary lock file via +.Xr link 2 . +.Pp +.Dv UU_LOCK_TRY_ERR : +Locking attempts are failed after 5 tries. +.Pp +If a value of +.Dv UU_LOCK_OK +is passed to +.Fn uu_lockerr , +an empty string is returned. +Otherwise, a string specifying +the reason for failure is returned. +.Fn uu_lockerr +uses the current value of +.Va errno +to determine the exact error. +Care should be made not to allow +.Va errno +to be changed between calls to +.Fn uu_lock +and +.Fn uu_lockerr . +.Pp +.Fn uu_lock_txfr +may return any of the following values: +.Pp +.Dv UU_LOCK_OK : +The transfer was successful. +The specified process now holds the device lock. +.Pp +.Dv UU_LOCK_OWNER_ERR : +The current process does not already own a lock on the specified device. +.Pp +.Dv UU_LOCK_WRITE_ERR : +The new process ID could not be written to the lock file via a call to +.Xr write 2 . +.Sh ERRORS +If +.Fn uu_lock +returns one of the error values above, the global value +.Va errno +can be used to determine the cause. +Refer to the respective manual pages for further details. +.Pp +.Fn uu_unlock +will set the global variable +.Va errno +to reflect the reason that the lock file could not be removed. +Refer to the description of +.Xr unlink 2 +for further details. +.Sh SEE ALSO +.Xr lseek 2 , +.Xr open 2 , +.Xr read 2 , +.Xr write 2 +.Sh BUGS +It is possible that a stale lock is not recognised as such if a new +process is assigned the same process ID as the program that left +the stale lock. +.Pp +The calling process must have write permissions to the +.Pa /var/spool/lock +directory. +There is no mechanism in place to ensure that the +permissions of this directory are the same as those of the +serial devices that might be locked. diff --git a/static/openbsd/man3/uuid_compare.3 b/static/openbsd/man3/uuid_compare.3 new file mode 100644 index 00000000..505edcb8 --- /dev/null +++ b/static/openbsd/man3/uuid_compare.3 @@ -0,0 +1,210 @@ +.\" $OpenBSD: uuid_compare.3,v 1.3 2023/07/03 08:53:27 jasper Exp $ +.\" $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 $Mdocdate: July 3 2023 $ +.Dt UUID_COMPARE 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 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 *uuid" +.Ft void +.Fn uuid_enc_be "void *buf" "const uuid_t *uuid" +.Ft void +.Fn uuid_dec_be "const void *buf" "uuid_t *uuid" +.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 unless it is +.Dv NULL . +Possible values are: +.Bl -tag -width "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 +.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. +.Pp +.Fn uuid_create +generates version 4 UUIDs, +specified by section 4.4 of RFC 4122. diff --git a/static/openbsd/man3/v2i_ASN1_BIT_STRING.3 b/static/openbsd/man3/v2i_ASN1_BIT_STRING.3 new file mode 100644 index 00000000..107a57ae --- /dev/null +++ b/static/openbsd/man3/v2i_ASN1_BIT_STRING.3 @@ -0,0 +1,126 @@ +.\" $OpenBSD: v2i_ASN1_BIT_STRING.3,v 1.2 2025/06/08 22:40:31 schwarze Exp $ +.\" +.\" Copyright (c) 2024 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 $Mdocdate: June 8 2025 $ +.Dt V2I_ASN1_BIT_STRING 3 +.Os +.Sh NAME +.Nm v2i_ASN1_BIT_STRING , +.Nm i2v_ASN1_BIT_STRING +.Nd ASN.1 BIT STRING utility functions for certificate extensions +.Sh SYNOPSIS +.Lb libcrypto +.In openssl/x509v3.h +.Ft ASN1_BIT_STRING * +.Fo v2i_ASN1_BIT_STRING +.Fa "X509V3_EXT_METHOD *method" +.Fa "X509V3_CTX *ctx" +.Fa "STACK_OF(CONF_VALUE) *nval" +.Fc +.Ft STACK_OF(CONF_VALUE) * +.Fo i2v_ASN1_BIT_STRING +.Fa "X509V3_EXT_METHOD *method" +.Fa "ASN1_BIT_STRING *bit_string" +.Fa "STACK_OF(CONF_VALUE) *nval" +.Fc +.Sh DESCRIPTION +.Fn v2i_ASN1_BIT_STRING +allocates a new ASN.1 +.Vt BIT STRING +object and initializes it from a list of bit names. +The +.Fa nval +argument is essentially used as the list of the names of the bits to set. +Both long names and short names can be used. +One name is taken from each element of +.Fa nval . +The +.Fa ctx +argument and any section names or values contained in the elements of +.Fa nval +are ignored. +To convert a C string containing a comma-separated list of names +to the input format of this function, +.Xr X509V3_parse_list 3 +can be used. +.Pp +.Fn i2v_ASN1_BIT_STRING +translates the numbers of the bits that are set in the +.Fa bit_string +to long names. +For each bit that is set, +one element containing the corresponding long name is added to +.Fa nval . +If a +.Dv NULL +pointer is passed for the +.Fa nval +argument, a new +.Vt STACK_OF(CONF_VALUE) +is allocated. +.Pp +For both functions, the +.Fa method +argument is only used for the translation of bit names to bit numbers +and vice versa. +Any names and bit numbers that do not occur in the +.Fa usr_data +translation table in the +.Fa method +are silently ignored. +.Pp +For the following arguments, +.Xr X509V3_EXT_get_nid 3 +returns static constant +.Fa method +objects supporting these functions: +.Pp +.Bl -tag -width NID_netscape_cert_type -compact +.It Dv NID_crl_reason +reason codes, RFC 5280 section 5.3.1 +.It Dv NID_key_usage +key usage purposes, RFC 5280 section 4.2.1.3 +.It Dv NID_netscape_cert_type +Netscape certificate types (obsolete) +.El +.Pp +While an application program could theoretically provide its own +.Fa method +object containing a custom translation table, that is unlikely to be +useful for any practical purpose. +.Sh RETURN VALUES +.Fn v2i_ASN1_BIT_STRING +returns the new +.Vt BIT STRING +object and +.Fn i2v_ASN1_BIT_STRING +the modified or new list of bit names. +Both functions return +.Dv NULL +if an error occurs, in particular if memory allocation fails. +.Sh SEE ALSO +.Xr ASN1_BIT_STRING_new 3 , +.Xr ASN1_BIT_STRING_set 3 , +.Xr i2s_ASN1_ENUMERATED_TABLE 3 , +.Xr STACK_OF 3 , +.Xr tls_peer_ocsp_crl_reason 3 , +.Xr X509_get_key_usage 3 , +.Xr X509V3_EXT_get_nid 3 , +.Xr X509V3_get_d2i 3 , +.Xr X509V3_parse_list 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . diff --git a/static/openbsd/man3/va.3 b/static/openbsd/man3/va.3 new file mode 100644 index 00000000..1ce64704 --- /dev/null +++ b/static/openbsd/man3/va.3 @@ -0,0 +1,13 @@ +.Dd July 28, 2016 +.Dt VA 3 +.Os +.Sh NAME +.Nm \&Va +.Nd indexing of variable type and name macros +.Sh SYNOPSIS +.Vt block vt_two +.Sh DESCRIPTION +.Vt vt_one +.Va va_one +.Vt struct vt_two +.Va int va_two diff --git a/static/openbsd/man3/valloc.3 b/static/openbsd/man3/valloc.3 new file mode 100644 index 00000000..096ebcae --- /dev/null +++ b/static/openbsd/man3/valloc.3 @@ -0,0 +1,79 @@ +.\" $OpenBSD: valloc.3,v 1.15 2018/11/05 10:31:32 otto 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. +.\" +.Dd $Mdocdate: November 5 2018 $ +.Dt VALLOC 3 +.Os +.Sh NAME +.Nm valloc +.Nd aligned memory allocation function +.Sh SYNOPSIS +.In unistd.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 +and both +.Xr aligned_alloc 3 +and +.Xr posix_memalign 3 , +which allocate memory with a given alignment. +.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 SEE ALSO +.Xr malloc 3 +.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/openbsd/man3/vis.3 b/static/openbsd/man3/vis.3 new file mode 100644 index 00000000..70cb2e2b --- /dev/null +++ b/static/openbsd/man3/vis.3 @@ -0,0 +1,394 @@ +.\" $OpenBSD: vis.3,v 1.37 2022/07/30 07:19:30 jsg 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. +.\" +.Dd $Mdocdate: July 30 2022 $ +.Dt VIS 3 +.Os +.Sh NAME +.Nm vis , +.Nm strvis , +.Nm strnvis , +.Nm strvisx , +.Nm stravis +.Nd visually encode characters +.Sh SYNOPSIS +.In stdlib.h +.In vis.h +.Ft char * +.Fn vis "char *dst" "int c" "int flag" "int nextc" +.Ft int +.Fn strvis "char *dst" "const char *src" "int flag" +.Ft int +.Fn strnvis "char *dst" "const char *src" "size_t dstsize" "int flag" +.Ft int +.Fn strvisx "char *dst" "const char *src" "size_t srclen" "int flag" +.Ft int +.Fn stravis "char **outp" "const char *src" "int flag" +.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. +.Fa dst +will be NUL-terminated and must be at least 5 bytes long +(maximum encoding requires 4 bytes plus the NUL). +The additional character, +.Fa nextc , +is only used when selecting the +.Dv VIS_CSTYLE +encoding format (explained below). +.Pp +The +.Fn strvis , +.Fn strnvis +and +.Fn strvisx +functions copy into +.Fa dst +a visual representation of +the string +.Fa src . +.Pp +The +.Fn strvis +function encodes characters from +.Fa src +up to the first NUL, into a buffer +.Fa dst +(which must be at least 4 * strlen(src) + 1 long). +.Pp +The +.Fn strnvis +function encodes characters from +.Fa src +up to the first NUL or the end of the buffer +.Fa dst , +as indicated by +.Fa dstsize . +.Pp +The +.Fn strvisx +function encodes exactly +.Fa srclen +characters from +.Fa src +into a buffer +.Fa dst +(which must be at least 4 * srclen + 1 long). +This +is useful for encoding a block of data that may contain NULs. +.Pp +The +.Fn stravis +function writes a visual representation of the string +.Fa src +into a newly allocated string +.Fa outp ; +it does not attempt to +.Xr realloc 3 +.Fa outp . +.Fa outp +should be passed to +.Xr free 3 +to release the allocated storage when it is no longer needed. +.Fn stravis +checks for integer overflow when allocating memory. +.Pp +All forms NUL-terminate +.Fa dst , +except for +.Fn strnvis +when +.Fa dstsize +is zero, in which case +.Fa dst +is not touched. +.Pp +The +.Fa flag +parameter is used for altering the default range of +characters considered for encoding and for altering the visual +representation. +.Ss Encodings +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 +or +.Xr strunvis 3 +functions. +.Pp +There are two parameters that can be controlled: the range of +characters that are encoded, 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_ALL +Encode all characters, whether visible or not. +.It Dv VIS_DQ +Also encode double quote characters +.Pf ( Ql \&" ) . +.It Dv VIS_GLOB +Also encode magic characters recognized by +.Xr glob 3 +.Pf ( 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_SAFE +Only encode +.Dq unsafe +characters. +These are 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 +There are three forms of encoding. +All forms use the backslash +.Ql \e +character to introduce a special +sequence; two backslashes are used to represent a real backslash. +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 a 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. +.It Dv \e-C +Represents character +.Ql C . +Only used with +.Dv VIS_ALL . +.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 - BEL No (007) +.Li \eb Tn - BS No (010) +.Li \ef Tn - NP No (014) +.Li \en Tn - NL No (012) +.Li \er Tn - CR No (015) +.Li \es Tn - SP No (040) +.Li \et Tn - HT No (011) +.Li \ev Tn - VT No (013) +.Li \e0 Tn - NUL No (000) +.Ed +.Pp +When using this format, the +.Fa nextc +parameter is looked at to determine +if a 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. +.It Dv VIS_OCTAL +Use a three digit octal sequence. +The form is +.Ql \eddd +where +.Ar d +represents an octal 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 RETURN VALUES +.Fn vis +returns a pointer to the terminating NUL character of the string +.Fa dst . +.Pp +.Fn strvis +and +.Fn strvisx +return the number of characters in +.Fa dst +(not including the trailing NUL). +.Pp +.Fn strnvis +returns the length that +.Fa dst +would become if it were of unlimited size (similar to +.Xr snprintf 3 +or +.Xr strlcpy 3 ) . +This can be used to detect truncation, but it also means that +the return value of +.Fn strnvis +must not be used without checking it against +.Fa dstsize . +.Pp +Upon successful completion, +.Fn stravis +returns the number of characters in +.Pf * Fa outp +(not including the trailing NUL). +Otherwise, +.Fn stravis +returns -1 and sets +.Va errno +to +.Er ENOMEM . +.Sh EXAMPLES +.Fn strvis +has unusual storage requirements that can lead to stack or heap corruption +if the destination is not carefully constructed. +A common mistake is to use the same size for the source and destination +when the destination actually needs up to 4 * strlen(source) + 1 bytes. +.Pp +If the length of a string to be encoded is not known at compile time, use +.Fn stravis : +.Bd -literal -offset indent +char *src, *dst; + +\&... +if (stravis(&dst, src, VIS_OCTAL) == -1) + err(1, "stravis"); + +\&... +free(dst); +.Ed +.Pp +To encode a fixed size buffer, +.Fn strnvis +can be used with a fixed size target buffer: +.Bd -literal -offset indent +char src[MAXPATHLEN]; +char dst[4 * MAXPATHLEN + 1]; + +\&... +if (strnvis(dst, src, sizeof(dst), VIS_OCTAL) >= sizeof(dst)) + err(1, "strnvis"); +.Ed +.Sh SEE ALSO +.Xr unvis 1 , +.Xr vis 1 , +.Xr free 3 , +.Xr snprintf 3 , +.Xr strlcpy 3 , +.Xr unvis 3 +.Sh HISTORY +The +.Fn vis , +.Fn strvis +and +.Fn strvisx +functions first appeared in +.Bx 4.3 Reno , +.Fn strnvis +in +.Ox 2.9 +and +.Fn stravis +in +.Ox 5.7 . +.Pp +The +.Dv VIS_ALL +flag first appeared in +.Ox 4.9 . diff --git a/static/openbsd/man3/wcrtomb.3 b/static/openbsd/man3/wcrtomb.3 new file mode 100644 index 00000000..85e22947 --- /dev/null +++ b/static/openbsd/man3/wcrtomb.3 @@ -0,0 +1,186 @@ +.\" $OpenBSD: wcrtomb.3,v 1.12 2023/09/12 08:33:37 jsg Exp $ +.\" $NetBSD: wcrtomb.3,v 1.4 2003/09/08 17:54:31 wiz Exp $ +.\" +.\" Copyright (c)2023 Ingo Schwarze +.\" 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 $Mdocdate: September 12 2023 $ +.Dt WCRTOMB 3 +.Os +.Sh NAME +.Nm wcrtomb , +.Nm c32rtomb +.Nd convert a wide character to a multibyte character +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fo wcrtomb +.Fa "const char * restrict s" +.Fa "wchar_t wc" +.Fa "mbstate_t * restrict mbs" +.Fc +.In uchar.h +.Ft size_t +.Fo c32rtomb +.Fa "char * restrict s" +.Fa "char32_t wc" +.Fa "mbstate_t * restrict mbs" +.Fc +.Sh DESCRIPTION +.Fn wcrtomb +and +.Fn c32rtomb +convert the wide character +.Fa wc +to the corresponding multibyte character, and store up to +.Dv MB_CUR_MAX +bytes in the array pointed to by +.Fa s +if +.Fa s +is not a +.Dv NULL +pointer. +The interpretation of +.Fa wc +is implementation-defined. +On +.Ox , +.Vt wchar_t +and +.Vt char32_t +are of the same width and both are always interpreted as Unicode codepoints. +.Pp +The output encoding that +.Fn wcrtomb +and +.Fn c32rtomb +use in +.Fa s +is determined by the +.Dv LC_CTYPE +category of the current locale. +.Ox +only supports UTF-8 and ASCII output, +and these functions are only useful for UTF-8. +.Pp +The following arguments cause special processing: +.Bl -tag -width 012345678901 +.It Fa wc No == 0 +A NUL byte is stored to +.Pf * Fa s +and the state object pointed to by +.Fa mbs +is reset to the initial state. +On operating systems other than +.Ox +that support state-dependent multibyte encodings, a special byte sequence +.Pq Dq shift sequence +is written before the NUL byte to return to the initial state +if that is required by the output encoding +and by the current output encoding state. +.It Fa mbs No == Dv NULL +.Fn mbrtowc +and +.Fn c32rtomb +each use their own internal state object instead of the +.Fa mbs +argument. +Both internal state objects are initialized at startup time of the program, +and no other +.Em libc +function ever changes either of them. +.It Fa s No == Dv NULL +The object pointed to by +.Fa mbs , +or the internal object if +.Fa mbs +is a +.Dv NULL +pointer, is reset to the initial state, +.Fa wc +is ignored, and 1 is returned. +.El +.Sh RETURN VALUES +.Fn wcrtomb +and +.Fn c32rtomb +return the number of bytes (including any shift sequences) +which are stored in the array pointed to by +.Fa s , +or 1 if +.Fa s +is +.Dv NULL . +If +.Fa wc +is not a valid wide character +or if it cannot be represented in the multibyte encoding selected with +.Dv LC_CTYPE , +both functions return +.Po Vt size_t Pc Ns \-1 +and set +.Va errno +to indicate the error. +.Sh ERRORS +.Fn wcrtomb +and +.Fn c32rtomb +cause an error in the following cases: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa wc +is not a valid wide character or cannot be represented using +.Dv LC_CTYPE . +.It Bq Er EINVAL +.Fa mbs +points to an invalid or uninitialized +.Vt mbstate_t +object. +.El +.Sh SEE ALSO +.Xr mbrtowc 3 , +.Xr setlocale 3 , +.Xr wctomb 3 +.Sh STANDARDS +.Fn wcrtomb +conforms to +.St -isoC-amd1 . +The restrict qualifier was added at +.St -isoC-99 . +.Pp +.Fn c32rtomb +conforms to +.St -isoC-2011 . +.Sh HISTORY +.Fn wcrtomb +has been available since +.Ox 3.8 +and has provided support for UTF-8 since +.Ox 4.8 . +.Pp +.Fn c32rtomb +has been available since +.Ox 7.4 . diff --git a/static/openbsd/man3/wcscasecmp.3 b/static/openbsd/man3/wcscasecmp.3 new file mode 100644 index 00000000..9db4a829 --- /dev/null +++ b/static/openbsd/man3/wcscasecmp.3 @@ -0,0 +1,134 @@ +.\" $OpenBSD: wcscasecmp.3,v 1.5 2017/09/05 03:16:14 schwarze Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2017 Ingo Schwarze +.\" +.\" 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. +.\" +.\" @(#)strcasecmp.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd $Mdocdate: September 5 2017 $ +.Dt WCSCASECMP 3 +.Os +.Sh NAME +.Nm wcscasecmp , +.Nm wcscasecmp_l , +.Nm wcsncasecmp , +.Nm wcsncasecmp_l +.Nd compare wide strings, ignoring case +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fo wcscasecmp +.Fa "const wchar_t *s1" +.Fa "const wchar_t *s2" +.Fc +.Ft int +.Fo wcscasecmp_l +.Fa "const wchar_t *s1" +.Fa "const wchar_t *s2" +.Fa "locale_t locale" +.Fc +.Ft int +.Fo wcsncasecmp +.Fa "const wchar_t *s1" +.Fa "const wchar_t *s2" +.Fa "size_t len" +.Fc +.Ft int +.Fo wcsncasecmp_l +.Fa "const wchar_t *s1" +.Fa "const wchar_t *s2" +.Fa "size_t len" +.Fa "locale_t locale" +.Fc +.Sh DESCRIPTION +These functions compare the wide 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 wide character to lower case. +The wide strings themselves are not modified. +.Pp +For the translation to lower case, +.Fn wcscasecmp +and +.Fn wcsncasecmp +use the thread-specific locale as defined with +.Xr uselocale 3 , +falling back to the global locale defined with +.Xr setlocale 3 . +.Fn wcscasecmp_l +and +.Fn wcsncasecmp_l +use the +.Fa locale +argument instead. +.Pp +.Fn wcsncasecmp +and +.Fn wcsncasecmp_l +compare at most +.Fa len +wide characters. +.Sh SEE ALSO +.Xr newlocale 3 , +.Xr setlocale 3 , +.Xr strcasecmp 3 , +.Xr wcscmp 3 , +.Xr wmemcmp 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn wcscasecmp +and +.Fn wcsncasecmp +functions have been available since +.Ox 5.0 , +and +.Fn wcscasecmp_l +and +.Fn wcsncasecmp_l +since +.Ox 6.2 . +.Sh AUTHORS +The +.Ox +versions of +.Fn wcscasecmp +and +.Fn wcsncasecmp +were implemented by +.An Marc Espie Aq Mt espie@openbsd.org . diff --git a/static/openbsd/man3/wcscat.3 b/static/openbsd/man3/wcscat.3 new file mode 100644 index 00000000..9b7588cf --- /dev/null +++ b/static/openbsd/man3/wcscat.3 @@ -0,0 +1,115 @@ +.\" $OpenBSD: wcscat.3,v 1.3 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WCSCAT 3 +.Os +.Sh NAME +.Nm wcscat , +.Nm wcsncat +.Nd concatenate wide strings +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wcscat "wchar_t * restrict s" "const wchar_t * restrict append" +.Ft wchar_t * +.Fo wcsncat +.Fa "wchar_t * restrict s" +.Fa "const wchar_t * restrict append" +.Fa "size_t count" +.Fc +.Sh DESCRIPTION +The +.Fn wcscat +and +.Fn wcsncat +functions append a copy of the wide string +.Fa append +to the end of the wide string +.Fa s , +then add a terminating null wide character (L'\e0'). +The wide string +.Fa s +must have sufficient space to hold the result. +.Pp +The +.Fn wcsncat +function appends not more than +.Fa count +wide characters where space for the terminating null wide character +should not be included in +.Fa count . +.Sh RETURN VALUES +The +.Fn wcscat +and +.Fn wcsncat +functions return the pointer +.Fa s . +.Sh SEE ALSO +.Xr strcat 3 , +.Xr strlcpy 3 , +.Xr wcscpy 3 , +.Xr wcslcpy 3 , +.Xr wmemcpy 3 , +.Xr wmemmove 3 +.Sh STANDARDS +The +.Fn wcscat +and +.Fn wcsncat +functions conform to +.St -isoC-99 +and were first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wcscat +and +.Fn wcsncat +functions were ported from +.Nx +and first appeared in +.Ox 3.8 . +.Sh CAVEATS +Using the functions +.Fn wcscat +and +.Fn wcsncat +is very error-prone with respect to buffer overflows; +see the EXAMPLES section in +.Xr strcat 3 +for correct usage. +Using +.Xr wcslcat 3 +is a better choice in most cases. diff --git a/static/openbsd/man3/wcschr.3 b/static/openbsd/man3/wcschr.3 new file mode 100644 index 00000000..bb714b20 --- /dev/null +++ b/static/openbsd/man3/wcschr.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: wcschr.3,v 1.4 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WCSCHR 3 +.Os +.Sh NAME +.Nm wcschr +.Nd locate first occurrence of a wide character in a wide string +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wcschr "const wchar_t *s" "wchar_t c" +.Sh DESCRIPTION +The +.Fn wcschr +function locates the first occurrence of the wide character +.Fa c +in the wide string +.Fa s . +The terminating null wide character is considered part of the wide string. +If +.Fa c +is the null wide character (L'\e0'), +.Fn wcschr +locates the terminating null wide character. +.Sh RETURN VALUES +The +.Fn wcschr +function returns a pointer to the located wide character or +.Dv NULL +if the wide character does not appear in the wide string. +.Sh SEE ALSO +.Xr strchr 3 , +.Xr wcscspn 3 , +.Xr wcspbrk 3 , +.Xr wcsrchr 3 , +.Xr wcsspn 3 , +.Xr wcsstr 3 , +.Xr wcstok 3 , +.Xr wmemchr 3 +.Sh STANDARDS +The +.Fn wcschr +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wcschr +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wcscmp.3 b/static/openbsd/man3/wcscmp.3 new file mode 100644 index 00000000..53cd15a1 --- /dev/null +++ b/static/openbsd/man3/wcscmp.3 @@ -0,0 +1,92 @@ +.\" $OpenBSD: wcscmp.3,v 1.3 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WCSCMP 3 +.Os +.Sh NAME +.Nm wcscmp , +.Nm wcsncmp +.Nd compare wide strings +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fn wcscmp "const wchar_t *s1" "const wchar_t *s2" +.Ft int +.Fn wcsncmp "const wchar_t *s1" "const wchar_t *s2" "size_t len" +.Sh DESCRIPTION +The +.Fn wcscmp +and +.Fn wcsncmp +functions lexicographically compare the wide strings +.Fa s1 +and +.Fa s2 . +The +.Fn wcsncmp +function compares at most +.Fa len +wide characters. +.Sh RETURN VALUES +The +.Fn wcscmp +and +.Fn wcsncmp +functions return an integer greater than, equal to, or less than 0, according +to whether the wide string +.Fa s1 +is greater than, equal to, or less than the wide string +.Fa s2 . +.Sh SEE ALSO +.Xr strcmp 3 , +.Xr wcscasecmp 3 , +.Xr wmemcmp 3 +.Sh STANDARDS +The +.Fn wcscmp +and +.Fn wcsncmp +functions conform to +.St -isoC-99 +and were first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wcscmp +and +.Fn wcsncmp +functions were ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wcscoll.3 b/static/openbsd/man3/wcscoll.3 new file mode 100644 index 00000000..559dbb5f --- /dev/null +++ b/static/openbsd/man3/wcscoll.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: wcscoll.3,v 1.2 2019/01/18 07:43:36 schwarze Exp $ +.\" +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: January 18 2019 $ +.Dt WCSCOLL 3 +.Os +.Sh NAME +.Nm wcscoll , +.Nm wcscoll_l +.Nd compare wide strings according to the current collation +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fn wcscoll "const wchar_t *s1" "const wchar_t *s2" +.Ft int +.Fn wcscoll_l "const wchar_t *s1" "const wchar_t *s2" "locale_t locale" +.Sh DESCRIPTION +The +.Fn wcscoll +and +.Fn wcscoll_l +functions lexicographically compare the NUL-terminated wide strings +.Fa s1 +and +.Fa s2 +according to the current locale collation +and return 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 . +.Pp +On +.Ox , +they have the same effect as +.Xr wcscmp 3 , +and the global locale, the thread-specific locale, and the +.Fa locale +argument are ignored. +On other operating systems, the results may depend on the +.Dv LC_CTYPE +and +.Dv LC_COLLATE +locale categories set with +.Xr setlocale 3 , +.Xr uselocale 3 , +or +.Xr newlocale 3 . +.Sh SEE ALSO +.Xr newlocale 3 , +.Xr setlocale 3 , +.Xr wcscmp 3 , +.Xr wcsxfrm 3 +.Sh STANDARDS +The +.Fn wcscoll +function conforms to +.St -isoC-99 , +and +.Fn wcscoll_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn wcscoll +function has been available since +.Ox 4.8 , +and +.Fn wcscoll_l +since +.Ox 6.2 . diff --git a/static/openbsd/man3/wcscpy.3 b/static/openbsd/man3/wcscpy.3 new file mode 100644 index 00000000..fcf01b5c --- /dev/null +++ b/static/openbsd/man3/wcscpy.3 @@ -0,0 +1,129 @@ +.\" $OpenBSD: wcscpy.3,v 1.5 2016/11/12 08:58:43 jmc 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. +.\" +.Dd $Mdocdate: November 12 2016 $ +.Dt WCSCPY 3 +.Os +.Sh NAME +.Nm wcscpy , +.Nm wcsncpy +.Nd copy wide strings +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wcscpy "wchar_t * restrict dst" "const wchar_t * restrict src" +.Ft wchar_t * +.Fo wcsncpy +.Fa "wchar_t * restrict dst" +.Fa "const wchar_t * restrict src" +.Fa "size_t len" +.Fc +.Sh DESCRIPTION +The +.Fn wcscpy +and +.Fn wcsncpy +functions copy the wide string +.Fa src +to +.Fa dst +(including the terminating null wide character). +.Pp +The +.Fn wcsncpy +function copies not more than +.Fa len +wide characters to +.Fa dst , +appending null wide characters if the length of +.Fa src +is less than +.Fa len , +and +.Em not +terminating +.Fa dst +if the length of +.Fa src +is greater than or equal to +.Fa len . +.Pp +If the +.Fa src +and +.Fa dst +strings overlap, the behavior is undefined. +.Sh RETURN VALUES +The +.Fn wcscpy +and +.Fn wcsncpy +functions return +.Fa dst . +.Sh SEE ALSO +.Xr strcpy 3 , +.Xr strlcpy 3 , +.Xr wcscat 3 , +.Xr wcslcpy 3 , +.Xr wmemcpy 3 , +.Xr wmemmove 3 +.Sh STANDARDS +The +.Fn wcscpy +and +.Fn wcsncpy +functions conform to +.St -isoC-99 +and were first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wcscpy +and +.Fn wcsncpy +functions were ported from +.Nx +and first appeared in +.Ox 3.8 . +.Sh CAVEATS +Using the functions +.Fn wcscpy +and +.Fn wcsncpy +is very error-prone with respect to buffer overflows; +see the EXAMPLES section in +.Xr strncpy 3 +for correct usage. +Using +.Xr wcslcpy 3 +is a better choice in most cases. diff --git a/static/openbsd/man3/wcscspn.3 b/static/openbsd/man3/wcscspn.3 new file mode 100644 index 00000000..520a7392 --- /dev/null +++ b/static/openbsd/man3/wcscspn.3 @@ -0,0 +1,83 @@ +.\" $OpenBSD: wcscspn.3,v 1.3 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WCSCSPN 3 +.Os +.Sh NAME +.Nm wcscspn +.Nd span the complement of a wide string +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn wcscspn "const wchar_t *s" "const wchar_t *charset" +.Sh DESCRIPTION +The +.Fn wcscspn +function spans the initial part of the wide string +.Fa s +as long as the wide characters from +.Fa s +do not occur in string +.Fa charset +(it spans the +.Em complement +of +.Fa charset ) . +.Sh RETURN VALUES +The +.Fn wcscspn +function returns the number of wide characters spanned. +.Sh SEE ALSO +.Xr strcspn 3 , +.Xr wcschr 3 , +.Xr wcspbrk 3 , +.Xr wcsrchr 3 , +.Xr wcsspn 3 , +.Xr wcsstr 3 , +.Xr wcstok 3 , +.Xr wmemchr 3 +.Sh STANDARDS +The +.Fn wcscspn +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wcscspn +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wcsdup.3 b/static/openbsd/man3/wcsdup.3 new file mode 100644 index 00000000..588a2571 --- /dev/null +++ b/static/openbsd/man3/wcsdup.3 @@ -0,0 +1,97 @@ +.\" $OpenBSD: wcsdup.3,v 1.4 2011/07/25 00:38:53 schwarze Exp $ +.\" $NetBSD: wcsdup.3,v 1.3 2010/12/16 17:42:28 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. +.\" +.\" @(#)strdup.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd $Mdocdate: July 25 2011 $ +.Dt WCSDUP 3 +.Os +.Sh NAME +.Nm wcsdup +.Nd save a copy of a wide string +.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 +const char *o = "foobar"; +wchar_t *p, b[32]; +size_t blen; + +blen = sizeof(b) / sizeof(b[0]); +if (mbstowcs(b, o, blen) == (size_t)-1) + err(1, NULL); +b[blen - 1] = 0; +if ((p = wcsdup(b)) == NULL) + err(1, NULL); +.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 STANDARDS +The +.Fn wcsdup +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn wcsdup +function was ported from +.Nx +and first appeared in +.Ox 5.0 . diff --git a/static/openbsd/man3/wcsftime.3 b/static/openbsd/man3/wcsftime.3 new file mode 100644 index 00000000..4c196466 --- /dev/null +++ b/static/openbsd/man3/wcsftime.3 @@ -0,0 +1,32 @@ +.\" $OpenBSD: wcsftime.3,v 1.4 2022/03/29 18:15:52 naddy Exp $ +.\" Copyright (c) 2011 Marc Espie +.\" +.\" 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: March 29 2022 $ +.Dt WCSFTIME 3 +.Os +.Sh NAME +.Nm wcsftime +.Nd format date and time to wide characters string +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn wcsftime "wchar_t *buf" "size_t maxsize" "const wchar_t *format" "const struct tm *timeptr" +.Sh DESCRIPTION +The +.Fn wcsftime +function is a wide char equivalent of +.Xr strftime 3 . +.Sh SEE ALSO +.Xr strftime 3 diff --git a/static/openbsd/man3/wcslcpy.3 b/static/openbsd/man3/wcslcpy.3 new file mode 100644 index 00000000..d2790380 --- /dev/null +++ b/static/openbsd/man3/wcslcpy.3 @@ -0,0 +1,160 @@ +.\" $OpenBSD: wcslcpy.3,v 1.8 2024/08/07 04:59:45 guenther Exp $ +.\" +.\" Copyright (c) 1998, 2000 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. +.\" +.Dd $Mdocdate: August 7 2024 $ +.Dt WCSLCPY 3 +.Os +.Sh NAME +.Nm wcslcpy , +.Nm wcslcat +.Nd size-bounded wide string copying and concatenation +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn wcslcpy "wchar_t * restrict dst" "const wchar_t * restrict src" "size_t size" +.Ft size_t +.Fn wcslcat "wchar_t * restrict dst" "const wchar_t * restrict src" "size_t size" +.Sh DESCRIPTION +The +.Fn wcslcpy +and +.Fn wcslcat +functions copy and concatenate wide strings respectively. +They are designed to be safer, more consistent, and less error prone +replacements for +.Xr wcsncpy 3 +and +.Xr wcsncat 3 . +Unlike those functions, +.Fn wcslcpy +and +.Fn wcslcat +take the full size of the buffer (not just the length) and guarantee to +terminate the result with a null wide character (as long as +.Fa size +is larger than 0 or, in the case of +.Fn wcslcat , +as long as there is at least one wide character free in +.Fa dst ) . +Note that a wide character for the null wide character should be included in +.Fa size . +Also note that +.Fn wcslcpy +and +.Fn wcslcat +only operate on wide strings that are terminated with a null wide character +(L'\e0'). +This means that for +.Fn wcslcpy +.Fa src +must be terminated with a null wide character and for +.Fn wcslcat +both +.Fa src +and +.Fa dst +must be terminated with a null wide character. +.Pp +The +.Fn wcslcpy +function copies up to +.Fa size +\(mi 1 wide characters from the wide string +.Fa src +to +.Fa dst , +terminating the result with a null wide character. +.Pp +The +.Fn wcslcat +function appends the wide string +.Fa src +to the end of +.Fa dst . +It will append at most +.Fa size +\(mi wcslen(dst) \(mi 1 wide characters, terminating the result with a null +wide character. +.Pp +If the +.Fa src +and +.Fa dst +strings overlap, the behavior is undefined. +.Sh RETURN VALUES +The +.Fn wcslcpy +and +.Fn wcslcat +functions return the total length of the wide string they tried to create. +For +.Fn wcslcpy +that means the length of +.Fa src . +For +.Fn wcslcat +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 wcslcat +traverses +.Fa size +wide characters without finding a null wide character, the length of the +string is considered to be +.Fa size +and the destination wide string will not be terminated with a null wide +character (since there was no space for it). +This keeps +.Fn wcslcat +from running off the end of a wide string. +In practice this should not happen (as it means that either +.Fa size +is incorrect or that +.Fa dst +is not terminated with a null wide character). +The check exists to prevent potential security problems in incorrect code. +.Sh SEE ALSO +.Xr strlcpy 3 , +.Xr swprintf 3 , +.Xr wcsncat 3 , +.Xr wcsncpy 3 +.Sh STANDARDS +The +.Fn wcslcpy +and +.Fn wcslcat +functions conform to +.St -p1003.1-2024 . +.Sh HISTORY +The +.Fn wcslcpy +and +.Fn wcslcat +functions first appeared in +.Ox 3.8 . +.Sh AUTHORS +The +.Fn wcslcpy +and +.Fn wcslcat +functions are based on code by +.An Todd C. Miller Aq Mt millert@openbsd.org . diff --git a/static/openbsd/man3/wcslen.3 b/static/openbsd/man3/wcslen.3 new file mode 100644 index 00000000..b6d9aafc --- /dev/null +++ b/static/openbsd/man3/wcslen.3 @@ -0,0 +1,102 @@ +.\" $OpenBSD: wcslen.3,v 1.4 2024/07/14 09:51:18 jca 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. +.\" +.Dd $Mdocdate: July 14 2024 $ +.Dt WCSLEN 3 +.Os +.Sh NAME +.Nm wcslen , +.Nm wcsnlen +.Nd find length of a wide string +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn wcslen "const wchar_t *s" +.Ft size_t +.Fn wcsnlen "const wchar_t *s" "size_t maxlen" +.Sh DESCRIPTION +The +.Fn wcslen +function computes the length of the wide string +.Fa s . +The +.Fn wcsnlen +function computes the length of the wide string +.Fa s , +up to +.Fa maxlen +wide characters. +The +.Fn wcsnlen +function will never attempt to address more than +.Fa maxlen +wide characters, making it suitable for use with wide character arrays +that are not guaranteed to be NUL-terminated. +.Sh RETURN VALUES +The +.Fn wcslen +function returns the number of wide characters that precede the terminating +null wide character. +.Pp +The +.Fn wcsnlen +function returns the number of wide characters that precede the terminating +null wide character +or +.Fa maxlen , +whichever is smaller. +.Sh SEE ALSO +.Xr strlen 3 , +.Xr wcswidth 3 +.Sh STANDARDS +The +.Fn wcslen +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +The +.Fn wcsnlen +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn wcslen +function was ported from +.Nx +and first appeared in +.Ox 3.8 . +The +.Fn wcsnlen +function first appeared in +.Ox 7.6 . diff --git a/static/openbsd/man3/wcspbrk.3 b/static/openbsd/man3/wcspbrk.3 new file mode 100644 index 00000000..602bfdc3 --- /dev/null +++ b/static/openbsd/man3/wcspbrk.3 @@ -0,0 +1,81 @@ +.\" $OpenBSD: wcspbrk.3,v 1.3 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WCSPBRK 3 +.Os +.Sh NAME +.Nm wcspbrk +.Nd locate multiple wide characters in a wide string +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wcspbrk "const wchar_t *s" "const wchar_t *charset" +.Sh DESCRIPTION +The +.Fn wcspbrk +function locates in the wide string +.Fa s +the first occurrence of any wide character in the wide string +.Fa charset +and returns a pointer to this wide character. +If no wide characters from +.Fa charset +occur anywhere in +.Fa s , +.Fn wcspbrk +returns +.Dv NULL . +.Sh SEE ALSO +.Xr strpbrk 3 , +.Xr wcschr 3 , +.Xr wcscspn 3 , +.Xr wcsrchr 3 , +.Xr wcsspn 3 , +.Xr wcsstr 3 , +.Xr wcstok 3 , +.Xr wmemchr 3 +.Sh STANDARDS +The +.Fn wcspbrk +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wcspbrk +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wcsrchr.3 b/static/openbsd/man3/wcsrchr.3 new file mode 100644 index 00000000..d4a2e7cf --- /dev/null +++ b/static/openbsd/man3/wcsrchr.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: wcsrchr.3,v 1.3 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WCSRCHR 3 +.Os +.Sh NAME +.Nm wcsrchr +.Nd locate last occurrence of a wide character in a wide string +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wcsrchr "const wchar_t *s" "wchar_t c" +.Sh DESCRIPTION +The +.Fn wcsrchr +function locates the last occurrence of the wide character +.Fa c +in the wide string +.Fa s . +The terminating null wide character is considered part of the wide string. +If +.Fa c +is the null wide character (L'\e0'), +.Fn wcsrchr +locates the terminating null wide character. +.Sh RETURN VALUES +The +.Fn wcsrchr +function returns a pointer to the located wide character or +.Dv NULL +if the wide character does not appear in the wide string. +.Sh SEE ALSO +.Xr strrchr 3 , +.Xr wcschr 3 , +.Xr wcscspn 3 , +.Xr wcspbrk 3 , +.Xr wcsspn 3 , +.Xr wcsstr 3 , +.Xr wcstok 3 , +.Xr wmemchr 3 +.Sh STANDARDS +The +.Fn wcsrchr +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wcsrchr +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wcsrtombs.3 b/static/openbsd/man3/wcsrtombs.3 new file mode 100644 index 00000000..40192a54 --- /dev/null +++ b/static/openbsd/man3/wcsrtombs.3 @@ -0,0 +1,195 @@ +.\" $OpenBSD: wcsrtombs.3,v 1.5 2013/06/05 03:39:22 tedu Exp $ +.\" $NetBSD: wcsrtombs.3,v 1.6 2003/09/08 17:54:32 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 $Mdocdate: June 5 2013 $ +.Dt WCSRTOMBS 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm wcsrtombs , +.Nm wcsnrtombs +.Nd converts a wide-character string to a multibyte character string \ +(restartable) +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn wcsrtombs "const char * restrict dst" "const wchar_t ** restrict src" \ +"size_t len" "mbstate_t * restrict ps" +.Ft size_t +.Fn wcsnrtombs "const char * restrict dst" "const wchar_t ** restrict src" \ +"size_t nwc" "size_t len" "mbstate_t * restrict ps" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn wcsrtombs +function converts the wide-character string indirectly pointed to by +.Fa src +to the corresponding multibyte character string +and stores it to the array pointed to by +.Fa dst . +The conversion stops due to the following reasons: +.Bl -bullet +.It +The conversion reaches a null wide character. +In this case, the null wide character is also converted. +.It +The conversion has already stored +.Fa len +bytes to the array pointed to by +.Fa dst . +.It +The conversion encounters an invalid character. +.El +.Pp +The +.Fn wcsnrtombs +function is equivalent to +.Fn wcsrtombs +except that it additionally stops the conversion after processing +.Fa nwc +wide characters. +.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 dst +is not a null pointer, +the pointer object pointed to by +.Fa src +is a null pointer (if the conversion is stopped due to reaching a null wide character) +or the address just past the last wide character processed. +.Pp +If +.Fa dst +is not a null pointer and the conversion is stopped due to reaching +a null wide character, +the state object pointed to by +.Fa ps +is set to an initial state after the conversion has taken place. +.Pp +The behaviour of the +.Fn wcsrtombs +and +.Fn wcsnrtombs +functions is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +There are two special cases: +.Bl -tag -width 012345678901 +.It "dst == NULL" +The conversion takes place, but the resulting multibyte string is discarded. +In this case, the pointer object pointed to by +.Fa src +is not modified and +.Fa len +is ignored. +.It "ps == NULL" +The +.Fn wcsrtombs +and +.Fn wcsnrtombs +functions use their own internal state objects to keep the conversion state, +instead of +.Fa ps +as mentioned in this manual page. +.Pp +Calling any other functions in +.Em libc +never change these internal states, +which are initialized at startup time of the program. +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +The +.Fn wcsrtombs +and +.Fn wcsnrtombs +functions return: +.Bl -tag -width 012345678901 +.It 0 or positive +Number of bytes stored to the array pointed to by +.Fa dst , +except for a null byte. +There is no cases that the value returned is greater than +.Fa len +(unless +.Fa dst +is a null pointer). +If the return value is equal to +.Fa len , +the string pointed to by +.Fa dst +will not be null-terminated. +.It (size_t)-1 +.Fa src +points to the string containing invalid wide character. +In this case, +.Va errno +is set to indicate the error. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +The +.Fn wcsrtombs +and +.Fn wcsnrtombs +functions may return the following errors: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa src +points to the string containing an invalid 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 wcrtomb 3 , +.Xr wcstombs 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn wcsrtombs +function conforms to +.St -ansiC . +The restrict qualifier is added at +.\" .St -isoC99 . +ISO/IEC 9899/AMD1:1995 +.Pq Dq ISO C99 . +.Pp +The +.Fn wcsnrtombs +function conforms to +.St -p1003.1-2008 . diff --git a/static/openbsd/man3/wcsspn.3 b/static/openbsd/man3/wcsspn.3 new file mode 100644 index 00000000..3be82344 --- /dev/null +++ b/static/openbsd/man3/wcsspn.3 @@ -0,0 +1,79 @@ +.\" $OpenBSD: wcsspn.3,v 1.3 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WCSSPN 3 +.Os +.Sh NAME +.Nm wcsspn +.Nd span a wide string +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn wcsspn "const wchar_t *s" "const wchar_t *charset" +.Sh DESCRIPTION +The +.Fn wcsspn +function spans the initial part of the wide string +.Fa s +as long as the wide characters from +.Fa s +occur in the wide string +.Fa charset . +.Sh RETURN VALUES +The +.Fn wcsspn +function returns the number of wide characters spanned. +.Sh SEE ALSO +.Xr strspn 3 , +.Xr wcschr 3 , +.Xr wcscspn 3 , +.Xr wcspbrk 3 , +.Xr wcsrchr 3 , +.Xr wcsstr 3 , +.Xr wcstok 3 , +.Xr wmemchr 3 +.Sh STANDARDS +The +.Fn wcsspn +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wcsspn +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wcsstr.3 b/static/openbsd/man3/wcsstr.3 new file mode 100644 index 00000000..203a76de --- /dev/null +++ b/static/openbsd/man3/wcsstr.3 @@ -0,0 +1,88 @@ +.\" $OpenBSD: wcsstr.3,v 1.3 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WCSSTR 3 +.Os +.Sh NAME +.Nm wcsstr +.Nd locate a wide substring in a wide string +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wcsstr "const wchar_t *big" "const wchar_t *little" +.Sh DESCRIPTION +The +.Fn wcsstr +function locates the first occurrence of the wide string +.Fa little +in the wide string +.Fa big . +.Pp +If +.Fa little +is an empty wide string, +.Fa big +is returned; +if +.Fa little +occurs nowhere in +.Fa big , +.Dv NULL +is returned; +otherwise a pointer to the first wide character of the first occurrence of +.Fa little +is returned. +.Sh SEE ALSO +.Xr strstr 3 , +.Xr wcschr 3 , +.Xr wcscspn 3 , +.Xr wcspbrk 3 , +.Xr wcsrchr 3 , +.Xr wcsspn 3 , +.Xr wcstok 3 , +.Xr wmemchr 3 +.Sh STANDARDS +The +.Fn wcsstr +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wcsstr +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wcstod.3 b/static/openbsd/man3/wcstod.3 new file mode 100644 index 00000000..2914a9c0 --- /dev/null +++ b/static/openbsd/man3/wcstod.3 @@ -0,0 +1,83 @@ +.\" $OpenBSD: wcstod.3,v 1.4 2025/06/13 18:34:00 schwarze Exp $ +.\" $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 $Mdocdate: June 13 2025 $ +.Dt WCSTOD 3 +.Os +.Sh NAME +.Nm wcstod , +.Nm wcstof , +.Nm wcstold +.Nd convert wide-character string to double, float or "long double" +.Sh SYNOPSIS +.In wchar.h +.Ft double +.Fn wcstod "const wchar_t * restrict nptr" "wchar_t ** restrict endptr" +.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" +.Sh DESCRIPTION +The +.Fn wcstod , +.Fn wcstof , +and +.Fn wcstold +functions are the wide-character versions of the +.Fn strtod , +.Fn strtof , +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 . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_NUMERIC +.Xr locale 1 +category can cause parsing failures; see CAVEATS in +.Xr setlocale 3 +for details. diff --git a/static/openbsd/man3/wcstok.3 b/static/openbsd/man3/wcstok.3 new file mode 100644 index 00000000..33ba1318 --- /dev/null +++ b/static/openbsd/man3/wcstok.3 @@ -0,0 +1,151 @@ +.\" $OpenBSD: wcstok.3,v 1.7 2011/07/25 00:38:53 schwarze Exp $ +.\" +.\" $NetBSD: wcstok.3,v 1.3 2003/09/08 17:54:33 wiz Exp $ +.\" +.\" Copyright (c) 1998 Softweyr LLC. All rights reserved. +.\" +.\" strtok_r, from Berkeley strtok +.\" Oct 13, 1998 by Wes Peters +.\" +.\" 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 $Mdocdate: July 25 2011 $ +.Dt WCSTOK 3 +.Os +.Sh NAME +.Nm wcstok +.Nd split wide-character string into tokens +.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 +.Xr strtok_r 3 +function. +.Pp +Since +.Fn wcstok +modifies the string, +.Fa str +should not point to an area in the initialized data segment. +.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 , +.Xr wcsstr 3 , +.Xr wmemchr 3 +.Sh STANDARDS +The +.Fn wcstok +function +conforms to +.St -isoC-99 . +.Sh HISTORY +The +.Fn wcstok +function was ported from +.Nx +and first appeared in +.Ox 3.8 . +.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/openbsd/man3/wcstol.3 b/static/openbsd/man3/wcstol.3 new file mode 100644 index 00000000..3c0de0e7 --- /dev/null +++ b/static/openbsd/man3/wcstol.3 @@ -0,0 +1,88 @@ +.\" $OpenBSD: wcstol.3,v 1.5 2025/06/13 18:34:00 schwarze Exp $ +.\" $NetBSD: wcstol.3,v 1.2 2006/08/08 17:32:05 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 $Mdocdate: June 13 2025 $ +.Dt WCSTOL 3 +.Os +.Sh NAME +.Nm wcstol , wcstoul , +.Nm wcstoll , wcstoull , +.Nm wcstoimax , wcstoumax +.Nd convert a wide-character string value to a long, unsigned long, \ +long long, unsigned long long, intmax_t, or uintmax_t integer +.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/openbsd/man3/wcstombs.3 b/static/openbsd/man3/wcstombs.3 new file mode 100644 index 00000000..fcef82a3 --- /dev/null +++ b/static/openbsd/man3/wcstombs.3 @@ -0,0 +1,130 @@ +.\" $OpenBSD: wcstombs.3,v 1.8 2022/03/29 18:15:52 naddy Exp $ +.\" $NetBSD: wcstombs.3,v 1.5 2003/09/08 17:54:32 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 $Mdocdate: March 29 2022 $ +.Dt WCSTOMBS 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm wcstombs +.Nd converts a wide-character string to a multibyte character string +.\" ---------------------------------------------------------------------- +.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 null-terminated wide-character string pointed to by +.Fa pwcs +to the corresponding multibyte character string, +and stores up to +.Fa n +bytes in 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 the +.Fn wcstombs +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +There are special cases: +.Bl -tag -width 012345678901 +.It s == NULL +The +.Fn wcstombs +function 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 causes 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 null-terminated. +.It (size_t)-1 +.Fa pwcs +points the string containing 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 cases: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa pwcs +Points to the string containing invalid wide character. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr setlocale 3 , +.Xr wctomb 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn wcstombs +function conforms to +.St -ansiC . +The restrict qualifier is added at +.\" .St -isoC99 . +ISO/IEC 9899/1999 +.Pq Dq ISO C99 . diff --git a/static/openbsd/man3/wcswidth.3 b/static/openbsd/man3/wcswidth.3 new file mode 100644 index 00000000..a2a5b2df --- /dev/null +++ b/static/openbsd/man3/wcswidth.3 @@ -0,0 +1,69 @@ +.\" $OpenBSD: wcswidth.3,v 1.2 2011/07/25 00:38:53 schwarze 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 $Mdocdate: July 25 2011 $ +.Dt WCSWIDTH 3 +.Os +.Sh NAME +.Nm wcswidth +.Nd number of column positions in wide-character string +.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 null 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 strlen 3 , +.Xr wcslen 3 , +.Xr wcwidth 3 +.Sh STANDARDS +The +.Fn wcswidth +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn wcswidth +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wcsxfrm.3 b/static/openbsd/man3/wcsxfrm.3 new file mode 100644 index 00000000..3ce59069 --- /dev/null +++ b/static/openbsd/man3/wcsxfrm.3 @@ -0,0 +1,104 @@ +.\" $OpenBSD: wcsxfrm.3,v 1.2 2019/01/18 07:43:36 schwarze Exp $ +.\" +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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. +.\" +.Dd $Mdocdate: January 18 2019 $ +.Dt WCSXFRM 3 +.Os +.Sh NAME +.Nm wcsxfrm , +.Nm wcsxfrm_l +.Nd transform a wide string under locale +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn wcsxfrm "wchar_t *dst" "const wchar_t *src" "size_t n" +.Ft size_t +.Fn wcsxfrm_l "wchar_t *dst" "const wchar_t *src" "size_t n" "locale_t locale" +.Sh DESCRIPTION +The idea of +.Fn wcsxfrm +and +.Fn wcsxfrm_l +is to +.Dq un-localize +a wide string: the functions transform +.Ar src , +storing the result in +.Ar dst , +such that +.Xr wcscmp 3 +on transformed wide strings returns what +.Xr wcscoll 3 +on the original untransformed wide strings would return. +.Pp +On +.Ox , +both have the same effect as +.Xr wcslcpy 3 , +and the global locale, the thread-specific locale, and the +.Fa locale +argument are ignored. +On other operating systems, the behaviour may depend on the +.Dv LC_CTYPE +and +.Dv LC_COLLATE +locale categories set with +.Xr setlocale 3 , +.Xr uselocale 3 , +or +.Xr newlocale 3 . +.Sh SEE ALSO +.Xr newlocale 3 , +.Xr setlocale 3 , +.Xr wcscmp 3 , +.Xr wcscoll 3 , +.Xr wcslcpy 3 +.Sh STANDARDS +The +.Fn wcsxfrm +function conforms to +.St -isoC-99 , +and +.Fn wcsxfrm_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn wcsxfrm +function has been available since +.Ox 4.8 , +and +.Fn wcsxfrm_l +since +.Ox 6.2 . diff --git a/static/openbsd/man3/wctob.3 b/static/openbsd/man3/wctob.3 new file mode 100644 index 00000000..383cd44b --- /dev/null +++ b/static/openbsd/man3/wctob.3 @@ -0,0 +1,85 @@ +.\" $OpenBSD: wctob.3,v 1.3 2007/05/31 19:19:29 jmc Exp $ +.\" $NetBSD: wctob.3,v 1.3 2003/04/16 13:34:41 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 $Mdocdate: May 31 2007 $ +.Dt WCTOB 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm wctob +.Nd convert a wide character to a single byte character +.\" ---------------------------------------------------------------------- +.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 the +.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/openbsd/man3/wctomb.3 b/static/openbsd/man3/wctomb.3 new file mode 100644 index 00000000..32f9e65a --- /dev/null +++ b/static/openbsd/man3/wctomb.3 @@ -0,0 +1,131 @@ +.\" $OpenBSD: wctomb.3,v 1.7 2022/03/29 18:15:52 naddy Exp $ +.\" $NetBSD: wctomb.3,v 1.3 2003/04/16 13:34:41 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 $Mdocdate: March 29 2022 $ +.Dt WCTOMB 3 +.Os +.Sh NAME +.Nm wctomb +.Nd converts a wide character to a multibyte character +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn wctomb "char * s" "wchar_t wchar" +.Sh DESCRIPTION +The +.Fn wctomb +function 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 null wide character +.Pq Sq \e0 , +this function places its own internal state to an initial conversion state. +.Pp +Calling any other functions in +.Em libc +never change the internal +state of +.Fn wctomb , +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 wctomb +is affected by +.Dv LC_CTYPE +category of the current locale. +.Pp +There is a 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 where 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/openbsd/man3/wctrans.3 b/static/openbsd/man3/wctrans.3 new file mode 100644 index 00000000..1ef1813b --- /dev/null +++ b/static/openbsd/man3/wctrans.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: wctrans.3,v 1.3 2017/09/05 03:16:13 schwarze Exp $ +.\" $NetBSD: wctrans.3,v 1.4 2004/01/24 16:58:54 wiz Exp $ +.\" +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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 $Mdocdate: September 5 2017 $ +.Dt WCTRANS 3 +.Os +.Sh NAME +.Nm wctrans , +.Nm wctrans_l +.Nd get a character mapping identifier by name +.Sh SYNOPSIS +.In wctype.h +.Ft wctrans_t +.Fn wctrans "const char *charmap" +.Ft wctrans_t +.Fn wctrans_l "const char *charmap" "locale_t locale" +.Sh DESCRIPTION +These functions return a character mapping identifier +corresponding to the locale-specific character mapping name +.Fa charmap . +This identifier can be used in the subsequent calls of +.Fn towctrans +or +.Fn towctrans_l , +respectively. +.Pp +The following names are defined in all locales: +.Bd -literal -offset indent +tolower toupper +.Ed +.Pp +The function +.Fn wctrans_l +uses the specified +.Fa locale , +whereas +.Fn wctrans +uses the thread-specific locale set with +.Xr uselocale 3 , +falling back to the global locale set with +.Xr setlocale 3 . +.Sh RETURN VALUES +These functions return the character mapping identifier, or +.Po Vt wctrans_t Pc Ns 0 +if +.Fa charmap +does not corresponding to a valid character mapping name. +.Sh SEE ALSO +.Xr newlocale 3 , +.Xr setlocale 3 , +.Xr towctrans 3 , +.Xr towlower 3 , +.Xr wctype 3 +.Sh STANDARDS +The +.Fn wctrans +function conforms to +.St -isoC-amd1 , +and +.Fn wctrans_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn wctrans +function has been available since +.Ox 3.8 , +and +.Fn wctrans_l +since +.Ox 6.2 . diff --git a/static/openbsd/man3/wctype.3 b/static/openbsd/man3/wctype.3 new file mode 100644 index 00000000..9613bb9d --- /dev/null +++ b/static/openbsd/man3/wctype.3 @@ -0,0 +1,96 @@ +.\" $OpenBSD: wctype.3,v 1.4 2017/09/05 03:16:13 schwarze Exp $ +.\" $NetBSD: wctype.3,v 1.4 2003/04/16 13:34:41 wiz Exp $ +.\" +.\" Copyright (c) 2017 Ingo Schwarze +.\" 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 $Mdocdate: September 5 2017 $ +.Dt WCTYPE 3 +.Os +.Sh NAME +.Nm wctype , +.Nm wctype_l +.Nd get a character class identifier by name +.Sh SYNOPSIS +.In wctype.h +.Ft wctype_t +.Fn wctype "const char *charclass" +.Ft wctype_t +.Fn wctype_l "const char *charclass" "locale_t locale" +.Sh DESCRIPTION +These functions return 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 +or +.Fn iswctype_l , +respectively. +.Pp +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 function +.Fn wctype_l +uses the specified +.Fa locale , +whereas +.Fn wctype +uses the thread-specific locale set with +.Xr uselocale 3 , +falling back to the global locale set with +.Xr setlocale 3 . +.Sh RETURN VALUES +These functions return the character class identifier, or +.Po Vt wctype_t Pc Ns 0 +if +.Fa charclass +does not correspond to a valid character class name. +.Sh SEE ALSO +.Xr iswctype 3 , +.Xr newlocale 3 , +.Xr setlocale 3 , +.Xr wctrans 3 +.Sh STANDARDS +The +.Fn wctype +function conforms to +.St -isoC-amd1 , +and +.Fn wctype_l +to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn wctype +function has been available since +.Ox 3.8 , +and +.Fn wctype_l +since +.Ox 6.2 . diff --git a/static/openbsd/man3/wcwidth.3 b/static/openbsd/man3/wcwidth.3 new file mode 100644 index 00000000..dc135274 --- /dev/null +++ b/static/openbsd/man3/wcwidth.3 @@ -0,0 +1,59 @@ +.\" $OpenBSD: wcwidth.3,v 1.2 2016/09/02 15:03:23 schwarze 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 $Mdocdate: September 2 2016 $ +.Dt WCWIDTH 3 +.Os +.Sh NAME +.Nm wcwidth +.Nd number of column positions of a wide-character code +.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 the NUL wide character (L'\e0'), \-1 if +.Fa wc +is not printable, or otherwise it returns the number of column +positions the character occupies, which may be 0, 1, or 2. +.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/openbsd/man3/wmemchr.3 b/static/openbsd/man3/wmemchr.3 new file mode 100644 index 00000000..17fbc9db --- /dev/null +++ b/static/openbsd/man3/wmemchr.3 @@ -0,0 +1,81 @@ +.\" $OpenBSD: wmemchr.3,v 1.10 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WMEMCHR 3 +.Os +.Sh NAME +.Nm wmemchr +.Nd locate wide character in wide string +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wmemchr "const wchar_t *b" "wchar_t c" "size_t len" +.Sh DESCRIPTION +The +.Fn wmemchr +function locates the first occurrence of +.Fa c +in wide string +.Fa b . +.Sh RETURN VALUES +The +.Fn wmemchr +function returns a pointer to the wide character located, or +.Dv NULL +if no such wide character exists within +.Fa len +wide characters. +.Sh SEE ALSO +.Xr memchr 3 , +.Xr wcschr 3 , +.Xr wcscspn 3 , +.Xr wcspbrk 3 , +.Xr wcsrchr 3 , +.Xr wcsspn 3 , +.Xr wcsstr 3 , +.Xr wcstok 3 +.Sh STANDARDS +The +.Fn wmemchr +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wmemchr +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wmemcmp.3 b/static/openbsd/man3/wmemcmp.3 new file mode 100644 index 00000000..bd8ddfd1 --- /dev/null +++ b/static/openbsd/man3/wmemcmp.3 @@ -0,0 +1,78 @@ +.\" $OpenBSD: wmemcmp.3,v 1.3 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WMEMCMP 3 +.Os +.Sh NAME +.Nm wmemcmp +.Nd compare wide strings +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fn wmemcmp "const wchar_t *s1" "const wchar_t *s2" "size_t len" +.Sh DESCRIPTION +The +.Fn wmemcmp +function compares the wide string +.Fa s1 +against the wide string +.Fa s2 . +Both wide strings are assumed to be +.Fa len +wide characters long. +.Sh RETURN VALUES +The +.Fn wmemcmp +function returns zero if the two wide strings are identical, +otherwise the difference between the first two differing wide characters is +returned. +Zero-length wide strings are always identical. +.Sh SEE ALSO +.Xr memcmp 3 , +.Xr wcscasecmp 3 , +.Xr wcscmp 3 +.Sh STANDARDS +The +.Fn wmemcmp +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wmemcmp +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wmemcpy.3 b/static/openbsd/man3/wmemcpy.3 new file mode 100644 index 00000000..2a6d528a --- /dev/null +++ b/static/openbsd/man3/wmemcpy.3 @@ -0,0 +1,79 @@ +.\" $OpenBSD: wmemcpy.3,v 1.5 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WMEMCPY 3 +.Os +.Sh NAME +.Nm wmemcpy +.Nd copy wide characters +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wmemcpy "wchar_t * restrict dst" "const wchar_t * restrict src" "size_t len" +.Sh DESCRIPTION +The +.Fn wmemcpy +function copies +.Fa len +wide characters from buffer +.Fa src +to buffer +.Fa dst . +If the two buffers may overlap, +.Xr wmemmove 3 +must be used instead. +.Sh RETURN VALUES +The +.Fn wmemcpy +function returns the original value of +.Fa dst . +.Sh SEE ALSO +.Xr memcpy 3 , +.Xr wcscpy 3 , +.Xr wcslcpy 3 , +.Xr wmemmove 3 +.Sh STANDARDS +The +.Fn wmemcpy +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wmemcpy +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wmemmove.3 b/static/openbsd/man3/wmemmove.3 new file mode 100644 index 00000000..46942e79 --- /dev/null +++ b/static/openbsd/man3/wmemmove.3 @@ -0,0 +1,78 @@ +.\" $OpenBSD: wmemmove.3,v 1.3 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WMEMMOVE 3 +.Os +.Sh NAME +.Nm wmemmove +.Nd copy wide characters +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wmemmove "wchar_t *dst" "const wchar_t *src" "size_t len" +.Sh DESCRIPTION +The +.Fn wmemmove +function copies +.Fa len +wide characters from buffer +.Fa src +to buffer +.Fa dst . +The two buffers may overlap; +the copy is always done in a non-destructive manner. +.Sh RETURN VALUES +The +.Fn wmemmove +function returns the original value of +.Fa dst . +.Sh SEE ALSO +.Xr memmove 3 , +.Xr wcscpy 3 , +.Xr wcslcpy 3 , +.Xr wmemcpy 3 +.Sh STANDARDS +The +.Fn wmemmove +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wmemmove +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wmemset.3 b/static/openbsd/man3/wmemset.3 new file mode 100644 index 00000000..2655d68b --- /dev/null +++ b/static/openbsd/man3/wmemset.3 @@ -0,0 +1,73 @@ +.\" $OpenBSD: wmemset.3,v 1.4 2013/06/05 03:39:23 tedu 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. +.\" +.Dd $Mdocdate: June 5 2013 $ +.Dt WMEMSET 3 +.Os +.Sh NAME +.Nm wmemset +.Nd write a wide string +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wmemset "wchar_t *s" "wchar_t c" "size_t len" +.Sh DESCRIPTION +The +.Fn wmemset +function writes +.Fa len +wide characters of value +.Fa c +to the wide string +.Fa s . +.Sh RETURN VALUES +The +.Fn wmemset +function returns the original value of +.Fa s . +.Sh SEE ALSO +.Xr memset 3 +.Sh STANDARDS +The +.Fn wmemset +function conforms to +.St -isoC-99 +and was first introduced in +.St -isoC-amd1 . +.Sh HISTORY +The +.Fn wmemset +function was ported from +.Nx +and first appeared in +.Ox 3.8 . diff --git a/static/openbsd/man3/wprintf.3 b/static/openbsd/man3/wprintf.3 new file mode 100644 index 00000000..78341785 --- /dev/null +++ b/static/openbsd/man3/wprintf.3 @@ -0,0 +1,629 @@ +.\" $OpenBSD: wprintf.3,v 1.11 2025/05/17 07:46:49 tobias 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 $Mdocdate: May 17 2025 $ +.Dt WPRINTF 3 +.Os +.Sh NAME +.Nm wprintf , fwprintf , swprintf , +.Nm vwprintf , vfwprintf , vswprintf +.Nd formatted wide character output conversion +.Sh SYNOPSIS +.In stdio.h +.In wchar.h +.Ft int +.Fo fwprintf +.Fa "FILE * restrict stream" +.Fa "const wchar_t * restrict format" +.Fa ... +.Fc +.Ft int +.Fo swprintf +.Fa "wchar_t * restrict ws" +.Fa "size_t n" +.Fa "const wchar_t * restrict format" +.Fa ... +.Fc +.Ft int +.Fo wprintf +.Fa "const wchar_t * restrict format" +.Fa ... +.Fc +.In stdarg.h +.Ft int +.Fo vfwprintf +.Fa "FILE * restrict stream" +.Fa "const wchar_t * restrict format" +.Fa "va_list ap" +.Fc +.Ft int +.Fo vswprintf +.Fa "wchar_t * restrict ws" +.Fa "size_t n" +.Fa "const wchar_t * restrict format" +.Fa "va_list ap" +.Fc +.Ft int +.Fo vwprintf +.Fa "const wchar_t * restrict format" +.Fa "va_list ap" +.Fc +.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 va_start 3 ) +are converted for output. +.Pp +These functions return the number of characters printed +(not including the trailing +.Ql \e0 +used to end output to strings). +.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 "'0' (space)" +.It Sq Cm # +The value should be converted to an +.Dq alternate form . +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. +For all other formats, behaviour is undefined. +.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 ' +On +.Ox , +this flag has no effect. +On other systems, it may cause the insertion of +.Xr locale 1 Ns -dependent +thousands separator characters into the integral parts of arguments +of the +.Cm d , i , u , f , +or +.Cm F +conversions. +.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 "q (deprecated)" "signed char" "unsigned long long" "long long *" +.It Sy Modifier Ta Sy "d, i" Ta Sy "o, u, x, X" Ta Sy n +.It hh Ta "signed char" Ta "unsigned char" Ta "signed char *" +.It h Ta short Ta "unsigned short" Ta "short *" +.It "l (ell)" Ta long Ta "unsigned long" Ta "long *" +.It "ll (ell ell)" Ta "long long" Ta "unsigned long long" Ta "long long *" +.It j Ta intmax_t Ta uintmax_t Ta "intmax_t *" +.It t Ta ptrdiff_t Ta (see note) Ta "ptrdiff_t *" +.It z Ta "(see note)" Ta size_t Ta "(see note)" +.It "q (deprecated)" Ta quad_t Ta u_quad_t Ta "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 "Modifier" "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 "Modifier" "wint_t" "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 "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 \(+- 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 \(+- 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 mantissa+exponent internal +floating point representation; the +.Sm off +.Oo \- Oc Li 0x Ar h Li \&. Ar hhh +.Sm on +portion represents exactly the mantissa; only denormalized +mantissas 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 mantissa and exponent. +.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 +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 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 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 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 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 +This conversion specifier has serious security implications, so it was changed to +no longer store the number of bytes written so far into the variable indicated +by the pointer argument. +Instead a +.Xr syslog 3 +message will be generated, after which the program is aborted with +.Dv SIGABRT . +.It Cm % +A +.Ql % +is written. +No argument is converted. +The complete conversion specification +is +.Ql %% . +.El +.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 ERRORS +In addition to the errors documented for the +.Xr write 2 +system call, the +.Fn wprintf +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 return value would be too large to be represented by an +.Vt int . +.El +.Sh SEE ALSO +.Xr btowc 3 , +.Xr fputws 3 , +.Xr printf 3 , +.Xr putwc 3 , +.Xr setlocale 3 , +.Xr wcsrtombs 3 +.Sh STANDARDS +The +.Fn wprintf , +.Fn fwprintf , +.Fn swprintf , +.Fn vwprintf , +.Fn vfwprintf +and +.Fn vswprintf +functions +conform to +.St -isoC-99 . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_NUMERIC +.Xr locale 1 +category can cause erratic output; see CAVEATS in +.Xr setlocale 3 +for details. diff --git a/static/openbsd/man3/wresize.3 b/static/openbsd/man3/wresize.3 new file mode 100644 index 00000000..252bc58e --- /dev/null +++ b/static/openbsd/man3/wresize.3 @@ -0,0 +1,67 @@ +.\" $OpenBSD: wresize.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.\" +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2010,2015 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1996 +.\" +.\" $Id: wresize.3,v 1.8 2023/10/17 09:52:08 nicm Exp $ +.TH wresize 3 2023-07-01 "ncurses 6.4" "Library calls" +.SH NAME +\fBwresize\fP \- resize a curses window +.SH SYNOPSIS +\fB#include \fP +.sp +\fBint wresize(WINDOW *\fIwin\fB, int \fIlines\fB, int \fIcolumns\fB);\fR +.SH DESCRIPTION +This is an extension to the curses library. +It reallocates storage for an \fBncurses\fP +window to adjust its dimensions to the specified values. +If either dimension is larger than the current values, the +window's data is filled with blanks that have the current background rendition +(as set by \fBwbkgdset\fP) merged into them. +.SH RETURN VALUE +The function returns the integer \fBERR\fP upon failure and \fBOK\fP on success. +It will fail if either of the dimensions less than or equal to zero, +or if an error occurs while (re)allocating memory for the window. +.SH NOTES +The only restriction placed on the dimensions is that they be greater than zero. +The dimensions are not compared to \fBcurses\fP screen dimensions to +simplify the logic of \fBresizeterm\fP. +The caller must ensure that the window's dimensions fit within the +actual screen dimensions. +.SH PORTABILITY +It is not possible to resize windows with SVr4 curses. +.PP +This extension of ncurses was introduced in mid-1995. +It was adopted in NetBSD curses (2001) and PDCurses (2003). +.SH SEE ALSO +\fBresizeterm\fP(3). +.SH AUTHOR +Thomas Dickey (from an equivalent function written in 1988 for BSD curses). diff --git a/static/openbsd/man3/wscanf.3 b/static/openbsd/man3/wscanf.3 new file mode 100644 index 00000000..714281a8 --- /dev/null +++ b/static/openbsd/man3/wscanf.3 @@ -0,0 +1,448 @@ +.\" $OpenBSD: wscanf.3,v 1.5 2019/08/30 20:27:25 jmc 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 +.\" FreeBSD: src/lib/libc/stdio/scanf.3,v 1.24 2003/06/28 09:03:25 das Exp +.\" +.Dd $Mdocdate: August 30 2019 $ +.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 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 read input according to the given +.Fa format +as described below. +This format may contain +.Dq conversion specifiers ; +the results of such conversions, if any, are stored through a set of pointer +arguments. +.Pp +The +.Fn wscanf +function reads input from the standard input stream +.Em stdin , +.Fn fwscanf +reads input from the supplied stream pointer +.Fa stream , +and +.Fn swscanf +reads its input from the wide character string pointed to by +.Fa str . +.Pp +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 va_start 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. +.Pp +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. +Whitespace (such as blanks, tabs, or newlines) in the +.Fa format +string match any amount of whitespace, 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 "ll (ell 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 aefg +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 aefg +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 an +.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 whitespace; +this whitespace 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 xX +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-whitespace wide characters; +the next pointer must be a pointer to +.Vt char , +and the provided array must be large enough to accept and store +the multibyte representation of the whole sequence and the +terminating NUL character. +The input string stops at whitespace +or at the maximum field width, whichever occurs first. +If specified, the maximum field length refers to the sequence +being scanned rather than the storage space, hence the provided +array must be 1 larger for the terminating NUL character. +.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 +Matches a sequence of wide characters consuming the number of wide characters +specified by the field width (defaults to 1 if unspecified); +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 NUL is added). +The usual skip of leading whitespace is suppressed. +To skip whitespace 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 \&[ +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 NUL character. +The usual skip of leading whitespace is suppressed. +.Pp +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 +(or, with a circumflex, in) the 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 +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 functions +.Fn wscanf , +.Fn fwscanf , +.Fn swscanf , +.Fn vwscanf , +.Fn vfwscanf , +and +.Fn vswscanf +conform to +.St -isoC-99 . +.Sh CAVEATS +On systems other than +.Ox , +the +.Dv LC_NUMERIC +.Xr locale 1 +category can cause parsing failures; see CAVEATS in +.Xr setlocale 3 +for details. +.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/openbsd/man3/x509_verify.3 b/static/openbsd/man3/x509_verify.3 new file mode 100644 index 00000000..b9fe13a5 --- /dev/null +++ b/static/openbsd/man3/x509_verify.3 @@ -0,0 +1,221 @@ +.\" $OpenBSD: x509_verify.3,v 1.2 2020/09/14 14:21:46 schwarze Exp $ +.\" +.\" Copyright (c) 2020 Bob Beck +.\" +.\" 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: September 14 2020 $ +.Dt X509_VERIFY 3 +.Os +.Sh NAME +.Nm x509_verify , +.Nm x509_verify_ctx_new , +.Nm x509_verify_ctx_free , +.Nm x509_verify_ctx_set_max_depth , +.Nm x509_verify_ctx_set_max_signatures , +.Nm x509_verify_ctx_set_max_chains , +.Nm x509_verify_ctx_set_purpose , +.Nm x509_verify_ctx_set_intermediates , +.Nm x509_verify_ctx_error_string , +.Nm x509_verify_ctx_error_depth , +.Nm x509_verify_ctx_chain +.Nd discover and verify X.509 certificate chains +.Sh SYNOPSIS +.In openssl/x509_verify.h +.Ft size_t +.Fo x509_verify +.Fa "X509_VERIFY_CTX *ctx" +.Fa "X509 *leaf" +.Fa "char *name" +.Fc +.Ft X509_VERIFY_CTX * +.Fo x509_verify_ctx_new +.Fa "STACK_OF(X509) *roots" +.Fc +.Ft void +.Fo x509_verify_ctx_free +.Fa "X509_VERIFY_CTX *ctx" +.Fc +.Ft int +.Fo x509_verify_ctx_set_max_depth +.Fa "X509_VERIFY_CTX *ctx" +.Fa "size_t max" +.Fc +.Ft int +.Fo x509_verify_ctx_set_max_signatures +.Fa "X509_VERIFY_CTX *ctx" +.Fa "size_t max" +.Fc +.Ft int +.Fo x509_verify_ctx_set_max_chains +.Fa "X509_VERIFY_CTX *ctx" +.Fa "size_t max" +.Fc +.Ft int +.Fo x509_verify_ctx_set_purpose +.Fa "X509_VERIFY_CTX *ctx" +.Fa "int purpose_id" +.Fc +.Ft int +.Fo x509_verify_ctx_set_intermediates +.Fa "X509_VERIFY_CTX *ctx" +.Fa "STACK_OF(X509) *intermediates" +.Fc +.Ft const char * +.Fo x509_verify_ctx_error_string +.Fa "X509_VERIFY_CTX *ctx" +.Fc +.Ft size_t +.Fo x509_verify_ctx_error_depth +.Fa "X509_VERIFY_CTX *ctx" +.Fc +.Ft STACK_OF(X509) * +.Fo x509_verify_ctx_chain +.Fa "X509_VERIFY_CTX *ctx" +.Fa "size_t index" +.Fc +.Sh DESCRIPTION +The +.Fn x509_verify +function attempts to discover and validate all certificate chains +for the +.Fa name +from the +.Fa leaf +certificate based on the parameters in +.Fa ctx . +Multiple chains may be built and validated. +Revocation checking is not done by this function, and should be +performed by the caller on any returned chains if so desired. +.Pp +.Fn x509_verify_ctx_new +allocates a new context using the trusted +.Fa roots . +In case of success, it increments the reference count of +.Fa roots . +.Pp +.Fn x509_verify_ctx_free +frees +.Fa ctx +and decrements the reference count of the +.Fa roots +and +.Fa intermediates +associated with it. +If +.Fa ctx +is +.Dv NULL , +no action occurs. +.Pp +.Fn x509_verify_ctx_set_max_depth +sets the maximum depth of certificate chains that will be constructed to +.Fa max , +which can be in the range from 1 to the default of 32. +.Pp +.Fn x509_verify_ctx_set_max_signatures +sets the maximum number of public key signature operations that will be +used when verifying certificate chains to +.Fa max , +which can be in the range from 1 to 100000. +The default is 256. +.Pp +.Fn x509_verify_ctx_set_max_chains +sets the maximum number of chains which may be returned to +.Fa max , +which can be in the range from 1 to the default of 8. +.Pp +.Fn x509_verify_ctx_set_purpose +sets the certificate purpose for validation to +.Fa purpose_id . +The +.Dv X509_PURPOSE_* +constants listed in +.Xr X509_check_purpose 3 +can be used. +.Pp +.Fn x509_verify_ctx_set_intermediates +provides some intermediate certificates, typically received from +the peer, to be used for building chains. +In case of success, this function increases the reference count of +.Fa intermediates . +.Pp +.Fn x509_verify_ctx_error_string +extracts a description of the last error encountered by a previous +call to +.Fn x509_verify +from +.Fa ctx . +.Pp +.Fn x509_verify_ctx_error_depth +extracts the depth of the last error encountered by a previous +call to +.Fn x509_verify +from +.Fa ctx . +.Pp +.Fn x509_verify_ctx_chain +extracts the validated chain with the given +.Fa index +from +.Fa ctx +after a previous call to +.Fn x509_verify . +The +.Fa index +starts at 0, and it is an error to pass a number +greater than or equal to the return value of +.Fn x509_verify . +The returned chain is neither copied, +nor is its reference count increased. +.Sh RETURN VALUES +.Fn x509_verify +returns the number of chains successfully built and validated +or 0 on failure. +.Pp +.Fn x509_verify_ctx_new +returns a newly allocated context or +.Dv NULL +on failure. +.Pp +.Fn x509_verify_ctx_set_max_depth , +.Fn x509_verify_ctx_set_max_signatures , +.Fn x509_verify_ctx_set_max_chains , +.Fn x509_verify_ctx_set_purpose , +and +.Fn x509_verify_ctx_set_intermediates +return 1 on success or 0 on failure. +.Pp +.Fn x509_verify_ctx_error_string +returns a pointer to a human readable error string. +If no error occurred, +.Qq ok +is returned. +.Pp +.Fn x509_verify_ctx_chain +returns an internal pointer to a validated chain or +.Dv NULL +if +.Fa index +is greater than or equal to the number of chains +that were successfully built and validated. +The returned pointer becomes invalid when +.Fa ctx +is destroyed. +.Sh SEE ALSO +.Xr X509_verify_cert 3 +.Sh HISTORY +These functions first appeared in +.Ox 6.8 . +.Sh AUTHORS +.An Bob Beck Aq Mt beck@openbsd.org diff --git a/static/openbsd/man3/xdr.3 b/static/openbsd/man3/xdr.3 new file mode 100644 index 00000000..418bb9e6 --- /dev/null +++ b/static/openbsd/man3/xdr.3 @@ -0,0 +1,567 @@ +.\" $OpenBSD: xdr.3,v 1.28 2022/09/11 06:38:11 jmc Exp $ +.\" Mostly converted to mandoc by Theo de Raadt, Tue Feb 24 04:04:46 MST 1998 +.\" +.\" Copyright (c) 2010, Oracle America, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer in the documentation and/or other materials +.\" provided with the distribution. +.\" * Neither the name of the "Oracle America, Inc." nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" 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. +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt XDR_ARRAY 3 +.Os +.Sh NAME +.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_inline , +.Nm xdr_int , +.Nm xdr_long , +.Nm xdr_int64_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 xdrstdio_create , +.Nm xdr_string , +.Nm xdr_u_char , +.Nm xdr_u_int , +.Nm xdr_u_long , +.Nm xdr_u_int64_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 +.In sys/types.h +.In rpc/xdr.h +.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 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_int64_t "XDR *xdrs" "int64_t *lp" +.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 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_int "XDR *xdrs" "unsigned int *up" +.Ft int +.Fn xdr_u_long "XDR *xdrs" "unsigned long *ulp" +.Ft int +.Fn xdr_u_int64_t "XDR *xdrs" "u_int64_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. +.Pp +.Fn xdr_array +is 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 size of 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. +.Pp +.Fn xdr_bool +is 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. +.Pp +.Fn xdr_bytes +is 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. +.Pp +.Fn xdr_char +is 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 . +.Pp +.Fn xdr_destroy +is 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. +.Pp +.Fn xdr_double +is a filter primitive that translates between C +.Vt double +precision numbers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_enum +is a filter primitive that translates between the C +.Vt enum +type (actually an integer) and its external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_float +is a filter primitive that translates between the C +.Vt float +type and its external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_free +is a 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 +.Fa not +freed, but what it points to is freed (recursively). +.Pp +.Fn xdr_getpos +is 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. +.Pp +.Fn xdr_inline +is 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 * . +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. +.Pp +.Fn xdr_int +is a filter primitive that translates between C integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_long +is a filter primitive that translates between C +.Vt long +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_int64_t +is a filter primitive that translates between C +.Vt int64_t +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdrmem_create +is a routine which 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 ) . +.Pp +.Fn xdr_opaque +is 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. +.Pp +.Fn xdr_pointer +is 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. +.Pp +.Fn xdrrec_create +is a routine which 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, +.Fn (*writeit) +is called. +Similarly, when a stream's input buffer is empty, +.Fn (*readit) +is called. +The behavior of these two routines is similar to the system calls +.Fn read +and +.Fn write , +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. +Warning: this XDR stream implements an intermediate record stream. +Therefore there are additional bytes in the stream +to provide record boundary information. +.Pp +.Fn xdrrec_endofrecord +is a routine which 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. +.Pp +.Fn xdrrec_eof +is a routine which 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. +.Pp +.Fn xdrrec_skiprecord +is a routine which 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. +.Pp +.Fn xdr_reference +is a primitive that provides pointer chasing within structures. +The parameter +.Fa pp +is the address of the pointer; +.Fa size +is the size of 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. +Warning: this routine does not understand +.Dv NULL +pointers. +Use +.Fn xdr_pointer +instead. +.Pp +.Fn xdr_setpos +is 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. +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. +.Pp +.Fn xdr_short +is a filter primitive that translates between C +.Vt short +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdrstdio_create +is a routine which 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 ) . +Warning: the destroy routine associated with such XDR streams calls +.Fn fflush +on the +.Fa file +stream, but never +.Fn fclose . +.Pp +.Fn xdr_string +is 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. +.Pp +.Fn xdr_u_char +is a filter primitive that translates between +.Vt unsigned +C characters and their external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_u_int +is a filter primitive that translates between C +.Vt unsigned +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_u_long +is a filter primitive that translates between C +.Vt unsigned long +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_u_int64_t +is a filter primitive that translates between C +.Vt u_int64_t +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_u_short +is a filter primitive that translates between C +.Vt unsigned short +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_union +is a filter primitive that translates between a discriminated C +.Vt union +and its corresponding external representation. +It first translates the discriminant of the union located at +.Fa dscmp . +This discriminant is always an +.Vt enum_t . +Next the union located at +.Fa unp +is translated. +The parameter +.Fa choices +is a pointer to an array of +.Vt struct xdr_discrim +structures, containing the two members +.Fa value +and +.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 +.Vt struct 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 +.Fn (*defaultarm) +procedure is called (if it is not +.Dv NULL ) . +Returns one if it succeeds, zero otherwise. +.Pp +.Fn xdr_vector +is 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 size of 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. +.Pp +.Fn xdr_void +is a routine which always returns one. +It may be passed to RPC +routines that require a function parameter, but where nothing is to be done. +.Pp +.Fn xdr_wrapstring +is a primitive that calls +.Nm xdr_string Ns Pq Fa xdrs , sp , Dv 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. +.Sh SEE ALSO +.Xr rpc 3 +.Rs +.%T eXternal Data Representation Standard: Protocol Specification +.Re +.Rs +.%T eXternal Data Representation: Sun Technical Notes +.Re +.Sh STANDARDS +.Rs +.%D June 1987 +.%Q Sun Microsystems, Inc. +.%R RFC 1014 +.%T XDR: External Data Representation Standard +.Re diff --git a/static/openbsd/man3/yp_bind.3 b/static/openbsd/man3/yp_bind.3 new file mode 100644 index 00000000..1c429e9c --- /dev/null +++ b/static/openbsd/man3/yp_bind.3 @@ -0,0 +1,355 @@ +.\" $OpenBSD: yp_bind.3,v 1.3 2025/10/14 06:30:16 jsg 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 REGENTS OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: October 14 2025 $ +.Dt YP_BIND 3 +.Os +.Sh NAME +.Nm yp_all , +.Nm yp_bind , +.Nm yp_first , +.Nm yp_get_default_domain , +.Nm yp_maplist , +.Nm yp_master , +.Nm yp_match , +.Nm yp_next , +.Nm yp_order , +.Nm yp_unbind , +.Nm yperr_string , +.Nm ypprot_err +.Nd Interface to the YP subsystem +.Sh SYNOPSIS +.In sys/types.h +.In rpc/rpc.h +.In rpcsvc/ypclnt.h +.In rpcsvc/yp_prot.h +.Ft int +.Fn yp_all "char *indomain" "char *inmap" "struct ypall_callback *incallback" +.Ft int +.Fn yp_bind "char *dom" +.Ft int +.Fn yp_first "char *indomain" "char *inmap" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen" +.Ft int +.Fn yp_get_default_domain "char **domp" +.Ft int +.Fn yp_maplist "char *indomain" "struct ypmaplist **outmaplist" +.Ft int +.Fn yp_master "char *indomain" "char *inmap" "char **outname" +.Ft int +.Fn yp_match "char *indomain" "char *inmap" "const char *inkey" "int inkeylen" "char **outval" "int *outvallen" +.Ft int +.Fn yp_next "char *indomain" "char *inmap" "char *inkey" "int inkeylen" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen" +.Ft int +.Fn yp_order "char *indomain" "char *inmap" "char *outorder" +.Ft void +.Fn yp_unbind "char *dom" +.Ft char * +.Fn yperr_string "int incode" +.Ft int +.Fn ypprot_err "unsigned int incode" +.Sh DESCRIPTION +This function 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 +.Sq in +and output values begin with +.Sq out . +Any output values of type +.Em char ** +should be the addresses of uninitialized character pointers. +Only if a call succeeds will memory be allocated by the YP client routines +using +.Fn malloc . +This memory can later be freed by the user if there is no additional need for +the data stored there. +For +.Fa outkey +and +.Fa outval , +two extra bytes of memory are allocated for a +.Ql \en +and +.Ql \e0 , +which are not +reflected in the values of +.Fa outkeylen +or +.Fa outvallen . +All occurrences of +.Fa indomain +and +.Fa inmap +must be non-null, NUL-terminated strings. +All input strings which also have +a corresponding length parameter cannot be null 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 +.Fa outdomain +is suitable for use as the +.Fa 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 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 suite provides the following functionality: +.Bl -tag -width "yperr_string()" +.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 +.Fa inkey +value should be the +.Fa 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 +.Fa outkey +value from the previous call to +.Fn yp_next +as the value for +.Fa 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 method uses TCP, unlike all other functions 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 +.Fn 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 +.Vt char * Ns Va data +argument is an opaque pointer for use by the callback function. +The +.Fn 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 ( + unsigned long 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 an +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; therefore, the +.Fn 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 +.Fn foreach +function, either. +.It Fa indata +This is the contents of the +.Fa incallback Ns -> Ns Va data +element of the callback structure. +It is provided as a means to share state between the +.Fn 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 yp_maplist +Returns a singly-linked list of the names of all the maps available in the +named domain. +The second argument to +.Fn yp_maplist +is: +.Bd -literal -offset indent +struct ypmaplist { + char *map; + struct ypmaplist *next; +}; +.Ed +.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 an error code suitable for +.Fn yperr_string . +.El +.Sh RETURN VALUES +All functions 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_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_NODOM +The local YP domain is not set. +.It Bq Er YPERR_NOMORE +There are no more records in the queried map. +.It Bq Er YPERR_PMAP +Cannot communicate with portmap. +.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_YPBIND +Cannot communicate with +.Xr ypbind 8 . +.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 -- cgit v1.2.3