--- name: "bsddialog" section: "1" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/bsddialog" --- # bsddialog(1) TUI dialogs ## NAME **bsddialog** – TUI dialogs ## SYNOPSIS **bsddialog** **-****-help** \| **-****-version** **bsddialog** \[**-****-option**\] **-****-dialog** *text* *rows* *cols* \[*dialog-argument*\] \[**-****-option**\] **bsddialog** ... **-****-dialog1** *...* \[**-****-and-dialog** **-****-dialog2** *...*\] ... ## DESCRIPTION The **bsddialog** utility builds Text User Interface dialogs and widgets. The option **-****-help** prints a brief list of features and exits. The option **-****-version** prints the version and exits. The option **-****-and-dialog** builds another dialog unless the previous one returns Error, ESC or Cancel. Each dialog accepts *text* to print a message inside, *rows* and *cols* to set height and width, 0 for autosize and -1 for fullscreen. The possible input from the user interface is printed to standard error at exit. ### Options The following options can change the default behavior of the utility and are common to some dialog. - **-****-alternate-screen** Set alternate screen mode if the terminal and [curses(3)](/curses/3.md) provide it. If enabled bsddialog draws to the alternate screen and restores the main screen after exit. See “smcup” in [terminfo(5)](/terminfo/5.md). - **-****-ascii-lines** Ascii characters to draw lines. - **-****-backtitle** *backtitle* Screen title. - **-****-begin-x** *x* Set dialog horizontal position, -1 center, 0 left screen. - **-****-begin-y** *y* Set dialog vertical position, -1 center, 0 top screen. - **-****-bikeshed** Random settings. Colors, title delimiter, button delimiter; see theme features. Title margin. Buttons always active or TAB to switch focus with other components, see **-****-switch-buttons**. Zero padding with time output; see **-****-time-format**. Zero padding with date output; see **-****-date-format**. User Interface date format for **-****-datebox**; see **-****-datebox-format**. - **-****-cancel-exit-code** *retval* Set an exit code value for the “Cancel” button. - **-****-cancel-label** *label* Label for the “Cancel” button. - **-****-clear-dialog** Hide the dialog at exit. - **-****-clear-screen** Clear the screen, wait a dialog if built. - **-****-columns-per-row** *columns* Try to set the number of columns for a row of text with autosizing; default 10. - **-****-cr-wrap** Keep new line in *text* also if it constains a “\\n”, see **-****-text-unchanged**. - **-****-datebox-format** *format* String to customize **-****-datebox** interface, possible values: “d/m/y”, “m/y/d”, “y/m/d”. - **-****-date-format** *format* String accepted by [strftime(3)](/strftime/3.md) to customize the output of **-****-datebox** and **-****-calendar**. - **-****-default-button** *label* Focus on the button with *label* on startup. - **-****-default-item** *name* Focus on the item with *name*, for Checklist, Menu, Radiolist and Treeview. - **-****-default-no** Focus on “Cancel” or “No” button on startup. - **-****-disable-esc** Disable ESC key to quit. - **-****-error-exit-code** *retval* Set an exit code value for the **bsddialog** errors. - **-****-esc-exit-code** *retval* Set an exit code value for the ESC key. - **-****-extra-button** Add a button with “Extra” label. - **-****-extra-exit-code** *retval* Set an exit code value for the “Extra” button. - **-****-extra-label** *label* Set *label* for the “Extra” button. - **-****-left1-button** *label* Add a button with *label*. - **-****-left1-exit-code** *retval* Set an exit code for **-****-left1-button**. - **-****-left2-button** *label* Add a button with *label*. - **-****-left2-exit-code** *retval* Set an exit code for **-****-left2-button**. - **-****-left3-button** *label* Add a button with *label*. - **-****-left3-exit-code** *retval* Set an exit code for **-****-left3-button**. - **-****-help-button** Add a button with “Help” label. - **-****-help-exit-code** *retval* Set an exit code value for the “Help” button. - **-****-help-label** *label* Set *label* for “Help” button. - **-****-help-print-items** Print also the selected items or form values if the “Help” button is pressed. - **-****-help-print-name** Print the name of the focused item if the “Help” button is pressed also with **-****-item-bottom-desc**. - **-****-hfile** *filename* Open *filename* in a Textbox if F1 key is pressed. - **-****-hline** *string* Dialog subtitle. - **-****-hmsg** *string* Open a Msgbox with *string* if the F1 key is pressed. - **-****-ignore** Do not exit with unknown options. - **-****-insecure** Print ‘\*’ to hide passwords while typing, white space otherwise. - **-****-item-bottom-desc** Set a help string for each item of a Checklist, Form, Menu, Mixedform, Passwordform, Radiolist and Treeview to display at the bottom screen side. - **-****-item-depth** Specify a margin for items, available for Checklist, Menu and Radiolist. - **-****-item-prefix** Set a string to prefix each item of a Checklist, Menu, Radiolist or Treeview. - **-****-load-theme** *file* Load theme from *file*. - **-****-max-input** *size* Maximum length of the input for **-****-inputbox** and **-****-passwordbox**, default 2048. - **-****-no-cancel** Do not show “Cancel” button. - **-****-no-descriptions** Do not display items desciption, for Checklist, Menu, Radiolist or Treeview; mutually exclusive with **-****-no-names**. - **-****-no-lines** Do not draw borders and lines. - **-****-no-names** Do not display items name, for Checklist, Menu and Radiolist; mutually exclusive with **-****-no-descriptions**. - **-****-no-ok** Do not draw “OK” button. - **-****-no-shadow** No not draw the shadow of the dialog. - **-****-ok-label** *label* Set *label* for “OK” button. - **-****-ok-exit-code** *retval* Set an exit code value for the “Ok” button. - **-****-normal-screen** Set normal screen mode. bsddialog does not restore the previous screen after exit. See “rmcup” in [terminfo(5)](/terminfo/5.md). - **-****-output-fd** *fd* Print input from user interface to the specified file descriptor. - **-****-output-separator** *sep* Set a sepator for the items in output, default white space. - **-****-print-maxsize** Screen size. This option can be used without a dialog. - **-****-print-size** Print dialog height and width at exit. - **-****-print-version** Print version. This option can be used without a dialog. - **-****-quoted** Quote items in output, default only when necessary. - **-****-right1-button** *label* Add a button with *label*. - **-****-right1-exit-code** *retval* Set an exit code for **-****-right1-button**. - **-****-right2-button** *label* Add a button with *label*. - **-****-right2-exit-code** *retval* Set an exit code for **-****-right2-button**. - **-****-right3-button** *label* Add a button with *label*. - **-****-right3-exit-code** *retval* Set an exit code for **-****-right3-button**. - **-****-save-theme** *file* Save the current theme. This option can be used without a dialog. - **-****-separate-output** Print selected items separated by a new line and avoid to quote. - **-****-shadow** Show a shadow for the dialog, enabled by default. - **-****-single-quoted** Use single quote for items in output. - **-****-sleep** *secs* Wait *secs* seconds to close the dialog. - **-****-stderr** Print input from user interface to standand error, default. - **-****-stdout** Print input from user interface to standard output. - **-****-switch-buttons** Enable focus switching between buttons and input components pressing TAB, otherwise buttons are always active and ENTER key closes the dialog. Suitable for: **-****-form**, **-****-inputbox**, **-****-mixedform**, **-****-passwordbox**, **-****-passwordform**, **-****-timebox**, **-****-calendar** and **-****-datebox**. - **-****-tab-escape** Replace “\\t” with a tab in *text*. - **-****-tab-len** *spaces* Number of spaces to print a TAB in *text*. - **-****-text-escape** Enable escapes in *text*: | | | --- | | “\\Z0” | | “\\Z1” | | “\\Z2” | | “\\Z3” | | “\\Z4” | | “\\Z5” | | “\\Z6” | | “\\Z7” | | “\\Zb” | | “\\ZB” | | “\\Zd” | | “\\ZD” | | “\\Zk” | | “\\ZK” | | “\\Zr” | | “\\ZR” | | “\\Zs” | | “\\ZS” | | “\\Zu” | | “\\ZU” | | “\\Zn” | - **-****-text-unchanged** Disable *text* modification. By default *text* is changed before to be printed in the dialog. If it contains at least a “\\n” each new line and TAB is converted to a space, subsequent spaces are merged. Otherwise new line characters are preserved and a TAB becomes a space. - **-****-theme** *theme* Set theme, possible values: “3d”, “blackwhite”, “flat”. - **-****-time-format** *format* String accepted by [strftime(3)](/strftime/3.md) to customize the output of **-****-timebox**. - **-****-timeout-exit-code** *retval* Set an exit code value for the **-****-pause** timeout. - **-****-title** *title* Dialog title. ### Keys The following keys are available at runtime: - Ctrl-l Redraw the dialog. - F1 See **-****-hfile** and **-****-hmsg**. - SPACE Select menu item. - UP DOWN LEFT RIGHT - + HOME END PAGEUP PAGEDOWN Ctrl-p Ctrl-n TAB Navigate elements and set value, depending on the dialog. ### Dialogs The following dialogs are available: - **-****-calendar** *text* *rows* *cols* \[*day* *month* *year*\] Dialog to select a date. - **-****-checklist** *text* *rows* *cols* *menurows* \[*name* *desc* *status*\] ... Checklist to select some item from a list via the SPACE key. An item has a *name*, *desc* and a default *status* specified by “on” or “off”. The names of the selected items are printed to standard error. *menurows* is the graphical height of the list, 0 for autosize. - **-****-datebox** *text* *rows* *cols* \[*day* *month* *year*\] Dialog to select a date. - **-****-form** *text* *rows* *cols* *formrows* \[*label* *ylabel* *xlabel* *init* *yfield* *xfield* *fieldlen* *maxletters*\] ... Dialog to get a list of strings via forms. A form has a *label* at the position *ylabel* and *xlabel*, a field to get the input at the position *yfield* and *xfield*. *fieldlen* is the field width, if negative is readonly and the width is the absolute value, if 0 the field becomes readonly and its value is the *init* width. The field input is not printed to output if it is readonly. *maxletters* is the maximum input length, if is 0 its value is *fieldlen*. *init* is the default value in the field. *formrows* is the graphical height of the list, 0 for autosize. - **-****-gauge** *text* *rows* *cols* \[*percentage*\] Dialog with a bar to shows *percentage*, then it waits to read “XXX” from the standard input, then the first string replaces percentage and the following strings replace *text* until the next “XXX”, the loop ends reading “EOF”. - **-****-infobox** *text* *rows* *cols* Dialog without buttons to display a message and to exit immediately. - **-****-inputbox** *text* *rows* *cols* \[*init*\] Dialog to get a string in input, *init* is the default value. - **-****-menu** *text* *rows* *cols* *menurows* \[*name* *desc*\] ... Builds a menu to select an item from a list, SPACE key is equivalent to ENTER. An item has a *name* and a *desc*. The name of the selected item is printed to standard error. *menurows* is the graphical height of the list, 0 for autosize. - **-****-mixedform** *text* *rows* *cols* *formrows* \[*label* *ylabel* *xlabel* *init* *yfield* *xfield* *fieldlen* *maxletters* *flag*\] ... Dialog to get a list of strings via forms. A form has a *label* at the position *ylabel* and *xlabel*, a field to get the input at the position *yfield* and *xfield*. *fieldlen* is the field width, if negative is readonly and the width is the absolute value, if 0 the field becomes readonly and its value is the *init* width. The field input is not printed to output if *fieldlen* is less than or equal to 0. *maxletters* is the maximum input length, if is 0 its value is *fieldlen*. *init* is the default value in the field. *flag* can customize *field*: 0 normal, 1 hide typed characters, 2 readonly. *formrows* is the graphical height of the list, 0 for autosize. - **-****-mixedgauge** *text* *rows* *cols* *mainperc* \[*minilabel* *miniperc*\] ... Dialog to show a main bar to represent *mainperc* from 0 to 100. Some mini bar with a *minilabel* string and a *miniperc* with a value from 0 and 100 or negative to print a descriptive string: -1 “Succeeded”, -2 “Failed”, -3 “Passed”, -4 “Completed”, -5 “Checked”, -6 “Done”, -7 “Skipped”, -8 “In Progress”, -9 to hide *miniperc*, -10 “N/A”, -11 “Pending”, otherwise “UNKNOWN”. - **-****-msgbox** *text* *rows* *cols* Dialog to diplay a message without the “Cancel” button. - **-****-passwordbox** *text* *rows* *cols* \[*init*\] Dialog to get a password, *init* is the default value. - **-****-passwordform** *text* *rows* *cols* *formrows* \[*label* *ylabel* *xlabel* *init* *yfield* *xfield* *fieldlen* *maxletters*\] ... Dialog to get a list of passwords, equivalent to **-****-form** except typed characters are hidden. - **-****-pause** *text* *rows* *cols* *seconds* Dialog runs until *seconds* timeout expires or a button is pressed. - **-****-radiolist** *text* *rows* *cols* *menurows* \[*name* *desc* *status*\] ... Radiolist to select at most an item from a list via the SPACE key. An item has a *name*, *desc* and a default *status* specified by “on” or “off”. The name of the selected item is printed to standard error. *menurows* is the graphical height of the list, 0 for autosize. - **-****-rangebox** *text* *rows* *cols* *min* *max* \[*init*\] Dialog to select a value between *min* and *max*, *init* is the default value. - **-****-textbox** *file* *rows* *cols* Opens and prints *file*. TAB changes button. Extra keys 0, h, l, k, j are available to navigate the text. “OK” button is renamed “EXIT”. - **-****-timebox** *text* *rows* *cols* \[*hour* *min* *sec*\] Dialog to select a time. - **-****-treeview** *text* *rows* *cols* *menurows* \[*depth* *name* *desc* *status*\] ... Equivalent to Radiolist with **-****-item-depth** and **-****-no-name**. - **-****-yesno** *text* *rows* *cols* “Yes-No Question”, “OK” and “Cancel” buttons are renamed “Yes” and “No”. ## ENVIRONMENT The following environment variables take effect only on startup, other options can override their setting. - NO\_COLOR If present and not an empty string (regardless of its value) equivalent to **-****-theme** *blackwhite*. - BSDDIALOG\_ERROR, BSDDIALOG\_OK, BSDDIALOG\_CANCEL, BSDDIALOG\_HELP, BSDDIALOG\_EXTRA, BSDDIALOG\_TIMEOUT, BSDDIALOG\_ESC, BSDDIALOG\_LEFT1, BSDDIALOG\_LEFT2, BSDDIALOG\_LEFT3, BSDDIALOG\_RIGHT1, BSDDIALOG\_RIGHT2, BSDDIALOG\_RIGHT3 Set exit codes. - BSDDIALOG\_THEMEFILE *file* Equivalent to **-****-load-theme** *file*. ## FILES The theme file *$HOME/.bsddialog.conf* is read on startup if exists. ## EXIT STATUS The **bsddialog** utility exits 255 on unsuccessful, otherwise depending on the button or key pressed the following values can be returned: | | | --- | | 0 | | 1 | | 2 | | 3 | | 4 | | 5 | | 6 | | 7 | | 8 | | 9 | | 10 | | 11 | ## EXAMPLES Backtitle, title and message: ``` bsddialog --backtitle MESSAGE --title Msgbox --msgbox Message 0 0 ``` Yes-No Question and theme: ``` bsddialog --theme blackwhite --yesno Question 10 30 ``` Save a custom theme: ``` bsddialog --save-theme mytheme.txt --infobox Saving theme... 0 0 ``` Load a custom theme: ``` bsddialog --load-theme mytheme.txt --infobox Custom theme 0 0 ``` Checklist: ``` bsddialog --checklist Checklist 0 0 3 N1 D1 off N2 D2 on N3 D3 off ``` Form: ``` bsddialog --form Form 0 0 0 L1: 0 0 X 0 4 20 25 L2: 1 0 Y 1 4 20 25 ``` Multi-dialog: ``` bsddialog --normal-screen --begin-y 1 --yesno Continue? 0 0 \ --and-dialog --begin-y 10 --infobox Yes 0 0 ``` Bikeshed: ``` bsddialog --bikeshed --inputbox Example 0 0 ``` ``` bsddialog --bikeshed --datebox Example 0 0 ``` Mixedgauge: ``` bsddialog --sleep 3 --mixedgauge Example 10 30 60 L1 -1 L2 30 ``` Mixedgauge script: ``` perc=0 while [ $perc -le 100 ] do bsddialog --sleep 1 --title Mixedgauge \ --mixedgauge "\nExample...\n" 0 0 $perc \ "Hidden" " -9" \ "Label 1" " -4" \ "Label 2" " -4" \ "Label 3" $perc perc=`expr $perc + 20` done ``` Gauge script: ``` i=1 for c in A B C D E F G H do sleep 1 echo XXX echo "$(expr $(expr $i "*" 100) "/" 8)" echo "[$i/8] Char: $c" echo XXX if [ $i -eq 8 ] then sleep 1 echo EOF fi i=`expr $i + 1` done | bsddialog --title Gauge --gauge "Starting..." 10 70 ``` ## COMPATIBILITY Outdated options are retained for compatibility, properly equivalent options are used: ``` Obsolete Equivalent --and-widget --and-dialog --calendar 2 --calendar 0 --clear --clear-screen --colors --text-escape --defaultno --default-no --exit-label --ok-label --help-status --help-print-items --help-tags --help-print-name --item-help --item-bottom-desc --keep-tite --alternate-screen --no-items --no-descriptions --no-label --cancel-label --no-tags --no-names --nocancel --no-cancel --nook --no-ok --separator --output-separator --yes-label --ok-label ``` ## SEE ALSO [bsddialog(3)](/bsddialog/3.md), [strftime(3)](/strftime/3.md), [terminfo(5)](/terminfo/5.md) ## HISTORY The **bsddialog** utility first appeared in FreeBSD 14.0. ## AUTHORS **bsddialog** was written by Alfonso Sabato Siciliano ⟨*asiciliano@FreeBSD.org*⟩. Braulio Rivas ⟨*brauliorivas@FreeBSD.org*⟩ implemented the slider dialog for the “GSoC 2025 Full Disk Administration Tool for FreeBSD”. **bsddialog** provides also a subset of the functionality described in the **dialog** manual. The following features were reimplemented: Options: **-****-and-widget**, **-****-ascii-lines**, **-****-backtitle**, **-****-cancel-label**, **-****-clear**, **-****-colors**, **-****-cr-wrap**, **-****-date-format**, **-****-defaultno**, **-****-default-button**, **-****-default-no**, **-****-default-item**, **-****-exit-label**, **-****-extra-button**, **-****-extra-label**, **-****-help**, **-****-help-button**, **-****-help-label**, **-****-help-status**, **-****-help-tags**, **-****-hfile**, **-****-hline**, **-****-ignore**, **-****-insecure**, **-****-item-help**, **-****-keep-tite**, **-****-max-input**, **-****-no-cancel**, **-****-nocancel**, **-****-no-items**, **-****-no-label**, **-****-no-lines**, **-****-no-ok**, **-****-nook**, **-****-no-shadow**, **-****-no-tags**, **-****-ok-label**, **-****-output-fd**, **-****-output-separator**, **-****-print-maxsize**, **-****-print-size**, **-****-print-version**, **-****-quoted**, **-****-separate-output**, **-****-separator**, **-****-shadow**, **-****-single-quoted**, **-****-sleep**, **-****-stderr**, **-****-stdout**, **-****-tab-len**, **-****-time-format**, **-****-title**, **-****-version**, **-****-yes-label**. Keys: Ctrl-l, F1. Dialogs: **-****-calendar**, **-****-checklist**, **-****-form**, **-****-gauge**, **-****-infobox**, **-****-inputbox**, **-****-menu**, **-****-mixedform**, **-****-mixedgauge**, **-****-msgbox**, **-****-passwordbox**, **-****-passwordform**, **-****-pause**, **-****-radiolist**, **-****-rangebox**, **-****-textbox**, **-****-timebox**, **-****-treeview**, **-****-yesno**. Some feature differs in input, output, or behavior. Compatibility is not a priority for future development. ## THANKS TO Baptiste Daroussin ⟨*bapt@FreeBSD.org*⟩, Ed Maste ⟨*emaste@FreeBSD.org*⟩, Juraj Lutter ⟨*otis@FreeBSD.org*⟩ and Trenton Schulz for suggestions, help, and testing.