Seth Woolley's Man Viewer

Manual for dialog - man 1 dialog

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

DIALOG(1)                                                            DIALOG(1)



NAME
       dialog(1,3,n) - display dialog(1,3,n) boxes from shell scripts

SYNOPSIS
       dialog(1,3,n) --clear
       dialog(1,3,n) --create-rc file(1,n)
       dialog(1,3,n) --print-maxsize
       dialog(1,3,n) common-options box-options

DESCRIPTION
       Dialog is a program that will let you to present a variety of questions
       or display messages using dialog(1,3,n) boxes  from  a  shell  script.   These
       types  of  dialog(1,3,n) boxes are implemented (though not all are necessarily
       compiled into dialog(1,3,n)):

              calendar, checklist, form, fselect,  gauge,  infobox,  inputbox,
              inputmenu, menu(3x,n,n tk_menuSetFocus), msgbox (message), password, radiolist, tailbox,
              tailboxbg, textbox, timebox, and yesno (yes/no).

       You can put more than one dialog(1,3,n) box into a script:

       -    Use the --and-widget token to force Dialog to proceed to the  next
            dialog(1,3,n) unless you have pressed ESC to cancel, or

       -    Simply  add  the  tokens  for the next dialog(1,3,n) box, making a chain.
            Dialog stops chaining when  the  return  code  from  a  dialog(1,3,n)  is
            nonzero, e.g., Cancel or No (see DIAGNOSTICS).

       Some  widgets,  e.g.,  checklist,  will  write(1,2) text to dialog(1,3,n)'s output.
       Normally that is the standard error(8,n), but there are options for changing
       this:  --output-fd,  --stderr  and --stdout.  No text is written if(3,n) the
       Cancel button (or ESC) is pressed; dialog(1,3,n)  exits  immediately  in(1,8)  that
       case.

OPTIONS
       All  options  begin  with  "--"  (two ASCII hyphens, for the benefit of
       those using systems with deranged locale(3,5,7) support).

       A "--" by itself is used as an escape, i.e., the next token on the com-
       mand-line is not treated as an option.
              dialog(1,3,n) --title -- --Not an option

       The "--file" option tells dialog(1,3,n) to read(2,n,1 builtins) parameters from the file(1,n) named(5,8)
       as its value.
              dialog(1,3,n) --file parameterfile
       Blanks not within double-quotes are discarded (use backslashes to quote
       single  characters).   The  result  is  inserted into the command-line,
       replacing --file and its option value.  Interpretation of the  command-
       line resumes from that point.

   Common Options
       --aspect ratio
              This  gives  you some control over the box dimensions when using
              auto(5,8) sizing (specifying 0 for height and width).  It  represents
              width / height.  The default is 9, which means 9 characters wide
              to every 1 line high.

       --backtitle backtitle
              Specifies a backtitle string(3,n) to be displayed on the backdrop, at
              the top of the screen.

       --beep Sound the audible alarm(1,2) each time(1,2,n) the screen is refreshed.

       --beep-after
              Beep if(3,n) input is interrupted, e.g., by a control/C.

       --begin y x
              Specify the position of the upper left corner of a dialog(1,3,n) box on
              the screen.

       --cancel-label string(3,n)
              Override the label used for "Cancel" buttons.

       --clear
              The screen will be cleared on exit.  This  may  be  used  alone,
              without other options.

       --colors
              Interpret embedded "\Z" sequences in(1,8) the dialog(1,3,n) text by the fol-
              lowing character, which tells dialog(1,3,n)  to  set(7,n,1 builtins)  colors  or  video
              attributes: 0 through 7 are the ANSI used in(1,8) curses: black, red,
              green, yellow, blue, magenta, cyan and white respectively.  Bold
              is  set(7,n,1 builtins)  by  'b', reset(1,7,1 tput) by 'B'.  Reverse is set(7,n,1 builtins) by 'r', reset(1,7,1 tput) by
              'R'.  Underline is set(7,n,1 builtins) by 'u', reset(1,7,1 tput) by 'U'.  The  settings  are
              cumulative,  e.g., "\Zb\Z1" makes the following text bright red.
              Restore normal settings with "\Zn".

       --cr-wrap
              Interpret embedded newlines in(1,8) the dialog(1,3,n) text as a  newline  on
              the screen.  Otherwise, dialog(1,3,n) will only wrap lines where needed
              to fit inside the text box.  Even though you  can  control  line
              breaks  with this, dialog(1,3,n) will still wrap any lines that are too
              long for the width of the box.  Without cr-wrap, the  layout  of
              your  text  may  be formatted to look(1,8,3 Search::Dict) nice(1,2) in(1,8) the source code of
              your script without affecting the way it will look(1,8,3 Search::Dict) in(1,8)  the  dia-
              log.

              See also the --no-collapse and --trim options.

       --create-rc file(1,n)
              When dialog(1,3,n) supports run-time configuration, this can be used to
              dump a sample configuration file(1,n) to the file(1,n) specified by  file(1,n).

       --defaultno
              Make  the  default value of the yes/no box a No.  Likewise, make
              the default button of widgets that provide "OK" and  "Cancel"  a
              Cancel.   If  --nocancel  was  given that option overrides this,
              making the default button always "Yes" (internally the  same  as
              "OK").

       --default-item string(3,n)
              Set the default item in(1,8) a checklist, form or menu(3x,n,n tk_menuSetFocus) box.  Normally
              the first item in(1,8) the box is the default.

       --exit-label string(3,n)
              Override the label used for "EXIT" buttons.

       --extra-button
              Show an extra button, between "OK" and "Cancel" buttons.

       --extra-label string(3,n)
              Override the label used for "Extra" buttons.  Note:  for  input-
              menu(3x,n,n tk_menuSetFocus) widgets, this defaults to "Rename".

       --help Prints the help message to dialog(1,3,n)'s output.  The help message is
              printed if(3,n) no options are given.

       --help-button
              Show a help-button after "OK" and  "Cancel"  buttons,  i.e.,  in(1,8)
              checklist,  radiolist  and  menu(3x,n,n tk_menuSetFocus)  boxes.  If --item-help is also
              given, on exit(3,n,1 builtins) the return status will be the  same  as  for  the
              "OK"  button, and the item-help text will be written to dialog(1,3,n)'s
              output after the token "HELP".   Otherwise,  the  return  status
              will  indicate  that the Help button was pressed, and no message
              printed.

       --help-label string(3,n)
              Override the label used for "Help" buttons.

       --help-status
              If the help-button is selected, writes the checklist,  radiolist
              or  form  information  after  the  item-help "HELP" information.
              This can be used to reconstruct the state of a  checklist  after
              processing the help request.

       --ignore
              Ignore  options that dialog(1,3,n) does not recognize.  Some well-known
              ones such as "--icon" are ignored anyway, but this is  a  better
              choice for compatibility with other implementations.

       --input-fd fd
              Read keyboard input from the given file(1,n) descriptor.  Most dialog(1,3,n)
              scripts read(2,n,1 builtins) from the standard input, but the gauge widget reads
              a pipe(2,8) (which is always standard input).  Some configurations do
              not work properly when dialog(1,3,n) tries to reopen the terminal.  Use
              this  option  (with appropriate juggling of file-descriptors) if(3,n)
              your script must work in(1,8) that type of environment.

       --insecure
              Makes the password widget friendlier but less(1,3) secure, by echoing
              asterisks for each character.

       --item-help
              Interpret  the tags data for checklist, radiolist and menu(3x,n,n tk_menuSetFocus) boxes
              adding a column which is displayed in(1,8) the  bottom  line  of  the
              screen, for the currently selected item.

       --keep-window
              Do  not  remove/repaint  the window on exit.  This is useful for
              keeping the window contents visible when several widgets are run
              in(1,8)  the  same  process.   Note that curses will clear(1,3x,3x clrtobot) the screen
              when starting a new process.

       --max-input size
              Limit input strings to the given size.  If  not  specified,  the
              limit is 2048.

       --no-cancel

       --nocancel
              Suppress the "Cancel" button in(1,8) checklist, inputbox and menu(3x,n,n tk_menuSetFocus) box
              modes.  A script can still test if(3,n) the user pressed the ESC  key
              to cancel to quit.

       --no-collapse
              Normally  dialog(1,3,n)  converts  tabs  to spaces and reduces multiple
              spaces to a single space for text which is displayed in(1,8)  a  mes-
              sage boxes, etc.  Use this option to disable that feature.  Note
              that dialog(1,3,n) will still wrap text, subject to the  --cr-wrap  and
              --trim options.

       --no-kill
              Tells  dialog(1,3,n) to put the tailboxbg box in(1,8) the background, print-
              ing its process id to dialog(1,3,n)'s output.  SIGHUP is  disabled  for
              the background process.

       --no-label string(3,n)
              Override the label used for "No" buttons.

       --no-shadow
              Suppress  shadows that would be drawn to the right and bottom of
              each dialog(1,3,n) box.

       --ok-label string(3,n)
              Override the label used for "OK" buttons.

       --output-fd fd
              Direct output to the given file(1,n) descriptor.  Most dialog(1,3,n) scripts
              write(1,2)  to  the  standard  error(8,n),  but error(8,n) messages may also be
              written there, depending on your script.

       --print-maxsize
              Print the maximum size of dialog(1,3,n) boxes, i.e., the  screen  size,
              to  dialog(1,3,n)'s  output.   This  may  be  used alone, without other
              options.

       --print-size
              Prints the size of each dialog(1,3,n) box to dialog(1,3,n)'s output.

       --print-version
              Prints dialog(1,3,n)'s version(1,3,5) to dialog(1,3,n)'s output.  This  may  be  used
              alone, without other options.

       --separate-output
              For checklist widgets, output result one line at a time(1,2,n), with no
              quoting.  This facilitates parsing by another program.

       --separator string(3,n)

       --separate-widget string(3,n)
              Specify a string(3,n) that will separate the output on dialog(1,3,n)'s  out-
              put  from  each  widget.   This  is used to simplify parsing the
              result of a dialog(1,3,n) with several widgets.  If this option is  not
              given, the default separator string(3,n) is a tab character.

       --shadow
              Draw a shadow(3,5) to the right and bottom of each dialog(1,3,n) box.

       --single-quoted
              Use single-quoting as needed (and no quotes if(3,n) unneeded) for the
              output of checklist's as well as the item-help  text.   If  this
              option  is  not set(7,n,1 builtins), dialog(1,3,n) uses double quotes around each item.
              That requires occasional use of backslashes to make  the  output
              useful in(1,8) shell scripts.

       --size-err
              Check  the  resulting  size of a dialog(1,3,n) box before trying to use
              it, printing the resulting size if(3,n) it is larger than the screen.
              (This  option  is  obsolete,  since  all  new-window  calls  are
              checked).

       --sleep secs
              Sleep (delay) for the given number of seconds after processing a
              dialog(1,3,n) box.

       --stderr
              Direct output to the standard error.  This is the default, since
              curses normally writes screen updates to the standard output.

       --stdout
              Direct output to the standard output.  This option  is  provided
              for  compatibility  with  Xdialog,  however using it in(1,8) portable
              scripts is not recommended, since  curses  normally  writes  its
              screen  updates to the standard output.  If you use this option,
              dialog(1,3,n) attempts to reopen the terminal so it can  write(1,2)  to  the
              display.   Depending  on the platform and your environment, that
              may fail.

       --tab-correct
              Convert each tab character to one or  more  spaces.   Otherwise,
              tabs  are rendered according to the curses library's interpreta-
              tion.

       --tab-len n
              Specify the number of spaces that a tab  character  occupies  if(3,n)
              the "--tab-correct" option is given.  The default is 8.

       --timeout secs
              Timeout  (exit(3,n,1 builtins)  with  error(8,n) code) if(3,n) no user response within the
              given number of seconds.

       --title title
              Specifies a title string(3,n) to be displayed at the top of the  dia-
              log box.

       --trim eliminate  leading  blanks,  trim  literal newlines and repeated
              blanks from message text.

              See also the --cr-wrap and --no-collapse options.

       --version
              Same as "--print-version".

       --visit-items
              Modify the tab-traversal of  checklist,  radiobox,  menubox  and
              inputmenu  to  include  the  list of items as one of the states.
              This is useful as a visual aid, i.e., the cursor position  helps
              some users.

       --yes-label string(3,n)
              Override the label used for "Yes" buttons.

   Box Options
       All dialog(1,3,n) boxes have at least three parameters:

       text the caption or contents of the box.

       height
            the height of the dialog(1,3,n) box.

       width
            the width of the dialog(1,3,n) box.

       Other parameters depend on the box type.

       --calendar text height width day month year
              A  calendar  box  displays  month,  day  and  year in(1,8) separately
              adjustable windows.  If the values for day, month  or  year  are
              missing or negative, the current date's corresponding values are
              used.  You can increment or decrement any  of  those  using  the
              left-,  up-, right- and down-arrows.  Use vi-style h, j, k and l
              for moving around the array of days in(1,8)  a  month.   Use  tab  or
              backtab  to move(3x,7,3x curs_move) between windows.  If the year is given as zero,
              the current date is used as an initial value.

              On exit(3,n,1 builtins), the date is printed in(1,8) the form day/month/year.

       --checklist text height width list-height [ tag item status ] ...
              A checklist box is similar to a menu(3x,n,n tk_menuSetFocus)  box;  there  are  multiple
              entries  presented  in(1,8)  the form of a menu.  Instead of choosing
              one entry among the entries, each entry can be turned on or  off
              by  the  user.  The initial on/off state of each entry is speci-
              fied by status.

              On exit(3,n,1 builtins), a list of the tag strings of  those  entries  that  are
              turned  on  will  be printed on dialog(1,3,n)'s output.  If the --sepa-
              rate-output option is not given, the strings will be  quoted  to
              make  it simple for scripts to separate them.  See the --single-
              quoted option, which modifies the quoting behavior.

       --form text height width formheight [ label y x item y x flen ilen ] ...
              The form dialog(1,3,n) displays a form consisting of labels and fields,
              which are positioned on a scrollable window by coordinates given
              in(1,8) the script.  The field length flen and input-length ilen tell
              how  long the field can be.  The former defines the length shown
              for a selected field, while the latter defines  the  permissible
              length  of  the data entered in(1,8) the field.  If flen is zero, the
              corresponding field cannot be altered.  If ilen is zero,  it  is
              set(7,n,1 builtins) to flen.

              Use  up/down  arrows  (or  control/N, control/P) to move(3x,7,3x curs_move) between
              fields.  Use tab to move(3x,7,3x curs_move) between windows.

              On exit(3,n,1 builtins), the contents of the form-fields are written to dialog(1,3,n)'s
              output,  each  field  separated by a newline.  Input-only fields
              (flen is zero) are not written out.

       --fselect filepath height width
              The file-selection dialog(1,3,n) displays a text-entry window in(1,8)  which
              you  can type a filename (or directory), and above that two win-
              dows with directory names and filenames.

              Here filepath can be a filepath  in(1,8)  which  case  the  file(1,n)  and
              directory  windows will display the contents of the path and the
              text-entry window will contain the preselected filename.

              Use tab or arrow keys to move(3x,7,3x curs_move) between the windows.   Within  the
              directory  or  filename  windows,  use the up/down arrow keys to
              scroll the current selection.  Use the  space-bar  to  copy  the
              current selection into the text-entry window.

              Typing any printable characters switches focus to the text-entry
              window, entering that character as well as scrolling the  direc-
              tory and filename windows to the closest match.

              Use  a  carriage return or the "OK" button to accept(2,8) the current
              value in(1,8) the text-entry window and exit.

              On exit(3,n,1 builtins), the contents of the text-entry window  are  written  to
              dialog(1,3,n)'s output.

       --gauge text height width [percent]
              A  gauge  box displays a meter along the bottom of the box.  The
              meter indicates the percentage.  New percentages are  read(2,n,1 builtins)  from
              standard  input,  one integer per line.  The meter is updated to
              reflect each new percentage.  If the standard  input  reads  the
              string(3,n) "XXX", then subsequent lines up to another "XXX" are used
              for a new prompt.  The gauge exits when EOF is  reached  on  the
              standard input.

              The  percent  value  denotes the initial percentage shown in(1,8) the
              meter.  If not specified, it is zero.

              On exit(3,n,1 builtins), no text is written  to  dialog(1,3,n)'s  output.   The  widget
              accepts no input, so the exit(3,n,1 builtins) status is always OK.

       --infobox text height width
              An  info(1,5,n) box is basically a message box.  However, in(1,8) this case,
              dialog(1,3,n) will exit(3,n,1 builtins) immediately after displaying the message to the
              user.   The screen is not cleared when dialog(1,3,n) exits, so that the
              message will remain on the screen until the calling shell script
              clears  it  later.   This  is useful when you want to inform the
              user that some operations are carrying on that may require  some
              time(1,2,n) to finish.

              On  exit(3,n,1 builtins),  no  text is written to dialog(1,3,n)'s output.  Only an "OK"
              button is provided for input, but an  ESC  exit(3,n,1 builtins)  status  may  be
              returned.

       --inputbox text height width [init]
              An  input  box  is  useful  when  you want to ask questions that
              require the user to input a string(3,n) as the answer.   If  init  is
              supplied it is used to initialize the input string.  When enter-
              ing the string(3,n), the backspace, delete and  cursor  keys  can  be
              used  to  correct  typing errors.  If the input string(3,n) is longer
              than can fit  in(1,8)  the  dialog(1,3,n)  box,  the  input  field  will  be
              scrolled.

              On exit(3,n,1 builtins), the input string(3,n) will be printed on dialog(1,3,n)'s output.

       --inputmenu text height width menu-height [ tag item ] ...
              An inputmenu box is very similar to an ordinary menu(3x,n,n tk_menuSetFocus) box.  There
              are only a few differences between them:

              1.  The  entries  are  not  automatically  centered   but   left
                  adjusted.

              2.  An  extra  button  (called  Rename) is implied to rename(1,2,n) the
                  current item when it is pressed.

              3.  It is possible to rename(1,2,n) the current entry by  pressing  the
                  Rename button.  Then dialog(1,3,n) will write(1,2) the following on dia-
                  log's output.

                  RENAMED <tag> <item>

       --menu text height width menu-height [ tag item ] ...
              As its name suggests, a menu(3x,n,n tk_menuSetFocus) box is a dialog(1,3,n)  box  that  can  be
              used  to present a list of choices in(1,8) the form of a menu(3x,n,n tk_menuSetFocus) for the
              user to choose.  Choices are displayed in(1,8) the order given.  Each
              menu(3x,n,n tk_menuSetFocus) entry consists of a tag string(3,n) and an item string.  The tag
              gives the entry a name to distinguish it from the other  entries
              in(1,8) the menu.  The item is a short description of the option that
              the entry represents.   The  user  can  move(3x,7,3x curs_move)  between  the  menu(3x,n,n tk_menuSetFocus)
              entries by pressing the cursor keys, the first letter of the tag
              as a hot-key, or the number  keys  1-9.  There  are  menu-height
              entries  displayed in(1,8) the menu(3x,n,n tk_menuSetFocus) at one time(1,2,n), but the menu(3x,n,n tk_menuSetFocus) will be
              scrolled if(3,n) there are more entries than that.

              On exit(3,n,1 builtins) the tag of the chosen menu(3x,n,n tk_menuSetFocus) entry will be printed on dia-
              log's  output.  If the --help-button option is given, the corre-
              sponding help text will be printed if(3,n) the user selects the  help
              button.

       --msgbox text height width
              A message box is very similar to a yes/no box.  The only differ-
              ence between a message box and a yes/no box is  that  a  message
              box has only a single OK button.  You can use this dialog(1,3,n) box to
              display any message you like.  After reading  the  message,  the
              user  can  press  the ENTER key so that dialog(1,3,n) will exit(3,n,1 builtins) and the
              calling shell script can continue its operation.

              On exit(3,n,1 builtins), no text is written to dialog(1,3,n)'s output.   Only  an  "OK"
              button  is  provided  for  input,  but an ESC exit(3,n,1 builtins) status may be
              returned.

       --passwordbox text height width [init]
              A password box is similar to an input box, except that the  text
              the user enters is not displayed.  This is useful when prompting
              for passwords or other sensitive information.  Be aware that  if(3,n)
              anything is passed in(1,8) "init", it will be visible in(1,8) the system's
              process table to casual snoopers.  Also, it is very confusing to
              the  user  to  provide  them with a default password they cannot
              see.  For these reasons, using  "init"  is  highly  discouraged.
              See "--insecure" if(3,n) you do not care about your password.

              On exit(3,n,1 builtins), the input string(3,n) will be printed on dialog(1,3,n)'s output.

       --radiolist text height width list-height  [ tag item status ] ...
              A  radiolist  box is similar to a menu(3x,n,n tk_menuSetFocus) box.  The only difference
              is that you can indicate which entry is currently  selected,  by
              setting its status to on.

              On  exit(3,n,1 builtins),  the  name of the selected item is written to dialog(1,3,n)'s
              output.

       --tailbox file(1,n) height width
              Display text from a file(1,n) in(1,8) a dialog(1,3,n) box, as in(1,8) a "tail -f" com-
              mand.   Scroll  left/right using vi-style 'h' and 'l', or arrow-
              keys.  A '0' resets the scrolling.

              On exit(3,n,1 builtins), no text is written to dialog(1,3,n)'s output.   Only  an  "OK"
              button  is  provided  for  input,  but an ESC exit(3,n,1 builtins) status may be
              returned.

       --tailboxbg file(1,n) height width
              Display text from a file(1,n) in(1,8) a dialog(1,3,n) box as a  background  task,
              as  in(1,8)  a "tail -f &" command.  Scroll left/right using vi-style
              'h' and 'l', or arrow-keys.  A '0' resets the scrolling.

              Dialog treats the background task specially if(3,n) there  are  other
              widgets  (--and-widget) on the screen concurrently.  Until those
              widgets are closed (e.g., an "OK"), dialog(1,3,n) will perform  all  of
              the  tailboxbg widgets in(1,8) the same process, polling for updates.
              You may use a tab to traverse between the widgets on the screen,
              and  close(2,7,n) them individually, e.g., by pressing ENTER.  Once the
              non-tailboxbg widgets are closed, dialog(1,3,n) forks a copy of  itself
              into  the background, and prints its process id if(3,n) the --no-kill
              option is given.

              On exit(3,n,1 builtins), no text is written to dialog(1,3,n)'s output.  Only an  "EXIT"
              button  is  provided  for  input,  but an ESC exit(3,n,1 builtins) status may be
              returned.

              NOTE: Older versions of dialog(1,3,n) forked immediately and  attempted
              to  update(7,n)  the screen individually.  Besides being bad for per-
              formance, it was unworkable.  Some older scripts  may  not  work
              properly with the polled scheme.

       --textbox file(1,n) height width
              A  text  box  lets  you display the contents of a text file(1,n) in(1,8) a
              dialog(1,3,n) box.  It is like a simple text file(1,n) viewer.  The user can
              move(3x,7,3x curs_move)  through  the  file(1,n)  by  using  the  cursor,  PGUP/PGDN and
              HOME/END keys available on most keyboards.  If the lines are too
              long to be displayed in(1,8) the box, the LEFT/RIGHT keys can be used
              to scroll the text region horizontally.  You may  also  use  vi-
              style keys h, j, k, l in(1,8) place of the cursor keys, and B or N in(1,8)
              place of the pageup/pagedown keys.   Scroll  up/down  using  vi-
              style  'k'  and 'j', or arrow-keys.  Scroll left/right using vi-
              style 'h' and 'l', or arrow-keys.  A '0' resets  the  left/right
              scrolling.   For more convenience, vi-style forward and backward
              searching functions are also provided.

              On exit(3,n,1 builtins), no text is written to dialog(1,3,n)'s output.  Only an  "EXIT"
              button  is  provided  for  input,  but an ESC exit(3,n,1 builtins) status may be
              returned.

       --timebox text height [width hour minute second]
              A dialog(1,3,n) is displayed which allows you to  select(2,7,2 select_tut)  hour,  minute
              and  second.  If the values for hour, minute or second are miss-
              ing or negative, the current  date's  corresponding  values  are
              used.   You  can  increment  or decrement any of those using the
              left-, up-, right- and down-arrows.  Use tab or backtab to  move(3x,7,3x curs_move)
              between windows.

              On exit(3,n,1 builtins), the result is printed in(1,8) the form hour:minute:second.

       --yesno text height width
              A yes/no dialog(1,3,n) box of size height rows by width columns will be
              displayed.  The string(3,n) specified by text is displayed inside the
              dialog(1,3,n)  box.   If this string(3,n) is too long to fit in(1,8) one line, it
              will be automatically divided into multiple lines at appropriate
              places.  The text string(3,n) can also contain the sub-string "\n" or
              newline characters `\n' to  control  line  breaking  explicitly.
              This  dialog(1,3,n) box is useful for asking questions that require the
              user to answer either yes or no.  The dialog(1,3,n) box has a Yes  but-
              ton  and  a  No  button, in(1,8) which the user can switch(1,n) between by
              pressing the TAB key.

              On exit(3,n,1 builtins), no text is written to dialog(1,3,n)'s output.  In addition  to
              the "Yes" and "No" exit(3,n,1 builtins) codes (see DIAGNOSTICS) an ESC exit(3,n,1 builtins) sta-
              tus may be returned.

              The codes used for "Yes" and "No" match those used for "OK"  and
              "Cancel", internally no distinction is made.

RUN-TIME CONFIGURATION
       1.  Create a sample configuration file(1,n) by typing:

                 "dialog(1,3,n) --create-rc <file(1,n)>"

       2.  At start, dialog(1,3,n) determines the settings to use as follows:

           a)  if(3,n)  environment  variable DIALOGRC is set(7,n,1 builtins), its value determines
               the name of the configuration file.

           b)  if(3,n) the file(1,n) in(1,8) (a) is not found, use the  file(1,n)  $HOME/.dialogrc
               as the configuration file.

           c)  if(3,n)  the  file(1,n)  in(1,8) (b) is not found, try using the GLOBALRC file(1,n)
               determined at compile-time, i.e., /etc/dialogrc.

           d)  if(3,n) the file(1,n) in(1,8) (c) is not found, use compiled in(1,8) defaults.

       3.  Edit the sample configuration file(1,n) and copy it to some  place  that
           dialog(1,3,n) can find, as stated in(1,8) step 2 above.

ENVIRONMENT
       DIALOGOPTS     Define  this variable to apply any of the common options
                      to each widget.  Most of the common  options  are  reset(1,7,1 tput)
                      before  processing  each widget.  If you set(7,n,1 builtins) the options
                      in(1,8) this environment variable, they are applied  to  dia-
                      log's  state  after the reset.  As in(1,8) the --file option,
                      double-quotes and backslashes are interpreted.

                      The --file option is not considered a common option  (so
                      you cannot embed it within this environment variable).

       DIALOGRC       Define  this variable if(3,n) you want to specify the name of
                      the configuration file(1,n) to use.

       DIALOG_CANCEL

       DIALOG_ERROR

       DIALOG_ESC

       DIALOG_EXTRA

       DIALOG_HELP

       DIALOG_OK      Define any of these variables to change the exit(3,n,1 builtins) code on
                      Cancel  (1), error(8,n) (-1), ESC (255), Extra (3), Help (2),
                      or OK (0).  Normally shell  scripts  cannot  distinguish
                      between -1 and 255.

       DIALOG_TTY     Set  this  variable to "1" to provide compatibility with
                      older versions of  dialog(1,3,n)  which  assumed  that  if(3,n)  the
                      script  redirects  the standard output, that the "--std-
                      out" option was given.

FILES
       $HOME/.dialogrc     default configuration file(1,n)

EXAMPLES
       The dialog(1,3,n) sources contain several samples of how to use the  different
       box  options  and  how  they look.  Just take a look(1,8,3 Search::Dict) into the directory
       samples/ of the source.

DIAGNOSTICS
       Exit status is subject to being overridden  by  environment  variables.
       Normally they are:

       0    if(3,n) dialog(1,3,n) is exited by pressing the Yes or OK button.

       1    if(3,n) the No or Cancel button is pressed.

       2    if(3,n) the Help button is pressed.

       3    if(3,n) the Extra button is pressed.

       -1   if(3,n)  errors occur inside dialog(1,3,n) or dialog(1,3,n) is exited by pressing the
            ESC key.

BUGS
       Perhaps.

AUTHOR
       Savio Lam (lam836@cs.cuhk.hk) - version(1,3,5) 0.3, "dialog(1,3,n)"

       Stuart Herbert (S.Herbert@sheffield.ac.uk) - patch for version(1,3,5) 0.4

       Pako (demarco_p@abramo.it) - version(1,3,5) 0.9a, "cdialog",

       Thomas Dickey (updates for 0.9b and beyond)

CONTRIBUTORS
       Tobias C. Rittweiler (tobrit@freebits.de)



$Date: 2004/06/06 01:07:03 $                                         DIALOG(1)

References for this manual (incoming links)