From da4a582eab825737b2ae0048f683e2a25e368c98 Mon Sep 17 00:00:00 2001 From: lissav Date: Wed, 9 Jan 2008 14:02:21 +0000 Subject: [PATCH] Add noderange manpage git-svn-id: https://svn.code.sf.net/p/xcat/code/xcat-core/trunk@231 8638fb3e-16cb-4fca-ae20-7b5d299a9bcd --- xCAT-client-2.0/share/man/man3/noderange.3 | 402 +++++++++++++++++++++ 1 file changed, 402 insertions(+) create mode 100644 xCAT-client-2.0/share/man/man3/noderange.3 diff --git a/xCAT-client-2.0/share/man/man3/noderange.3 b/xCAT-client-2.0/share/man/man3/noderange.3 new file mode 100644 index 000000000..7cae1d010 --- /dev/null +++ b/xCAT-client-2.0/share/man/man3/noderange.3 @@ -0,0 +1,402 @@ +.\" Process this file with +.\" groff -man -Tascii noderange.3 +.\" +.TH NODERANGE 3 "JUNE 2002" xCAT "xCAT" +.SH NAME +noderange \- generate a list of node names +.SH SYNOPSIS +.B noderange +[\fIcomma delimited nodelists and grouplists\fR] +.br + +.I e.g. +.br + +node1,node2,node8,node20,group1 +.br + +node14-node56,node70-node203,group1-group10 +.br + +node1,node2,node8,node20,node14-node56,node70-node203 +.br + +all,-node129-node256,-frame01-frame03 +.br + +@node.* +.br + +^/tmp/nodes +.br + +node10+5 +.br + +10-15,-13 +.br + +.br +.SH DESCRIPTION +.B noderange +is a function +that a single +operation may be applied to a range of nodes often in parallel. + +.B noderange +lists can be an individual node and/or group: + +.I node01 +.br +.I group1 +.br + +a range of nodes and/or groups: + +.I node01-node10 +.br +.I group1-group3 +.br + +a regular expression match of nodes and/or groups: + +.I @node[345].* +.br +.I @group[12].* +.br + +an incremented range of nodes: + +.I node10+5 +.br + +a file containing noderanges of nodes and/or groups: + +.I ^/tmp/nodelist +.br + +a node shorthand range of nodes: + +.I 10-20 +.br +.I 10+5 +.br + +or any combination: + +.I node01-node30,node40,^/tmp/nodes,@node[13].*,2-10,node50+5 +.br + +Any individual +.B noderange +may be prefixed with an exclusion operator +(default -) with the exception of the file operator (default ^). + +Any combination or multiple combinations of inclusive +and exclusive ranges of nodes and groups is legal. There +is no precedence implied in the order of the +arguments. Exclusive ranges have precedence over inclusive. + +Nodes have precedence over groups. If a node range match is made +then no group range match will be attempted. + +All node names are validated against +the nodelist table. +Invalid nodes are ignored and return nothing. + +All group names are validated against +the nodelist and nodetype table. +Invalid groups are ignored and return nothing. + +Throughout this +man page the term +\fIxCAT Node Format\fR +will be used. + +\fIxCAT Node Format\fR is defined by the following regex: + +^([A-Za-z-]+)([0-9]+)(([A-Za-z-]+[A-Za-z0-9-]*)*) + +In plain english a node or group is in +\fIxCAT Node Format\fR +if starting from the begining there are one or more +alpha characters of any case and any number of - in any +combination, followed by +one or more numbers, then optionally followed by one +alpha character of any case or the - followed by any +combination of case mixed alphanumerics and the -. + +.B noderange +supports node/group names in +.I any +format. +\fIxCAT Node Format\fR +is +.B not +required, however some node range +methods used to determine range will not be used. +E.g. If using a +.B noderange +of +.I node1a-node9a +with a +.BR nodelist.tab (5) +only listing +.I node1a +through +.IR node5a , +.B noderange +will enumerate then validate and return a proper +range. If using a node range of +.I aa-az +with +.BR nodelist.tab (5) +only listing +.I aa +through +.IR ay, +.B noderange +will fail to return any values. + +Example +\fIxCAT Node Format\fR +node/group names: + +.B nodename prefix number suffix +.br +node1 node 1 +.br +node001 node 001 +.br +node-001 node- 001 +.br +node-foo-001-bar node-foo- 001 -bar +.br +node-foo-1bar node-foo- 1 bar +.br +foo1bar2 foo 1 bar2 +.br +rack01unit34 rack 01 unit34 +.br +unit34rack01 unit 34 rack01 +.br +pos0134 pos 0134 +.br + +Example non-\fIxCAT Node Format\fR +node/group names, but still valid: + +aa +.br +yellow +.br +red +.br +12foo +.br + + +First +.B noderange +checks for the multiple range operator (default ,). Each range is +also processed by +.BR noderange . + +Next +.B noderange +checks for the file operator (default ^). If the file exists +each line will be processed as a +.BR noderange . +Lines starting +with +.I # +or the file operator (default ^) are ignored. Only +one +.B noderange +per line is read. All characters are ignored +after the first white space. + +e.g. + +^/tmp/nodes + +where + +cat /tmp/nodes outputs: + +#my node list (this line ignored) +.br +^/tmp/foo #ignored +.br +node01 #node comment +.br +node02 +.br +node03 +.br +node10-node20 +.br +@group[456].* +.br +-node50 +.br + +Next +.B noderange +checks for the exclusion operator (default -) then continues. +This operator supports nodes and groups. +.B noderange +is smart and will not confuse the exclusion or range +operators with the +- character in names. + +Next +.B noderange +checks for the for the regular expression operator (default @). +Regular expressions offer the most flexibility. If you are +interested in learing regex read the book +\fIMastering Regular Expressions\fR. +This operator supports nodes and groups. + +Next +.B noderange +checks for a numeric only range (e.g. 10-20, 5+3, or just 10), then uses +.I $XCAT_NODE_PREFIX +and +.I $XCAT_NODE_SUFFIX +(optional) +as the defaults to complete the node names. +.I $XCAT_NODE_PREFIX +must be defined to use noderange +shorthand. If you use padded node names (e.g. node001, node002, etc...) +then you must specify +.I $XCAT_NODE_PADDING +or the default of +.I 1 +will be used. E.g. if you use node names node001, node002, etc..., then +.I $XCAT_NODE_PADDING +should be set to +.IR 3 . +Noderange shorthand supports nodes only. Noderange shorthand can +be mixed with all other operators except regex. i.e. exclusion, +increment, range, and file may be used. + +Next +.B noderange +checks for the increment range operator (default +). Increment +range operator noderanges are in the format: + +.IB valid_node_name + number_of_sequential_nodes + +e.g. + +.I node10+5 + +would yield node10 plus the next +.I 4 +nodes. + +This action is performed using two different methods. +If +.I valid_node_name +is in +\fIxCAT Node Format\fR +then the range is enumerated to one less than +.IR number_of_sequential_nodes . +If not in +\fIxCAT Node Format\fR +then a sorted +.BR nodelist.tab (5) +is used to return the node range. +This operator supports nodes only. + +Next +.B noderange +checks for a single node name or group name. + +Next +.B noderange +checks for the range operator (default -). Ranges are +performed first by validating that both the start +and end nodes or groups defining the range exist and if +so the range is returned based on the content of +.BR nodelist.tab (5), +.BR nodetype.tab (5), +and +.BR nodemodel.tab (5). +If the start and end nodes or groups +defined in the range do not exist, +.I and +if both are in +\fIxCAT Node Format\fR, +.I and +if both the prefix and suffix match, +then the range is enumerated and each node/group +validated. Only valid nodes/groups will be returned. +.B noderange +is smart and will not confuse the exclusion or range +operators with the +- character in names. + +Last +.B noderange +returns nothing if no match can be found. + +.B noderange +uses the smallest integer to determine +padding. e.g. \fInode1-node10\fR will generate a list of nodes +with numbers 1, 2, 3, 4, 5, 6, 7, 8, 9, 10. \fInode001-node010\fR will +generate a list of nodes with numbers 001, 002, 003, 004, +005, 006, 007, 008, 009, 010. + +Multiple instances of a node name are treated as one +instance. e.g. \fInode1-node10,node4,node4,node4\fR will generate +a list of nodes numbered 1 through 10, the number 4 +will only be listed once. + +.SH EXAMPLES +.I all,-node5-node10 + +Generates a list of all nodes (assuming all is a group) +listed in +.BR nodelist.tab (5) +less node5 through node10. + +.I node1-node10,-node3-node5,node4 + +Generates a list of nodes 1 through 10 less nodes 3,4,5. Note +that node4 is listed twice, first in the range and then at +the end. Because exclusion has precedence node4 will be excluded. + +.I node1-node10,-node3,-node5 + +Generates a list of nodes 1 through 10 less nodes 3 and 5. + +.I -node17-node32,all + +Generates a list of all (assuming 'all' is a group) nodes in +.BR nodelist.tab (5) +less 17 through 32. + +.I node1-node128,user1-user4 + +Generates a list of nodes 1 through 128, and user nodes 1 through 4. + +.I all,-rack1-rack3,-node100-node200,node150,-storage + +Generates a list of all nodes (assuming 'all' is a group), less +nodes in groups rack1 through rack3 (assuming groups rack1, +rack2, and rack3 are defined), less nodes 100 through +200, less nodes in the storage group. Note that +node150 is listed but is excluded. + +.I @node[23].* + +Generates a list of nodes matching the regex +.IR node[23].* . +That is all nodes that start with node2 or node3 and end in anything +or nothing. E.g. node2, node3, node20, node30, node21234 all match. + +.SH "NOTES" +.IX Header "NOTES" +This command is part of the xCAT software product.