bio | home | mobile | papers | videos



PQ(2)                         System Calls Manual                        PQ(2)



NAME
       pq - IRDB directory query and network interface

SYNOPSIS
       char *pq_open (char **argv)

       int pq_close (char *pq)

       int pq_read (char *pq, **vec)

       int pq_write (char *pq, **vec)

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

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

       extern char pq_error[];

DESCRIPTION
       pq  is a set of routines that provides access to local or remote direc-
       tories (databases).

       pq_open arranges for a local directory or network (for remote  directo-
       ries) to be accessed.  argv identifies the particular directory or net-
       work and is described in modules(7); it should be terminated by a  null
       pointer.  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 han-
       dle 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  direc-
       tory  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 attribute from  selected  records  in  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 direc-
       tory.  The attribute names are directory specific; the  matching  algo-
       rithms are directory and attribute specific.

       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.

SOURCE
       /sys/src/cmd/pq/lib

SEE ALSO
       pq(1), modules(7).



                                                                         PQ(2)