---
name: "libtar_list_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_list_new"
---

# libtar\_list\_new(3)

linked list routines

## NAME

libtar\_list\_new, libtar\_list\_free, libtar\_list\_next, libtar\_list\_prev, libtar\_list\_add, libtar\_list\_del, libtar\_list\_search, libtar\_list\_dup, libtar\_list\_merge, libtar\_list\_add\_str - linked list routines

## SYNOPSIS

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

**libtar\_list\_t \*libtar\_list\_new(int** *flags***,** **int (\****cmpfunc***)());**\
 **void libtar\_list\_free(libtar\_list\_t \****l***, void (\****freefunc***)());**\
 **int libtar\_list\_add\_str(libtar\_list\_t \****l***, char \****str***,** **char \****delim***);**\
 **int libtar\_list\_add(libtar\_list\_t \****l***, void \****data***);**\
 **void libtar\_list\_del(libtar\_list\_t \****l***, libtar\_node\_t \*\****n***);**\
 **int libtar\_list\_search(libtar\_list\_t \****l***, libtar\_node\_t \*\****n***,** **void \****data***, int (\****matchfunc***)());**\
 **int libtar\_list\_next(libtar\_list\_t \****l***, libtar\_node\_t \*\****n***);**\
 **int libtar\_list\_prev(libtar\_list\_t \****l***, libtar\_node\_t \*\****n***);**\
 **libtar\_list\_t \*libtar\_list\_dup(libtar\_list\_t \****l***);**\
 **libtar\_list\_t \*libtar\_list\_merge(int (\****cmpfunc***)(), int** *flags***,** **libtar\_list\_t \****list1***, libtar\_list\_t \****list2***);**

## DESCRIPTION

The **libtar\_list\_new**() function creates a new list.  The *flags* argument must be one of the following values:

- **LIST\_USERFUNC**

  The *cmpfunc* argument points to a user-supplied function which determines the ordering of the list.

- **LIST\_STACK**

  Use the list as a stack.  New elements are added to the front of the list.

- **LIST\_QUEUE**

  Use the list as a queue.  New elements are added to the end of the list.

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

The **libtar\_list\_add**() function adds the element pointed to by *data* to the list *l*.  The position of the new element will be determined by the flags passed to **libtar\_list\_new**() when the list was created.

The **libtar\_list\_add\_str**() function tokenizes the string *str* using the delimiter characters in the string *delim*.  The resulting tokens are added to list *l* using **libtar\_list\_add**().

The **libtar\_list\_search**() function searches for an element which matches *data* using the matching function *matchfunc*.  If *matchfunc* is *NULL*, a default matching function designed for ASCII strings is used.  Searching begins from the node pointed to by *n*.

The **libtar\_list\_del**() function removes the entry pointed to by *n* from the list pointed to by *l*.

The **libtar\_list\_dup**() function creates a copy of the list *l* using dynamically allocated memory.

The **libtar\_list\_merge**() function creates a new list with *flags* and *cmpfunc*, in the same way as **libtar\_list\_new**().  It then adds all elements from *list1* and *list2* using **libtar\_list\_add**().

## RETURN VALUE

The **libtar\_list\_new**(), **libtar\_list\_dup**(), and **libtar\_list\_merge**() functions return a pointer to the new list structure, or *NULL* on error.

The **libtar\_list\_next**(), **libtar\_list\_prev**(), and **libtar\_list\_search**() functions return 1 when valid data is returned, or 0 otherwise.

The **libtar\_list\_add**() and **libtar\_list\_add\_str**() functions return 0 on success, or -1 on error.

## SEE ALSO

[**libtar\_hash\_new**(3)](/libtar_hash_new/3.md)