Stanza(3tlib)


Stanza -- interfaces for managing Stanza files

Synopsis

StanzaOpen stanzaFile mode
StanzaClose stanzaHandle
StanzaPrint stanzaHandle
StanzaSync stanzaHandle
StanzaCallbacks stanzaFile beginCB endCB attrCB
StanzaFilenamestanzaHandle

StanzaGetSects stanzaHandle
StanzaAddSect stanzaHandle sect
StanzaModSect stanzaHandle oldSectName newSectName
StanzaDelSect stanzaHandle sect

StanzaGetAttrs stanzaHandle sect
StanzaAddAttr stanzaHandle sect attr
StanzaModAttr stanzaHandle sect oldAttr newAttr
StanzaDelAttr stanzaHandle sect attr

StanzaGetVals stanzaHandle sect attr
StanzaAddValue stanzaHandle sect attr value
StanzaModValue stanzaHandle sect attr oldValue newValue
StanzaDelValue stanzaHandle sect attr value
StanzaReplaceValue stanzaHandle sect attr values
StanzaModIdxValue stanzaHandle sect attr index newValue

Description

The stanza functions implement a three-level hierarchical database for textual information which is stored in a human-readable file, the format of which is described below. A stanza file consists of zero or more sections, each of which contains zero or more attributes. Attributes in turn consist of zero or move values. Stanza files are automatically locked so that only one process at a time can modify a given file.

File operations


StanzaOpen
opens a stanza file, reads it into memory, and returns a stanza handle. If the file is opened for writing (using the STZ_RDWR or STZ_WRONLY flags) and another process has the same file open for writing, the open will not return until the other process has closed the file. An error is thrown if there is an error opening the file, if there is a syntax error in the file, or if there is a problem opening a lock file.

StanzaClose
writes the stanza file to disk if it was modified, and frees up the stanza handle. An error will occur if there was an error opening a temporary file, writing the new version of the file, or moving the temporary file to the new file.

StanzaSync
updates the stanza file on disk while keeping the stanza handle available for further modification. An error will occur if there was an error opening a temporary file, writing the new version of the file, or moving the temporary file to the new file.

StanzaCallbacks
opens a stanza file and calls user defined callbacks for beginning, end, and attributes of each stanza section.

The Tcl callbacks are called with the following arguments:

   beginCB sect
   endCB
   attrCB attr value
An error is thrown if there is an error opening the file, if there is a syntax error in the file, or if there is a problem opening a lock file.

Stanza File Data Operations

Arguments


stanzaFile
pathname of stanza database file.

mode - open mode
this defines the way the Stanza manager interacts with the file:
   STZ_RDONLY - read only
   STZ_RDWR  - read and write
   STZ_WRONLY - write only
   STZ_NOTAB - equivalent to STZ_RDWR, but the file will
   be written with no tabs before the attributes lines,
   which is a requirement for certain files in /etc/default.

stanzaHandle
file handle returned by StanzaOpen.

sect
Stanza section name.

attr
Stanza attribute name within a section.

value
value assigned to an attribute. Can be a list.

index
index into a list of values associated with an attribute.

beginCB
user-defined callback function for begin of section.

endCB
user-defined callback function for end of section.

attrCB
user-defined callback function for attributes.

File Format

A stanza file is line-oriented, consisting of zero or more section lines in the format

<section-name>:"

Each section line is followed by zero or more attribute lines in the format

<attribute-name> = <value1>, <value2>, <value3> ...

The convention is for the attribute line to be preceded by a tab, but this is not necessary. White space is stripped from the beginning and end of strings but not within them.

The sections, attributes, and values can use any ASCII character, but a few characters and sequences are special, as described below. When using the stanza functions, special characters do not need to be escaped because they will be escaped automatically when the file is written.


\
escapes any special character including another \. At the end of a line, it causes the next line to be interpreted as part of the current line but doesn't stand for any value in itself. If \ is followed by a nonspecial character, it stands for the value of the nonspecial character.

\0nnn
(where nnn is an octal number from 1 to 377) is the character with the value nnn. All three digits are not required.

\0xnn
is the character with the value nn (where nn is a hex number from 1 to FF). Both digits are not required.

\n
stands for newline (value 10)

\t
stands for tab (value 9)

,
is the delimiter between values

=
is the delimiter between an attribute and its values

:
denotes the end of a section name

''
Double quotes around a string will escape all special characters in that string

#
Denotes the beginning of a comment; all characters from the # to the end of the line will be ignored. The ``#'' can be anywhere within the line

Here is a stanza file showing some examples of the above:

   section1:
           attrib1 = value1, value2
           attrib2 = this is all one value  # spaces aren't special
   	within value
           attrib3 = "value, with, commas"
           attrib4 = another\, way\, to\, escape\, commas
   section 2:                         # sections can contain spaces too
           long value = if we want a value to be very long but we want \
   to split it up into lines we can use a \\ at the end of the line\, but \
   if we want a literal \\ we have to escape it.
           another value = \"quotes can be part of the value too if you \
   escape them\"

References

SaScreenPolicy(3tlib), Error(3tlib).
25 April 2004
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004