Options and Qualifiers Parent topic: Options and Qualifiers

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 commas. For example:

Note: 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:

backlog=num_kb
The maximum delta size, in KB, to keep before flushing this OCB (Open Control Block). If you don't specify this option, or you specify a value of 0, then the default backlog value of 256 KB is used; you can override this by specifying the -d option when you start pps. The flow and backlog options are mutually exclusive.

If the total accumulated delta is more than num_kb, then a purge notification is generated, in the form: 

|@objname
cred
Output the credentials for this object. You can use this option only in conjunction with the flow or server option. When a new client connects to a server or flow object, the connect notification also contains the client credentials, in the form: 
+@objname.client_id.nnode_id.pprocess_id.uuser_id.ggroup_id.g...
critical
Designate the publisher as critical to the object. See “The critical option.”
crypt=domain
Set the crypto domain for this object. In order to use this option, you must start the pps service with a -p option that specifies a location of persistent storage on a mounted Power-Safe (fs-qnx6.so) partition that contains encryption domains.

Assigning a PPS object to a domain means that it will be put into the specified encryption domain when it's saved in persistent storage. For example, this code: 

open(“/pps/test_obj?crypt=10”, O_CREAT, 0666)

assigns the test_obj PPS object to encryption domain 10 when it's saved in persistent storage.

If you open multiple file descriptors for the same PPS object with different encryption domains, the last one is used. In the following example, the domain used is 11: 

fd1 = open(“/pps/test_obj”, O_RDWR|O_CREAT, 0666);
fd2 = open(“/pps/test_obj?crypt=10”, O_RDWR, 0666);
fd3 = open(“/pps/test_obj?crypt=11”, O_RDWR, 0666);
delta
Open the object in delta mode. See “Subscription modes.”
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 and to monitor filesystem changes without having to also monitor attribute changes.

See “Subscribing to multiple objects.”

f=filter ...
Place a filter on notifications based on changes to the listed attributes. See “Filtering notifications.”
flow[=num_kb]
Treat the object as a server object, with purge and overflow notifications. The optional num_kb is the maximum backlog size in kilobytes. If you don't specify num_kb, or you specify a value of 0, the default backlog size of 256 KB is used; you can override this by specifying the -d option when you start pps. The format of the overflow notification is: 
^@objname

The flow and backlog options are mutually exclusive. You can use the hiwater option with flow to generate overflow notifications.

See “Server Objects.”

hiwater=hw_percent
Specify the flow high water mark as a percentage of the client backlog. If the backlog exceeds this percentage, overflow notifications are generated. Overflow notifications are generated for each delta buffered while the total accumulated delta size is above hw_percent of the specified backlog. The format of the overflow notification is: 
^@objname

You can specify a value in the range from 1 to 99 percent; if you don't specify this option, the default of 100 percent is used. You can use the hiwater option only in conjunction with the flow option.

See “Server Objects.”

nopersist
Make the object nonpersistent. When the system restarts, the object won't exist. The default setting is for all objects to be persistent and reloaded on restart. See “Object and attribute qualifiers.”
notify=id:value
Associate the opened file descriptor with the notification group specified by id. This id is returned on the first read from an open() on the .notify file in the root of the PPS mountpoint. The value is an arbitrary string that you want to associate with the group.

Reads of the .notify file return the string id:value whenever data is available on the file descriptor opened with the notify= query.

See “Subscribing to multiple objects.”

opens
Update an _opens::rd,wr attribute when the open count changes. This option lets you receive notifications about the number of file descriptors opened for an object for writing and reading. A notification is generated in following format: 
%@objname.read_count,write_count

Notifications are sent each time that the number of readers or writers changes. These numbers increase each time that open() is called, and decrease when close() is called. O_RDONLY increases the number of readers, O_WRONLY the number of writers, and O_RDWR the number of readers and writers. For example, if you use the following code to create a PPS object: 

fd = open(“/pps/test_obj?opens”, O_CREAT|O_RDWR, 0666);

then after reading from this file descriptor, the following notification is received: 

%@test_obj.1,1

If you open the same PPS object with O_WRONLY, then the following notification is generated: 

%@test_obj.1,2
reflect
Reflect attribute changes made on this object back to it.
server
Designate the publisher as a “server” for the object. See “Server Objects” for more information.
verbose[=level]
Set the verbosity level for this object. If you specify this option without an argument, the level is 9 (the highest).
wait
Open the file with the O_NONBLOCK flag cleared so that read() calls wait until the object changes or a delta appears. See the Subscribing chapter for more information.
Parent topic: Options and Qualifiers