---
name: "genders_query"
section: "3"
platform: "linux"
package: "libgenders0-dev"
version: "1.27-3-3.1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/genders_query"
---

# genders\_query(3)

query genders database for a set of nodes

## NAME

genders\_query - query genders database for a set of nodes

## SYNOPSIS

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

**int genders\_query(genders\_t handle, char \*nodes\[\], int len, const char \*query);**\

## DESCRIPTION

**genders\_query()** queries the genders database for a set of nodes based on the union, intersection, difference, or complement of genders attributes and values.  The query for a set of nodes is passed as a string through the *query* parameter.  The set operation union is represented by two pipe symbols ('\|\|'), intersection by two ampersand symbols ('&&'), difference by two minus symbols ('--'), and complement by a tilde ('~').  Set operations are performed left to right. Parentheses may be used to change the order of operations.  A list of query examples are listed below.  A NULL query retrieves all nodes from the genders database.

The nodes from the query are stored in the list pointed to by *nodes*.  *len* indicates the number of nodes that can be stored in the list.

To avoid passing in a list that is not large enough to store all the nodes, [**genders\_getnumnodes**(3)](/genders_getnumnodes/3.md) should be used to determine the minimum number of elements *nodes* should be able to store. [**genders\_nodelist\_create**(3)](/genders_nodelist_create/3.md) could be used to create a list that is guaranteed to be large enough to store all of the nodes.\

## EXAMPLES

The following are example queries that can be passed to **genders\_query()**.

Determine the set of nodes with the mgmt or login attribute:\
         "mgmt\|\|login"

Determine the set of nodes that are not login nodes:\
         "all--login"

Determine the set of nodes that both login nodes and ntp servers:\
         "login&&ntpserv"

Determine the set of nodes that are not mgmt or login nodes:\
         "~(mgmt\|\|login)"

## RETURN VALUES

On success, the number of nodes stored in *nodes* is returned.  On error, -1 is returned, and an error code is returned in *handle*. The error code can be retrieved via [**genders\_errnum**(3)](/genders_errnum/3.md) , and a description of the error code can be retrieved via [**genders\_strerror**(3)](/genders_strerror/3.md). Error codes are defined in genders.h.\

## ERRORS

- **GENDERS\_ERR\_NULLHANDLE**

  The *handle* parameter is NULL.  The genders handle must be created with [**genders\_handle\_create**(3)](/genders_handle_create/3.md).

- **GENDERS\_ERR\_NOTLOADED**

  [**genders\_load\_data**(3)](/genders_load_data/3.md) has not been called to load genders data.

- **GENDERS\_ERR\_OVERFLOW**

  The list pointed to by *nodes* is not large enough to store all the nodes.

- **GENDERS\_ERR\_PARAMETERS**

  An incorrect parameter has been passed in.

- **GENDERS\_ERR\_SYNTAX**

  There is a syntax error in the query.

- **GENDERS\_ERR\_OUTMEM**

  [**malloc**(3)](/malloc/3.md) has failed internally, system is out of memory.

- **GENDERS\_ERR\_NULLPTR**

  A null pointer has been found in the list passed in.

- **GENDERS\_ERR\_MAGIC**

  *handle* has an incorrect magic number.  *handle* does not point to a genders handle or *handle* has been destroyed by [**genders\_handle\_destroy**(3)](/genders_handle_destroy/3.md).

- **GENDERS\_ERR\_INTERNAL**

  An internal system error has occurred.  \

## FILES

/usr/include/genders.h

## SEE ALSO

[libgenders(3)](/libgenders/3.md), [genders\_handle\_create(3)](/genders_handle_create/3.md), [genders\_load\_data(3)](/genders_load_data/3.md), [genders\_getnumnodes(3)](/genders_getnumnodes/3.md), [genders\_nodelist\_create(3)](/genders_nodelist_create/3.md), [genders\_errnum(3)](/genders_errnum/3.md), [genders\_strerror(3)](/genders_strerror/3.md)