pq man pages

Content-type: text/html


Section: User Commands (1)


pq, pqgen, pqsrv - PQ IRDB directory access  


pq -o format [ -a attrs ] [ -m modules ] [ -s seps ] [ -d debug ] query ...

pqgen [ directory ]

pqsrv [ modules ]


Pq connects to an Implicit Relational Database (IRDB) directory and outputs the record(s) that match the query arguments. The directory contacted may be specified by a modules argument (see dispatch(7)).

Each query argument results in an independent query of the directory, consisting of a set of input attributes, obtained from the query argument, and a set of output attributes, obtained from the output format (see the -o option). The output of all the queries are formatted according to the output format and concatenated on standard output.

Each query argument is a list of strings of the form attribute=value separated by any number of separator characters (default is |, but can be changed via the -s option). The string attribute= may be elided, in which case the attribute name is taken from the corresponding token in the -a option. It is an error if there is no corresponding attribute name. The query argument may be the empty string; in this case, all records that contain the output attributes are returned. The options are:

-m modules
    Contact the directory specified by the modules string; the format is described in dispatch(7). The default value for modules is the empty string. 
-s seps
    Set the separator character list for delimiting tokens in query arguments and the -a option string; |, is the default. 
-o format
    Use the output format specified. See below for a full description. 
-a attrs
    Set the default attribute names for query components that do not specify them. 
-d debug

    Print information regarding internal operations. Values for debug range from 1 to 3, with 3 yielding the most detail.

Output Formatting

The format argument specified with the -o option is used like a print(2) string for formatting the output of directory queries. All characters are copied literally, except for attribute substitutions and backslash escapes. Quoting may be necessary to prevent shell interpretation. The syntax for attribute substitutions is this:

    % flags minimum . maximum {attribute}

Only % and attribute are required. Curly braces, {}, are required only when the attribute is immediately followed by an alphanumeric. Flags may be one or more of the following:

    -   Right justify (left justification is the default). 
    ^   Capitalize the first letter of each word. 
    +   Capitalize all letters in the value. 
    <   If the value is empty, delete back to the last \< or beginning
        of output. 
    >   If the value is empty, skip to the next \> or end of format

Minimum is an integer giving the minimum field width. If the value has fewer than the minimum number of characters, the field will be padded with blanks. The default minimum is zero. Maximum is an integer that specifies the maximum number of characters to be output from the value. If the value has more characters than this number, the value will be truncated. A maximum of zero (the default) causes all characters to be output. A period is used to separate minimum and maximum and is only required if maximum is specified.

The following table lists backslash escapes that are recognized by pq(1)::

Output Format Backslash Escapes

\cSuppress terminating newline
\oooASCII character defined by an octal number
\rCarriage return
\vVertical tab
\<Marker for < flag
\>Marker for > flag

Pqgen is used to create index files for an existing IRDB ev(7) directory. Once indexed, the speed of lookups is greatly improved. However, it is then necessary to rerun pqgen after any changes are made to the ev database. The directory is the location of the ev database. If not an absolute pathname, it is interpreted relative to /lib/pq.

Pqsrv is the server that handles incoming PQ requests. It is meant to be run by listen(8), typically for TCP port 411. The optional modules argument is the same as that to pq(1) above.  


Find the telephone number of employee with login of liz:

    pq -o %telephone 'login=liz' 

List addresses of employees in New Jersey and Texas who are full-time:

    pq -o '%20name %25addr %state %zip' 'status=FT|state=NJ|state=TX'

Consult /sys/src/cmd/pq/example for a more detailed example.


    default dispatch file 

    typical location for pqsrv


pq(2), dispatch(7), ev(7), listen(8).

Content-type: text/html


Section: System Calls (2)


pq - IRDB directory query and network interface


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[];


pq is a set of routines that provides access to local or remote directories (databases). pq_open arranges for a local directory or network (for remote directories) to be accessed. argv identifies the particular directory or network 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 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 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 directory. The attribute names are directory specific; the matching algorithms 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.


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.  




pq(1), modules(7).

Content-type: text/html


Section: Environments, Tables, and Troff Macros (7)


ev - PQ IRDB database system


Ev is a simple database system used for pq(1) Implicit Relational Database (IRDB) directory queries. An ev database consists of a data file, a proto file describing the contents of the data file and optional index files for efficient database queries. The arguments to ev provide the data and proto file names, the directory containing the index files, and the database separator. See modules(7). An ev data file is a Unicode file composed of newline-terminated lines. Each line in the data file represents a database record and contains delimited, variable-length fields denoting database attributes. Information describing the database attributes is stored in a proto file and used to create the index files and to resolve runtime queries. Lines in the proto file are newline terminated and have the following tab- or space-separated fields:

attribute name
    Name of attribute in the database. Cannot be the string attribute or contain the equal sign character (=). Must be less than 15 characters.
attribute address
    Position of the attribute in the data file. Attributes are counted left to right starting with field 1 and are separated by a character delimiter. See modules(7).
primary length
    Length (in bytes) of entries in the primary index file. For attributes that use the numeric matching algorithm, the attribute length must be at least as large as the longest value. If index files are not used, this is set to a period (.). 
secondary length
    Length (in bytes) of entries in the secondary index file. For attributes that use the numeric matching algorithm, the attribute length must be at least as large as the longest value. If index files are not used, this is set to a period (.). 
    The match flag is a single character representing the matching algorithm used for this attribute in database queries. The possible values are listed below under Match Type. The match flag may be accompanied by zero or more of the Value Characteristics also listed below. The order of these one-character flags is not significant. 
    Contains either a period (.), m, or m=x. Value m denotes a multiple field. Value m=x signifies the database attribute used to distinguish between the main line in the data file (attribute=x) and auxiliary ones (attribute!=x). There can be at most one attribute with value m=x per proto file. 
default index
    Index files are create by pqgen(1M) for those attributes with default index flag equal to i. Attributes with default index equal to a period (.) can also be used to query the database but with worse performance. Attributes used frequently for database queries should be indexed.

Match Type

e Exact match. 

n Numeric match. 

p Prefix match. 

s Exact match unless argument ends with a star (*), in which case prefix match. 

Value Characteristics

a Ignore non-alphanumerics. 

i Ignore case. 

m Multiple entry match. If argument is empty, 1 or 2, retrieve first, second or third record for query, respectively. The order of the attributes as they appear in the proto file is significant. For database queries with two or more qualifiers, the attribute that appears first in the proto file is used to perform the search of the database. Attributes with index files are preferred. Index files, created by pqgen(1) using the data and proto files, improve performance of database queries. Index files are arranged in a multiway tree format to improve performance and limit the amount of core memory needed. The C interface to ev can be seen in pq(2). 


    default pq configuration file 
    sample dispatch file 


pq(1), pqgen(1), pq(2), modules(7).

Content-type: text/html


Section: Environments, Tables, and Troff Macros (7)


modules - PQ IRDB directory software configuration


A modules argument describes a particular Implicit Relational Database (IRDB) directory or network address. The -m option of pq(1) must describe a directory, and the pq_open call of pq(2) can describe either a directory or a network address. The syntax for modules arguments is described below. The dirmod and netmod arguments below are modules arguments themselves; in this way various modules can be stacked in a pipeline fashion. The default modules argument is opt join.

Directory modules

join file
    Attach to one or more directories listed in file. Relative paths are prefixed with /lib/pq.
call [ netmod ... ]
    Connect to the network address specified by netmod and use the pqsrv protocol.
ev [ name [ data proto lock ] ]
    Specify the location of the data, prototype and lock files for the ev(7) IRDB name. With no options, the location is assumed to be ".". If only name is specified, the data file is assumed to be in either name/Data or D.name. Likewise, the prototype and lock files are sought in name/Proto or P.name and name/Lock or L.name, respectively. If name is not an absolute pathname it is assumed to be relative to /lib/pq.
opt [ dirmod ]
    Optimize the performance of the module argument.


    default dispatch file

pq(1), pqsrv(1), pq(2).

These documents were created by man2html, using the manual pages.
Time: 02:51:35 GMT, November 13, 2015