PLCTL(1) General Commands Manual PLCTL(1)

NAME

plctlget or set values in a property list

SYNOPSIS

plctl file [-n] [-r | -x] [-w | -W] command ...

plctl file [-n] [-r | -x] [-w | -W] -a

plctl file [-n] [-r | -x] [-w | -W] -f commandfile

DESCRIPTION

The plctl utility is used to get and set values in a propertylist. Key/values are retrieved and set by specifying a node through a separated path. Traditionally, dots are used, but the ‘/' character may also be used.

command specifies either a Complex Command, or a node path. In the case of a node path the values are displayed. If the node is not a leaf, then all values under that node are displayed. These can be repeated.

The following options are available:

-a
Act as if a single command was specified with a node path of just the separator. This is syntatic compatibility to show the entire tree.
-f commandfile
Read commands from commandfile instead of the command line.
-n

Suppress printing of node name on output. The separator string is also omitted.
-r
Print raw values for nodes. Note that this can potentially be binary data (for CDATA nodes), or raw UTF encoding. This option conflicts with -x option.
-x
Hex dump output values for nodes instead of printing their string representation. This option conflicts with -r option.
-w
If the internal model is dirty (changes have been made) add an implicit ‘save' command to the end of the string. If the the model is still dirty after all commands have been run, then an error code is returned. (See Return Codes below.) This option conflicts with -W option.
-W
Ignore if the model is dirty after command completion and otherwise return a clean exit. This option conflicts with -w option.
-R
This is an alias for specifying both the -n and the -r options.

COMMANDS

Commands perform actions that change a plist. The are indicated by the use of two separator characters at the start. The syntax is [<sep><sep><command>][[[?]=<node path>][,<attributes...>]].

Using the ‘?=' syntax will not cause an error if the node does not exist [set], or can't be created [create]. In other cases it has no effect.

A shortcut for the ‘set' command is <node path>=<value>. A shortcut for the ‘show' command is <node path>.

Attributes modify the command, and can specify values. Value modifier flags must be last. Commands may take differing attributes.

Commands:

initialize
Create a new plist as the working model. Cut buffers are not cleared. Requires node Attributes are:
template
Optional argument specifying a file to use as a default template.
create
Create a new node, optionally with a specified type. If no type is specified the default is dictionary. If a value is specified, the default is string. Attributes are:
type
Optional argument specifying the type of node.
signed
Signed number [64bit] value.
unsigned
Unsigned number [64bit] value.
number
Alias for signed.
string
ASCII string value
boolean
Boolean, value= is case insensitive "True" / "False", or 0 / !0.
data
Binary blob
dictionary
key/value dictionary
array
0 indexed array
value
Set initial value to specified string. Types are converted as appropriate.
fvalue
Set initial value to contents of the referenced file name.
descriptor
Set initial value to read till EOF of specified descriptor. This is to allow careful fork/exec to handle sensitive information.
set
Update the value of a node. Requires a leaf (data type) node. Attributes are:
value
Set initial value to specified string. Types are converted as appropriate.
fvalue
Set initial value to contents of the referenced file name.
descriptor
Set initial value to read till EOF of specified descriptor. This is to allow careful fork/exec to handle sensitive information.
destroy
Remove node, and all subnodes from the model. Requires node.
show
Emit the value of the node as per the global flags. Requires node. Attributes are:
flags
Display modifier flags per above, exept on a per node basis.
save
Save the state of the model. This will clear the dirty bit. Attributes are:
file
Specify an alternate file to write out the plist. The file name is not saved between calls to //save.
type
Specify property list format for the save. Types are: ‘binary', ‘xml'.
cut
Copy a node, and any nodes under them, to a buffer, then remove from the model. Requires node. Attributes are:
buffer
Optional buffer number 1..9 to place copy into.
copy
Copy a node, and any nodes under them, to a buffer. Requires node. Attributes are:
buffer
Optional buffer number 1..9 to place copy into.
paste
Paste nodes from a buffer into the model. Targt node must be a dictionary or array. Requires node. Attributes are:
buffer
Optional buffer number 1..9 to use as source. If the buffer is empty, generate and error.
query
Describes node type. Output type defaults to common. Requires node. Attributes are:
style
Display style for output: ‘numeric', ‘proplib', ‘common'

RETURN CODES

0
Success
1
Invalid commandline option
2
Dirty Exit
8
Node not found
9
Node type conflict [leaf]
10
Node type conflict [parent]
126
Internal Error

EXAMPLES

To display all values (include node paths) one would use the following:
plctl config.plist -a

To initialize a new plist, one would use the following:

plctl config.plist -w //initialize
To create and set a debug node at the top level of a plist, one would use the following:
plctl config.plist -w //create=debug,type=number,value=1

To create a dictionary at the top level, one would use the following:

plctl config.plist -w //create=paths

To create an array at the top level, one would use the following:

plctl config.plist -w //create=locations,type=array

Convert a binary stored plist to an XML stored plist, one would use the following:

plctl config.plist //save,file=config-xml.plist,type=xml

To destroy a subtree (or leaf), one would use the follwing:

plctl config.plist -w //destroy=locations

BUGS

HISTORY

This software first appeared in version 1.0 of the CryptoSeal, Inc software suite.
 
October 11, 2012 NetBSD 6.0_RC2