info > Curses(3pm)

Curses(3pm) User Contributed Perl Documentation Curses(3pm)

๐Ÿท๏ธ NAME

Curses - terminal screen handling and optimization

๐Ÿš€ Quick Reference

Use CaseCommandDescription
Initialize cursesinitscr()Initialize terminal screen
End cursesendwin()End curses mode, restore terminal
Add string at cursoraddstr(y, x, string)Add string at position (y,x)
Get character inputgetch()Get a single character
Refresh windowrefresh()Refresh stdscr to screen
Unified function callfunction(win, y, x, args)Call any unified function with optional window and coordinates
Wide character inputgetchar()Get a wide character, returns string or function key
Add wide stringaddstring(string)Add a Perl string using wide-character-aware function

๐Ÿ“ SYNOPSIS

use Curses;

initscr;
...
endwin;

๐Ÿ“– DESCRIPTION

Curses is the interface between Perl and your system's curses(3) library. For descriptions on the usage of a given function, variable, or constant, consult your system's documentation, as such information invariably varies (:-) between different curses(3) libraries and operating systems. This document describes the interface itself, and assumes that you already know how your system's curses(3) library works.

๐Ÿ”— Unified Functions

Many curses(3) functions have variants starting with the prefixes w-, mv-, and/or wmv-. These variants differ only in the explicit addition of a window, or by the addition of two coordinates that are used to move the cursor first. For example, addch() has three other variants: waddch(), mvaddch(), and mvwaddch(). The variants aren't very interesting; in fact, we could roll all of the variants into original function by allowing a variable number of arguments and analyzing the argument list for which variant the user wanted to call.

Unfortunately, curses(3) predates varargs(3), so in C we were stuck with all the variants. However, Curses is a Perl interface, so we are free to "unify" these variants into one function. The section "Available Functions" below lists all curses(3) functions Curses makes available as Perl equivalents, along with a column listing if it is unified. If so, it takes a varying number of arguments as follows:

function( [win], [y, x], args );

win is an optional window argument, defaulting to stdscr if not specified.

y, x is an optional coordinate pair used to move the cursor, defaulting to no move if not specified.

args are the required arguments of the function. These are the arguments you would specify if you were just calling the base function and not any of the variants.

This makes the variants obsolete, since their functionality has been merged into a single function, so Curses does not define them by default. You can still get them if you want, by setting the variable $Curses::OldCurses to a non-zero value before using the Curses package. See "Perl 4.X "cursperl" Compatibility" for an example of this.

๐ŸŒ Wide-Character-Aware Functions

The following are the preferred functions for working with strings, though they don't follow the normal unified function naming convention (based on the names in the Curses library) described above. Despite the naming, each corresponds to a Curses library function. For example, a getchar call performs a Curses library function in the getch family.

In addition to these functions, The Curses module contains corresponding functions with the conventional naming (e.g. getch); the duplication is for historical reasons. The preferred functions were new in Curses 1.29 (April 2014). They use the wide character functions in the Curses library if available (falling back to using the traditional non-wide-character versions). They also have a more Perl-like interface, taking care of some gory details under the hood about which a Perl programmer shouldn't have to worry.

The reason for two sets of string-handling functions is historical. The original Curses Perl module predates Curses libraries that understand multiple byte character encodings. Moreover, the module was designed to have a Perl interface that closely resembles the C interface syntactically and directly passes the internal byte representation of Perl strings to C code. This was probably fine before Perl got Unicode function, but today, Perl stores strings internally in either Latin-1 or Unicode UTF-8 and the original module was not sensitive to which encoding was used.

While most of the problems could be worked around in Perl code using the traditional interface, it's hard to get right and you need a wide-character-aware curses library (e.g. ncursesw) anyway to make it work properly. Because existing consumers of the Curses module may be relying on the traditional behavior, Curses module designers couldn't simply modify the existing functions to understand wide characters and convert from and to Perl strings.

None of these functions exist if Perl is older than 5.6.

getchar

This calls wget_wch(). It returns a character โ€” more precisely, a one-character (not necessarily one-byte!) string holding the character โ€” for a normal key and a two-element list (undef, key-number) for a function key. It returns undef on error.

If you don't expect function keys (i.e. with keypad(0)), you can simply do

my $ch = getchar;
die "getchar failed" unless defined $ch;

If you do expect function keys (i.e. with keypad(1)), you can still assign the result to a scalar variable as above. Because of of the way the comma operator works, that variable will receive either undef or the string or the number, and you can decode it yourself.

my $ch = getchar;
die "getchar failed" unless defined $ch;
if ($ch looks like a number >= 0x100) {
    # handle function key
} else {
    # handle normal key
}

or do

my ($ch, $key) = getchar;
if (defined $key) {
    # handle function key $key
} elsif (defined $ch) {
    # handle normal key $ch
} else {
    die "getchar failed";
}

If wget_wch() is not available (i.e. The Curses library does not understand wide characters), this calls wgetch(), but returns the values described above nonetheless. This can be a problem because with a multibyte character encoding like UTF-8, you will receive two one-character strings for a two-byte-character (e.g. "o" and "a1/2" for "a1/2"). If you append these characters to a Perl string, that string may internally contain a valid UTF-8 encoding of a character, but Perl will not interpret it that way. Perl may even try to convert what it believes to be two characters to UTF-8, giving you four bytes.

getstring

This calls wgetn_wstr and returns a string or undef. It cannot return a function key value; the Curses library will itself interpret KEY_LEFT and KEY_BACKSPACE.

If wgett_wstr() is unavailable, this calls wgetstr().

In both cases, the function allocates a buffer of fixed size to hold the result of the Curses library call.

my $s = getstring();
die "getstring failed" unless defined $s;

addstring/insstring

This adds/inserts the Perl string passed as an argument to the Curses window using waddnwstr()/wins_nwstr() or, if unavailable, waddnstr()/winsnstr(). It returns a true value on success, false on failure.

addstring("Hรคlla!, Wรคrld") || die "addstring failed";

instring

This returns a Perl string (or undef on failure) holding the characters from the current cursor position up to the end of the line. It uses winnwstr() if available, and otherwise innstr().

my $s = instring();
die "instring failed" unless defined $s;

ungetchar

This pushes one character (passed as a one-character Perl string) back to the input queue. It uses unget_wch() or ungetch(). It returns a true value on success, false on failure. It cannot push back a function key; the Curses library provides no way to push back function keys, only characters.

ungetchar("X") || die "ungetchar failed";

The Curses module provides no interface to the complex-character routines (wadd_wch(), wadd_wchnstr(), wecho_wchar(), win_wch(), win_wchnstr(), wins_wch()) because there is no sensible way of converting from Perl to a C cchar_t or back.

๐Ÿงฉ Objects

Objects work. Example:

$win = new Curses;
$win->addstr(10, 10, 'foo');
$win->refresh;
...

Any function that has been marked as unified (see "Available Functions" below and "Unified Functions" above) can be called as a method for a Curses object.

Do not use initscr() if using objects, as the first call to get a new Curses will do it for you.

๐Ÿ”’ Security Concerns

It has always been the case with the curses functions, but please note that the following functions:

are subject to buffer overflow attack. This is because you pass in the buffer to be filled in, which has to be of finite length, but there is no way to stop a bad guy from typing.

In order to avoid this problem, use the alternate functions:

which take an extra "size of buffer" argument or the wide-character-aware getstring() and instring() versions.

๐Ÿ”„ COMPATIBILITY

๐Ÿช Perl 4.X "cursperl" Compatibility

Curses was written to take advantage of features of Perl 5 and later. The author thought it was better to provide an improved curses programming environment than to be 100% compatible. However, many old "curseperl" applications will probably still work by starting the script with:

BEGIN { $Curses::OldCurses = 1; }
use Curses;

Any old application that still does not work should print an understandable error message explaining the problem.

Some functions and variables are not available through Curses, even with the BEGIN line. They are listed under "Curses items not available through Perl Curses".

The variables $stdscr and $curscr are also available as functions stdscr and curscr. This is because of a Perl bug. See the LIMITATIONS section for details.

โš ๏ธ Incompatibilities with previous versions of Curses

In previous versions of this software, some Perl functions took a different set of parameters than their C counterparts. This is not true in the current version. You should now use getstr($str) and getyx($y, $x) instead of $str = getstr() and ($y, $x) = getyx().

๐Ÿฉบ DIAGNOSTICS

โ›” LIMITATIONS

If you use the variables $stdscr and $curscr instead of their functional counterparts (stdscr and curscr), you might run into a bug in Perl where the "magic" isn't called early enough. This is manifested by the Curses package telling you $stdscr isn't a window. One workaround is to put a line like $stdscr = $stdscr near the front of your program.

๐Ÿ‘ค AUTHOR

William Setzer <William_Setzer AT ncsu.edu>

๐Ÿ“‹ SYNOPSIS OF PERL CURSES AVAILABILITY

๐Ÿ“‹ Available Functions

Available FunctionUnified?Available via $OldCurses[*]
addchYeswaddch mvaddch mvwaddch
echocharYeswechochar
addchstrYeswaddchstr mvaddchstr mvwaddchstr
addchnstrYeswaddchnstr mvaddchnstr mvwaddchnstr
addstrYeswaddstr mvaddstr mvwaddstr
addnstrYeswaddnstr mvaddnstr mvwaddnstr
attroffYeswattroff
attronYeswattron
attrsetYeswattrset
standendYeswstandend
standoutYeswstandout
attr_getYeswattr_get
attr_offYeswattr_off
attr_onYeswattr_on
attr_setYeswattr_set
chgatYeswchgat mvchgat mvwchgat
COLOR_PAIRNo
PAIR_NUMBERNo
beepNo
flashNo
bkgdYeswbkgd
bkgdsetYeswbkgdset
getbkgdYes
borderYeswborder
boxYes
hlineYeswhline mvhline mvwhline
vlineYeswvline mvvline mvwvline
eraseYeswerase
clearYeswclear
clrtobotYeswclrtobot
clrtoeolYeswclrtoeol
start_colorNo
init_pairNo
init_colorNo
has_colorsNo
can_change_colorNo
color_contentNo
pair_contentNo
delchYeswdelch mvdelch mvwdelch
deletelnYeswdeleteln
insdellnYeswinsdelln
insertlnYeswinsertln
getchYeswgetch mvgetch mvwgetch
ungetchNo
has_keyNo
KEY_FNo
getstrYeswgetstr mvgetstr mvwgetstr
getnstrYeswgetnstr mvgetnstr mvwgetnstr
getyxYes
getparyxYes
getbegyxYes
getmaxyxYes
inchYeswinch mvinch mvwinch
inchstrYeswinchstr mvinchstr mvwinchstr
inchnstrYeswinchnstr mvinchnstr mvwinchnstr
initscrNo
endwinNo
isendwinNo
newtermNo
set_termNo
delscreenNo
cbreakNo
nocbreakNo
echoNo
noechoNo
halfdelayNo
intrflushYes
keypadYes
metaYes
nodelayYes
notimeoutYes
rawNo
norawNo
qiflushNo
noqiflushNo
timeoutYeswtimeout
typeaheadNo
inschYeswinsch mvinsch mvwinsch
insstrYeswinsstr mvinsstr mvwinsstr
insnstrYeswinsnstr mvinsnstr mvwinsnstr
instrYeswinstr mvinstr mvwinstr
innstrYeswinnstr mvinnstr mvwinnstr
def_prog_modeNo
def_shell_modeNo
reset_prog_modeNo
reset_shell_modeNo
resettyNo
savettyNo
getsyxNo
setsyxNo
curs_setNo
napmsNo
moveYeswmove
clearokYes
idlokYes
idcokYes
immedokYes
leaveokYes
setscrregYeswsetscrreg
scrollokYes
nlNo
nonlNo
overlayNo
overwriteNo
copywinNo
newpadNo
subpadNo
prefreshNo
pnoutrefreshNo
pechocharNo
refreshYeswrefresh
noutrefreshYeswnoutrefresh
doupdateNo
redrawwinYes
redrawlnYeswredrawln
scr_dumpNo
scr_restoreNo
scr_initNo
scr_setNo
scrollYes
scrlYeswscrl
slk_initNo
slk_setNo
slk_refreshNo
slk_noutrefreshNo
slk_labelNo
slk_clearNo
slk_restoreNo
slk_touchNo
slk_attronNo
slk_attrsetNo
slk_attrNo
slk_attroffNo
slk_colorNo
baudrateNo
erasecharNo
has_icNo
has_ilNo
killcharNo
longnameNo
termattrsNo
termnameNo
touchwinYes
touchlineYes
untouchwinYes
touchlnYeswtouchln
is_linetouchedYes
is_wintouchedYes
unctrlNo
keynameNo
filterNo
use_envNo
putwinNo
getwinNo
delay_outputNo
flushinpNo
newwinNo
delwinYes
mvwinYes
subwinYes
derwinYes
mvderwinYes
dupwinYes
syncupYeswsyncup
syncokYes
cursyncupYeswcursyncup
syncdownYeswsyncdown
getmouseNo
ungetmouseNo
mousemaskNo
encloseYeswenclose
mouse_trafoYeswmouse_trafo
mouseintervalNo
BUTTON_RELEASENo
BUTTON_PRESSNo
BUTTON_CLICKNo
BUTTON_DOUBLE_CLICKNo
BUTTON_TRIPLE_CLICKNo
BUTTON_RESERVED_EVENTNo
use_default_colorsNo
assume_default_colorsNo
define_keyNo
keyboundNo
keyokNo
resizetermNo
resizeYeswresize
getmaxyYes
getmaxxYes
flusokYes
getcapNo
touchoverlapNo
new_panelNo
bottom_panelNo
top_panelNo
show_panelNo
update_panelsNo
hide_panelNo
panel_windowNo
replace_panelNo
move_panelNo
panel_hiddenNo
panel_aboveNo
panel_belowNo
set_panel_userptrNo
panel_userptrNo
del_panelNo
set_menu_foreNo
menu_foreNo
set_menu_backNo
menu_backNo
set_menu_greyNo
menu_greyNo
set_menu_padNo
menu_padNo
pos_menu_cursorNo
menu_driverNo
set_menu_formatNo
menu_formatNo
set_menu_itemsNo
menu_itemsNo
item_countNo
set_menu_markNo
menu_markNo
new_menuNo
free_menuNo
menu_optsNo
set_menu_optsNo
menu_opts_onNo
menu_opts_offNo
set_menu_patternNo
menu_patternNo
post_menuNo
unpost_menuNo
set_menu_userptrNo
menu_userptrNo
set_menu_winNo
menu_winNo
set_menu_subNo
menu_subNo
scale_menuNo
set_current_itemNo
current_itemNo
set_top_rowNo
top_rowNo
item_indexNo
item_nameNo
item_descriptionNo
new_itemNo
free_itemNo
set_item_optsNo
item_opts_onNo
item_opts_offNo
item_optsNo
item_userptrNo
set_item_userptrNo
set_item_valueNo
item_valueNo
item_visibleNo
menu_request_nameNo
menu_request_by_nameNo
set_menu_spacingNo
menu_spacingNo
pos_form_cursorNo
data_aheadNo
data_behindNo
form_driverNo
set_form_fieldsNo
form_fieldsNo
field_countNo
move_fieldNo
new_formNo
free_formNo
set_new_pageNo
new_pageNo
set_form_optsNo
form_opts_onNo
form_opts_offNo
form_optsNo
set_current_fieldNo
current_fieldNo
set_form_pageNo
form_pageNo
field_indexNo
post_formNo
unpost_formNo
set_form_userptrNo
form_userptrNo
set_form_winNo
form_winNo
set_form_subNo
form_subNo
scale_formNo
set_field_foreNo
field_foreNo
set_field_backNo
field_backNo
set_field_padNo
field_padNo
set_field_bufferNo
field_bufferNo
set_field_statusNo
field_statusNo
set_max_fieldNo
field_infoNo
dynamic_field_infoNo
set_field_justNo
field_justNo
new_fieldNo
dup_fieldNo
link_fieldNo
free_fieldNo
set_field_optsNo
field_opts_onNo
field_opts_offNo
field_optsNo
set_field_userptrNo
field_userptrNo
field_argNo
form_request_nameNo
form_request_by_nameNo

[*] To use any functions in this column, the program must set the variable $Curses::OldCurses variable to a non-zero value before using the Curses package. See "Perl 4.X cursperl Compatibility" for an example of this.

๐ŸŒ Available Wide-Character-Aware Functions

FunctionUses wide-character callReverts to legacy call
getcharwget_wchwgetch
getstringwgetn_wstrwgetnstr
ungetcharunget_wchungetch
instringwinnwtrwinnstr
addstringwaddnwstrwaddnstr
insstringwins_nwstrwinsnstr

๐Ÿงฎ Available Variables

๐Ÿ”ข Available Constants

๐Ÿšซ Curses functions not available through Perl Curses

Curses menu functions not available through Perl Curses:

Curses form functions not available through Perl Curses:

perl v5.34.0 2022-02-06 Curses(3pm)

Curses(3pm)
Curses(3pm) User Contributed Perl Documentation Curses(3pm) ๐Ÿท๏ธ NAME ๐Ÿš€ Quick Reference ๐Ÿ“ SYNOPSIS ๐Ÿ“– DESCRIPTION
๐Ÿ”— Unified Functions ๐ŸŒ Wide-Character-Aware Functions ๐Ÿงฉ Objects ๐Ÿ”’ Security Concerns
๐Ÿ”„ COMPATIBILITY
๐Ÿช Perl 4.X "cursperl" Compatibility โš ๏ธ Incompatibilities with previous versions of Curses
๐Ÿฉบ DIAGNOSTICS โ›” LIMITATIONS ๐Ÿ‘ค AUTHOR ๐Ÿ“‹ SYNOPSIS OF PERL CURSES AVAILABILITY
๐Ÿ“‹ Available Functions ๐ŸŒ Available Wide-Character-Aware Functions ๐Ÿงฎ Available Variables ๐Ÿ”ข Available Constants ๐Ÿšซ Curses functions not available through Perl Curses

Generated by phpman v4.9.26-1-g511901d Author: Che Dong Under GNU General Public License
2026-08-08 12:36 @216.73.216.150
CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
Valid XHTML 1.0 Transitional!Valid CSS!
Enhanced by LLM: deepseek-v4-flash / taotoken.net / www.chedong.com - original format