---
name: "libressl-OPENSSL_sk_new"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-OPENSSL_sk_new"
---

# libressl-OPENSSL\_sk\_new(3)

variable-sized arrays of void pointers, called OpenSSL stacks

## NAME

**sk\_new\_null**, **sk\_new**, **sk\_set\_cmp\_func**, **sk\_dup**, **sk\_free**, **sk\_pop\_free**, **sk\_num**, **sk\_value**, **sk\_find**, **sk\_sort**, **sk\_is\_sorted**, **sk\_push**, **sk\_unshift**, **sk\_insert**, **sk\_set**, **sk\_pop**, **sk\_shift**, **sk\_delete**, **sk\_delete\_ptr**, **sk\_zero** – variable-sized arrays of void pointers, called OpenSSL stacks

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

**#include \<openssl/stack.h\>**

*\_STACK* *\**\

**sk\_new\_null**(*void*);

*\_STACK* *\**\

**sk\_new**(*int (\*compfunc)(const void \*, const void \*)*);

*old\_function\_pointer*\

**sk\_set\_cmp\_func**(*\_STACK \*stack*, *int (\*compfunc)(const void \*, const void \*)*);

*\_STACK* *\**\

**sk\_dup**(*\_STACK \*stack*);

*void*\

**sk\_free**(*\_STACK \*stack*);

*void*\

**sk\_pop\_free**(*\_STACK \*stack*, *void (\*freefunc)(void \*)*);

*int*\

**sk\_num**(*const \_STACK \*stack*);

*void* *\**\

**sk\_value**(*const \_STACK \*stack*, *int index*);

*int*\

**sk\_find**(*\_STACK \*stack*, *void \*wanted*);

*void*\

**sk\_sort**(*\_STACK \*stack*);

*int*\

**sk\_is\_sorted**(*const \_STACK \*stack*);

*int*\

**sk\_push**(*\_STACK \*stack*, *void \*new\_item*);

*int*\

**sk\_unshift**(*\_STACK \*stack*, *void \*new\_item*);

*int*\

**sk\_insert**(*\_STACK \*stack*, *void \*new\_item*, *int index*);

*void* *\**\

**sk\_set**(*\_STACK \*stack*, *int index*, *void \*new\_item*);

*void* *\**\

**sk\_pop**(*\_STACK \*stack*);

*void* *\**\

**sk\_shift**(*\_STACK \*stack*);

*void* *\**\

**sk\_delete**(*\_STACK \*stack*, *int index*);

*void* *\**\

**sk\_delete\_ptr**(*\_STACK \*stack*, *void \*wanted*);

*void*\

**sk\_zero**(*\_STACK \*stack*);

## DESCRIPTION

OpenSSL introduced an idiosyncratic concept of variable sized arrays of pointers and somewhat misleadingly called such an array a “stack”. Intrinsically, and as documented in this manual page, OpenSSL stacks are not type safe but only handle *void* *\** function arguments and return values.

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 [cpp(1)](/cpp/1.md) macros; see the STACK\_OF(3) manual page for details.

The fundamental data type is the *\_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.

**sk\_new\_null**() allocates and initializes a new, empty stack. **sk\_new**() is identical except that it also installs *compfunc* as the comparison function for the new stack object. **sk\_set\_cmp\_func**() installs *compfunc* for the existing *stack*. The *compfunc* is allowed to be NULL, but the *stack* is not.

**sk\_dup**() creates a shallow copy of the given *stack*, which must not be a 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 **sk\_free**() on one copy and only calling **sk\_pop\_free**() on the other.

**sk\_free**() frees the given *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 **sk\_free**(), in order to avoid leaking memory. If *stack* is a NULL pointer, no action occurs.

**sk\_pop\_free**() is severely misnamed. It does not at all do what one would expect from a function called “pop”. Instead, it does the same as **sk\_free**(), except that it also calls the function *freefunc* on each of the pointers contained in the *stack*. If the calls to *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.

**sk\_find**() searches the *stack* for the *wanted* pointer. If the *stack* contains more than one copy of the *wanted* pointer, only the first match is found. If a comparison function is installed for the stack, the stack is first sorted with **sk\_sort**(), and instead of comparing pointers, two pointers are considered to match if the comparison function returns 0.

**sk\_sort**() sorts the *stack* using [qsort(3)](/qsort/3.md) and the installed comparison function. If *stack* is a NULL pointer or already considered sorted, no action occurs. This function can only be called if a comparison function is installed.

**sk\_is\_sorted**() reports whether the *stack* is considered sorted. Calling **sk\_new\_null**() or **sk\_new**(), successfully calling **sk\_push**(), **sk\_unshift**(), **sk\_insert**(), or **sk\_set**(), or changing the comparison function sets the state to unsorted. If a comparison function is installed, calling **sk\_sort**(), or **sk\_find**() sets the state to sorted.

**sk\_push**() pushes *new\_item* onto the end of the *stack*, increasing the number of pointers by 1. If *stack* is a NULL pointer, no action occurs.

**sk\_unshift**() inserts *new\_item* at the beginning of the *stack*, such that it gets the index 0. The number of pointers increases by 1. If *stack* is a NULL pointer, no action occurs.

**sk\_insert**() inserts the *new\_item* into the *stack* such that it gets the given *index*. If *index* is less than 0 or greater than or equal to **sk\_num**(*stack*), the effect is the same as for **sk\_push**(). If *stack* is a NULL pointer, no action occurs.

**sk\_set**() replaces the pointer with the given *index* on the *stack* with the *new\_item*. The old pointer is not freed, which may leak memory if no copy of it exists elsewhere. If *stack* is a NULL pointer or if *index* is less than 0 or greater than or equal to **sk\_num**(*stack*), no action occurs.

**sk\_pop**() and **sk\_shift**() remove the pointer with the highest or lowest index from the *stack*, respectively, reducing the number of pointers by 1. If *stack* is a NULL pointer or if it is empty, no action occurs.

**sk\_delete**() removes the pointer with the given *index* from the *stack*, reducing the number of pointers by 1. If *stack* is a NULL pointer or the *index* is less than 0 or greater than or equal to **sk\_num**(*stack*), no action occurs.

**sk\_delete\_ptr**() removes the *wanted* pointer from the *stack*, reducing the number of pointers by 1 if it is found. It never uses a comparison function but only compares pointers themselves. The *stack* pointer must not be NULL.

**sk\_zero**() removes all pointers from the *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 **sk\_zero**(), in order to avoid leaking memory. If *stack* is a NULL pointer, no action occurs.

## RETURN VALUES

**sk\_new\_null**(), **sk\_new**(), and **sk\_dup**() return a pointer to the newly allocated stack object or NULL if insufficient memory is available.

**sk\_set\_cmp\_func**() returns a pointer to the comparison function that was previously installed for the *stack* or NULL if none was installed.

**sk\_num**() returns the number of pointers currently stored on the *stack*, or -1 if *stack* is a NULL pointer.

**sk\_value**() returns the pointer with the given *index* from the *stack*, or NULL if *stack* is a NULL pointer or if the *index* is less than 0 or greater than or equal to **sk\_num**(*stack*).

**sk\_find**() returns the lowest index considered to match or -1 if *stack* is a NULL pointer or if no match is found.

**sk\_is\_sorted**() returns 1 if the *stack* is considered sorted or if it is a NULL pointer, or 0 otherwise.

**sk\_push**(), **sk\_unshift**(), and **sk\_insert**() return the new number of pointers on the *stack* or 0 if *stack* is a NULL pointer or if memory allocation fails.

**sk\_set**() returns *new\_item* or NULL if *stack* is a NULL pointer or if the *index* is less than 0 or greater than or equal to **sk\_num**(*stack*).

**sk\_pop**() and **sk\_shift**() return the deleted pointer or NULL if *stack* is a NULL pointer or if it is empty.

**sk\_delete**() returns the deleted pointer or NULL if *stack* is a NULL pointer or if the *index* is less than 0 or greater than or equal to **sk\_num**(*stack*).

**sk\_delete\_ptr**() returns *wanted* or NULL if it is not found.

## SEE ALSO

STACK\_OF(3)

## HISTORY

**sk\_new\_null**(), **sk\_new**(), **sk\_free**(), **sk\_pop\_free**(), **sk\_num**(), **sk\_value**(), **sk\_find**(), **sk\_push**(), **sk\_unshift**(), **sk\_insert**(), **sk\_pop**(), **sk\_shift**(), **sk\_delete**(), and **sk\_delete\_ptr**() first appeared in SSLeay 0.5.1. **sk\_set\_cmp\_func**(), **sk\_dup**(), and **sk\_zero**() first appeared in SSLeay 0.8.0. These functions have been available since OpenBSD 2.4.

**sk\_set**() first appeared in OpenSSL 0.9.3. **sk\_sort**() first appeared in OpenSSL 0.9.4. Both functions have been available since OpenBSD 2.6.

**sk\_is\_sorted**() first appeared in OpenSSL 0.9.7e and has been available since OpenBSD 3.8.

## BUGS

Even if a comparison function is installed, empty stacks and stacks containing a single pointer are sometimes considered sorted and sometimes considered unsorted.

If a comparison function is installed, the concept of “first match” in **sk\_find**() is ill-defined because [qsort(3)](/qsort/3.md) is not a stable sorting function. It is probably best to only assume that they return an arbitrary match.