{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1760043501, "reponame":"openssl", "desc":"OpenSSL", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://warmcat.com/repo/openssl", "f":3, "items": [ {"schema":"libjg2-1", "cid":"1b700f4437965765f2ee06411981716a", "oid":{ "oid": "66e59702f1effae94e88e3e586e9b736151d8d98", "alias": []},"blobname": "doc/man3/DEFINE_STACK_OF.pod", "blob": "\u003dpod\n\n\u003dhead1 NAME\n\nDEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF,\nDEFINE_SPECIAL_STACK_OF_CONST,\nOPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr,\nOPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_free,\nOPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null,\nOPENSSL_sk_num, OPENSSL_sk_pop, OPENSSL_sk_pop_free, OPENSSL_sk_push,\nOPENSSL_sk_set, OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort,\nOPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero,\nsk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, sk_TYPE_free,\nsk_TYPE_zero, sk_TYPE_delete, sk_TYPE_delete_ptr, sk_TYPE_push,\nsk_TYPE_unshift, sk_TYPE_pop, sk_TYPE_shift, sk_TYPE_pop_free,\nsk_TYPE_insert, sk_TYPE_set, sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort,\nsk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func -\nstack container\n\n\u003dhead1 SYNOPSIS\n\n\u003dfor comment generic\n\n #include \u003copenssl/safestack.h\u003e\n\n STACK_OF(TYPE)\n DEFINE_STACK_OF(TYPE)\n DEFINE_STACK_OF_CONST(TYPE)\n DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE)\n DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE)\n\n typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b);\n typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a);\n typedef void (*sk_TYPE_freefunc)(TYPE *a);\n\n int sk_TYPE_num(const STACK_OF(TYPE) *sk);\n TYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx);\n STACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare);\n STACK_OF(TYPE) *sk_TYPE_new_null(void);\n void sk_TYPE_free(const STACK_OF(TYPE) *sk);\n void sk_TYPE_zero(const STACK_OF(TYPE) *sk);\n TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i);\n TYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr);\n int sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr);\n int sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr);\n TYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk);\n TYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk);\n void sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc);\n int sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx);\n TYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr);\n int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr);\n int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr);\n void sk_TYPE_sort(const STACK_OF(TYPE) *sk);\n int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk);\n STACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk);\n STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk,\n sk_TYPE_copyfunc copyfunc,\n sk_TYPE_freefunc freefunc);\n sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk,\n sk_TYPE_compfunc compare));\n\n\u003dhead1 DESCRIPTION\n\nApplications can create and use their own stacks by placing any of the macros\ndescribed below in a header file. These macros define typesafe inline\nfunctions that wrap around the utility B\u003cOPENSSL_sk_\u003e API.\nIn the description here, I\u003cTYPE\u003e is used\nas a placeholder for any of the OpenSSL datatypes, such as I\u003cX509\u003e.\n\nSTACK_OF() returns the name for a stack of the specified B\u003cTYPE\u003e.\nDEFINE_STACK_OF() creates set of functions for a stack of B\u003cTYPE\u003e. This\nwill mean that type B\u003cTYPE\u003e is stored in each stack, the type is referenced by\nSTACK_OF(TYPE) and each function name begins with I\u003csk_TYPE_\u003e. For example:\n\n TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);\n\nDEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except\neach element is constant. For example:\n\n const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);\n\nDEFINE_SPECIAL_STACK_OF() defines a stack of B\u003cTYPE\u003e but\neach function uses B\u003cFUNCNAME\u003e in the function name. For example:\n\n TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);\n\nDEFINE_SPECIAL_STACK_OF_CONST() is similar except that each element is\nconstant:\n\n const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);\n\nsk_TYPE_num() returns the number of elements in B\u003csk\u003e or -1 if B\u003csk\u003e is\nB\u003cNULL\u003e.\n\nsk_TYPE_value() returns element B\u003cidx\u003e in B\u003csk\u003e, where B\u003cidx\u003e starts at\nzero. If B\u003cidx\u003e is out of range then B\u003cNULL\u003e is returned.\n\nsk_TYPE_new() allocates a new empty stack using comparison function B\u003ccompar\u003e.\nIf B\u003ccompar\u003e is B\u003cNULL\u003e then no comparison function is used.\n\nsk_TYPE_new_null() allocates a new empty stack with no comparison function.\n\nsk_TYPE_set_cmp_func() sets the comparison function of B\u003csk\u003e to B\u003ccompar\u003e.\nThe previous comparison function is returned or B\u003cNULL\u003e if there was\nno previous comparison function.\n\nsk_TYPE_free() frees up the B\u003csk\u003e structure. It does B\u003cnot\u003e free up any\nelements of B\u003csk\u003e. After this call B\u003csk\u003e is no longer valid.\n\nsk_TYPE_zero() sets the number of elements in B\u003csk\u003e to zero. It does not free\nB\u003csk\u003e so after this call B\u003csk\u003e is still valid.\n\nsk_TYPE_pop_free() frees up all elements of B\u003csk\u003e and B\u003csk\u003e itself. The\nfree function freefunc() is called on each element to free it.\n\nsk_TYPE_delete() deletes element B\u003ci\u003e from B\u003csk\u003e. It returns the deleted\nelement or B\u003cNULL\u003e if B\u003ci\u003e is out of range.\n\nsk_TYPE_delete_ptr() deletes element matching B\u003cptr\u003e from B\u003csk\u003e. It returns\nthe deleted element or B\u003cNULL\u003e if no element matching B\u003cptr\u003e was found.\n\nsk_TYPE_insert() inserts B\u003cptr\u003e into B\u003csk\u003e at position B\u003cidx\u003e. Any existing\nelements at or after B\u003cidx\u003e are moved downwards. If B\u003cidx\u003e is out of range\nthe new element is appended to B\u003csk\u003e. sk_TYPE_insert() either returns the\nnumber of elements in B\u003csk\u003e after the new element is inserted or zero if\nan error (such as memory allocation failure) occurred.\n\nsk_TYPE_push() appends B\u003cptr\u003e to B\u003csk\u003e it is equivalent to:\n\n sk_TYPE_insert(sk, ptr, -1);\n\nsk_TYPE_unshift() inserts B\u003cptr\u003e at the start of B\u003csk\u003e it is equivalent to:\n\n sk_TYPE_insert(sk, ptr, 0);\n\nsk_TYPE_pop() returns and removes the last element from B\u003csk\u003e.\n\nsk_TYPE_shift() returns and removes the first element from B\u003csk\u003e.\n\nsk_TYPE_set() sets element B\u003cidx\u003e of B\u003csk\u003e to B\u003cptr\u003e replacing the current\nelement. The new element value is returned or B\u003cNULL\u003e if an error occurred:\nthis will only happen if B\u003csk\u003e is B\u003cNULL\u003e or B\u003cidx\u003e is out of range.\n\nsk_TYPE_find() searches B\u003csk\u003e for the element B\u003cptr\u003e. In the case\nwhere no comparison function has been specified, the function performs\na linear search for a pointer equal to B\u003cptr\u003e. The index of the first\nmatching element is returned or B\u003c-1\u003e if there is no match. In the case\nwhere a comparison function has been specified, B\u003csk\u003e is sorted then\nsk_TYPE_find() returns the index of a matching element or B\u003c-1\u003e if there\nis no match. Note that, in this case, the matching element returned is\nnot guaranteed to be the first; the comparison function will usually\ncompare the values pointed to rather than the pointers themselves and\nthe order of elements in B\u003csk\u003e could change.\n\nsk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison\nfunction has been specified and no matching element is found. Instead\nof returning B\u003c-1\u003e, sk_TYPE_find_ex() returns the index of the element\neither before or after the location where B\u003cptr\u003e would be if it were\npresent in B\u003csk\u003e.\n\nsk_TYPE_sort() sorts B\u003csk\u003e using the supplied comparison function.\n\nsk_TYPE_is_sorted() returns B\u003c1\u003e if B\u003csk\u003e is sorted and B\u003c0\u003e otherwise.\n\nsk_TYPE_dup() returns a copy of B\u003csk\u003e. Note the pointers in the copy\nare identical to the original.\n\nsk_TYPE_deep_copy() returns a new stack where each element has been copied.\nCopying is performed by the supplied copyfunc() and freeing by freefunc(). The\nfunction freefunc() is only called if an error occurs.\n\n\u003dhead1 NOTES\n\nCare should be taken when accessing stacks in multi-threaded environments.\nAny operation which increases the size of a stack such as sk_TYPE_insert() or\nsk_push() can \u0022grow\u0022 the size of an internal array and cause race conditions\nif the same stack is accessed in a different thread. Operations such as\nsk_find() and sk_sort() can also reorder the stack.\n\nAny comparison function supplied should use a metric suitable\nfor use in a binary search operation. That is it should return zero, a\npositive or negative value if B\u003ca\u003e is equal to, greater than\nor less than B\u003cb\u003e respectively.\n\nCare should be taken when checking the return values of the functions\nsk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the\nmatching element. In particular B\u003c0\u003e indicates a matching first element.\nA failed search is indicated by a B\u003c-1\u003e return value.\n\nSTACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and\nDEFINE_SPECIAL_STACK_OF() are implemented as macros.\n\n\u003dhead1 RETURN VALUES\n\nsk_TYPE_num() returns the number of elements in the stack or B\u003c-1\u003e if the\npassed stack is B\u003cNULL\u003e.\n\nsk_TYPE_value() returns a pointer to a stack element or B\u003cNULL\u003e if the\nindex is out of range.\n\nsk_TYPE_new() and sk_TYPE_new_null() return an empty stack or B\u003cNULL\u003e if\nan error occurs.\n\nsk_TYPE_set_cmp_func() returns the old comparison function or B\u003cNULL\u003e if\nthere was no old comparison function.\n\nsk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do\nnot return values.\n\nsk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr()\nreturn a pointer to the deleted element or B\u003cNULL\u003e on error.\n\nsk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total\nnumber of elements in the stack and 0 if an error occurred.\n\nsk_TYPE_set() returns a pointer to the replacement element or B\u003cNULL\u003e on\nerror.\n\nsk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element\nor B\u003c-1\u003e on error.\n\nsk_TYPE_is_sorted() returns B\u003c1\u003e if the stack is sorted and B\u003c0\u003e if it is\nnot.\n\nsk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the\nstack.\n\n\u003dhead1 HISTORY\n\nBefore OpenSSL 1.1.0, this was implemented via macros and not inline functions\nand was not a public API.\n\n\u003dhead1 COPYRIGHT\n\nCopyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.\n\nLicensed under the OpenSSL license (the \u0022License\u0022). You may not use\nthis file except in compliance with the License. You can obtain a copy\nin the file LICENSE in the source distribution or at\nL\u003chttps://www.openssl.org/source/license.html\u003e.\n\n\u003dcut\n","s":{"c":1760043501,"u": 1499}} ],"g": 4469,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 1, "si": 0, "db":0, "di":0, "sat":0, "lfc": "0000"}