Options and Qualifiers

PPS supports pathname open options, and objects and attribute qualifiers. PPS uses pathname open options to apply open options on the file descriptor used to open an object. Object and attribute qualifiers set specific actions to take with an object or attribute; for example, make an object non-persistent, or delete an attribute.

Pathname open options

PPS objects support an extended syntax on the pathnames used to open them. Open options are added as suffixes to the pathname, following a question mark (“?”). That is, the PPS service uses any data that follows a question mark in a pathname to apply open options on the file descriptor used to access the object. Multiple options are separated by question marks. For example:

"/pps/media/PlayList" — open the PlayList file with no options
"/pps/media/PlayList?wait" — open the PlayList file with the wait option
"/pps/media/Playlist?wait,delta" — open PlayList file with the wait and delta options
"/pps/media/.all?wait" — open the media directory with the wait option
"/pps/fish?notify=345:water" — open fish and associate it with .notify group 345

The syntax used for specifying PPS pathname open query options will be easily recognizable to anyone familiar with the getsubopt() library routine.

Supported pathname open options include:

critical: Designate the publisher as critical to the object. See “Critical option” below.
delta: Open the object in delta mode.; See “Subscribing to multiple objects” in the chapter Subscribing.
deltadir: Return the names of all objects (files) in the directory — valid only on the special .all object in a directory.; If any objects in the directory are created or deleted, these changes are indicated by a “+” (created) or a “-” (deleted) sign prefixed to their names. This behavior allows you to effectively perform a readdir() within PPS, as well as monitor filesystem changes without having to also monitor attribute changes.; See “Subscribing to multiple objects” in the chapter Subscribing.
f=attr+attr ...: Place a filter on notifications based upon changes to the listed attribute names only. Multiple attributes are separated by “+” signs.; In full mode, the file descriptor will only get notifications if one of the listed attributes changes. When this occurs the entire object is returned.; In delta mode, only the listed attributes will be queued. Changes to non-listed attributes are filtered out.
nopersist: Make the object non-persistent. When the system restarts, the object will not exist. The default setting is for all objects to be persistent and reloaded on restart. See “Object and attribute options” below.
notify=id:value: Associate the opened file descriptor with the notify group specified by id. This id is returned on the first read from an open() all on the “.notify” file in the root of the PPS mount point.; Reads of the “.notify” file will return the string: id:value whenever data is available on the file descriptor opened with the notify= query.; See “Subscribing to multiple objects” in the chapter Subscribing.
server: Designate the publisher as a "server" for the object. See “Server objects” in the chapter Subscribing.
wait: Open the file with the O_NONBLOCK flag clear so that read() calls wait until the object changes or a delta appears. See the chapter Subscribing.

Critical option

The critical option can be used as an attribute cleanup mechanism on the abnormal termination of a publisher.

If this option is used when opening a file descriptor for a write, when the file descriptor is closed PPS deletes all non-persistent attributes and prefixes an asterisk (“*”) to the object name in the notification string it sends to all subscribers. PPS does not provide a list of the deleted attributes.

Duplicate file descriptors

You should ensure that you never have duplicate critical or server file descriptors.

Critical file descriptors

You should never have more than one critical file descriptor for any one PPS object.

File descriptors can be duplicated, either explicitly by dup(), dup2() or fcntl(), etc.; or implicitly by fork(), spawn(), etc. Duplicated descriptors in effect increment a reference count on the underlying critical descriptor. The behavior required of critical objects (the notification and deletion of volatile attributes) is not triggered until the reference count for a file descriptor drops to zero, indicating that the original and all duplicates are closed.

However, if you open a PPS object more than once in critical mode, each file descriptor behaves as a critical descriptor: if the reference count of any one file descriptor drops to zero, the notification and deletion behavior is triggered for the object — even if other descriptors remain open.

Server file descriptors

Do not duplicate server file descriptors. Behavior with duplicate server file descriptors is undetermined.

Object and attribute qualifiers

Object and attribute qualifiers are contained in square brackets (“[qualifier]”), and prefixed to lines containing an object or an attribute name.

You can set qualifiers to read() and write() calls by starting a line containing an object or attribute name with an open square bracket, followed by a list of single-letter or single-numeral qualifiers and terminated by a close square bracket.

Qualifiers supported for objects and attributes are:

n: No-persistence; see “No-persistence qualifier” below.

Qualifiers supported for attributes only are:

i: Item; see “Item qualifier” below.

Qualifier defaults are always “clear”.
On a read() call you will only see a preceding qualifier list “[option letters]” for options which have been set.
Attribute options always precede both the special character and the object or attribute name.

Setting qualifiers

If nothing precedes a qualifier, that qualifier is set. It the qualifier is preceded by a minus sign (“-”), that qualifier is cleared. If a qualifier is not specified, that qualifier is not changed. For example:

[n]url::www.qnx.com — set the no-persist qualifier on this attribute
[-n]url::www.qnx.com — clear the no-persist qualifier on this attribute
url::www.qnx.com — do not change the current no-persist qualifier on this attribute
[i]items::hammer, — add hammer to the set
[-i]items::screw driver, — remove screw driver from the set

No-persistence qualifier

The no-persistence qualifier can be used for objects and attributes. It is very useful on attributes that may not be valid across a system restart and do not need to be saved.

The table below describes the effects of the no-persistence qualifier on PPS objects and attributes:

Syntax	Action	Object	Attribute
`n`	Set	Make the object and its attributes non-persistent; ignore any persistence qualifiers set on this object's attributes.	Make the attribute non-persistent.
`-n`	Clear	Make the object persistent; persistence of the object's attributes is determined by the individual attribute's qualifiers.	Make the attribute persistent, if the attribute's object is also persistent.

Setting the no-persistence qualifier on an object overrides any no-persistence qualifiers set on the object's attributes, and is therefore convenient if you need to make a temporary object in which nothing persists.

For more information about persistence, see the chapter Persistence.

Item qualifier

The item qualifier can be used for attributes only. It causes PPS to treat the value following the qualifier as a set of items. Items in a set are separated by a user-defined separator, such as a comma.

The item separator:

is required
must be the last character in a value that uses the item qualifier
can be any character not used in the items

Adding and deleting set items

You may add or delete only one set item at a time. For example, to add items to a set:

[i]items::hammer,
[i]items::screw driver,

Or, to delete an item from a set:

[-i]items::hammer,

Incorrect item syntax

The following are not permitted:

[i]items::hammer,screw driver,

Or:

[-i]items::hammer,screw driver,

Examples

In the examples below, the separator is a comma: “,”.

Example 1: Duplicate items

This example shows that PPS ignores a duplicate attempt to add the same item to a set. The following lines written:

[i]items::hammer,
[i]items::hammer,
[i]items::screw driver,

would result in the following being read by a subscriber:

items::hammer,screw driver,

Example 2: Null items

This example shows how PPS supports a null item in a set. The following line written to the set created in the previous example:

[i]items::,

would result in the following being read by a subscriber:

items::hammer,screw driver,,

Example 3: Delete an item

This example shows how to delete an item from a set. The following line written to the set created and updated in the previous examples:

[-i]items::hammer,

would result in the following being read by a subscriber:

items::screw driver,,