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'
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