ludesc(1M)                                                                                                                              ludesc(1M)

NAME

       ludesc - display or set boot environment description

SYNOPSIS

       /usr/sbin/ludesc -A BE_description | -f  {filename | -}  [-l error_log] [-o outfile] [-X]

       /usr/sbin/ludesc -n BE_name [-f filename | -] [-l error_log] [-o outfile] [-X]

       /usr/sbin/ludesc -n BE_name [-l error_log] [-o outfile] [-X] BE_description

DESCRIPTION

       The  ludesc  command  is  part  of  a  suite  of  commands  that make up the Live Upgrade feature of the Solaris operating environment. See
       live_upgrade(5) for a description of the Live Upgrade feature.

       The ludesc command allows you to manipulate boot environment (BE) descriptions. A BE description is an optional attribute of a BE.  It  can
       be  text or binary data. For example, it might be a string such as "S9 beta test BE" or it be a file that contains 8-bit multi-byte charac-
       ters. The ludesc command in general and the options to manipulate binary-format descriptions in particular are suitable  for  use  in  pro-
       grams.

       You  create a BE description using ludesc or lucreate(1M). Only ludesc allows you to change a BE description or add a description following
       BE creation.

       While a BE description is associated with a BE name, it is not interchangeable with that name. No Live Upgrade command allows you to  spec-
       ify a BE description instead of a BE name when performing an operation on a BE.

       A  shell might restrict what you enter for a BE description (in both ludesc and lucreate(1M)). In entering a description, use the following
       guidelines:

         o  Always enclose a description in single quotes ('), unless the description includes a single quote.

         o  If your description includes a single quote, enclose the description in double quotes ("). You then must use an escape sequence  (usu-
            ally  a backslash []) to enter a character that is special to the shell. See sh(1) for a list of special characters and a description
            of the escape sequence mechanism.

       Descriptions that include many special characters might be more conveniently inserted in a file (-f option) than entered on a command  line
       (-A option).

       When  ludesc  outputs a BE description, it does so exactly as the description was entered. Because of this feature, a description that is a
       text string does not have a concluding newline, which means the system prompt immediately follows the last character of the description.

       The ludesc command requires root privileges.

OPTIONS

       The ludesc command has the following options:

       -A BE_description

           Displays the BE name associated with BE_description.

       -f {filename | -}

           Specify the BE description contained in filename or read from stdin. When used without -n, displays the BE  name  associated  with  the
           specified BE description. Used with -n, changes the description for the specified BE to the description specified with -f.

       -l error_log

           Error and status messages are sent to error_log, in addition to where they are sent in your current environment.

       -n BE_name

           With  no  other  arguments, displays the BE description for the specified BE. With the -f option or the BE_description operand, changes
           the description for the specified BE to that specified with -f or BE_description.

       -o outfile

           All command output is sent to outfile, in addition to where it is sent in your current environment.

       -X

           Enable XML output. Characteristics of XML are defined in DTD, in /usr/share/lib/xml/dtd/lu_cli.dtd.<num>, where <num>  is  the  version
           number of the DTD file.

OPERANDS

       BE_description

           Used only with the -n option. BE_description replaces the current BE description for the specified BE.

EXAMPLES

       The following are examples of the use of ludesc.

       Example 1: Basic Use

       The  first  command,  below,  assigns  a  description  to a BE. The second command returns the name of the BE associated with the specified
       description. The last command returns the description associated with a specified BE.

       # ludesc -n first_disk 'Test disk'
       Setting description for boot environment <first_disk>.
       Propagating the change of BE description to all BEs.

       # ludesc -A 'Test disk'
       first_disk
       #

       # ludesc -n first_disk
       Test disk#

       As seen above and noted in the DESCRIPTION, ludesc does not append a newline to the display of BE description that is a text string.

       Example 2: Using Binary Files

       The following commands are analogs of the preceding examples, substituting a binary file-here, a file containing a description in  Russian,
       using  the Cyrillic alphabet--for a text string. In the third command, note the use of a file to capture output. Sending output of a binary
       file to the console can produce erratic results.

       # ludesc -n first_disk -f arrayBE.ru
       Setting description for boot environment <first_disk>.
       Propagating the change of BE description to all BEs.

       # ludesc -f arrayBE.ru
       first_disk

       # ludesc -n first_disk > /tmp/arrayBE.out

EXIT STATUS

       The following exit values are returned:

       0        Successful completion.

       >0       An error occurred.

FILES

       /etc/lutab

           list of BEs on the system

       /usr/share/lib/xml/dtd/lu_cli.dtd.<num>

           Live Upgrade DTD (see -X option)

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Availability                 |SUNWluu                      |
       +-----------------------------+-----------------------------+

SEE ALSO

       lu(1M), luactivate(1M), lucancel(1M), lucompare(1M), lucreate(1M), ludelete(1M), lufslist(1M), lumake(1M), lumount(1M), lurename(1M),  lus-
       tatus(1M), luupgrade(1M), lutab(4), attributes(5), live_upgrade(5)

SunOS 5.10                                                          24 Jan 2002                                                         ludesc(1M)