---
name: "libtar_hash_new"
section: "3"
platform: "linux"
package: "libtar"
version: "1.2.20-8"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libtar_hash_new"
---

# libtar\_hash\_new(3)

hash table routines

## NAME

libtar\_hash\_new, libtar\_hash\_free, libtar\_hash\_next, libtar\_hash\_prev, libtar\_hash\_getkey, libtar\_hash\_search, libtar\_hash\_add, libtar\_hash\_del - hash table routines

## SYNOPSIS

**#include \<libtar.h\>**

**libtar\_hash\_t \*libtar\_hash\_new(int** *num***, int (\****hashfunc***)());**\
 **void libtar\_hash\_free(libtar\_hash\_t \****h***, void (\****freefunc***)());**\
 **int libtar\_hash\_next(libtar\_hash\_t \****h***, libtar\_hashptr\_t \****hp***);**\
 **int libtar\_hash\_prev(libtar\_hash\_t \****h***, libtar\_hashptr\_t \****hp***);**\
 **int libtar\_hash\_search(libtar\_hash\_t \****h***, libtar\_hashptr\_t \****hp***,** **void \****data***, int (\****matchfunc***)());**\
 **int libtar\_hash\_getkey(libtar\_hash\_t \****h***, libtar\_hashptr\_t \****hp***,** **void \****data***, int (\****matchfunc***)());**\
 **int libtar\_hash\_add(libtar\_hash\_t \****h***, void \****data***);**\
 **int libtar\_hash\_del(libtar\_hash\_t \****h***, libtar\_hashptr\_t \****hp***);**

## DESCRIPTION

The **libtar\_hash\_new**() function creates a new hash with *num* buckets and using hash function pointed to by *hashfunc*.  If *hashfunc* is *NULL*, a default hash function designed for 7-bit ASCII strings is used.

The **libtar\_hash\_free**() function deallocates all memory associated with the hash structure *h*.  If *freefunc* is not *NULL*, it is called to free memory associated with each node in the hash.

The **libtar\_hash\_next**() and **libtar\_hash\_prev**() functions are used to iterate through the hash.  The *libtar\_hashptr\_t* structure has two fields: *bucket*, which indicates the current bucket in the hash, and *node*, which is a pointer to the current node in the current bucket.  To start at the beginning or end of the hash, the caller should initialize *hp.bucket* to -1 and *hp.node* to *NULL*.

The **libtar\_hash\_search**() function searches iteratively through the hash *h* until it finds a node whose contents match *data* using the matching function *matchfunc*.  Searching begins at the location pointed to by *hp*.

The **libtar\_hash\_getkey**() function uses the hash function associated with *h* to determine which bucket *data* should be in, and searches only that bucket for a matching node using *matchfunc*.  Searching begins at the location pointed to by *hp*.

The **libtar\_hash\_add**() function adds *data* into hash *h*.

The **libtar\_hash\_del**() function removes the node referenced by *hp*.

## RETURN VALUE

The **libtar\_hash\_new**() function returns a pointer to the new hash structure, or *NULL* on error.

The **libtar\_hash\_next**() and **libtar\_hash\_prev**() functions return 1 when valid data is returned, and 0 at the end of the hash.

The **libtar\_hash\_getkey**() and **libtar\_hash\_search**() functions return 1 when a match is found, or 0 otherwise.

The **libtar\_hash\_add**() function returns 0 on success, or -1 on error (and sets *errno*).

The **libtar\_hash\_del**() function returns 0 on success, or -1 on error (and sets *errno*).

## SEE ALSO

[**libtar\_list\_new**(3)](/libtar_list_new/3.md)