PQ(3C)

NAME
pq - post directory query and network interface

SYNOPSIS
char *pq_open (argv)
char **argv;

int pq_close (pq)
char *pq;

int pq_read (pq, vec)
char *pq, **vec;

int pq_write (pq, vec)
char *pq, **vec;

int pq_read (pq, buf, size)
char *pq, *buf;
int size;

int pq_write (pq, buf, size)
char *pq, *buf;
int size;

extern char *pq_error;

DESCRIPTION
pq is a set of routines that provides access to a directory (database) or a network.

pq_open arranges for a directory or network to be accessed. argv identifies the particular directory or network and is described in modules(4). The return value is a handle to the opened object and is used in subsequent operations on that object.

pq_close ends access to the directory or network referenced by the handle pq. All resources used by the handle are released.

pq_read and pq_write access the object referenced by the handle pq and have different calling sequences for directory and network handles. Directory handles pass an array of strings vec and network handles pass a character buffer buf and its size in bytes size.

pq_write, where pq is a directory handle, arranges to query the directory for the attributes and values listed in the array of strings vec, which is terminated by a null pointer. Each string is either attribute=value, which selects records whose attribute matches value; or attribute, which projects records with attribute from the directory. Selects with different attributes are anded; selects with like attributes are ored. If vec consists of exactly one string attribute, the query projects the names of the attributes in the directory. The attribute names are directory specific, and the matching algorithms are directory and attribute specific (see modules(4)).

pq_read, where pq is a directory handle, returns an array of strings in vec for the next record that matches the query requested by the last pq_write call. The strings are returned in the same order as the query. Attributes that are repeated in the query have their values repeated in the return vector, which is terminated by a null pointer.

Where pq is a network handle, pq_read reads at most size bytes from the network connection into the buffer buf, and pq_write writes size bytes from the buffer buf to the network connection.

DIAGNOSTICS
All functions return -1 on failure, except for pq_open, which returns a null pointer. An error message is placed in pq_error for all failures, except for functions that take a network handle argument, which set errno instead.

pq_read returns a positive integer if a record is retrieved for a directory handle, or the number of bytes read from the connection for a network handle. It returns 0 if no more records match in a directory, or if the network connection is closed remotely.

pq_write returns a positive integer if the query is accepted by the directory, or the number of bytes written to the network connection.

SEE ALSO
post(1), modules(4).